《互联网产品的 AI 架构·多能力编排与任务闭环》11.2 引擎扩展点与插件边界

// file: src/orch/extensions.ts
// tier: L2
// verify: node --test test/orch/platform.test.ts

import { AiError } from "../core/errors.ts";
import { compareSemver, isValidRange, parseSemver, satisfiesRange } from "./platform.ts";

export type ExtensionPoint = "node-type" | "policy" | "store" | "observability";

export const EXTENSION_POINTS: readonly ExtensionPoint[] = [
  "node-type",
  "policy",
  "store",
  "observability",
];

export interface ExtensionDescriptor {
  name: string;
  point: ExtensionPoint;
  apiVersion: string;
  engineRange: string;
  owner: string;
  hooks: readonly string[];
}

export type ExtensionIssueCode =
  | "invalid-name"
  | "unknown-point"
  | "missing-owner"
  | "invalid-api-version"
  | "invalid-engine-version"
  | "invalid-engine-range"
  | "incompatible-major"
  | "engine-too-old"
  | "engine-range-mismatch"
  | "forbidden-hook"
  | "duplicate-extension";

export interface ExtensionIssue {
  extension: string;
  code: ExtensionIssueCode;
  detail: string;
}

export interface ExtensionRegistry {
  engineApiVersion: string;
  points: readonly ExtensionPoint[];
  extensions: readonly ExtensionDescriptor[];
}

export type RegisterResult =
  | { ok: true; registry: ExtensionRegistry }
  | { ok: false; issues: ExtensionIssue[] };

const NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;

/**
 * 每个扩展点能挂什么钩子、不能碰什么是平台契约的一部分。
 * 引擎保留图结构、预算上限、授权与原始载荷的所有权。
 */
const FORBIDDEN_HOOKS: Record<ExtensionPoint, readonly string[]> = {
  "node-type": ["graph.rewrite", "budget.override", "auth.bypass"],
  policy: ["graph.rewrite", "auth.bypass", "store.global-write"],
  store: ["graph.rewrite", "budget.override", "auth.bypass", "policy.override"],
  observability: ["graph.rewrite", "budget.override", "auth.bypass", "payload.read"],
};

export function forbiddenHooks(point: ExtensionPoint): readonly string[] {
  return FORBIDDEN_HOOKS[point] ?? [];
}

function issue(
  extension: string,
  code: ExtensionIssueCode,
  detail: string,
): ExtensionIssue {
  return { extension, code, detail };
}

export function createRegistry(
  engineApiVersion: string,
  points: readonly ExtensionPoint[] = EXTENSION_POINTS,
): ExtensionRegistry {
  if (parseSemver(engineApiVersion) === null) {
    throw new AiError("invalid-request", `extensions: invalid engine API ${engineApiVersion}`);
  }
  if (points.length === 0) {
    throw new AiError("invalid-request", "extensions: at least one extension point is required");
  }
  return { engineApiVersion, points: [...points], extensions: [] };
}

/**
 * 兼容规则：主版本必须相等；引擎次版本不得低于扩展要求的次版本；
 * 另外还要满足扩展自己声明的 engineRange。补丁号不参与兼容判定。
 */
export function checkExtensionCompatibility(
  engineApiVersion: string,
  descriptor: ExtensionDescriptor,
): { ok: true; mode: "exact" | "additive" } | { ok: false; issues: ExtensionIssue[] } {
  const issues: ExtensionIssue[] = [];
  const engine = parseSemver(engineApiVersion);
  const api = parseSemver(descriptor.apiVersion);
  if (engine === null) {
    issues.push(issue(descriptor.name, "invalid-engine-version", `bad engine API ${engineApiVersion}`));
  }
  if (api === null) {
    issues.push(issue(descriptor.name, "invalid-api-version", `bad extension API ${descriptor.apiVersion}`));
  }
  const rangeValid = isValidRange(descriptor.engineRange);
  if (!rangeValid) {
    issues.push(issue(descriptor.name, "invalid-engine-range", `bad range ${descriptor.engineRange}`));
  }
  if (engine !== null && api !== null) {
    if (engine.major !== api.major) {
      issues.push(
        issue(descriptor.name, "incompatible-major", `engine ${engine.major}.x vs extension ${api.major}.x`),
      );
    } else if (engine.minor < api.minor) {
      issues.push(
        issue(descriptor.name, "engine-too-old", `engine ${engineApiVersion} < extension ${descriptor.apiVersion}`),
      );
    }
  }
  if (engine !== null && rangeValid && !satisfiesRange(engineApiVersion, descriptor.engineRange)) {
    issues.push(
      issue(descriptor.name, "engine-range-mismatch", `engine ${engineApiVersion} outside ${descriptor.engineRange}`),
    );
  }
  if (issues.length > 0) return { ok: false, issues };
  return { ok: true, mode: compareSemver(engineApiVersion, descriptor.apiVersion) === 0 ? "exact" : "additive" };
}

export function registerExtension(
  registry: ExtensionRegistry,
  descriptor: ExtensionDescriptor,
): RegisterResult {
  const issues: ExtensionIssue[] = [];
  if (!NAME.test(descriptor.name)) {
    issues.push(issue(descriptor.name, "invalid-name", "name must be kebab-case"));
  }
  if (!registry.points.includes(descriptor.point)) {
    issues.push(issue(descriptor.name, "unknown-point", `point ${descriptor.point} is not open`));
  }
  if (descriptor.owner.trim() === "") {
    issues.push(issue(descriptor.name, "missing-owner", "owner is empty"));
  }
  const compatibility = checkExtensionCompatibility(registry.engineApiVersion, descriptor);
  if (!compatibility.ok) issues.push(...compatibility.issues);
  const blocked = [...new Set(descriptor.hooks)].filter((hook) =>
    forbiddenHooks(descriptor.point).includes(hook),
  );
  for (const hook of blocked.sort()) {
    issues.push(issue(descriptor.name, "forbidden-hook", `hook ${hook} crosses the plugin boundary`));
  }
  if (registry.extensions.some((item) => item.name === descriptor.name && item.point === descriptor.point)) {
    issues.push(issue(descriptor.name, "duplicate-extension", `already registered at ${descriptor.point}`));
  }
  if (issues.length > 0) return { ok: false, issues };
  const extensions = [...registry.extensions, descriptor].sort((a, b) =>
    a.point < b.point ? -1 : a.point > b.point ? 1 : a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
  );
  return { ok: true, registry: { ...registry, extensions } };
}

export function listExtensions(
  registry: ExtensionRegistry,
  point?: ExtensionPoint,
): readonly string[] {
  return registry.extensions
    .filter((item) => point === undefined || item.point === point)
    .map((item) => `${item.point}:${item.name}`)
    .sort();
}