@kungfu-tech/buildchain 4.0.2-alpha.8 → 4.0.2

package/scripts/generate-v4-universal-workflow-facades.mjs

@@ -0,0 +1,458 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import crypto from "node:crypto";
+import { currentWorkflowPath, writeWorkflowSource, rewriteRepositoryWorkflowPaths } from "./workflow-taxonomy.mjs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const contractPath = path.join(
+  root,
+  "architecture/v4-universal-workflow-bootstrap.json",
+);
+const contract = JSON.parse(fs.readFileSync(contractPath, "utf8"));
+const laneBudgetPath = path.join(
+  root,
+  "architecture/ci-lane-change-budget.json",
+);
+const recoveryTemplatePath = path.join(
+  root,
+  contract.bootstrap.consumerRecoveryTemplate,
+);
+const recoveryWorkflowPath = path.join(
+  root,
+  contract.bootstrap.consumerRecoveryWorkflow,
+);
+const universalInput = `      universal-request-json:
+        description: "Versioned exact-candidate request envelope; empty preserves the compatibility path"
+        default: ""
+        required: false
+        type: string
+`;
+const bootstrapJob = `  universal-bootstrap:
+    name: Universal exact-candidate execution
+    if: \${{ inputs.universal-request-json != '' }}
+    uses: ./.github/workflows/bootstrap.yml
+    with:
+      request-json: \${{ inputs.universal-request-json }}
+
+`;
+
+function fail(message) {
+  throw new Error(message);
+}
+
+function activeFacadePaths() {
+  const retired = new Set(contract.retiredWorkflowSurfaces || []);
+  return contract.inventoryWorkflows.filter(
+    (relative) =>
+      relative !== contract.bootstrap.publicWorkflow &&
+      relative !== contract.bootstrap.consumerRecoveryWorkflow &&
+      !retired.has(relative),
+  );
+}
+
+function sourceRevision() {
+  const revision = contract.migration.facadeSourceRevision;
+  if (!/^[0-9a-f]{40}$/u.test(revision || ""))
+    fail("migration.facadeSourceRevision must be an exact commit");
+  return revision;
+}
+
+function materializeSourceRevision() {
+  const revision = sourceRevision();
+  try {
+    execFileSync("git", ["cat-file", "-e", `${revision}^{commit}`], {
+      cwd: root,
+      stdio: "ignore",
+    });
+    return;
+  } catch {}
+  try {
+    execFileSync(
+      "git",
+      ["fetch", "--no-tags", "--depth=1", "origin", revision],
+      { cwd: root, stdio: "pipe" },
+    );
+    execFileSync("git", ["cat-file", "-e", `${revision}^{commit}`], {
+      cwd: root,
+      stdio: "ignore",
+    });
+  } catch (error) {
+    const detail = String(error?.stderr || error?.message || error).trim();
+    fail(
+      `facade source revision ${revision} is unavailable and could not be hydrated from origin${detail ? `: ${detail}` : ""}`,
+    );
+  }
+}
+
+function frozenFacadeSource(relative) {
+  return execFileSync("git", ["show", `${sourceRevision()}:${relative}`], {
+    cwd: root,
+    encoding: "utf8",
+  });
+}
+
+const mutableFacades = new Set([
+  ...(contract.migration.channelGeneratedFacades || []),
+  ".github/workflows/dev-pr-auto-merge.yml",
+]);
+
+function isMutableFacade(relative) {
+  return mutableFacades.has(relative);
+}
+
+function addUniversalInput(source, relative) {
+  if (source.includes("      universal-request-json:\n")) return source;
+  const workflowCall = source.match(/^(\s*)workflow_call:\s*$/mu);
+  if (!workflowCall) fail(`${relative} has no workflow_call mapping`);
+  const callIndent = workflowCall[1];
+  const inputHeader = `${callIndent}  inputs:\n`;
+  const callEnd = workflowCall.index + workflowCall[0].length;
+  if (source.slice(callEnd + 1).startsWith(inputHeader)) {
+    const insertion = callEnd + 1 + inputHeader.length;
+    return `${source.slice(0, insertion)}${universalInput}${source.slice(insertion)}`;
+  }
+  return `${source.slice(0, callEnd + 1)}\n${inputHeader}${universalInput}${source.slice(callEnd + 1)}`;
+}
+
+function conditionExpression(source, relative, jobId) {
+  const child = source.match(/^(\s+)[A-Za-z0-9_-]+:/mu);
+  const indent = child?.[1] || "    ";
+  const match = source.match(new RegExp(`^${indent}if:\\s*(.*)$`, "mu"));
+  if (!match)
+    return `${indent}if: \${{ inputs.universal-request-json == '' }}\n`;
+  const suffix = match[1].trim();
+  if (suffix === ">-" || suffix === "|") {
+    const start = match.index + match[0].length + 1;
+    const tail = source.slice(start);
+    const endMatch = tail.match(/^    [A-Za-z0-9_-]+:/mu);
+    const end = endMatch ? start + endMatch.index : source.length;
+    const raw = source.slice(start, end).trim();
+    const inner = raw
+      .replace(/^\$\{\{\s*/u, "")
+      .replace(/\s*\}\}$/u, "")
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .join("\n          ");
+    if (!inner) fail(`${relative}#${jobId} has an empty multiline if`);
+    return {
+      start: match.index,
+      end,
+      value: `${indent}if: >-\n${indent}  \${{\n${indent}    inputs.universal-request-json == '' &&\n${indent}    (\n${indent}      ${inner}\n${indent}    )\n${indent}  }}\n`,
+    };
+  }
+  const inner = suffix.startsWith("${{")
+    ? suffix.replace(/^\$\{\{\s*/u, "").replace(/\s*\}\}$/u, "")
+    : suffix;
+  return {
+    start: match.index,
+    end:
+      match.index +
+      match[0].length +
+      (source[match.index + match[0].length] === "\n" ? 1 : 0),
+    value: `${indent}if: \${{ inputs.universal-request-json == '' && (${inner}) }}\n`,
+  };
+}
+
+function guardCompatibilityJobs(source, relative) {
+  const jobs = source.match(/^jobs:\s*$/mu);
+  if (!jobs) fail(`${relative} has no jobs mapping`);
+  const bodyStart = jobs.index + jobs[0].length + 1;
+  const body = source.slice(bodyStart);
+  const headers = [...body.matchAll(/^  ([A-Za-z0-9_-]+):\s*$/gmu)];
+  if (headers.length === 0) fail(`${relative} has no jobs`);
+  let rewritten = body;
+  for (let index = headers.length - 1; index >= 0; index -= 1) {
+    const header = headers[index];
+    if (header[1] === "universal-bootstrap") continue;
+    const start = header.index + header[0].length + 1;
+    const end = headers[index + 1]?.index ?? body.length;
+    const job = body.slice(start, end);
+    if (job.includes("inputs.universal-request-json == ''")) continue;
+    const condition = conditionExpression(job, relative, header[1]);
+    if (typeof condition === "string") {
+      rewritten = `${rewritten.slice(0, start)}${condition}${rewritten.slice(start)}`;
+    } else {
+      rewritten = `${rewritten.slice(0, start + condition.start)}${condition.value}${rewritten.slice(start + condition.end)}`;
+    }
+  }
+  const withGuards = `${source.slice(0, bodyStart)}${rewritten}`;
+  return withGuards.includes("  universal-bootstrap:\n")
+    ? withGuards
+    : `${withGuards.slice(0, bodyStart)}${bootstrapJob}${withGuards.slice(bodyStart)}`;
+}
+
+function addRuntimeBootstrapDependencies(source, relative) {
+  if (
+    relative !== ".github/workflows/.build.yml" ||
+    source.includes(
+      ".buildchain/workflow-shell/scripts/github-output.mjs\n",
+    )
+  )
+    return source;
+  const anchor =
+    "            .buildchain/workflow-shell/scripts/build-contract-core.mjs\n";
+  return source.replace(
+    anchor,
+    `${anchor}            .buildchain/workflow-shell/scripts/github-output.mjs\n`,
+  );
+}
+
+function applyPublicationFacadePatches(source, relative) {
+  const document = JSON.parse(fs.readFileSync(path.join(root,
+    "architecture/v4-publication-facade-patches.json"), "utf8"));
+  const patch = document.facades.find(entry => entry.workflow === relative);
+  if (!patch) return source;
+  const digest = value => crypto.createHash("sha256").update(value).digest("hex");
+  if (digest(source) === patch.afterSha256) return source;
+  if (digest(source) !== patch.beforeSha256) fail(`${relative}: publication facade source drift`);
+  for (const { before, after } of patch.replacements) {
+    if (source.split(before).length !== 2) fail(`${relative}: ambiguous publication patch`);
+    source = source.replace(before, () => after);
+  }
+  if (digest(source) !== patch.afterSha256) fail(`${relative}: publication facade result drift`);
+  return source;
+}
+
+export function migrateV4UniversalWorkflowFacade(source, relative) {
+  return rewriteRepositoryWorkflowPaths(root, applyPublicationFacadePatches(guardCompatibilityJobs(
+    addUniversalInput(addRuntimeBootstrapDependencies(source, relative), relative),
+    relative,
+  ), relative));
+}
+
+function verify(source, relative) {
+  for (const snippet of [
+    "      universal-request-json:\n",
+    "  universal-bootstrap:\n",
+    "uses: ./.github/workflows/bootstrap.yml",
+  ]) {
+    if (!source.includes(snippet))
+      fail(`${relative} is missing ${snippet.trim()}`);
+  }
+  const jobs = source.slice(source.search(/^jobs:\s*$/mu));
+  const headers = [...jobs.matchAll(/^  ([A-Za-z0-9_-]+):\s*$/gmu)];
+  for (let index = 0; index < headers.length; index += 1) {
+    const header = headers[index];
+    if (header[1] === "universal-bootstrap") continue;
+    const end = headers[index + 1]?.index ?? jobs.length;
+    const block = jobs.slice(header.index, end);
+    if (!block.includes("inputs.universal-request-json == ''"))
+      fail(`${relative}#${header[1]} can overlap universal execution`);
+  }
+  if (!isMutableFacade(relative)) {
+    const expected = migrateV4UniversalWorkflowFacade(
+      frozenFacadeSource(relative),
+      relative,
+    );
+    if (source !== expected)
+      fail(
+        `${relative} differs from the exact generated facade rooted at ${sourceRevision()}`,
+      );
+  }
+}
+
+function laneBudget({ laneId, authorityClass, triggerClass, minutes, metric }) {
+  return {
+    laneId,
+    authorityClass,
+    triggerClass,
+    concurrencyPolicy: { mode: "none", cancelInProgress: false },
+    expectedRunnerMinutes: minutes,
+    cancellationBehavior: "finish-started",
+    sloImpact: {
+      mergeCritical: false,
+      metric,
+      expectedContributionSeconds: 0,
+      rationale:
+        "The opt-in universal path preserves the default compatibility lane and executes only an exact admitted runtime.",
+    },
+  };
+}
+
+function updateLaneBudgets() {
+  const policy = JSON.parse(fs.readFileSync(laneBudgetPath, "utf8"));
+  const mixed = new Set([
+    ".github/workflows/release-governance-reconcile.yml",
+    ".github/workflows/v4-adopter-delivery.yml",
+  ]);
+  const facadeLanes = activeFacadePaths().map(
+    (relative) => `${relative}#universal-bootstrap`,
+  );
+  policy.declarationFamilies = [
+    {
+      ...laneBudget({
+        laneId: "",
+        authorityClass: "governed-delegation",
+        triggerClass: "reusable",
+        minutes: 60,
+        metric: "opt-in exact-candidate execution latency",
+      }),
+      laneIds: facadeLanes.filter(
+        (laneId) => !mixed.has(laneId.split("#", 1)[0]),
+      ),
+    },
+    {
+      ...laneBudget({
+        laneId: "",
+        authorityClass: "governed-delegation",
+        triggerClass: "mixed",
+        minutes: 60,
+        metric: "mixed-trigger exact-candidate execution latency",
+      }),
+      laneIds: facadeLanes.filter((laneId) =>
+        mixed.has(laneId.split("#", 1)[0]),
+      ),
+    },
+  ].map(({ laneId: _laneId, ...family }) => family);
+  const universalLaneIds = new Set([
+    ".github/workflows/bootstrap.yml#admit",
+    ".github/workflows/bootstrap.yml#execute",
+    ".github/workflows/bootstrap.yml#settle",
+    ".github/workflows/universal-bootstrap-recovery.yml#recovery-admit",
+    ".github/workflows/universal-bootstrap-recovery.yml#recovery-execute",
+    ".github/workflows/universal-bootstrap-recovery.yml#recovery-settle",
+    ".github/workflows/universal-bootstrap-dogfood.yml#public-bootstrap",
+    ".github/workflows/universal-bootstrap-dogfood.yml#prepare",
+    ".github/workflows/universal-bootstrap-dogfood.yml#primary-conformance",
+    ".github/workflows/universal-bootstrap-dogfood.yml#recovery-conformance",
+    ".github/workflows/universal-bootstrap-dogfood.yml#primary-alpha",
+    ".github/workflows/universal-bootstrap-dogfood.yml#recovery-alpha",
+    ".github/workflows/universal-bootstrap-dogfood.yml#primary-stable",
+    ".github/workflows/universal-bootstrap-dogfood.yml#recovery-stable",
+    ".github/workflows/universal-bootstrap-dogfood.yml#reconcile",
+  ]);
+  policy.declarations = policy.declarations.filter(
+    ({ laneId }) => !universalLaneIds.has(laneId),
+  );
+  policy.declarations.push(
+    laneBudget({
+      laneId: ".github/workflows/bootstrap.yml#admit",
+      authorityClass: "evidence",
+      triggerClass: "reusable",
+      minutes: 10,
+      metric: "exact-candidate admission latency",
+    }),
+    laneBudget({
+      laneId: ".github/workflows/bootstrap.yml#execute",
+      authorityClass: "governed-delegation",
+      triggerClass: "reusable",
+      minutes: 60,
+      metric: "exact-candidate execution latency",
+    }),
+    laneBudget({
+      laneId: ".github/workflows/bootstrap.yml#settle",
+      authorityClass: "evidence",
+      triggerClass: "reusable",
+      minutes: 10,
+      metric: "universal terminal settlement latency",
+    }),
+    laneBudget({
+      laneId:
+        ".github/workflows/universal-bootstrap-recovery.yml#recovery-admit",
+      authorityClass: "evidence",
+      triggerClass: "reusable",
+      minutes: 10,
+      metric: "consumer-owned exact-candidate admission latency",
+    }),
+    laneBudget({
+      laneId:
+        ".github/workflows/universal-bootstrap-recovery.yml#recovery-execute",
+      authorityClass: "governed-delegation",
+      triggerClass: "reusable",
+      minutes: 60,
+      metric: "consumer-owned exact-candidate execution latency",
+    }),
+    laneBudget({
+      laneId:
+        ".github/workflows/universal-bootstrap-recovery.yml#recovery-settle",
+      authorityClass: "evidence",
+      triggerClass: "reusable",
+      minutes: 10,
+      metric: "consumer-owned terminal settlement latency",
+    }),
+    laneBudget({
+      laneId: ".github/workflows/universal-bootstrap-dogfood.yml#prepare",
+      authorityClass: "evidence",
+      triggerClass: "mixed",
+      minutes: 10,
+      metric: "Train-first self-dogfood admission latency",
+    }),
+    ...[
+      "primary-conformance",
+      "recovery-conformance",
+      "primary-alpha",
+      "recovery-alpha",
+      "primary-stable",
+      "recovery-stable",
+    ].map((job) =>
+      laneBudget({
+        laneId: `.github/workflows/universal-bootstrap-dogfood.yml#${job}`,
+        authorityClass: "governed-delegation",
+        triggerClass: "mixed",
+        minutes: 60,
+        metric: "Train-first exact-candidate self-dogfood latency",
+      }),
+    ),
+    laneBudget({
+      laneId: ".github/workflows/universal-bootstrap-dogfood.yml#reconcile",
+      authorityClass: "evidence",
+      triggerClass: "mixed",
+      minutes: 10,
+      metric: "primary and recovery equivalence latency",
+    }),
+  );
+  fs.writeFileSync(laneBudgetPath, `${JSON.stringify(policy, null, 2)}\n`);
+}
+
+function main() {
+  const check = process.argv.includes("--check");
+  const fresh = process.argv.includes("--fresh");
+  materializeSourceRevision();
+  if (check) {
+    if (
+      fs.readFileSync(recoveryWorkflowPath, "utf8") !==
+      fs.readFileSync(recoveryTemplatePath, "utf8")
+    )
+      fail(
+        "consumer recovery workflow differs from its pre-positioned template",
+      );
+  } else {
+    writeWorkflowSource(
+      root, path.relative(root, recoveryWorkflowPath),
+      fs.readFileSync(recoveryTemplatePath, "utf8"),
+    );
+  }
+  for (const relative of activeFacadePaths()) {
+    const current = currentWorkflowPath(root, relative);
+    const target = path.join(root, current);
+    const source = fresh
+      ? frozenFacadeSource(relative)
+      : fs.readFileSync(target, "utf8");
+    if (check) verify(source, relative);
+    else
+      writeWorkflowSource(
+        root, current,
+        migrateV4UniversalWorkflowFacade(source, relative),
+      );
+  }
+  if (!check) {
+    contract.bootstrapGovernedWorkflows = [
+      contract.bootstrap.publicWorkflow,
+      ...activeFacadePaths(),
+    ].sort();
+    contract.migration.compatibilityFacades = "generated-dual-path";
+    fs.writeFileSync(contractPath, `${JSON.stringify(contract, null, 2)}\n`);
+    updateLaneBudgets();
+    process.stdout.write(
+      `${JSON.stringify({ migrated: activeFacadePaths().length })}\n`,
+    );
+  }
+}
+
+const isMain =
+  process.argv[1] &&
+  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) main();

