@kungfu-tech/buildchain 4.0.1-alpha.5 → 4.0.1-alpha.6

package/scripts/resume-from-candidate-run.mjs

@@ -3,6 +3,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { execFileSync } from "node:child_process";
 import { pathToFileURL } from "node:url";
 
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
@@ -27,6 +28,15 @@ import {
 } from "../packages/core/publication-artifact-candidate.js";
 import { createPublicationSealedBundle } from "../packages/core/publication-sealed-bundle.js";
 import { releaseTransactionStateRef } from "../packages/core/publish-transaction.js";
+import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
+import { validateV4StageCapsule } from "../packages/core/v4-stage-capsule.js";
+import {
+  authorizeV4RuntimeSelection,
+  createV4RuntimeResumeLineage,
+  scanV4RuntimeSelectorPersistence,
+  v4RuntimeResumeDocumentRoot,
+  verifyV4RuntimeAuthorizationReceipt,
+} from "../packages/core/v4-runtime-ref-resume-authority.js";
 
 function env(name, fallback = "") {
   return process.env[name] || fallback;
@@ -99,8 +109,373 @@ function readOnlyJson(files, label) {
   return JSON.parse(fs.readFileSync(files[0].absolutePath, "utf8"));
 }
 
-async function readExistingTransaction({ repoInfo, apiUrl, token, fetchImpl, version }) {
-  const stateRef = releaseTransactionStateRef(version);
+function trackedRuntimePersistenceScan() {
+  const paths = execFileSync(
+    "git",
+    ["ls-files", ".github/workflows", ".github/actions", ".buildchain"],
+    { encoding: "utf8" },
+  )
+    .split(/\r?\n/)
+    .filter((entry) => /\.(?:json|toml|ya?ml)$/u.test(entry));
+  return scanV4RuntimeSelectorPersistence({ root: process.cwd(), paths });
+}
+
+export function verifyReleaseCandidateStageCapsules({ sidecar, passport, downloads }) {
+  if (
+    !sidecar ||
+    sidecar.contract !==
+      "kungfu-buildchain-v4-release-candidate-stage-capsules/v1" ||
+    sidecar.status !== "sealed"
+  ) {
+    throw new Error(
+      "cross-runtime recovery requires original sealed release-candidate Stage Capsules",
+    );
+  }
+  const payload = { ...sidecar };
+  delete payload.root;
+  const expectedAttempt =
+    `github-run:${passport.workflow.runId}:attempt:${passport.workflow.runAttempt}`;
+  if (
+    sidecar.root !== v4RuntimeResumeDocumentRoot(payload) ||
+    sidecar.repository !== passport.repository ||
+    sidecar.source?.sha !== passport.source.headSha ||
+    sidecar.source?.treeSha !== passport.source.treeHash ||
+    sidecar.buildAttempt?.id !== expectedAttempt ||
+    sidecar.buildAttempt?.runtimeSha !== passport.buildchain.sha ||
+    sidecar.consumerPolicyReceiptRoot !== passport.consumerPolicy?.receiptRoot
+  ) {
+    throw new Error("release-candidate Stage Capsule sidecar identity mismatch");
+  }
+  const artifactByName = new Map(downloads.map((entry) => [entry.artifact.name, entry]));
+  const required = [...passport.platformMatrix.map((entry) => entry.platformId)].sort();
+  const entries = [...(sidecar.capsules || [])].sort((left, right) =>
+    left.platform.localeCompare(right.platform),
+  );
+  if (
+    entries.length !== required.length ||
+    entries.some((entry, index) => entry.platform !== required[index])
+  ) {
+    throw new Error("release-candidate Stage Capsule platform set is incomplete");
+  }
+  return entries.map((entry) => {
+    validateV4StageCapsule(entry.capsule);
+    const download = artifactByName.get(entry.artifactName);
+    const artifact = entry.artifact;
+    if (
+      !download ||
+      artifact?.platformId !== entry.platform ||
+      artifact?.id !== String(download.artifact.id) ||
+      artifact?.name !== download.artifact.name ||
+      artifact?.digest !== entry.artifactDigest ||
+      artifact?.digest !== download.artifact.digest ||
+      artifact?.digest !== download.record.digest ||
+      artifact?.digest !== download.record.downloadedDigest ||
+      artifact?.expiresAt !==
+        new Date(download.artifact.expires_at).toISOString() ||
+      entry.capsule.identity.policyRoot !== sidecar.consumerPolicyReceiptRoot ||
+      entry.capsule.identity.sourceRoot !==
+        v4ContentRoot("candidate-identity", passport.source) ||
+      entry.capsule.identity.runtimeRoot !==
+        v4ContentRoot("candidate-identity", { sha: passport.buildchain.sha })
+    ) {
+      throw new Error(
+        `Stage Capsule ${entry.platform} does not bind the verified provider artifact`,
+      );
+    }
+    return {
+      platform: entry.platform,
+      capsuleRoot: entry.capsule.capsuleRoot,
+      identityRoot: entry.capsule.identityRoot,
+      artifactDigest: entry.artifactDigest,
+      sourceSha: sidecar.source.sha,
+      sourceTreeSha: sidecar.source.treeSha,
+      policyRoot: sidecar.consumerPolicyReceiptRoot,
+      buildRuntimeSha: sidecar.buildAttempt.runtimeSha,
+      sealed: true,
+    };
+  });
+}
+
+export function validateV4RuntimeResumePublicReadback({
+  targetRef,
+  targetSha,
+  alphaSha,
+  exactTagSha,
+  tagLineage,
+  runtimeSha,
+  version,
+  transaction,
+  main,
+  npm,
+}) {
+  if (
+    transaction?.target_ref !== targetRef ||
+    transaction?.version !== version ||
+    exactTagSha !== transaction?.source_sha ||
+    !["ahead", "identical"].includes(tagLineage?.status) ||
+    alphaSha !== runtimeSha ||
+    !targetSha ||
+    npm["dist-tags"]?.alpha !== version ||
+    npm.versions?.[version]?.dist?.integrity !== main.digest
+  ) {
+    throw new Error(
+      "cross-runtime final public readback does not match durable publication bytes and runtime",
+    );
+  }
+}
+
+export async function readPublicResumeState({
+  repoInfo,
+  targetRef,
+  runtimeSha,
+  version,
+  transaction,
+  token,
+  apiUrl,
+  fetchImpl,
+}) {
+  const readRef = async (ref) =>
+    (await githubJson({
+      apiUrl,
+      token,
+      fetchImpl,
+      path: `/repos/${repoInfo.owner}/${repoInfo.repo}/git/ref/${ref}`,
+    })).object?.sha || "";
+  const main = transaction?.artifacts?.find((entry) => entry.kind === "npm" && entry.required !== false);
+  if (!main || main.ref !== version || !main.digest) {
+    throw new Error(
+      "cross-runtime recovery requires exact durable npm publication evidence",
+    );
+  }
+  const packageUrl =
+    `https://registry.npmjs.org/${encodeURIComponent(main.name)}`;
+  const exactTag = transaction.exact_tag || `v${version}`;
+  const [targetSha, alphaSha, exactTagSha, npmResponse] = await Promise.all([
+    readRef(`heads/${targetRef}`),
+    readRef("tags/v4-alpha"),
+    readRef(`tags/${exactTag}`),
+    fetchImpl(packageUrl),
+  ]);
+  if (!npmResponse.ok) {
+    throw new Error(`npm public readback failed with HTTP ${npmResponse.status}`);
+  }
+  const npm = await npmResponse.json();
+  const tagLineage = await githubJson({
+    apiUrl,
+    token,
+    fetchImpl,
+    path: `/repos/${repoInfo.owner}/${repoInfo.repo}/compare/${exactTagSha}...${targetSha}`,
+  });
+  validateV4RuntimeResumePublicReadback({
+    targetRef,
+    targetSha,
+    alphaSha,
+    exactTagSha,
+    tagLineage,
+    runtimeSha,
+    version,
+    transaction,
+    main,
+    npm,
+  });
+  const body = {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-v4-runtime-resume-public-readback/v1",
+    observedAt: new Date().toISOString(),
+    repository: repoInfo.fullName,
+    version,
+    refs: {
+      target: { ref: targetRef, sha: targetSha },
+      floating: { ref: "v4-alpha", sha: alphaSha },
+      exactTag: { ref: exactTag, sha: exactTagSha },
+    },
+    npm: {
+      package: main.name,
+      version,
+      distTag: "alpha",
+      integrity: npm.versions[version].dist.integrity,
+    },
+  };
+  return { ...body, root: v4RuntimeResumeDocumentRoot(body) };
+}
+
+function prepareRuntimeResumeEvidence({
+  repoInfo,
+  targetRef,
+  runtimeSha,
+  version,
+  passport,
+  sidecar,
+  stageCapsules,
+  recovery,
+  outputDir,
+}) {
+  const authorizationPath = path.resolve(
+    ".buildchain/release-candidate/v4-runtime-authorization.json",
+  );
+  if (!fs.existsSync(authorizationPath)) {
+    throw new Error(
+      "cross-runtime recovery requires a fresh runtime authorization receipt",
+    );
+  }
+  const delegated = readOnlyJson([{ absolutePath: authorizationPath }], "runtime authorization");
+  const delegatedVerification = verifyV4RuntimeAuthorizationReceipt({
+    receipt: delegated.receipt,
+    receiptRoot: delegated.receiptRoot,
+    repository: repoInfo.fullName,
+    runtimeSha,
+  });
+  if (!delegatedVerification.ok) {
+    throw new Error(
+      `fresh recovery runtime authorization rejected: ${delegatedVerification.failures.join(", ")}`,
+    );
+  }
+  const policy = passport.consumerPolicy.receipt;
+  const authorization = authorizeV4RuntimeSelection({
+    repository: repoInfo.fullName,
+    eventName: "workflow_dispatch",
+    mode: "resume",
+    actor: delegated.receipt.actor.login,
+    actorPermission: delegated.receipt.actor.permission,
+    reason:
+      `resume sealed candidate run ${passport.workflow.runId} from a tree-equivalent protected source`,
+    authorizedAt: new Date().toISOString(),
+    sourceSha: sidecar.source.sha,
+    sourceTreeSha: sidecar.source.treeSha,
+    requestedRef: delegated.receipt.request.ref,
+    resolvedRuntimeSha: runtimeSha,
+    approvedRefReadbacks: delegated.receipt.runtime.reachableFrom,
+    stableContractLockRoot: policy.contractLocks.stable.root,
+    alphaContractLockRoot: policy.contractLocks.alpha.root,
+    consumerPolicyReceiptRoot: sidecar.consumerPolicyReceiptRoot,
+    persistenceScan: trackedRuntimePersistenceScan(),
+  });
+  const planBody = {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-v4-runtime-resume-plan/v1",
+    originalRunId: String(passport.workflow.runId),
+    resumeRunId: String(env("GITHUB_RUN_ID")),
+    recoveryReceiptRoot: recovery.receipt.root,
+    requiredPlatforms: stageCapsules.map((entry) => entry.platform),
+    reusedCapsuleRoots: stageCapsules.map((entry) => entry.capsuleRoot),
+    rebuildPlatforms: [],
+    skippedBuildStages: recovery.receipt.skippedBuildStages,
+  };
+  const plan = { ...planBody, root: v4RuntimeResumeDocumentRoot(planBody) };
+  const materialBody = {
+    schemaVersion: 1,
+    contract: "kungfu-buildchain-v4-runtime-resume-material/v1",
+    repository: repoInfo.fullName,
+    targetRef,
+    runtimeSha,
+    version,
+    authorization: authorization.receipt,
+    authorizationRoot: authorization.receiptRoot,
+    buildAttempt: sidecar.buildAttempt,
+    resumeAttempt: {
+      id: `github-run:${env("GITHUB_RUN_ID")}:attempt:${env("GITHUB_RUN_ATTEMPT", "1")}`,
+      runtimeSha,
+    },
+    source: sidecar.source,
+    consumerPolicyReceiptRoot: sidecar.consumerPolicyReceiptRoot,
+    requiredPlatforms: stageCapsules.map((entry) => entry.platform),
+    stageCapsules,
+    resumePlanRoot: plan.root,
+    floatingRefBefore: {
+      ref: "v4-alpha",
+      sha: sidecar.buildAttempt.runtimeSha,
+    },
+  };
+  const material = {
+    ...materialBody,
+    root: v4RuntimeResumeDocumentRoot(materialBody),
+  };
+  for (const [name, value] of [
+    ["v4-runtime-resume-plan.json", plan],
+    ["v4-runtime-resume-material.json", material],
+  ]) {
+    fs.writeFileSync(
+      path.join(outputDir, name),
+      `${JSON.stringify(value, null, 2)}\n`,
+    );
+  }
+  return path.join(outputDir, "v4-runtime-resume-evidence.json");
+}
+
+export async function finalizeRuntimeResumeEvidence({
+  materialPath,
+  transaction,
+  token = env("GITHUB_TOKEN", env("INPUT_TOKEN")),
+  apiUrl = env("GITHUB_API_URL", "https://api.github.com"),
+  fetchImpl = globalThis.fetch,
+  outputDir = path.dirname(materialPath),
+}) {
+  const material = JSON.parse(fs.readFileSync(materialPath, "utf8"));
+  const body = { ...material };
+  delete body.root;
+  if (
+    material.contract !== "kungfu-buildchain-v4-runtime-resume-material/v1" ||
+    material.root !== v4RuntimeResumeDocumentRoot(body)
+  ) {
+    throw new Error("cross-runtime resume material root mismatch");
+  }
+  const repoInfo = splitRepository(material.repository);
+  const version = env("BUILDCHAIN_RELEASE_VERSION", material.version);
+  const targetRef = env("BUILDCHAIN_RELEASE_TARGET_REF", material.targetRef);
+  if (
+    version !== material.version ||
+    targetRef !== material.targetRef ||
+    transaction?.version !== version ||
+    transaction?.state !== "complete"
+  ) {
+    throw new Error(
+      "cross-runtime resume finalization does not match the completed publication transaction",
+    );
+  }
+  const readback = await readPublicResumeState({
+    repoInfo,
+    targetRef,
+    runtimeSha: material.runtimeSha,
+    version,
+    transaction,
+    token,
+    apiUrl,
+    fetchImpl,
+  });
+  const resumed = createV4RuntimeResumeLineage({
+    authorization: material.authorization,
+    authorizationRoot: material.authorizationRoot,
+    buildAttempt: material.buildAttempt,
+    resumeAttempt: material.resumeAttempt,
+    source: material.source,
+    consumerPolicyReceiptRoot: material.consumerPolicyReceiptRoot,
+    requiredPlatforms: material.requiredPlatforms,
+    stageCapsules: material.stageCapsules,
+    resumePlanRoot: material.resumePlanRoot,
+    finalPublicReadbackRoot: readback.root,
+    floatingRefBefore: material.floatingRefBefore,
+    floatingRefAfter: { ref: "v4-alpha", sha: material.runtimeSha },
+  });
+  const evidence = {
+    authorization: material.authorization,
+    authorizationRoot: material.authorizationRoot,
+    lineage: resumed.lineage,
+    lineageRoot: resumed.lineageRoot,
+  };
+  const evidencePath = path.join(outputDir, "v4-runtime-resume-evidence.json");
+  for (const [name, value] of [
+    ["v4-runtime-resume-public-readback.json", readback],
+    [path.basename(evidencePath), evidence],
+  ]) {
+    fs.writeFileSync(
+      path.join(outputDir, name),
+      `${JSON.stringify(value, null, 2)}\n`,
+    );
+  }
+  return { evidence, path: evidencePath, readback };
+}
+
+async function readTransactionAtRef({ repoInfo, apiUrl, token, fetchImpl, stateRef }) {
   const response = await githubJson({
     apiUrl,
     token,
@@ -109,10 +484,65 @@ async function readExistingTransaction({ repoInfo, apiUrl, token, fetchImpl, ver
     path: `/repos/${repoInfo.owner}/${repoInfo.repo}/contents/state.json?ref=${encodeURIComponent(stateRef)}`,
   });
   if (!response) return undefined;
-  if (response.type !== "file" || response.encoding !== "base64" || !response.content) {
-    throw new Error(`durable transaction ${stateRef} did not expose a base64 state.json file`);
+  if (
+    response.type !== "file" ||
+    response.encoding !== "base64" ||
+    !response.content
+  ) {
+    throw new Error(
+      `durable transaction ${stateRef} did not expose a base64 state.json file`,
+    );
+  }
+  return JSON.parse(
+    Buffer.from(
+      String(response.content).replace(/\s/g, ""),
+      "base64",
+    ).toString("utf8"),
+  );
+}
+
+async function readExistingTransaction({
+  repoInfo,
+  apiUrl,
+  token,
+  fetchImpl,
+  version,
+}) {
+  return readTransactionAtRef({
+    repoInfo,
+    apiUrl,
+    token,
+    fetchImpl,
+    stateRef: releaseTransactionStateRef(version),
+  });
+}
+
+async function readExistingTransactionById({
+  repoInfo,
+  apiUrl,
+  token,
+  fetchImpl,
+  transactionId,
+}) {
+  if (!transactionId) return undefined;
+  const statePrefix = "buildchain/release-state/";
+  const refs = await githubJson({
+    apiUrl,
+    token,
+    fetchImpl,
+    path: `/repos/${repoInfo.owner}/${repoInfo.repo}/git/matching-refs/heads/${statePrefix}`,
+  });
+  for (const ref of refs) {
+    const transaction = await readTransactionAtRef({
+      repoInfo,
+      apiUrl,
+      token,
+      fetchImpl,
+      stateRef: String(ref.ref).replace(/^refs\/heads\//, ""),
+    });
+    if (transaction?.id === transactionId) return transaction;
   }
-  return JSON.parse(Buffer.from(String(response.content).replace(/\s/g, ""), "base64").toString("utf8"));
+  throw new Error(`durable publication transaction ${transactionId} was not found`);
 }
 
 function outputPath(filePath) {
@@ -349,6 +779,14 @@ async function recoverCandidateEvidence({
   for (const artifact of [selected.passport, selected.summary]) initialDownloads.push(await downloadArtifact({ artifact, repoInfo, apiUrl, token, archiveDir, bundleRoot, fetchImpl }));
   const passport = readOnlyJson(initialDownloads[0].files.filter((file) => path.basename(file.path) === "release-candidate-passport.json"), "release-candidate-passport.json");
   const buildSummary = readOnlyJson(initialDownloads[1].files.filter((file) => path.basename(file.path) === "build-summary.json"), "build-summary.json");
+  const sidecarFiles = initialDownloads[0].files.filter(
+    (file) =>
+      path.basename(file.path) === "release-candidate-stage-capsules.json",
+  );
+  const stageCapsuleSidecar =
+    sidecarFiles.length === 1
+      ? readOnlyJson(sidecarFiles, "release-candidate-stage-capsules.json")
+      : undefined;
   const { names: requiredNames, publicationNames } = candidateArtifactNames({ passport, selected, artifacts, artifactPatterns });
   const chosen = artifacts.filter((artifact) => requiredNames.has(artifact.name));
   if (chosen.length !== requiredNames.size) {
@@ -360,7 +798,7 @@ async function recoverCandidateEvidence({
   for (const artifact of chosen.filter((entry) => ![selected.passport.id, selected.summary.id].includes(entry.id))) downloads.push(await downloadArtifact({ artifact, repoInfo, apiUrl, token, archiveDir, bundleRoot, fetchImpl }));
   return {
     run, workflow, selected, resolvedOutput, bundleRoot, initialDownloads,
-    passport, buildSummary, chosen, downloads, publicationNames,
+    passport, buildSummary, stageCapsuleSidecar, chosen, downloads, publicationNames,
   };
 }
 
@@ -370,6 +808,52 @@ async function resolveTargetAdvance({ observedTargetSha, targetSha, transactionI
   return { status: comparison.status, mergeIsAncestor: ["ahead", "identical"].includes(comparison.status) };
 }
 
+async function resolveRecoveryTransaction({
+  repoInfo,
+  apiUrl,
+  token,
+  fetchImpl,
+  transactionId,
+  publicationVersion,
+}) {
+  const byId = await readExistingTransactionById({
+    repoInfo,
+    apiUrl,
+    token,
+    fetchImpl,
+    transactionId,
+  });
+  const version = byId?.version || publicationVersion;
+  const transaction = byId || await readExistingTransaction({
+    repoInfo,
+    apiUrl,
+    token,
+    fetchImpl,
+    version,
+  });
+  return { version, transaction };
+}
+
+function resolveRecoveredStageCapsules({
+  candidateRuntimeSha,
+  runtimeSha,
+  sidecar,
+  passport,
+  downloads,
+}) {
+  if (candidateRuntimeSha === runtimeSha) return [];
+  return verifyReleaseCandidateStageCapsules({ sidecar, passport, downloads });
+}
+
+function validateRecoveryCoordinates(candidateRunId, expectedSourceTree, expectedCandidateRoot) {
+  const runId = String(candidateRunId || "").trim();
+  if (!/^\d+$/.test(runId)) throw new Error("candidate run ID must be numeric");
+  if (!String(expectedSourceTree || "").trim() && !String(expectedCandidateRoot || "").trim()) {
+    throw new Error("candidate recovery requires expectedSourceTree or expectedCandidateRoot");
+  }
+  return runId;
+}
+
 export async function resumeFromCandidateRun({
   repository, targetRepository = repository, candidateRunId,
   expectedWorkflowFile, expectedWorkflowName,
@@ -384,16 +868,12 @@ export async function resumeFromCandidateRun({
   recoveryRunId = env("GITHUB_RUN_ID"), fetchImpl = globalThis.fetch,
 } = {}) {
   const repoInfo = splitRepository(repository);
-  const runId = String(candidateRunId || "").trim();
-  if (!/^\d+$/.test(runId)) throw new Error("candidate run ID must be numeric");
-  if (!String(expectedSourceTree || "").trim() && !String(expectedCandidateRoot || "").trim()) {
-    throw new Error("candidate recovery requires expectedSourceTree or expectedCandidateRoot");
-  }
+  const runId = validateRecoveryCoordinates(candidateRunId, expectedSourceTree, expectedCandidateRoot);
   const archiveDir = fs.mkdtempSync(path.join(os.tmpdir(), "buildchain-resume-"));
   try {
     const {
       run, workflow, selected, resolvedOutput, bundleRoot, initialDownloads,
-      passport, buildSummary, chosen, downloads, publicationNames,
+      passport, buildSummary, stageCapsuleSidecar, chosen, downloads, publicationNames,
     } = await recoverCandidateEvidence({
       repoInfo, runId, artifactName, artifactPatterns, requiredArtifactCount,
       outputDir, apiUrl, token, fetchImpl, archiveDir,
@@ -419,8 +899,24 @@ export async function resumeFromCandidateRun({
       releasePatterns,
       platformManifests: platformManifestEvidence.manifests,
     });
-    const candidateVersion = publication.version;
-    const existingTransaction = await readExistingTransaction({ repoInfo, apiUrl, token, fetchImpl, version: candidateVersion });
+    const stageCapsules = resolveRecoveredStageCapsules({
+      candidateRuntimeSha,
+      runtimeSha,
+      sidecar: stageCapsuleSidecar,
+      passport,
+      downloads,
+    });
+    const {
+      version: candidateVersion,
+      transaction: existingTransaction,
+    } = await resolveRecoveryTransaction({
+      repoInfo,
+      apiUrl,
+      token,
+      fetchImpl,
+      transactionId,
+      publicationVersion: publication.version,
+    });
     const targetAdvance = await resolveTargetAdvance({
       observedTargetSha, targetSha, transactionId, existingTransaction,
       repoInfo, apiUrl, token, fetchImpl,
@@ -491,6 +987,19 @@ export async function resumeFromCandidateRun({
     if (publication.manifest) fs.writeFileSync(sealedManifestPath, `${JSON.stringify(publication.manifest, null, 2)}\n`);
     const publishRequiredArtifacts = publication.publishRequiredArtifacts;
     fs.writeFileSync(requiredArtifactsPath, `${JSON.stringify(publishRequiredArtifacts, null, 2)}\n`);
+    const runtimeResumeEvidencePath = stageCapsules.length
+      ? prepareRuntimeResumeEvidence({
+          repoInfo,
+          targetRef,
+          runtimeSha,
+          version: candidateVersion,
+          passport,
+          sidecar: stageCapsuleSidecar,
+          stageCapsules,
+          recovery,
+          outputDir: resolvedOutput,
+        })
+      : "";
     const tarballs = publication.npmArtifacts.map((entry) => outputPath(entry.file.absolutePath));
     return {
       enabled: true,
@@ -514,6 +1023,9 @@ export async function resumeFromCandidateRun({
         sealedBundleRoot: publication.manifest ? outputPath(bundleRoot) : "",
         sealedBundleManifest: publication.manifest ? outputPath(sealedManifestPath) : "",
         recoveryReceipt: outputPath(recoveryReceiptPath),
+        runtimeResumeEvidence: runtimeResumeEvidencePath
+          ? outputPath(runtimeResumeEvidencePath)
+          : "",
       },
     };
   } finally {
@@ -565,6 +1077,10 @@ export async function resumeFromCandidateRunCli() {
       "release-candidate-run-url": result.run.url,
       "release-candidate-recovery-receipt-path": result.paths.recoveryReceipt,
       "release-candidate-recovery-root": result.receipt.root,
+      "v4-runtime-resume-evidence-path": result.paths.runtimeResumeEvidence,
+      "v4-runtime-resume-finalize-command": result.paths.runtimeResumeEvidence
+        ? "node .buildchain/runtime/promotion-shell/scripts/resume-from-candidate-run.mjs finalize"
+        : "",
       "release-candidate-root": result.candidateRoot,
       "release-candidate-artifact-root": result.artifactRoot,
       "publish-sealed-bundle-root": result.paths.sealedBundleRoot,
@@ -586,7 +1102,21 @@ export async function resumeFromCandidateRunCli() {
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
-  resumeFromCandidateRunCli().catch((error) => {
+  const operation = process.argv[2] === "finalize"
+    ? finalizeRuntimeResumeEvidence({
+        materialPath: requiredEnv("BUILDCHAIN_V4_RUNTIME_RESUME_MATERIAL"),
+        transaction: JSON.parse(
+          requiredEnv("BUILDCHAIN_RELEASE_TRANSACTION_JSON"),
+        ),
+        outputDir: env(
+          "BUILDCHAIN_RELEASE_PASSPORT_OUTPUT_DIR",
+          path.dirname(requiredEnv("BUILDCHAIN_V4_RUNTIME_RESUME_MATERIAL")),
+        ),
+      }).then((result) =>
+        console.log(JSON.stringify({ files: [outputPath(result.path)] })),
+      )
+    : resumeFromCandidateRunCli();
+  operation.catch((error) => {
     const failure = error.recoveryFailure || recoveryFailure(error);
     console.error(`candidate recovery rejected [${failure.code}]: ${failure.reason}`);
     console.error(`next action: ${failure.nextAction}`);

package/scripts/site-capability-metadata.mjs

@@ -13,6 +13,11 @@ export function cliCommandMeta(id) {
   const map = new Map(Object.entries({
     audit: { group: "release-passport-trust", purpose: "Inspect read-only publication authority audit commands." },
     architecture: { group: "governance-versioning", purpose: "Inspect and qualify the Buildchain v4 capability and state-machine architecture contract." },
+    "adopter-delivery": { group: "reusable-build", purpose: "Run public protocol-neutral adopter delivery, exact readback, N-1 bootstrap, and published archive checks." },
+    "adopter-delivery-run": { group: "reusable-build", purpose: "Run one exact public adopter driver and artifact-profile selection offline." },
+    "adopter-delivery-verify": { group: "reusable-build", purpose: "Recompute and verify exact adopter delivery readback without authority widening." },
+    "adopter-delivery-bootstrap": { group: "reusable-build", purpose: "Qualify exact v3 N-1 bootstrap lineage against the v4 adopter delivery substrate." },
+    "adopter-delivery-archive": { group: "reusable-build", purpose: "Load content-addressed public npm archive bytes and verify their exact identity and readback root." },
     "architecture-list": { group: "governance-versioning", purpose: "Generate the Agent-readable capability list from the validated v4 architecture manifest." },
     "architecture-qualify": { group: "governance-versioning", purpose: "Qualify an exact candidate against a distinct N-1 Git authority revision without candidate self-qualification." },
     "architecture-show": { group: "governance-versioning", purpose: "Generate one capability and its state-machine details from the validated v4 architecture manifest." },
@@ -223,6 +228,17 @@ export function nodeApiMeta(exportName) {
     "./v4-runtime-ref-resume-authority": { group: "release-passport-trust", summary: "Transient exact-runtime authorization, persisted-selector rejection, fresh-attempt Stage Capsule reuse, and A+B Passport lineage APIs." },
     "./v4-tail-reseal": { group: "release-passport-trust", summary: "Effect-pure retained Stage Capsule validation and explicit Warrant-, credential-, and release-tail-fenced macOS reseal planning APIs." },
     "./v4-tail-reseal-receipt": { group: "release-passport-trust", summary: "Four-platform byte readback, standard candidate Passport binding, and terminal v4 tail-reseal receipt APIs." },
+    "./v4-publication-rehearsal": { group: "release-passport-trust", summary: "Content-addressed v4 publication rehearsal capsules, shared production release-tail execution, replay, provider observation, and fail-closed verification APIs." },
+    "./adopter-delivery-gate": { group: "reusable-build", summary: "Protocol-neutral adopter delivery gate, driver interface, artifact profiles, and canonical result APIs." },
+    "./kfd-adopter-category-driver": { group: "kfd-trust", summary: "Published KFD adopter-category driver and exact package-cut verification APIs." },
+    "./buildchain-delivery-infrastructure": { group: "reusable-build", summary: "Public delivery-infrastructure instance creation and KFD verification APIs." },
+    "./buildchain-delivery-bootstrap": { group: "reusable-build", summary: "Protected, published N-1 Buildchain delivery bootstrap qualification APIs." },
+    "./buildchain-delivery-self-dogfood": { group: "reusable-build", summary: "Public archive-backed Buildchain delivery-infrastructure self-dogfood APIs." },
+    "./published-delivery-authority": { group: "release-passport-trust", summary: "Content-addressed public Buildchain and KFD archive loading and identity verification APIs." },
+    "./legacy-kfd-adopter-driver": { group: "kfd-trust", summary: "One-way legacy KFD support-matrix adapter driver APIs." },
+    "./adopter-delivery-passport": { group: "release-passport-trust", summary: "Non-authoritative adopter delivery Release Passport binding and substitution checks." },
+    "./adopter-delivery-vectors": { group: "reusable-build", summary: "Rooted public adopter delivery conformance vector suite APIs." },
+    "./v4-adopter-delivery": { group: "reusable-build", summary: "Public v4 adopter delivery runtime, exact readback, N-1 lineage, and published archive verification APIs." },
     "./release-candidate-recovery": { group: "release-passport-trust", summary: "Fail-closed verification and immutable receipts for reusing a successful sealed candidate run without rebuilding product payloads." },
     "./release-train": { group: "governance-versioning", summary: "Frozen Release Cut identity, rooted Release Train transitions, Dev observations, supersession, replay, and legacy read compatibility APIs." },
     "./next-development-transition": { group: "governance-versioning", summary: "Provider-neutral completed-Alpha preservation and rooted next-development state, version-model, idempotency, and local materialization APIs." },