《互联网产品的 AI 架构·平台化与治理》3.1 契约版本与兼容规则

// file: src/gov/versions.ts
// tier: L2
// verify: node --test test/gov/versions.test.ts

import { parseSemver } from "../orch/platform.ts";

export type ChangeSurface = "input" | "output" | "error" | "behavior";
export type ChangeKind =
  | "field-add-optional"
  | "field-add-required"
  | "field-remove"
  | "enum-add"
  | "enum-remove"
  | "error-add"
  | "error-remove"
  | "default-change"
  | "semantic-change"
  | "docs-only";

export interface ContractChange {
  surface: ChangeSurface;
  kind: ChangeKind;
  field: string;
  detail?: string;
}

export type Compatibility = "compatible" | "breaking";

export interface ChangeVerdict {
  change: ContractChange;
  compatibility: Compatibility;
  reason: string;
}

const RULES: Record<string, readonly [Compatibility, string]> = {
  "input:field-add-optional": ["compatible", "新增可选输入字段，旧调用方不传也能运行"],
  "input:field-add-required": ["breaking", "新增必填输入字段，旧调用方会缺参数"],
  "input:field-remove": ["breaking", "删除输入字段，旧调用方的参数被忽略或拒绝"],
  "input:enum-add": ["compatible", "输入枚举新增取值，旧调用方不会主动发送"],
  "input:enum-remove": ["breaking", "输入枚举删除取值，旧调用方可能仍在发送"],
  "output:field-add-optional": ["compatible", "新增可选输出字段，宽容解析的调用方不受影响"],
  "output:field-add-required": ["breaking", "输出新增必填字段，严格解析的调用方会失败"],
  "output:field-remove": ["breaking", "删除输出字段，依赖该字段的调用方会读到空值"],
  "output:enum-add": ["breaking", "输出枚举新增取值，穷举分支的调用方没有默认路径"],
  "output:enum-remove": ["breaking", "输出枚举删除取值，调用方可能仍在匹配"],
  "error:error-add": ["breaking", "新增错误码，调用方可能没有对应的处理分支"],
  "error:error-remove": ["breaking", "删除错误码，依赖该码的补偿逻辑会失效"],
  "behavior:default-change": ["breaking", "默认值变化会改变同一请求的结果"],
  "behavior:semantic-change": ["breaking", "语义变化无法从 schema 看出来，只能靠契约声明"],
  "behavior:docs-only": ["compatible", "只改文档，不改变运行时行为"],
  "input:docs-only": ["compatible", "只改文档，不改变运行时行为"],
  "output:docs-only": ["compatible", "只改文档，不改变运行时行为"],
  "error:docs-only": ["compatible", "只改文档，不改变运行时行为"],
};

/** 未知变更按不兼容处理：治理规则宁可误报，也不让未分类变化静默上线。 */
export function classifyChange(change: ContractChange): ChangeVerdict {
  const hit = RULES[`${change.surface}:${change.kind}`];
  if (hit === undefined) {
    return { change, compatibility: "breaking", reason: "未登记的变更类型，按不兼容处理" };
  }
  return { change, compatibility: hit[0], reason: hit[1] };
}

export interface CompatibilityReport {
  total: number;
  compatible: number;
  breaking: number;
  requiredBump: "major" | "minor" | "patch";
  verdicts: ChangeVerdict[];
}

export function classifyChanges(changes: readonly ContractChange[]): CompatibilityReport {
  const verdicts = changes.map(classifyChange);
  const breaking = verdicts.filter((verdict) => verdict.compatibility === "breaking").length;
  const requiredBump = breaking > 0 ? "major" : changes.length > 0 ? "minor" : "patch";
  return { total: changes.length, compatible: changes.length - breaking, breaking, requiredBump, verdicts };
}

export function nextContractVersion(current: string, report: CompatibilityReport): string {
  const version = parseSemver(current);
  if (version === null) throw new Error(`versions: invalid current version ${current}`);
  if (report.requiredBump === "major") return `${version.major + 1}.0.0`;
  if (report.requiredBump === "minor") return `${version.major}.${version.minor + 1}.0`;
  return current;
}

export type DeclaredBump = "major" | "minor" | "patch";
export interface BumpDecision { ok: boolean; required: DeclaredBump; declared: DeclaredBump; reason: string }

const BUMP_RANK: Record<DeclaredBump, number> = { patch: 0, minor: 1, major: 2 };