package/scripts/generate-workflow-taxonomy.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import {
+  readWorkflowTaxonomy,
+  renderWorkflowCatalog,
+  TAXONOMY_DOC,
+  workflowPath,
+  writeWorkflowSource,
+} from "./workflow-taxonomy.mjs";
+
+const root = process.cwd();
+const policy = readWorkflowTaxonomy(root);
+if (!policy) throw new Error("workflow taxonomy is missing");
+for (const entry of policy.entries) {
+  writeWorkflowSource(
+    root,
+    workflowPath(entry),
+    fs.readFileSync(path.join(root, workflowPath(entry)), "utf8"),
+  );
+}
+fs.writeFileSync(path.join(root, TAXONOMY_DOC), renderWorkflowCatalog(policy));
+process.stdout.write(
+  `Generated ${policy.entries.length} canonical workflow declarations and their exact compatibility projections.\n`,
+);

package/scripts/github-output.mjs

@@ -0,0 +1,31 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+
+function githubOutputRecord(key, value) {
+  const normalized = String(value ?? "");
+  if (!/[\r\n]/u.test(normalized)) return `${key}=${normalized}\n`;
+  const valueLines = normalized.split(/\r\n|\r|\n/u);
+  let delimiter = `BUILDCHAIN_OUTPUT_${crypto
+    .createHash("sha256")
+    .update(`${key}\0${normalized}`)
+    .digest("hex")}`;
+  while (valueLines.includes(delimiter)) delimiter += "_";
+  const separator = normalized.endsWith("\n") ? "" : "\n";
+  return `${key}<<${delimiter}\n${normalized}${separator}${delimiter}\n`;
+}
+
+export function writeGitHubOutputs(outputs) {
+  const outputPath = process.env.GITHUB_OUTPUT;
+  if (!outputPath) {
+    for (const [key, value] of Object.entries(outputs)) {
+      console.log(`${key}=${value}`);
+    }
+    return;
+  }
+  fs.appendFileSync(
+    outputPath,
+    Object.entries(outputs)
+      .map(([key, value]) => githubOutputRecord(key, value))
+      .join(""),
+  );
+}

