@kungfu-tech/buildchain 4.0.2 → 4.0.3-alpha.0

package/scripts/{v4-stage-capsule-qualification.mjs → stage-capsule-qualification.mjs}

@@ -7,31 +7,31 @@ import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
 import {
-  V4ContractFault,
-  v4CanonicalBytes,
-  v4ContentRoot,
-} from "../packages/core/v4-canonical-contracts.js";
-import { V4StageCapsuleLocalStore } from "../packages/core/v4-stage-capsule-local-store.js";
+  ContractFault,
+  domainCanonicalBytes,
+  domainContentRoot,
+} from "../packages/core/canonical-contracts.js";
+import { StageCapsuleLocalStore } from "../packages/core/stage-capsule-local-store.js";
 import {
-  restoreV4PlatformStageCheckpoint,
-  validateV4PlatformStageCheckpointDeclaration,
-} from "../packages/core/v4-platform-stage-checkpoints.js";
+  restorePlatformStageCheckpoint,
+  validatePlatformStageCheckpointDeclaration,
+} from "../packages/core/platform-stage-checkpoints.js";
 import {
-  V4_STAGE_CAPSULE_CAMPAIGN_RECORDED_AT,
-  createV4StageCapsuleCampaignProfile,
-  emitV4StageCapsuleCampaignCheckpoint,
-  runV4StageCapsuleFaultCampaign,
-  v4StageCapsuleCampaignAggregateRoots,
-  v4StageCapsuleCampaignDependencies,
-  v4StageCapsuleCampaignStages,
-} from "../packages/core/v4-stage-capsule-qualification-campaign.js";
+  STAGE_CAPSULE_CAMPAIGN_RECORDED_AT,
+  createStageCapsuleCampaignProfile,
+  emitStageCapsuleCampaignCheckpoint,
+  runStageCapsuleFaultCampaign,
+  stageCapsuleCampaignAggregateRoots,
+  stageCapsuleCampaignDependencies,
+  stageCapsuleCampaignStages,
+} from "../packages/core/stage-capsule-qualification-campaign.js";
 import {
-  V4_STAGE_CAPSULE_PLATFORM_QUALIFICATION_CONTRACT,
-  qualifyV4StageCapsuleCampaign,
-  reconcileV4StageCapsuleWave,
-  validateV4StageCapsulePlatformQualification,
-} from "../packages/core/v4-stage-capsule-qualification.js";
-import { planV4StageCapsuleResume } from "../packages/core/v4-stage-capsule-resume-planner.js";
+  STAGE_CAPSULE_PLATFORM_QUALIFICATION_CONTRACT,
+  qualifyStageCapsuleCampaign,
+  reconcileStageCapsuleWave,
+  validateStageCapsulePlatformQualification,
+} from "../packages/core/stage-capsule-qualification.js";
+import { planStageCapsuleResume } from "../packages/core/stage-capsule-resume-planner.js";
 
 const repoRoot = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -56,13 +56,13 @@ function readJson(file) {
 
 function writeJson(file, value) {
   fs.mkdirSync(path.dirname(file), { recursive: true });
-  fs.writeFileSync(file, v4CanonicalBytes(value), { flag: "wx" });
+  fs.writeFileSync(file, domainCanonicalBytes(value), { flag: "wx" });
 }
 
 function declaration() {
-  return validateV4PlatformStageCheckpointDeclaration(
+  return validatePlatformStageCheckpointDeclaration(
     readJson(
-      path.join(repoRoot, "architecture/v4-platform-stage-checkpoints.json"),
+      path.join(repoRoot, "architecture/platform-stage-checkpoints.json"),
     ),
   );
 }
@@ -96,7 +96,7 @@ function prepareContext(context) {
   context.lifecycleConfig = buildchainConfigModule.loadBuildchainConfig(
     context.consumerRoot,
   );
-  context.campaignProfile = createV4StageCapsuleCampaignProfile(context);
+  context.campaignProfile = createStageCapsuleCampaignProfile(context);
   return context;
 }
 
@@ -115,28 +115,28 @@ function directoryBytes(directory) {
 
 function seed(context) {
   prepareContext(context);
-  const campaignStages = v4StageCapsuleCampaignStages(context);
+  const campaignStages = stageCapsuleCampaignStages(context);
   const retainedStages = campaignStages.slice(
     0,
     Math.max(1, campaignStages.indexOf("verify")),
   );
   const failedStage = "verify";
   const targetStage = campaignStages.at(-1);
-  const referenceStore = new V4StageCapsuleLocalStore(
+  const referenceStore = new StageCapsuleLocalStore(
     path.join(context.workRoot, "reference-store"),
   );
-  const retainedStore = new V4StageCapsuleLocalStore(
+  const retainedStore = new StageCapsuleLocalStore(
     path.join(context.workRoot, "retained-store"),
   );
   const reference = campaignStages.map((stage) => ({
     stage,
-    ...emitV4StageCapsuleCampaignCheckpoint(context, stage, referenceStore),
+    ...emitStageCapsuleCampaignCheckpoint(context, stage, referenceStore),
   }));
   const retained = retainedStages.map((stage) => ({
     stage,
-    ...emitV4StageCapsuleCampaignCheckpoint(context, stage, retainedStore),
+    ...emitStageCapsuleCampaignCheckpoint(context, stage, retainedStore),
   }));
-  const lateFailure = emitV4StageCapsuleCampaignCheckpoint(
+  const lateFailure = emitStageCapsuleCampaignCheckpoint(
     context,
     failedStage,
     retainedStore,
@@ -150,7 +150,7 @@ function seed(context) {
     platform: context.platform,
     runtimeRef: context.runtimeRef,
     campaignProfileRoot: context.campaignProfile.profileRoot,
-    referenceRoots: v4StageCapsuleCampaignAggregateRoots(reference),
+    referenceRoots: stageCapsuleCampaignAggregateRoots(reference),
     retainedCapsuleRoots: retained.map(({ stage, capsule }) => ({
       stage,
       capsuleRoot: capsule.capsuleRoot,
@@ -165,7 +165,7 @@ function seed(context) {
   };
   const evidence = {
     ...body,
-    evidenceRoot: v4ContentRoot("stage-capsule-seed-evidence", body),
+    evidenceRoot: domainContentRoot("stage-capsule-seed-evidence", body),
   };
   writeJson(path.join(context.workRoot, "seed-evidence.json"), evidence);
   writeJson(path.join(context.workRoot, "campaign-state.json"), {
@@ -179,7 +179,7 @@ function seed(context) {
     dependencies: Object.fromEntries(
       campaignStages.map((stage) => [
         stage,
-        v4StageCapsuleCampaignDependencies(context, stage),
+        stageCapsuleCampaignDependencies(context, stage),
       ]),
     ),
     retainedStages,
@@ -200,7 +200,7 @@ function stageNode(state, store, reference) {
   if (state.retainedStages.includes(reference.stage)) {
     const restored = store.restore({
       capsuleRoot: reference.capsule.capsuleRoot,
-      recordedAt: V4_STAGE_CAPSULE_CAMPAIGN_RECORDED_AT,
+      recordedAt: STAGE_CAPSULE_CAMPAIGN_RECORDED_AT,
     });
     candidate = {
       capsule: restored.capsule,
@@ -219,7 +219,7 @@ function stageNode(state, store, reference) {
 function resumeRequest(state, store) {
   return {
     schema: "buildchain-v4-stage-capsule-resume-request/v1",
-    evaluatedAt: V4_STAGE_CAPSULE_CAMPAIGN_RECORDED_AT,
+    evaluatedAt: STAGE_CAPSULE_CAMPAIGN_RECORDED_AT,
     nodes: state.reference.map((reference) =>
       stageNode(state, store, reference),
     ),
@@ -229,7 +229,7 @@ function resumeRequest(state, store) {
 }
 
 function emitMissing(context, state, store, stageId) {
-  const emitted = emitV4StageCapsuleCampaignCheckpoint(context, stageId, store);
+  const emitted = emitStageCapsuleCampaignCheckpoint(context, stageId, store);
   const expected = state.reference.find(({ stage }) => stage === stageId);
   if (
     emitted.capsule.capsuleRoot !== expected.capsule.capsuleRoot ||
@@ -253,18 +253,18 @@ function resume(context) {
     ["consumerSourceRevision", "stage-capsule-campaign-source-revision-drift"],
   ])
     if (state[name] !== context[name])
-      throw new V4ContractFault(code, `$/campaign/${name}`, `${name} differs`);
+      throw new ContractFault(code, `$/campaign/${name}`, `${name} differs`);
   if (state.campaignProfileRoot !== context.campaignProfile.profileRoot)
-    throw new V4ContractFault(
+    throw new ContractFault(
       "stage-capsule-campaign-lifecycle-profile-drift",
       "$/campaign/campaignProfileRoot",
       "campaign lifecycle profile differs",
     );
-  const store = new V4StageCapsuleLocalStore(
+  const store = new StageCapsuleLocalStore(
     path.join(context.workRoot, "retained-store"),
   );
   const request = resumeRequest(state, store);
-  const plan = planV4StageCapsuleResume(request);
+  const plan = planStageCapsuleResume(request);
   const expectedRestores = [state.retainedStages.at(-1)];
   const expectedStages = state.campaignStages.filter(
     (stage) => !state.retainedStages.includes(stage),
@@ -292,12 +292,12 @@ function resume(context) {
   const started = process.hrtime.bigint();
   for (const stageId of plan.requiredRestores) {
     const reference = state.reference.find(({ stage }) => stage === stageId);
-    restoreV4PlatformStageCheckpoint({
+    restorePlatformStageCheckpoint({
       declaration: context.declaration,
       expectedPlatform: context.platform,
       expectedStage: stageId,
       capsuleRoot: reference.capsule.capsuleRoot,
-      recordedAt: V4_STAGE_CAPSULE_CAMPAIGN_RECORDED_AT,
+      recordedAt: STAGE_CAPSULE_CAMPAIGN_RECORDED_AT,
       targetDirectory: path.join(context.workRoot, "restored", stageId),
       store,
     });
@@ -316,9 +316,9 @@ function resume(context) {
       state.campaignStages.indexOf(left.stage) -
       state.campaignStages.indexOf(right.stage),
   );
-  const freshBuild = v4StageCapsuleCampaignAggregateRoots(state.reference);
-  const resumedBuild = v4StageCapsuleCampaignAggregateRoots(resumedEntries);
-  const campaignFaults = runV4StageCapsuleFaultCampaign(request);
+  const freshBuild = stageCapsuleCampaignAggregateRoots(state.reference);
+  const resumedBuild = stageCapsuleCampaignAggregateRoots(resumedEntries);
+  const campaignFaults = runStageCapsuleFaultCampaign(request);
   const metrics = {
     fullStageCount: state.campaignStages.length,
     rebuiltStageCount: plan.requiredStages.length,
@@ -341,7 +341,7 @@ function resume(context) {
     planRoot: plan.planRoot,
     freshBuild,
     resumedBuild,
-    faultCampaignRoot: v4ContentRoot(
+    faultCampaignRoot: domainContentRoot(
       "stage-capsule-fault-campaign",
       campaignFaults,
     ),
@@ -349,10 +349,13 @@ function resume(context) {
   };
   const resumeEvidence = {
     ...resumeBody,
-    evidenceRoot: v4ContentRoot("stage-capsule-resume-evidence", resumeBody),
+    evidenceRoot: domainContentRoot(
+      "stage-capsule-resume-evidence",
+      resumeBody,
+    ),
   };
   const reportBody = {
-    schema: V4_STAGE_CAPSULE_PLATFORM_QUALIFICATION_CONTRACT,
+    schema: STAGE_CAPSULE_PLATFORM_QUALIFICATION_CONTRACT,
     mode: "shadow-only",
     productionAuthority: "v3",
     consumer: context.consumer,
@@ -389,9 +392,9 @@ function resume(context) {
     providerEffects: false,
     productionWrites: false,
   };
-  const report = validateV4StageCapsulePlatformQualification({
+  const report = validateStageCapsulePlatformQualification({
     ...reportBody,
-    reportRoot: v4ContentRoot(
+    reportRoot: domainContentRoot(
       "stage-capsule-platform-qualification",
       reportBody,
     ),
@@ -401,7 +404,7 @@ function resume(context) {
     resumeEvidence,
   );
   writeJson(path.join(context.workRoot, "report.json"), report);
-  process.stdout.write(v4CanonicalBytes(report));
+  process.stdout.write(domainCanonicalBytes(report));
 }
 
 function child(action, context) {
@@ -439,7 +442,7 @@ function child(action, context) {
 function campaign(context) {
   if (option("stage-capsule-mode", "shadow") === "v3") {
     process.stdout.write(
-      v4CanonicalBytes({
+      domainCanonicalBytes({
         schema: "buildchain-v4-stage-capsule-rollback/v1",
         switch: "stage-capsule-mode=v3",
         productionAuthority: "v3",
@@ -485,13 +488,10 @@ function aggregate() {
         .map((value) => value.trim())
         .filter(Boolean)
     : undefined;
-  const qualification = qualifyV4StageCapsuleCampaign(
-    reports,
-    expectedConsumers,
-  );
+  const qualification = qualifyStageCapsuleCampaign(reports, expectedConsumers);
   const output = option("output");
   if (output) writeJson(path.resolve(output), qualification);
-  process.stdout.write(v4CanonicalBytes(qualification));
+  process.stdout.write(domainCanonicalBytes(qualification));
 }
 
 function reconcile() {
@@ -499,10 +499,10 @@ function reconcile() {
   const request = readJson(path.resolve(required("wave-evidence")));
   if (request.qualificationRoot !== qualification.qualificationRoot)
     throw new Error("wave evidence does not bind the qualification root");
-  const reconciliation = reconcileV4StageCapsuleWave(request);
+  const reconciliation = reconcileStageCapsuleWave(request);
   const output = option("output");
   if (output) writeJson(path.resolve(output), reconciliation);
-  process.stdout.write(v4CanonicalBytes(reconciliation));
+  process.stdout.write(domainCanonicalBytes(reconciliation));
 }
 
 const action = process.argv[2] || "";
@@ -516,7 +516,7 @@ else if (action === "aggregate") aggregate();
 else if (action === "reconcile") reconcile();
 else if (action === "smoke") {
   const temporary = fs.mkdtempSync(
-    path.join(os.tmpdir(), "buildchain-v4-capsule-"),
+    path.join(os.tmpdir(), "buildchain-capsule-"),
   );
   const context = contextFromArgs();
   context.workRoot = temporary;

package/scripts/{v4-stage-capsule-resume-rehearsal.mjs → stage-capsule-resume-rehearsal.mjs}

@@ -4,8 +4,8 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { v4CanonicalBytes } from "../packages/core/v4-canonical-contracts.js";
-import { planV4StageCapsuleResume } from "../packages/core/v4-stage-capsule-resume-planner.js";
+import { domainCanonicalBytes } from "../packages/core/canonical-contracts.js";
+import { planStageCapsuleResume } from "../packages/core/stage-capsule-resume-planner.js";
 
 const repoRoot = path.resolve(
   path.dirname(fileURLToPath(import.meta.url)),
@@ -22,7 +22,7 @@ if (!platform) throw new Error("--platform is required");
 
 const declaration = JSON.parse(
   fs.readFileSync(
-    path.join(repoRoot, "architecture/v4-platform-stage-checkpoints.json"),
+    path.join(repoRoot, "architecture/platform-stage-checkpoints.json"),
     "utf8",
   ),
 );
@@ -38,13 +38,13 @@ const fixture = JSON.parse(
     "utf8",
   ),
 );
-const first = planV4StageCapsuleResume(fixture);
-const second = planV4StageCapsuleResume(structuredClone(fixture));
+const first = planStageCapsuleResume(fixture);
+const second = planStageCapsuleResume(structuredClone(fixture));
 if (first.planRoot !== second.planRoot)
   throw new Error("resume planner is not deterministic");
 
 process.stdout.write(
-  v4CanonicalBytes({
+  domainCanonicalBytes({
     schema: "buildchain-v4-stage-capsule-resume-rehearsal/v1",
     mode: "shadow-only",
     platform,

package/scripts/{v4-tail-reseal-macos-rehearsal.mjs → tail-reseal-macos-rehearsal.mjs}

@@ -6,8 +6,8 @@ import os from "node:os";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 
-import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
-import { verifyV4TailResealPlatform } from "./v4-tail-reseal.mjs";
+import { domainContentRoot } from "../packages/core/canonical-contracts.js";
+import { verifyTailResealPlatform } from "./tail-reseal.mjs";
 
 function flag(args, name, fallback = "") {
   const index = args.indexOf(`--${name}`);
@@ -56,12 +56,12 @@ function writeCandidate(root, request, content) {
   fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
   fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
   return {
-    artifactRoot: v4ContentRoot("tail-reseal-artifact-files", [file]),
+    artifactRoot: domainContentRoot("tail-reseal-artifact-files", [file]),
     manifestRoot: fileRoot(manifestPath),
   };
 }
 
-export function rehearseV4TailResealMacos({
+export function rehearseTailResealMacos({
   fixturePath = "contracts/fixtures/v4-tail-reseal-v1/valid.json",
   outputPath = "",
 } = {}) {
@@ -69,20 +69,20 @@ export function rehearseV4TailResealMacos({
     fs.readFileSync(path.resolve(fixturePath), "utf8"),
   );
   const workRoot = fs.mkdtempSync(
-    path.join(os.tmpdir(), "buildchain-v4-tail-macos-"),
+    path.join(os.tmpdir(), "buildchain-tail-macos-"),
   );
   try {
     const retainedRoots = writeCandidate(workRoot, request, "unsigned");
     const platform = request.platforms.find(({ id }) => id === "macos-arm64");
     Object.assign(platform, retainedRoots);
-    const retained = verifyV4TailResealPlatform({
+    const retained = verifyTailResealPlatform({
       request,
       platformId: "macos-arm64",
       artifactRoot: workRoot,
       mode: "retained",
     });
     writeCandidate(workRoot, request, "signed-and-notarized");
-    const resealed = verifyV4TailResealPlatform({
+    const resealed = verifyTailResealPlatform({
       request,
       platformId: "macos-arm64",
       artifactRoot: workRoot,
@@ -100,7 +100,7 @@ export function rehearseV4TailResealMacos({
     };
     const evidence = {
       ...payload,
-      evidenceRoot: v4ContentRoot("tail-reseal-admission", payload),
+      evidenceRoot: domainContentRoot("tail-reseal-admission", payload),
     };
     if (outputPath) {
       const output = path.resolve(outputPath);
@@ -118,7 +118,7 @@ if (
   import.meta.url === pathToFileURL(process.argv[1]).href
 ) {
   try {
-    const evidence = rehearseV4TailResealMacos({
+    const evidence = rehearseTailResealMacos({
       fixturePath: flag(
         process.argv.slice(2),
         "fixture",

package/scripts/{v4-tail-reseal.mjs → tail-reseal.mjs}

@@ -6,13 +6,13 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 import {
-  V4_TAIL_RESEAL_PLATFORMS,
-  normalizeV4TailResealRequest,
-  planV4TailReseal,
-} from "../packages/core/v4-tail-reseal.js";
-import { createV4TailResealReceipt } from "../packages/core/v4-tail-reseal-receipt.js";
-import { validateV4TailResealGitHubEvidence } from "../packages/core/v4-tail-reseal-github.js";
-import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
+  TAIL_RESEAL_PLATFORMS,
+  normalizeTailResealRequest,
+  planTailReseal,
+} from "../packages/core/tail-reseal.js";
+import { createTailResealReceipt } from "../packages/core/tail-reseal-receipt.js";
+import { validateTailResealGitHubEvidence } from "../packages/core/tail-reseal-github.js";
+import { domainContentRoot } from "../packages/core/canonical-contracts.js";
 
 function flag(args, name, fallback = "") {
   const index = args.indexOf(`--${name}`);
@@ -137,7 +137,7 @@ async function admitFromGitHub(request) {
       token,
     ),
   ]);
-  return validateV4TailResealGitHubEvidence({
+  return validateTailResealGitHubEvidence({
     request,
     sourceCommit,
     sourceRun,
@@ -183,14 +183,14 @@ function resolvePayload(root, relative, platformId) {
   return absolute;
 }
 
-export function verifyV4TailResealPlatform({
+export function verifyTailResealPlatform({
   request,
   platformId,
   artifactRoot,
   mode = "retained",
   providerReadbackRoot = null,
 } = {}) {
-  const normalized = normalizeV4TailResealRequest(request);
+  const normalized = normalizeTailResealRequest(request);
   const platform = normalized.platforms.find(({ id }) => id === platformId);
   if (!platform)
     throw new Error(`tail reseal request does not bind platform ${platformId}`);
@@ -243,7 +243,7 @@ export function verifyV4TailResealPlatform({
     );
   if (files.length === 0)
     throw new Error(`${platformId} manifest has no retained files`);
-  const observedArtifactRoot = v4ContentRoot(
+  const observedArtifactRoot = domainContentRoot(
     "tail-reseal-artifact-files",
     files,
   );
@@ -290,21 +290,21 @@ function collectReadbacks(directory) {
       throw new Error(`duplicate tail reseal readback for ${value.platformId}`);
     byPlatform.set(value.platformId, value);
   }
-  return V4_TAIL_RESEAL_PLATFORMS.map((platformId) => {
+  return TAIL_RESEAL_PLATFORMS.map((platformId) => {
     if (!byPlatform.has(platformId))
       throw new Error(`missing tail reseal readback for ${platformId}`);
     return byPlatform.get(platformId);
   });
 }
 
-export function runV4TailResealCli(args = process.argv.slice(2)) {
+export function runTailResealCli(args = process.argv.slice(2)) {
   const [command, ...options] = args;
   const requestPath = flag(options, "request");
   if (command === "plan") {
-    const request = normalizeV4TailResealRequest(
+    const request = normalizeTailResealRequest(
       readJson(required(requestPath, "--request"), "tail reseal request"),
     );
-    const plan = planV4TailReseal(request);
+    const plan = planTailReseal(request);
     const output = writeJson(
       flag(options, "output", ".buildchain/tail-reseal/plan.json"),
       plan,
@@ -331,7 +331,7 @@ export function runV4TailResealCli(args = process.argv.slice(2)) {
     return plan;
   }
   if (command === "admit") {
-    const request = normalizeV4TailResealRequest(
+    const request = normalizeTailResealRequest(
       readJson(required(requestPath, "--request"), "tail reseal request"),
     );
     return admitFromGitHub(request).then((admission) => {
@@ -347,7 +347,7 @@ export function runV4TailResealCli(args = process.argv.slice(2)) {
     });
   }
   if (command === "verify-platform") {
-    const readback = verifyV4TailResealPlatform({
+    const readback = verifyTailResealPlatform({
       request: readJson(required(requestPath, "--request")),
       platformId: required(flag(options, "platform"), "--platform"),
       artifactRoot: flag(options, "artifact-root", process.cwd()),
@@ -371,7 +371,7 @@ export function runV4TailResealCli(args = process.argv.slice(2)) {
   }
   if (command === "seal") {
     const request = readJson(required(requestPath, "--request"));
-    const receipt = createV4TailResealReceipt({
+    const receipt = createTailResealReceipt({
       request,
       plan: readJson(required(flag(options, "plan"), "--plan")),
       readbacks: collectReadbacks(
@@ -409,7 +409,7 @@ if (
   process.argv[1] &&
   import.meta.url === pathToFileURL(process.argv[1]).href
 ) {
-  runV4TailResealCli().catch((error) => {
+  runTailResealCli().catch((error) => {
     console.error(`tail-reseal: ${error.message}`);
     process.exitCode = 1;
   });

package/scripts/universal-facade-maintainability.mjs

@@ -5,7 +5,7 @@ import { execFileSync } from "node:child_process";
 function loadUniversalFacadeMigration(root) {
   const contract = JSON.parse(
     fs.readFileSync(
-      path.join(root, "architecture/v4-universal-workflow-bootstrap.json"),
+      path.join(root, "architecture/universal-workflow-bootstrap.json"),
       "utf8",
     ),
   );
@@ -20,13 +20,17 @@ function loadUniversalFacadeMigration(root) {
       "universal facade migration requires an exact facadeSourceRevision",
     );
   }
-  return { paths: new Set(paths), sourceRevision };
+  return {
+    paths: new Set(paths),
+    sourceRevision,
+    postMigration: new Set(contract.migration?.postMigrationWorkflows || []),
+  };
 }
 
 function verifyUniversalFacadeMigration(root) {
   execFileSync(
     process.execPath,
-    ["scripts/generate-v4-universal-workflow-facades.mjs", "--check"],
+    ["scripts/generate-universal-workflow-facades.mjs", "--check"],
     { cwd: root, stdio: "pipe" },
   );
 }
@@ -40,6 +44,11 @@ function governUniversalFacadeWorkflowMetrics({
   verifyUniversalFacadeMigration(root);
   const frozen = workflowMetricsAtRevision(root, migration.sourceRevision);
   const governed = { ...current, workflows: { ...current.workflows } };
+  for (const file of migration.postMigration) {
+    if (frozen[file] || !migration.paths.has(file))
+      throw new Error(`invalid post-migration workflow declaration ${file}`);
+    migration.paths.delete(file);
+  }
   for (const file of migration.paths) {
     if (!frozen[file])
       throw new Error(`frozen universal facade source is missing ${file}`);

package/scripts/{v4-universal-workflow-backflow.mjs → universal-workflow-backflow.mjs}

@@ -3,9 +3,9 @@ import crypto from "node:crypto";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import {
-  validateV4UniversalWorkflowRequest,
-  v4UniversalWorkflowRequestRoot,
-} from "../packages/core/v4-universal-workflow-bootstrap.js";
+  validateUniversalWorkflowRequest,
+  universalWorkflowRequestRoot,
+} from "../packages/core/universal-workflow-bootstrap.js";
 const SHA = /^[0-9a-f]{40}$/u;
 const ROOT = /^sha256:[0-9a-f]{64}$/u;
 
@@ -39,7 +39,7 @@ function validateTerminalReceipt(value, request) {
     value.status !== "succeeded" ||
     value.runtime?.repository !== request.candidate.repository ||
     value.runtime?.sha !== request.candidate.expectedSha ||
-    value.requestRoot !== v4UniversalWorkflowRequestRoot(request) ||
+    value.requestRoot !== universalWorkflowRequestRoot(request) ||
     !SHA.test(value.runtime?.sha || "") ||
     !ROOT.test(value.receiptRoot || "")
   )
@@ -49,11 +49,11 @@ function validateTerminalReceipt(value, request) {
   return value;
 }
 
-export function createV4UniversalBackflowPlan({
+export function createUniversalBackflowPlan({
   request: requestValue,
   receipt,
 }) {
-  const request = validateV4UniversalWorkflowRequest(requestValue);
+  const request = validateUniversalWorkflowRequest(requestValue);
   if (request.mode !== "train") fail("only Train delivery can create backflow");
   if (request.capability.id !== "release-candidate-promote")
     fail("only a release-candidate-promote delivery can create backflow");
@@ -120,13 +120,13 @@ async function githubJson({ path, method = "GET", token, body, fetchImpl }) {
   return value;
 }
 
-export async function upsertV4UniversalBackflow({
+export async function upsertUniversalBackflow({
   request,
   receipt,
   token,
   fetchImpl = globalThis.fetch,
 }) {
-  const admitted = validateV4UniversalWorkflowRequest(request);
+  const admitted = validateUniversalWorkflowRequest(request);
   if (
     admitted.mode !== "train" ||
     admitted.capability.id !== "release-candidate-promote" ||
@@ -141,7 +141,7 @@ export async function upsertV4UniversalBackflow({
   }
   if (!token) fail("GH_TOKEN is required for protected backflow");
   if (typeof fetchImpl !== "function") fail("fetch is required for backflow");
-  const plan = createV4UniversalBackflowPlan({ request: admitted, receipt });
+  const plan = createUniversalBackflowPlan({ request: admitted, receipt });
   const encodedRepository = plan.repository;
   const pull = await githubJson({
     path: `/repos/${encodedRepository}/pulls/${plan.pullRequest}`,
@@ -198,7 +198,7 @@ async function main() {
     process.env.BUILDCHAIN_UNIVERSAL_TERMINAL_RECEIPT_JSON ||
       fail("terminal receipt is required"),
   );
-  const result = await upsertV4UniversalBackflow({
+  const result = await upsertUniversalBackflow({
     request,
     receipt,
     token: process.env.GH_TOKEN || process.env.GITHUB_TOKEN,