《互联网产品的 AI 架构·平台化与治理》3.2 模型与提示版本的联动

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

import assert from "node:assert/strict";
import test from "node:test";

import {
  checkBump,
  classifyChanges,
  diffTriple,
  nextContractVersion,
  planRollback,
  validateRelease,
} from "../../src/gov/versions.ts";
import type { CapabilityRelease, ContractChange } from "../../src/gov/versions.ts";
import {
  migrationChecklist,
  planConvergence,
  planDeprecation,
  scanCallers,
  summarizeMatrix,
  windowPhase,
} from "../../src/gov/version-matrix.ts";
import type { CallerUsage, MatrixCell, VersionMatrix } from "../../src/gov/version-matrix.ts";

const contractChanges: ContractChange[] = [
  { surface: "input", kind: "field-add-optional", field: "traceId" },
  { surface: "input", kind: "field-add-required", field: "tenantId" },
  { surface: "input", kind: "field-remove", field: "locale" },
  { surface: "output", kind: "field-add-optional", field: "citations" },
  { surface: "output", kind: "field-remove", field: "debugRaw" },
  { surface: "error", kind: "error-add", field: "rate_limited" },
  { surface: "error", kind: "error-remove", field: "timeout" },
  { surface: "behavior", kind: "default-change", field: "temperature 0.2 -> 0.0" },
  { surface: "behavior", kind: "semantic-change", field: "summary includes citations" },
];

const releaseA: CapabilityRelease = {
  capability: "content.summarize",
  contractVersion: "3.1.1",
  model: "m-4.1",
  prompt: "p-2026-10-a",
  evalSet: "eval-7",
};

const releaseB: CapabilityRelease = { ...releaseA, prompt: "p-2026-10-b" };
const releaseC: CapabilityRelease = { ...releaseB, model: "m-4.2", evalSet: "eval-8" };
const releaseD: CapabilityRelease = { ...releaseB, model: "m-4.2", prompt: "p-2026-11-a", evalSet: "eval-8" };

test("contract changes split into compatible and breaking", () => {
  const report = classifyChanges(contractChanges);
  assert.equal(report.total, 9);
  assert.equal(report.compatible, 2);
  assert.equal(report.breaking, 7);
  assert.equal(report.requiredBump, "major");
  assert.equal(nextContractVersion("2.3.0", report), "3.0.0");
  assert.equal(checkBump(report, "minor").ok, false);
  assert.equal(checkBump(report, "major").ok, true);
});

test("compatible additions only need a minor bump", () => {
  const report = classifyChanges([
    { surface: "input", kind: "field-add-optional", field: "traceId" },
    { surface: "output", kind: "field-add-optional", field: "citations" },
    { surface: "behavior", kind: "docs-only", field: "examples" },
  ]);
  assert.equal(report.compatible, 3);
  assert.equal(report.breaking, 0);
  assert.equal(report.requiredBump, "minor");
  assert.equal(nextContractVersion("2.3.0", report), "2.4.0");
  assert.equal(checkBump(report, "minor").ok, true);
});

test("unknown change kinds are breaking", () => {
  const unknown = { surface: "input", kind: "rename-field", field: "query" } as unknown as ContractChange;
  const report = classifyChanges([unknown]);
  assert.equal(report.breaking, 1);
  assert.match(report.verdicts[0].reason, /未登记/);
});

test("release triples must be pinned", () => {
  assert.deepEqual(validateRelease(releaseA), []);
  const issues = validateRelease({ ...releaseA, model: "latest", prompt: "prod", evalSet: "eval-x" });
  assert.deepEqual(issues.map((issue) => issue.code), [
    "floating-model",
    "unpinned-prompt",
    "unpinned-eval-set",
  ]);
});

test("prompt-only change rolls back the prompt only", () => {
  const diff = diffTriple(releaseA, releaseB);
  assert.deepEqual(diff.changed, ["prompt"]);
  const plan = planRollback(releaseA, releaseB);
  assert.equal(plan.atomic, false);
  assert.match(plan.steps.join(" "), /把提示/);
  assert.doesNotMatch(plan.steps.join(" "), /把模型/);
});

test("model and prompt change roll back atomically", () => {
  const plan = planRollback(releaseB, releaseD);
  assert.deepEqual(plan.changed, ["model", "prompt", "evalSet"]);
  assert.equal(plan.atomic, true);
  assert.match(plan.steps.join(" "), /整体回切/);
  assert.match(plan.steps.join(" "), /保留评测集 eval-8/);
});

test("identical triples produce a no-op rollback", () => {
  const plan = planRollback(releaseA, { ...releaseA });
  assert.deepEqual(plan.changed, []);
  assert.equal(plan.atomic, false);
  assert.equal(plan.steps.length, 1);
});

test("rollback matrix classifies all eight change combinations", () => {
  const counts = { noop: 0, single: 0, multi: 0 };
  for (const model of ["m-4.1", "m-4.2"]) {
    for (const prompt of ["p-2026-10-a", "p-2026-10-b"]) {
      for (const evalSet of ["eval-7", "eval-8"]) {
        const plan = planRollback(releaseA, { ...releaseA, model, prompt, evalSet });
        if (plan.changed.length === 0) counts.noop += 1;
        else if (plan.changed.length === 1) counts.single += 1;
        else counts.multi += 1;
        const runtime = plan.changed.filter((component) => component !== "evalSet").length;
        assert.equal(plan.atomic, runtime > 1);
      }
    }
  }
  assert.deepEqual(counts, { noop: 1, single: 3, multi: 4 });
});