package/scripts/maintainability-metrics.mjs

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { projectWorkflowIdentities } from "./workflow-taxonomy.mjs";
 
 import fs from "node:fs";
 import path from "node:path";
@@ -280,10 +281,17 @@ function collectMaintainabilityMetrics({
       analyzeJavaScript(file, readTrackedFile(root, file, revision)),
     ]),
   );
+  const physicalWorkflows = workflowFiles.map((file) => ({
+    path: file,
+    text: readTrackedFile(root, file, revision),
+  }));
+  const logicalWorkflows = revision
+    ? physicalWorkflows
+    : projectWorkflowIdentities(root, physicalWorkflows);
   const workflowMetrics = Object.fromEntries(
-    workflowFiles.map((file) => [
-      file,
-      analyzeWorkflow(file, readTrackedFile(root, file, revision)),
+    logicalWorkflows.map((entry) => [
+      entry.path,
+      analyzeWorkflow(entry.path, entry.text),
     ]),
   );
   const sumLines = (entries) =>
@@ -316,8 +324,11 @@ function collectMaintainabilityMetrics({
       ),
       testFiles: testFiles.length,
       testLines: sumLines(testFiles),
-      workflowFiles: workflowFiles.length,
-      workflowLines: sumLines(workflowFiles),
+      workflowFiles: logicalWorkflows.length,
+      workflowLines: logicalWorkflows.reduce(
+        (total, entry) => total + lineCount(entry.text),
+        0,
+      ),
       documentationFiles: documentationFiles.length,
       documentationLines: sumLines(documentationFiles),
       generatedFiles: generatedFiles.length,

package/scripts/maintainability-public-surface.mjs

@@ -0,0 +1,115 @@
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import {
+  isGeneratedFacadePublicTransition,
+  loadUniversalFacadeMigration,
+} from "./universal-facade-maintainability.mjs";
+
+function readJson(root, file) {
+  return JSON.parse(fs.readFileSync(path.join(root, file), "utf8"));
+}
+
+function readJsonAtRevision(root, revision, file) {
+  return JSON.parse(
+    execFileSync("git", ["show", `${revision}:${file}`], {
+      cwd: root,
+      encoding: "utf8",
+    }),
+  );
+}
+
+function publicSurfaceContract(entry, kind) {
+  if (kind === "cli") return { id: entry.id, usage: entry.usage };
+  if (kind === "node")
+    return {
+      export: entry.export,
+      specifier: entry.specifier,
+      target: entry.target,
+    };
+  return {
+    id: entry.id,
+    path: entry.path,
+    reusable: entry.reusable,
+    inputs: entry.inputs || [],
+    secrets: entry.secrets || [],
+    outputs: entry.outputs || [],
+  };
+}
+
+function evaluatePublicSurface({
+  root,
+  revision,
+  policy,
+  migration = loadUniversalFacadeMigration(root),
+}) {
+  const issues = [];
+  const capabilityGroups = new Set(
+    readJson(root, "dist/site/capability-registry.json").groups.map(
+      (entry) => entry.id,
+    ),
+  );
+  const definitions = [
+    ["dist/site/cli-registry.json", "commands", "cli", "id"],
+    ["dist/site/node-api-registry.json", "exports", "node", "export"],
+    ["dist/site/workflow-registry.json", "workflows", "workflow", "id"],
+    ["dist/site/workflow-registry.json", "actions", "action", "id"],
+  ];
+  for (const [file, collection, kind, key] of definitions) {
+    const current = readJson(root, file)[collection] || [];
+    const baseline = readJsonAtRevision(root, revision, file)[collection] || [];
+    const previousByKey = new Map(baseline.map((entry) => [entry[key], entry]));
+    for (const entry of current) {
+      const label = `${kind}:${entry[key]}`;
+      for (const field of policy.publicSurfacePolicy.requiredLifecycleFields) {
+        if (
+          !Object.prototype.hasOwnProperty.call(entry, field) ||
+          typeof entry[field] !== "string"
+        )
+          issues.push(`${label}: lifecycle field ${field} is missing`);
+      }
+      if (!capabilityGroups.has(entry.capabilityGroup))
+        issues.push(
+          `${label}: capability group ${entry.capabilityGroup || "<empty>"} is not registered`,
+        );
+      const previous = previousByKey.get(entry[key]);
+      const currentContract = publicSurfaceContract(entry, kind);
+      if (
+        previous &&
+        JSON.stringify(currentContract) !==
+          JSON.stringify(publicSurfaceContract(previous, kind))
+      ) {
+        const approval = policy.approvedPublicSurfaceTransitions?.[label];
+        const approvedContract =
+          approval?.fromRevision === revision &&
+          String(approval?.rationale || "").trim()
+            ? approval.contract
+            : null;
+        const generated = isGeneratedFacadePublicTransition({
+          entry,
+          kind,
+          migration,
+          baseContract:
+            approvedContract || publicSurfaceContract(previous, kind),
+          currentContract,
+        });
+        if (
+          !generated &&
+          (!approvedContract ||
+            JSON.stringify(approvedContract) !==
+              JSON.stringify(currentContract))
+        )
+          issues.push(
+            `${label}: existing public contract drifted from ${revision}`,
+          );
+      }
+      if (!previous && !entry.nonDuplicationRationale)
+        issues.push(
+          `${label}: new public surface requires a non-duplication rationale`,
+        );
+    }
+  }
+  return issues;
+}
+
+export { evaluatePublicSurface, publicSurfaceContract };