export function checkBump(report: CompatibilityReport, declared: DeclaredBump): BumpDecision {
  const ok = BUMP_RANK[declared] >= BUMP_RANK[report.requiredBump];
  const reason = ok
    ? `声明的 ${declared} 覆盖了 ${report.requiredBump} 要求`
    : `${report.breaking} 个不兼容变更要求 ${report.requiredBump}`;
  return { ok, required: report.requiredBump, declared, reason };
}

export interface CapabilityTriple {
  model: string;
  prompt: string;
  evalSet: string;
}

export interface CapabilityRelease extends CapabilityTriple {
  capability: string;
  contractVersion: string;
}

export type TripleComponent = "model" | "prompt" | "evalSet";
export const TRIPLE_COMPONENTS: readonly TripleComponent[] = ["model", "prompt", "evalSet"];

export function releaseId(release: CapabilityRelease): string {
  return `${release.capability}@${release.contractVersion}[${release.model}/${release.prompt}/${release.evalSet}]`;
}

export type TripleIssueCode =
  | "empty-component"
  | "floating-model"
  | "unpinned-prompt"
  | "unpinned-eval-set";

export interface TripleIssue { capability: string; component: TripleComponent; code: TripleIssueCode; detail: string }

const PROMPT_ID = /^p-\d{4}-\d{2}-[a-z0-9]+$/;
const EVAL_SET_ID = /^eval-\d+$/;

/** 三元组是行为的版本，不允许浮动别名；任何一项变化都必须生成新的 release。 */
export function validateRelease(release: CapabilityRelease): TripleIssue[] {
  const issues: TripleIssue[] = [];
  for (const component of TRIPLE_COMPONENTS) {
    if (release[component].trim() === "") {
      issues.push({ capability: release.capability, component, code: "empty-component", detail: `${component} is empty` });
    }
  }
  if (/latest|\*|^auto$/i.test(release.model)) {
    issues.push({ capability: release.capability, component: "model", code: "floating-model", detail: `model ${release.model} is not pinned` });
  }
  if (!PROMPT_ID.test(release.prompt)) {
    issues.push({ capability: release.capability, component: "prompt", code: "unpinned-prompt", detail: `prompt ${release.prompt} is not a released prompt id` });
  }
  if (!EVAL_SET_ID.test(release.evalSet)) {
    issues.push({ capability: release.capability, component: "evalSet", code: "unpinned-eval-set", detail: `evalSet ${release.evalSet} is not a released eval id` });
  }
  return issues;
}

export interface TripleDiff { from: string; to: string; changed: TripleComponent[]; same: boolean }

export function diffTriple(from: CapabilityRelease, to: CapabilityRelease): TripleDiff {
  const changed = TRIPLE_COMPONENTS.filter((component) => from[component] !== to[component]);
  return { from: releaseId(from), to: releaseId(to), changed, same: changed.length === 0 };
}

export interface RollbackPlan { from: string; to: string; changed: TripleComponent[]; atomic: boolean; steps: string[] }

const RUNTIME_COMPONENT: Record<TripleComponent, boolean> = {
  model: true,
  prompt: true,
  evalSet: false,
};

/**
 * 一个能力版本是原子的：模型与提示同时变化时不能只回滚其中一个。
 * 评测集只影响判定基线，不承载线上流量。
 */
export function planRollback(from: CapabilityRelease, to: CapabilityRelease): RollbackPlan {
  const diff = diffTriple(from, to);
  const runtime = diff.changed.filter((component) => RUNTIME_COMPONENT[component]);
  const atomic = runtime.length > 1;
  const steps: string[] = [];
  if (diff.same) {
    steps.push("版本三元组一致，无需回滚");
  } else {
    if (diff.changed.includes("evalSet")) {
      steps.push(`保留评测集 ${to.evalSet}，重置对比基线，不切换线上流量`);
    }
    if (atomic) {
      steps.push(`冻结 ${releaseId(to)}，把模型与提示作为一个能力版本整体回切`);
      steps.push(`回切到 ${from.model} + ${from.prompt}，用 ${from.evalSet} 重跑回归`);
    } else {
      if (diff.changed.includes("model")) {
        steps.push(`把模型从 ${to.model} 切回 ${from.model}，提示保持 ${to.prompt}`);
      }
      if (diff.changed.includes("prompt")) {
        steps.push(`把提示从 ${to.prompt} 切回 ${from.prompt}，模型保持 ${to.model}`);
      }
    }
    steps.push("按 10%→50%→100% 回撤灰度，逐档核对成功率与成本");
  }
  return { from: diff.from, to: diff.to, changed: diff.changed, atomic, steps };
}