《互联网产品的 AI 架构·多能力编排与任务闭环》11.3 多团队共享能力目录

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

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

export type ChangeProcess = "patch-auto" | "minor-review" | "major-migration";

export interface CapabilitySlo {
  /** 成功返回可用结果的比例，分母是该版本的全部调用。 */
  availability: number; p95LatencyMs: number;
}

export interface CapabilityVersion {
  version: string;
  /** 契约必须与能力名和版本绑定，同一个版本不能换契约。 */
  contractRef: string;
  slo: CapabilitySlo; costMicrosPerCall: number;
  owner: string; changeProcess: ChangeProcess; deprecated?: boolean;
}

export interface CapabilityEntry { name: string; description: string; versions: readonly CapabilityVersion[] }
export interface CapabilityCatalog { entries: readonly CapabilityEntry[] }

export type CatalogIssueCode =
  | "invalid-name" | "duplicate-capability" | "no-versions" | "invalid-version"
  | "duplicate-version" | "missing-owner" | "invalid-slo" | "invalid-cost"
  | "invalid-change-process" | "contract-mismatch";

export interface CatalogIssue { capability: string; version?: string; code: CatalogIssueCode; detail: string }

const PROCESSES: readonly ChangeProcess[] = ["patch-auto", "minor-review", "major-migration"];
const PROCESS_RANK: Record<ChangeProcess, number> = {
  "patch-auto": 0, "minor-review": 1, "major-migration": 2,
};

function catalogIssue(
  capability: string,
  code: CatalogIssueCode,
  detail: string,
  version?: string,
): CatalogIssue {
  return version === undefined ? { capability, code, detail } : { capability, version, code, detail };
}

export function validateCatalog(catalog: CapabilityCatalog): CatalogIssue[] {
  const issues: CatalogIssue[] = [];
  const names = new Set<string>();
  for (const entry of catalog.entries) {
    if (entry.name.trim() === "") issues.push(catalogIssue(entry.name, "invalid-name", "name is empty"));
    if (names.has(entry.name)) issues.push(catalogIssue(entry.name, "duplicate-capability", "appears twice"));
    names.add(entry.name);
    if (entry.versions.length === 0) issues.push(catalogIssue(entry.name, "no-versions", "no versions"));
    const versions = new Set<string>();
    for (const version of entry.versions) {
      const label = `${entry.name}@${version.version}`;
      if (parseSemver(version.version) === null) {
        issues.push(catalogIssue(entry.name, "invalid-version", `bad ${version.version}`, version.version));
      }
      if (versions.has(version.version)) {
        issues.push(catalogIssue(entry.name, "duplicate-version", `duplicate ${version.version}`, version.version));
      }
      versions.add(version.version);
      if (version.owner.trim() === "") {
        issues.push(catalogIssue(entry.name, "missing-owner", `no owner for ${label}`, version.version));
      }
      if (!(version.slo.availability > 0 && version.slo.availability <= 1)) {
        issues.push(catalogIssue(entry.name, "invalid-slo", `availability ${version.slo.availability}`, version.version));
      }
      if (!(version.slo.p95LatencyMs > 0)) {
        issues.push(catalogIssue(entry.name, "invalid-slo", `p95 ${version.slo.p95LatencyMs}`, version.version));
      }
      if (!Number.isInteger(version.costMicrosPerCall) || version.costMicrosPerCall < 0) {
        issues.push(catalogIssue(entry.name, "invalid-cost", `cost ${version.costMicrosPerCall}`, version.version));
      }
      if (!PROCESSES.includes(version.changeProcess)) {
        issues.push(catalogIssue(entry.name, "invalid-change-process", `process ${version.changeProcess}`, version.version));
      }
      if (version.contractRef !== `contract:${entry.name}@${version.version}`) {
        issues.push(catalogIssue(entry.name, "contract-mismatch", `expected contract:${entry.name}@${version.version}`, version.version));
      }
    }
  }
  return issues;
}

function selectVersion(entry: CapabilityEntry, includeDeprecated: boolean): CapabilityVersion | undefined {
  return entry.versions
    .filter((version) => includeDeprecated || !version.deprecated)
    .slice()
    .sort((a, b) => compareSemver(b.version, a.version))[0];
}

export interface CatalogQuery {
  capability?: string; owner?: string; maxCostMicros?: number;
  minAvailability?: number; includeDeprecated?: boolean;
}

export interface CatalogHit {
  capability: string; version: string; owner: string; contractRef: string;
  costMicrosPerCall: number; p95LatencyMs: number; availability: number; deprecated: boolean;
}

export function queryCatalog(catalog: CapabilityCatalog, query: CatalogQuery = {}): CatalogHit[] {
  const hits: CatalogHit[] = [];
  for (const entry of catalog.entries) {
    if (query.capability !== undefined && entry.name !== query.capability) continue;
    const version = selectVersion(entry, query.includeDeprecated ?? false);
    if (version === undefined) continue;
    if (query.owner !== undefined && version.owner !== query.owner) continue;
    if (query.maxCostMicros !== undefined && version.costMicrosPerCall > query.maxCostMicros) continue;
    if (query.minAvailability !== undefined && version.slo.availability < query.minAvailability) continue;
    hits.push({
      capability: entry.name, version: version.version, owner: version.owner,
      contractRef: version.contractRef, costMicrosPerCall: version.costMicrosPerCall,
      p95LatencyMs: version.slo.p95LatencyMs, availability: version.slo.availability,
      deprecated: version.deprecated ?? false,
    });
  }
  return hits.sort((a, b) => (a.capability < b.capability ? -1 : a.capability > b.capability ? 1 : 0));
}

