@kungfu-tech/buildchain 4.0.1 → 4.0.2-alpha.2

package/scripts/audit-publication-control-plane.mjs

@@ -196,7 +196,6 @@ function normalizeNpmPublisher(value, { packageName, repository, workflowFilenam
     configurationRead: true,
   };
 }
-
 function main() {
   const repository = flag("repository");
   const workflowRepository = flag("workflow-repository", repository);

package/scripts/check-inventory.mjs

@@ -127,7 +127,6 @@ const requiredPaths = [
   "scripts/npm-publish-transaction.mjs",
   "scripts/paper.mjs",
   "scripts/publication-package.mjs",
-  "scripts/publication-commit-evidence.mjs",
   "scripts/publication-reproducibility.mjs",
   "scripts/release-candidate-resolver.mjs",
   "scripts/resume-from-candidate-run.mjs",
@@ -300,8 +299,8 @@ if (channelPromotionWorkflow !== generateChannelPromotionWorkflow(advancedPromot
   throw new Error("generated channel promotion workflow is stale");
 }
 for (const requiredSnippet of [
-  "uses: kungfu-systems/buildchain/.github/workflows/.release-candidate-promote.yml@alpha/v4/v4.0",
-  "promotion-shell-ref: ${{ needs.consumer-admission.outputs.shell-call-ref }}",
+  "name: Adapt recovery inputs into the canonical v4 publisher",
+  "uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v4-alpha",
   "declarative-release-tail: true",
 ]) {
   if (!boundedAlphaRecoveryWorkflow.includes(requiredSnippet)) {
@@ -316,8 +315,8 @@ for (const workflowSource of [boundedAlphaRecoveryWorkflow, channelPromotionWork
 for (const requiredSnippet of [
   "buildchain-channel:",
   `/${promotionShellRouting.alpha.workflowPath}@${promotionShellRouting.alpha.callRef}`,
-  `/${promotionShellRouting.stable.workflowPath}@${promotionShellRouting.stable.callRef}`,
-  `STABLE_SHELL_REF: v${selfDogfoodMajor}`,
+  `SELECTED_SHELL_REF: v${selfDogfoodMajor}-alpha`,
+  "name: Invoke the single v4 publisher adapter",
   "promotion-contract-lock-digest:",
   "authorize-promotion-runtime-override.cjs",
   "BUILDCHAIN_ROUTER_REPOSITORY: ${{ inputs.buildchain-repository }}",
@@ -329,6 +328,9 @@ for (const requiredSnippet of [
     throw new Error(`channel promotion workflow missing routing contract: ${requiredSnippet}`);
   }
 }
+if (channelPromotionWorkflow.includes("Promote with stable workflow shell")) {
+  throw new Error("channel promotion workflow retains a parallel stable publisher");
+}
 for (const forbiddenSnippet of ["job.workflow_repository", "job.workflow_sha"]) {
   if (channelPromotionWorkflow.includes(forbiddenSnippet)) {
     throw new Error(`channel promotion workflow uses unsupported GitHub context: ${forbiddenSnippet}`);
@@ -1046,7 +1048,6 @@ for (const requiredSnippet of [
   "resume-candidate-run-id:",
   "resume-expected-source-tree:",
   "resume-buildchain-runtime-ref:",
-  "uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v4",
   "release-passport-buildchain-self-kfd: true",
   "declarative-release-tail: true",
   "release-passport-impact-json: .buildchain/release-impact.json",
@@ -1057,61 +1058,28 @@ for (const requiredSnippet of [
 }
 const releaseCandidatePromoteWorkflow = fs.readFileSync(path.join(root, ".github/workflows/.release-candidate-promote.yml"), "utf8");
 for (const requiredSnippet of [
-  "release-passport-kfd-1-witness-jsons:",
-  "release-passport-kfd-1-witness-jsons: ${{ inputs.release-passport-kfd-1-witness-jsons }}",
-  "release-passport-kfd-2-claim-jsons:",
-  "release-passport-kfd-2-claim-jsons: ${{ inputs.release-passport-kfd-2-claim-jsons }}",
-  "release-passport-kfd-3-prebuild-witness-jsons:",
-  "release-passport-kfd-3-prebuild-witness-jsons: ${{ inputs.release-passport-kfd-3-prebuild-witness-jsons }}",
-  "release-passport-kfd-3-artifact-witness-jsons:",
-  "release-passport-kfd-3-artifact-witness-jsons: ${{ inputs.release-passport-kfd-3-artifact-witness-jsons }}",
-  "release-passport-kfd-3-artifact-verify-command:",
-  "release-passport-kfd-adopter-manifest-json:", "release-passport-kfd-adopter-manifest-json: ${{ inputs.release-passport-kfd-adopter-manifest-json }}",
-  "release-passport-kfd-support-matrix-json:", "release-passport-kfd-support-matrix-json: ${{ inputs.release-passport-kfd-support-matrix-json }}",
-  "release-passport-kfd-product-gate-jsons:",
-  "release-passport-kfd-product-gate-jsons: ${{ inputs.release-passport-kfd-product-gate-jsons }}",
-  "release-passport-invariant-passport-jsons:",
-  "release-passport-invariant-passport-jsons: ${{ inputs.release-passport-invariant-passport-jsons }}",
-  "release-passport-invariant-passport-command:",
-  "release-passport-invariant-passport-command: ${{ inputs.release-passport-invariant-passport-command }}",
-  "release-passport-buildchain-self-kfd:",
-  "release-passport-buildchain-self-kfd: ${{ inputs.release-passport-buildchain-self-kfd }}",
-  "github-release:",
-  "default: true",
-  "github-release: ${{ inputs.github-release }}",
-  "github-release-payload-patterns:",
-  "github-release-artifact-paths: ${{ steps.rc.outputs.release-candidate-github-release-artifact-paths }}",
-  "github-release-title: ${{ inputs.github-release-title }}",
-  "github-release-notes: ${{ inputs.github-release-notes }}",
-  "publication-commit-command:",
-  "BUILDCHAIN_PUBLICATION_COMMIT_SIGNING_KEY:",
-  "KUNGFU_GOVERNANCE_AUDITOR_APP_PRIVATE_KEY:",
-  "Commit consumer publication authority last",
-  "node .buildchain/runtime/scripts/publication-commit-evidence.mjs",
-  "require-publish-source-lock: \"true\"",
-  "publish-source-ref: ${{ steps.publish-gate.outputs.ref }}",
-  "publish-source-sha: ${{ steps.publish-gate.outputs.sha }}",
-  "publish-source-locked: ${{ steps.publish-gate.outputs.locked }}",
-  "expected-publication-version: ${{ needs.publication-plan.outputs.version }}",
-  "publication-version: ${{ needs.publication-plan.outputs.version }}",
-  "name: Plan exact publication version",
-  "name: Install exact publication planning dependencies",
-  "DRY_RUN: ${{ inputs.dry-run }}",
-  "if (dryRun) {",
-  "Enforce Buildchain stable release canary gate",
-  "BUILDCHAIN_STABLE_RELEASE_POLICY: .buildchain/stable-release-policy.json",
-  "Consumer has no binary-distribution.yml; standalone binary dispatch is not applicable.",
-  "gh workflow view binary-distribution.yml",
-  "resume-candidate-run-id:",
-  "node .buildchain/runtime/scripts/resume-from-candidate-run.mjs",
-  "publish-sealed-bundle-root: ${{ steps.rc.outputs.publish-sealed-bundle-root }}",
-  "BUILDCHAIN_EXPECTED_TRANSACTION_ID: ${{ inputs.resume-transaction-id }}",
-  "if: ${{ inputs.resume-candidate-run-id == '' }}",
-  "Bridge Buildchain self-runtime dependencies",
-  "ln -s .buildchain/runtime/node_modules node_modules",
+  "name: QUALIFY canonical v4 release invocation inputs",
+  "name: APPLY one rooted provider transaction",
+  "name: SETTLE terminal ReleaseReceipt projection",
+  "uses: ./.buildchain/runtime/actions/v4-release-candidate-promote",
+  "publisher-workflow-sha:",
+  "runtime-commit:",
+  "runtime-tree:",
+  "release-invocation-root:",
+  "release-transaction-root:",
+  "release-receipt-root:",
 ]) {
   if (!releaseCandidatePromoteWorkflow.includes(requiredSnippet)) {
-    throw new Error(`release candidate promote workflow missing KFD gate pass-through: ${requiredSnippet}`);
+    throw new Error(`release candidate promote workflow missing canonical v4 boundary: ${requiredSnippet}`);
+  }
+}
+for (const retiredSnippet of [
+  "Commit consumer publication authority last",
+  "publish-github-artifact-attestation-evidence.mjs",
+  "capture-package-release-propagation.mjs",
+]) {
+  if (releaseCandidatePromoteWorkflow.includes(retiredSnippet)) {
+    throw new Error(`release candidate promote workflow retains parallel publication authority: ${retiredSnippet}`);
   }
 }
 const workflowDir = path.join(root, ".github/workflows");

package/scripts/check-maintainability.mjs

@@ -20,17 +20,25 @@ import {
   evaluateWorkflowBudgets,
 } from "./maintainability-governance.mjs";
 
-function collectHotspots(root, current, limit = 20, shallowFallback = []) {
+function collectHotspots(
+  root,
+  current,
+  limit = 20,
+  shallowFallback = [],
+  {
+    baseRef = process.env.GITHUB_BASE_REF || process.env.GITHUB_REF_NAME || "",
+  } = {},
+) {
   const maintained = new Set([
     ...Object.keys(current.files || {}),
     ...Object.keys(current.tests || {}),
     ...Object.keys(current.workflows || {}),
   ]);
-  // Shallow consumers cannot reproduce repository-wide churn ranking.
-  // Reuse the audited routes; full clones still re-rank them below.
-  // This keeps consumer verification deterministic without inventing history.
+  // Release-line reconciliation reuses audited routes across equivalent-tree DAG shapes.
   if (
-    gitOutput(root, ["rev-parse", "--is-shallow-repository"]).trim() === "true"
+    gitOutput(root, ["rev-parse", "--is-shallow-repository"]).trim() ===
+      "true" ||
+    /^(?:alpha|release|publish-gate)\//u.test(baseRef)
   ) {
     return shallowFallback.slice(0, limit);
   }

package/scripts/check-v3-v4-capability-inventory.mjs

@@ -8,6 +8,7 @@ import {
   collectHistoryRows,
   collectRevisionCatalog,
   countsBy,
+  ensureCapabilityCutLineage,
   git,
   sha256,
 } from "./v3-v4-capability-catalog.mjs";
@@ -17,9 +18,8 @@ export const V3_V4_CAPABILITY_INVENTORY_CONTRACT =
 export const V3_V4_CAPABILITY_CUTS = Object.freeze({
   priorFamilyV3: "6b96bdad8d9f8ccf9275f27d9370a226a9c78465",
   liveV3: "8493bf140a7f567e76aff3119f3d39ff026afc84",
-  liveV4: "11b4ab21405cdffcc9d6dc10cd947618d9d1bf9c",
+  liveV4: "97edd5b93eb67e5bf36ad55726e08231b47b70c0",
 });
-
 const INVENTORY_PATH = "architecture/v3-v4-live-capability-inventory.json";
 const ALLOWED_DISPOSITIONS = new Set([
   "v4-native",
@@ -92,64 +92,6 @@ function capabilityCutAvailable(root, revision) {
   }
 }
 
-export function assertCapabilityCutAncestor({
-  root = process.cwd(),
-  revision,
-  descendant = "HEAD",
-  label = "capability cut",
-} = {}) {
-  try {
-    execFileSync("git", ["merge-base", "--is-ancestor", revision, descendant], {
-      cwd: root,
-      stdio: "ignore",
-    });
-  } catch {
-    throw new Error(
-      `${label} ${revision} must be an ancestor of ${descendant}; regenerate the cut after rebasing instead of relying on a retained local object`,
-    );
-  }
-}
-
-function repositoryIsShallow(root) {
-  return (
-    execFileSync("git", ["rev-parse", "--is-shallow-repository"], {
-      cwd: root,
-      encoding: "utf8",
-    }).trim() === "true"
-  );
-}
-
-export function ensureCapabilityCutAncestor({
-  root = process.cwd(),
-  revision,
-  descendant = "HEAD",
-  label = "capability cut",
-} = {}) {
-  try {
-    assertCapabilityCutAncestor({ root, revision, descendant, label });
-    return;
-  } catch (error) {
-    if (!repositoryIsShallow(root)) throw error;
-  }
-  const descendantCommit = execFileSync(
-    "git",
-    ["rev-parse", `${descendant}^{commit}`],
-    { cwd: root, encoding: "utf8" },
-  ).trim();
-  try {
-    execFileSync(
-      "git",
-      ["fetch", "--no-tags", "--depth=128", "origin", descendantCommit],
-      { cwd: root, stdio: "ignore" },
-    );
-  } catch {
-    throw new Error(
-      `${label} ${revision} ancestry could not be hydrated from ${descendantCommit} through a bounded origin fetch`,
-    );
-  }
-  assertCapabilityCutAncestor({ root, revision, descendant, label });
-}
-
 function ensureCapabilityCutsAvailable(root) {
   const revisions = Object.values(V3_V4_CAPABILITY_CUTS);
   const missing = revisions.filter(
@@ -170,7 +112,7 @@ function ensureCapabilityCutsAvailable(root) {
       `v3/v4 capability cuts are unavailable after a bounded origin fetch: ${unavailable.join(", ")}`,
     );
   }
-  ensureCapabilityCutAncestor({
+  ensureCapabilityCutLineage({
     root,
     revision: V3_V4_CAPABILITY_CUTS.liveV4,
     label: "live v4 capability cut",

package/scripts/check-v4-floating-consumer-policy-contract.mjs

@@ -52,16 +52,11 @@ function assertOrdered(relative, markers) {
 
 export function assertPromotionCertificationWiring(source) {
   for (const marker of [
-    "path: .buildchain/runtime/candidate-policy-runtime",
-    "BUILDCHAIN_EXPECTED_RUNTIME_SHA: ${{ steps.v4-policy-caller.outputs.runtime-sha }}",
-    "policy_runtime=.buildchain/runtime",
-    'node "${policy_runtime}/scripts/v4-consumer-policy.mjs" certify',
-    "passport.consumerPolicy?.receipt?.caller?.sourceSha",
-    "path: .buildchain/runtime/policy-caller",
-    '--caller-root "${{ github.workspace }}/.buildchain/runtime/policy-caller"',
-    '--stable-lock "${{ inputs.buildchain-stable-contract-lock-path }}"',
-    '--alpha-lock "${{ inputs.buildchain-alpha-contract-lock-path }}"',
-    "release-passport-v4-consumer-policy-certification-root: ${{ steps.v4-policy-certification.outputs.v4-consumer-policy-certification-root }}",
+    "Translate and admit legacy-compatible inputs",
+    "BUILDCHAIN_PROMOTION_INPUTS_JSON: ${{ toJSON(inputs) }}",
+    "Resolve and qualify the sealed release candidate",
+    "BUILDCHAIN_RUNTIME_AUTHORIZATION_JSON",
+    "QUALIFY canonical v4 release invocation inputs",
   ]) {
     if (!source.includes(marker)) {
       fail(`promotion certification is missing ${marker}`);
@@ -165,8 +160,7 @@ export function checkV4FloatingConsumerPolicyContract() {
   const promotion = read(".github/workflows/release-candidate-promote.yml");
   if (
     !promotion.includes("consumer-admission:") ||
-    !jobDependsOn(promotion, "alpha", "consumer-admission") ||
-    !jobDependsOn(promotion, "stable", "consumer-admission")
+    !jobDependsOn(promotion, "invoke", "consumer-admission")
   ) {
     fail(
       "release candidate promotion is not transitively gated by consumer admission",
@@ -179,16 +173,12 @@ export function checkV4FloatingConsumerPolicyContract() {
     ["packages/core/release-candidate.js", "consumerPolicy"],
     ["packages/core/release-passport.js", "v4ConsumerPolicy"],
     [
-      "actions/promote-buildchain-ref/action.yml",
-      "release-passport-v4-consumer-policy-certification-json",
+      "actions/v4-release-candidate-promote/index.js",
+      "candidate.consumerPolicy?.receiptRoot",
     ],
     [
-      "actions/promote-buildchain-ref/action.yml",
-      "release-passport-v4-consumer-policy-certification-root",
-    ],
-    [
-      ".github/workflows/.release-candidate-promote.yml",
-      "v4-policy-certification",
+      "actions/v4-release-candidate-promote/index.js",
+      "createV4ReleaseInvocation",
     ],
   ]) {
     if (!read(relative).includes(marker)) {

package/scripts/check-v4-release-topology.mjs

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import {
+  parseWorkflowDocument,
+  parseYamlUses,
+} from "../packages/core/workflow-yaml-contract.js";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const ledgerPath = path.join(root, "architecture/v4-release-topology.json");
+const releaseMarker =
+  /(?:release-candidate-promote\.yml|promote-buildchain-ref|v4-release-candidate-promote|release-tail-runtime)/u;
+
+function read(relative) {
+  return fs.readFileSync(path.join(root, relative), "utf8");
+}
+
+function jobBlock(source, jobId) {
+  const escaped = jobId.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+  return (
+    source.match(
+      new RegExp(
+        `^  ${escaped}:\\n([\\s\\S]*?)(?=^  [A-Za-z0-9_.-]+:|(?![\\s\\S]))`,
+        "mu",
+      ),
+    )?.[1] || ""
+  );
+}
+
+function permission(block, name) {
+  return (
+    new RegExp(`^      ${name}:\\s*([^#\\n]+)`, "mu")
+      .exec(block)?.[1]
+      ?.trim() || null
+  );
+}
+
+function workflowSnapshot(relative) {
+  const source = read(relative);
+  const document = parseWorkflowDocument(source);
+  const jobs = document.jobs.map((job) => {
+    const block = jobBlock(source, job.id);
+    const uses = job.uses || null;
+    return {
+      id: job.id,
+      kind: uses ? "reusable-call" : "runner",
+      uses,
+      permissions: {
+        contents: permission(block, "contents"),
+        idToken: permission(block, "id-token"),
+      },
+      carriers: {
+        artifactDownload: /uses:\s+actions\/download-artifact@/u.test(block),
+        artifactUpload: /uses:\s+actions\/upload-artifact@/u.test(block),
+        jobOutput: /GITHUB_OUTPUT/u.test(block),
+      },
+      mutationSignals: [
+        /contents:\s*write/u.test(block) && "contents-write",
+        /id-token:\s*write/u.test(block) && "oidc-write",
+        /(?:promote-buildchain-ref|v4-release-candidate-promote)/u.test(
+          block,
+        ) && "promotion-runtime",
+        /(?:git push|npm publish|gh release (?:create|upload))/u.test(block) &&
+          "direct-publication-command",
+      ].filter(Boolean),
+    };
+  });
+  return {
+    path: relative,
+    triggers: document.triggers,
+    jobs,
+    reusableEdges: parseYamlUses(source)
+      .map(({ value }) => value)
+      .filter((value) => /\.github\/workflows\//u.test(value))
+      .sort(),
+  };
+}
+
+export function discoverV4ReleaseTopology(
+  workflowPaths,
+  semanticWorkflowPaths = workflowPaths,
+) {
+  const workflows = workflowPaths.map(workflowSnapshot);
+  const jobs = workflows.flatMap((workflow) => workflow.jobs);
+  const mutationJobs = jobs.filter((job) => job.mutationSignals.length > 0);
+  const semanticPaths = new Set(semanticWorkflowPaths);
+  const semanticJobs = workflows
+    .filter((workflow) => semanticPaths.has(workflow.path))
+    .flatMap((workflow) => workflow.jobs);
+  const semanticMutationJobs = semanticJobs.filter(
+    (job) => job.kind === "runner" && job.mutationSignals.length > 0,
+  );
+  return {
+    jobRecordFields: [
+      "id",
+      "kind",
+      "uses",
+      "contentsPermission",
+      "oidcPermission",
+      "carriers",
+      "mutationSignals",
+    ],
+    workflows: workflows.map((workflow) => ({
+      path: workflow.path,
+      triggers: workflow.triggers,
+      jobs: workflow.jobs.map((job) =>
+        [
+          job.id,
+          job.kind,
+          job.uses || "-",
+          job.permissions.contents || "-",
+          job.permissions.idToken || "-",
+          Object.entries(job.carriers)
+            .filter(([, present]) => present)
+            .map(([name]) => name)
+            .join(",") || "-",
+          job.mutationSignals.join(",") || "-",
+        ].join("|"),
+      ),
+      reusableEdges: workflow.reusableEdges,
+    })),
+    metrics: {
+      workflowCount: workflows.length,
+      jobCount: jobs.length,
+      reusableEdgeCount: workflows.reduce(
+        (count, workflow) => count + workflow.reusableEdges.length,
+        0,
+      ),
+      mutationRelevantNodeCount: jobs.filter(
+        (job) =>
+          job.kind === "reusable-call" ||
+          job.mutationSignals.length > 0 ||
+          job.carriers.artifactDownload ||
+          job.carriers.artifactUpload,
+      ).length,
+      contentsWriteJobCount: mutationJobs.filter((job) =>
+        job.mutationSignals.includes("contents-write"),
+      ).length,
+      oidcWriteJobCount: mutationJobs.filter((job) =>
+        job.mutationSignals.includes("oidc-write"),
+      ).length,
+    },
+    semanticMetrics: {
+      workflowCount: semanticPaths.size,
+      mutationRelevantNodeCount: semanticJobs.filter(
+        (job) =>
+          job.kind === "reusable-call" ||
+          job.mutationSignals.length > 0 ||
+          job.carriers.artifactDownload ||
+          job.carriers.artifactUpload,
+      ).length,
+      contentsWriteJobCount: semanticMutationJobs.filter((job) =>
+        job.mutationSignals.includes("contents-write"),
+      ).length,
+      oidcWriteJobCount: semanticMutationJobs.filter((job) =>
+        job.mutationSignals.includes("oidc-write"),
+      ).length,
+    },
+  };
+}
+
+export function findUnknownV4ReleaseTopology(
+  workflowPaths,
+  allWorkflowPaths = fs
+    .readdirSync(path.join(root, ".github/workflows"))
+    .filter((name) => /\.ya?ml$/u.test(name))
+    .map((name) => `.github/workflows/${name}`),
+  readWorkflow = read,
+) {
+  const declared = new Set(workflowPaths);
+  return allWorkflowPaths
+    .filter((relative) => !declared.has(relative))
+    .filter((relative) => releaseMarker.test(readWorkflow(relative)))
+    .sort();
+}
+
+function assertClosedWorld(workflowPaths) {
+  const unknown = findUnknownV4ReleaseTopology(workflowPaths);
+  assert.deepEqual(
+    unknown,
+    [],
+    `unknown v4 release topology workflows: ${unknown.join(", ")}`,
+  );
+}
+
+export function checkV4ReleaseTopology() {
+  const ledger = JSON.parse(fs.readFileSync(ledgerPath, "utf8"));
+  assert.equal(ledger.contract, "kungfu-buildchain-v4-release-topology/v1");
+  assertClosedWorld(ledger.closedWorld.workflowPaths);
+  const actual = discoverV4ReleaseTopology(
+    ledger.closedWorld.workflowPaths,
+    ledger.semanticScope.workflowPaths,
+  );
+  assert.deepEqual(actual, ledger.observedTopology);
+  assert.equal(
+    ledger.targetBudgets.maximumMutationRelevantNodeCount,
+    Math.floor(ledger.baselineMetrics.semanticMutationRelevantNodeCount / 2),
+  );
+  if (ledger.enforcement === "converged") {
+    assert.ok(
+      actual.semanticMetrics.mutationRelevantNodeCount <=
+        ledger.targetBudgets.maximumMutationRelevantNodeCount,
+    );
+    assert.equal(actual.semanticMetrics.contentsWriteJobCount, 1);
+    assert.equal(actual.semanticMetrics.oidcWriteJobCount, 1);
+    const publisher = actual.workflows.find(
+      ({ path: workflowPath }) =>
+        workflowPath === ".github/workflows/.release-candidate-promote.yml",
+    );
+    assert.deepEqual(
+      publisher.jobs.map((job) => job.split("|", 1)[0]),
+      ["apply", "qualify", "settle"],
+    );
+  }
+  return actual;
+}
+
+if (process.argv.includes("--print")) {
+  const ledger = JSON.parse(fs.readFileSync(ledgerPath, "utf8"));
+  process.stdout.write(
+    `${JSON.stringify(
+      discoverV4ReleaseTopology(
+        ledger.closedWorld.workflowPaths,
+        ledger.semanticScope.workflowPaths,
+      ),
+      null,
+      2,
+    )}\n`,
+  );
+} else {
+  checkV4ReleaseTopology();
+  process.stdout.write("v4 release topology: ok\n");
+}

package/scripts/dev-delivery-warrant-options.mjs

@@ -33,11 +33,8 @@ function terminalEvidenceOptions(rest, environment) {
   };
 }
 
-export function devDeliveryCliOptions(args = [], environment = process.env) {
-  const [command = "", ...rest] = args;
+function authorityStateOptions(rest, environment) {
   return {
-    command,
-    repository: flag(rest, "repository", environment.GITHUB_REPOSITORY),
     branch: flag(
       rest,
       "branch",
@@ -53,6 +50,20 @@ export function devDeliveryCliOptions(args = [], environment = process.env) {
       "expected-old",
       environment.BUILDCHAIN_DEV_DELIVERY_EXPECTED_OLD,
     ),
+    legacyTerminalRecoveryPath: flag(
+      rest,
+      "legacy-terminal-recovery",
+      environment.BUILDCHAIN_DEV_DELIVERY_LEGACY_TERMINAL_RECOVERY,
+    ),
+  };
+}
+
+export function devDeliveryCliOptions(args = [], environment = process.env) {
+  const [command = "", ...rest] = args;
+  return {
+    command,
+    repository: flag(rest, "repository", environment.GITHUB_REPOSITORY),
+    ...authorityStateOptions(rest, environment),
     pullRequestNumber: flag(
       rest,
       "pull-request",

package/scripts/dev-delivery-warrant.mjs

@@ -15,6 +15,7 @@ import {
   settleDevDeliveryTerminalEvent,
   submitDevDeliveryCandidate,
 } from "../packages/core/dev-delivery-warrant.js";
+import { recoverLegacyTerminalDevDeliveryQueue } from "../packages/core/dev-delivery-warrant-legacy-recovery.js";
 import { runV4DeliveryWarrantReadCandidate } from "../packages/core/v4-delivery-warrant-read-candidate.js";
 
 import { GitHubDevDeliveryStore } from "./dev-delivery-warrant-store.mjs";
@@ -80,7 +81,9 @@ function reconcileTerminalEvidenceCommand(queue, options) {
 
 function requireTerminalEvidenceCas(options) {
   if (
-    options.command === "reconcile-terminal-evidence" &&
+    ["reconcile-terminal-evidence", "recover-legacy-terminal"].includes(
+      options.command,
+    ) &&
     options.execute &&
     !options.expectedOldStateRoot
   ) {
@@ -267,6 +270,13 @@ function transitionFor(command, queue, options) {
   }
   if (command === "recover")
     return recoverExpiredDevDeliveryWarrant(queue, { now: options.now });
+  if (command === "recover-legacy-terminal") {
+    return recoverLegacyTerminalDevDeliveryQueue(
+      queue,
+      jsonFile(options.legacyTerminalRecoveryPath, "legacy terminal recovery"),
+      { now: options.now },
+    );
+  }
   if (command === "close") {
     return closeDevDeliveryWarrant(queue, warrantIdentity(queue, options), {
       outcome: options.outcome,
@@ -416,22 +426,33 @@ export async function runDevDeliveryCommand(optionsInput = {}, clientInput) {
     stateRef: options.stateRef,
     protectedBase: options.branch,
     now: options.now,
-    allowLegacyV3Readback: options.command === "observe",
+    allowLegacyV3Readback: ["observe", "recover-legacy-terminal"].includes(
+      options.command,
+    ),
   });
+  let concurrencyRecovery = null;
   if (
     options.expectedOldStateRoot &&
     loaded.queue.stateRoot !== options.expectedOldStateRoot
   ) {
-    throw new Error(
-      `expected-old state drift: ${loaded.queue.stateRoot} != ${options.expectedOldStateRoot}`,
-    );
+    if (options.command !== "heartbeat") {
+      throw new Error(
+        `expected-old state drift: ${loaded.queue.stateRoot} != ${options.expectedOldStateRoot}`,
+      );
+    }
+    concurrencyRecovery = {
+      schema: "kungfu.buildchain.dev-delivery-concurrency-recovery/v1",
+      action: "heartbeat-state-root-rebased",
+      requestedStateRoot: options.expectedOldStateRoot,
+      observedStateRoot: loaded.queue.stateRoot,
+      observedCommitSha: loaded.commitSha,
+    };
   }
   if (options.command === "observe") return observeQueue(loaded, options);
   const initialLoaded = loaded;
   let changed = transitionFor(options.command, loaded.queue, options);
   let mutates = changed.queue.stateRoot !== loaded.queue.stateRoot;
   let write = null;
-  let concurrencyRecovery = null;
   if (options.execute && mutates) {
     if (changed.receipt.expectedOldStateRoot !== loaded.queue.stateRoot) {
       throw new Error(
@@ -496,7 +517,7 @@ export async function runDevDeliveryCommand(optionsInput = {}, clientInput) {
 }
 
 function usage() {
-  return "Usage:\n  buildchain dev warrant <submit|select|heartbeat|qualify|recover|close|settle|reconcile-terminal-evidence|cancel-queued|observe> --repository owner/repo --branch dev/vN/vN.M [--execute] [--output FILE] [--json]\n\nRead candidate:\n  observe --read-mode v4 --read-qualification FILE --read-qualification-root sha256:... --read-typescript-revision SHA --read-rust-revision SHA --read-validator-version TOKEN [--read-evidence-output FILE]\n";
+  return "Usage:\n  buildchain dev warrant <submit|select|heartbeat|qualify|recover|recover-legacy-terminal|close|settle|reconcile-terminal-evidence|cancel-queued|observe> --repository owner/repo --branch dev/vN/vN.M [--execute] [--output FILE] [--json]\n\nLegacy terminal recovery:\n  recover-legacy-terminal --expected-old sha256:... --legacy-terminal-recovery FILE [--execute]\n\nRead candidate:\n  observe --read-mode v4 --read-qualification FILE --read-qualification-root sha256:... --read-typescript-revision SHA --read-rust-revision SHA --read-validator-version TOKEN [--read-evidence-output FILE]\n";
 }
 
 async function main() {
@@ -513,6 +534,7 @@ async function main() {
       "heartbeat",
       "qualify",
       "recover",
+      "recover-legacy-terminal",
       "close",
       "settle",
       "reconcile-terminal-evidence",