function buildMatrix(): VersionMatrix {
  const capabilities = [
    "content.summarize",
    "moderation.classify",
    "chat.reply",
    "search.rerank",
    "support.assist",
  ];
  const cells: MatrixCell[] = [];
  for (const capability of capabilities) {
    cells.push({ capability, model: "m-4.0", status: "retired" });
  }
  const m41: MatrixCell["status"][] = ["active", "active", "dual-run", "deprecated", "deprecated"];
  const m42: MatrixCell["status"][] = ["active", "active", "active", "dual-run", "dual-run"];
  capabilities.forEach((capability, index) => {
    cells.push({ capability, model: "m-4.1", status: m41[index] });
    cells.push({ capability, model: "m-4.2", status: m42[index] });
  });
  return { cells };
}

test("matrix summary counts every support status", () => {
  const summary = summarizeMatrix(buildMatrix());
  assert.equal(summary.total, 15);
  assert.equal(summary.capabilities, 5);
  assert.equal(summary.models, 3);
  assert.equal(summary.active, 5);
  assert.equal(summary["dual-run"], 3);
  assert.equal(summary.deprecated, 2);
  assert.equal(summary.retired, 5);
});

test("convergence assigns every closed cell an action", () => {
  const matrix = buildMatrix();
  const narrow = planConvergence(matrix, ["m-4.2"]);
  assert.equal(narrow.targetCells, 5);
  assert.equal(narrow.closedCells, 10);
  assert.equal(narrow.migrate.length, 3);
  assert.equal(narrow.forceOff.length, 2);
  assert.equal(narrow.alreadyRetired.length, 5);

  const wide = planConvergence(matrix, ["m-4.2", "m-4.1"]);
  assert.equal(wide.targetCells, 10);
  assert.equal(wide.closedCells, 5);
  assert.equal(wide.migrate.length, 0);
});

test("deprecation schedule is deterministic and phase boundaries are explicit", () => {
  const schedule = planDeprecation("2026-11-05", { announceDays: 14, dualRunDays: 30, forceOffDays: 7 });
  assert.deepEqual(schedule, {
    announce: "2026-11-05",
    dualRunStart: "2026-11-19",
    forceOffStart: "2026-12-19",
    offline: "2026-12-26",
    totalDays: 51,
  });
  assert.equal(windowPhase("2026-11-10", schedule), "announced");
  assert.equal(windowPhase("2026-11-19", schedule), "dual-running");
  assert.equal(windowPhase("2026-12-01", schedule), "dual-running");
  assert.equal(windowPhase("2026-12-19", schedule), "force-off");
  assert.equal(windowPhase("2026-12-26", schedule), "offline");
});

const usages: CallerUsage[] = [
  { team: "team-content", capability: "content.summarize", version: "3.1.1", lastSeenDaysAgo: 2 },
  { team: "team-content", capability: "content.summarize", version: "3.1.1", lastSeenDaysAgo: 5 },
  { team: "team-content", capability: "content.summarize", version: "2.3.0", lastSeenDaysAgo: 10 },
  { team: "team-content", capability: "content.summarize", version: "2.3.0", lastSeenDaysAgo: 45 },
  { team: "team-support", capability: "content.summarize", version: "3.1.1", lastSeenDaysAgo: 1 },
  { team: "team-support", capability: "content.summarize", version: "3.1.1", lastSeenDaysAgo: 3 },
  { team: "team-support", capability: "content.summarize", version: "3.0.0", lastSeenDaysAgo: 12 },
  { team: "team-trade", capability: "content.summarize", version: "3.1.1", lastSeenDaysAgo: 4 },
];

test("caller scan separates behind callers from silent ones", () => {
  const scan = scanCallers(usages, "content.summarize", "3.1.1");
  assert.equal(scan.total, 8);
  assert.equal(scan.onTarget, 5);
  assert.equal(scan.behind, 3);
  assert.equal(scan.stale, 1);
  assert.deepEqual(scan.behindTeams, ["team-content", "team-support"]);
  assert.equal(scan.readyToForceOff, false);

  const schedule = planDeprecation("2026-11-05", { announceDays: 14, dualRunDays: 30, forceOffDays: 7 });
  const checklist = migrationChecklist(scan, schedule);
  assert.equal(checklist.length, 4);
  assert.match(checklist.join(" "), /3 个调用方/);
  assert.match(checklist.join(" "), /1 个静默调用方/);
});

test("caller scan allows force-off only when nobody is behind", () => {
  const clean = scanCallers(
    usages.filter((usage) => usage.version === "3.1.1"),
    "content.summarize",
    "3.1.1",
  );
  assert.equal(clean.onTarget, 5);
  assert.equal(clean.behind, 0);
  assert.equal(clean.readyToForceOff, true);
  const schedule = planDeprecation("2026-11-05", { announceDays: 14, dualRunDays: 30, forceOffDays: 7 });
  assert.equal(migrationChecklist(clean, schedule).length, 3);
});