export type ResolveFailure = "unknown-capability" | "invalid-range" | "no-match" | "deprecated-only";

export type ResolveResult =
  | { ok: true; capability: string; requested: string; version: string; pinned: boolean }
  | { ok: false; capability: string; requested: string; reason: ResolveFailure };

/** 精确版本可以选中已弃用版本；范围选择默认跳过弃用版本。 */
export function resolveVersion(catalog: CapabilityCatalog, capability: string, constraint: string): ResolveResult {
  const entry = catalog.entries.find((item) => item.name === capability);
  if (entry === undefined) return { ok: false, capability, requested: constraint, reason: "unknown-capability" };
  if (!isValidRange(constraint)) return { ok: false, capability, requested: constraint, reason: "invalid-range" };
  const pinned = parseSemver(constraint) !== null;
  const matches = entry.versions
    .filter((version) => (pinned || !version.deprecated) && satisfiesRange(version.version, constraint))
    .sort((a, b) => compareSemver(b.version, a.version));
  if (matches.length === 0) {
    const deprecated = entry.versions.some(
      (version) => version.deprecated && satisfiesRange(version.version, constraint),
    );
    return { ok: false, capability, requested: constraint, reason: deprecated ? "deprecated-only" : "no-match" };
  }
  return { ok: true, capability, requested: constraint, version: matches[0].version, pinned };
}

export type CatalogAction = "publish" | "upgrade" | "deprecate";

export interface OwnerDecision {
  ok: boolean; capability: string; version: string; actor: string; owner: string;
  action: CatalogAction; reason?: "invalid-actor" | "unknown-capability" | "unknown-version" | "actor-not-owner";
}

export function checkOwner(
  catalog: CapabilityCatalog, capability: string, version: string, actor: string, action: CatalogAction,
): OwnerDecision {
  const entry = catalog.entries.find((item) => item.name === capability);
  if (entry === undefined) return { ok: false, capability, version, actor, owner: "", action, reason: "unknown-capability" };
  const target = entry.versions.find((item) => item.version === version);
  if (target === undefined) return { ok: false, capability, version, actor, owner: "", action, reason: "unknown-version" };
  if (actor.trim() === "") return { ok: false, capability, version, actor, owner: target.owner, action, reason: "invalid-actor" };
  if (actor !== target.owner) return { ok: false, capability, version, actor, owner: target.owner, action, reason: "actor-not-owner" };
  return { ok: true, capability, version, actor, owner: target.owner, action };
}

export type UpgradeFailure =
  | "unknown-capability" | "unknown-version" | "not-forward"
  | "actor-not-owner" | "process-too-weak";

export interface UpgradePlan {
  capability: string; from: string; to: string; fromOwner: string; toOwner: string;
  changeProcess: ChangeProcess; approvals: string[]; steps: string[];
}

export type UpgradeResult =
  | { ok: true; plan: UpgradePlan }
  | { ok: false; capability: string; from: string; to: string; reason: UpgradeFailure };

function requiredProcess(from: string, to: string): ChangeProcess {
  const a = parseSemver(from)!;
  const b = parseSemver(to)!;
  if (a.major !== b.major) return "major-migration";
  if (a.minor !== b.minor) return "minor-review";
  return "patch-auto";
}

/** 升级由目标版本的所有者发起；跨所有者大版本还需要原所有者与平台评审。 */
export function planUpgrade(
  catalog: CapabilityCatalog, capability: string, from: string, to: string, actor: string,
): UpgradeResult {
  const entry = catalog.entries.find((item) => item.name === capability);
  if (entry === undefined) return { ok: false, capability, from, to, reason: "unknown-capability" };
  const source = entry.versions.find((item) => item.version === from);
  const target = entry.versions.find((item) => item.version === to);
  if (source === undefined || target === undefined) {
    return { ok: false, capability, from, to, reason: "unknown-version" };
  }
  if (compareSemver(to, from) <= 0) return { ok: false, capability, from, to, reason: "not-forward" };
  if (actor !== target.owner) return { ok: false, capability, from, to, reason: "actor-not-owner" };
  const required = requiredProcess(from, to);
  if (PROCESS_RANK[target.changeProcess] < PROCESS_RANK[required]) {
    return { ok: false, capability, from, to, reason: "process-too-weak" };
  }
  const approvals = [...new Set([
    target.owner, source.owner, ...(required === "patch-auto" ? [] : ["platform-review"]),
  ])];
  return {
    ok: true,
    plan: {
      capability, from, to, fromOwner: source.owner, toOwner: target.owner,
      changeProcess: required, approvals,
      steps: [
        `发布 ${target.contractRef}，冻结 ${source.contractRef}`,
        `通知钉在 ${from} 的调用方，给出迁移窗口`,
        `按 10%→50%→100% 灰度，逐档核对 SLO 与成本`,
        `把 ${from} 标记为 deprecated，保留窗口后下线`,
      ],
    },
  };
}