@kungfu-tech/buildchain 3.0.6-alpha.6 → 3.0.6

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

@@ -9,13 +9,19 @@ import {
   matchesGithubDeploymentPolicy,
 } from "../packages/core/publication-control-plane-audit.js";
 
+const GITHUB_JSON_MAX_BUFFER = 16 * 1024 * 1024;
+
 function flag(name, fallback = "") {
   const index = process.argv.indexOf(`--${name}`);
   return index === -1 ? fallback : String(process.argv[index + 1] || "");
 }
 
 function commandJson(command, args, label) {
-  const result = spawnSync(command, args, { encoding: "utf8", timeout: 60_000 });
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    timeout: 60_000,
+    maxBuffer: GITHUB_JSON_MAX_BUFFER,
+  });
   if (result.status !== 0) {
     const category = /401|E401|unauthorized/i.test(result.stderr) ? "unauthorized" : "unavailable";
     throw new Error(`${label} is ${category}; publication control-plane audit fails closed`);
@@ -35,6 +41,7 @@ function githubJsonOptional(apiPath, label, fallback) {
   const result = spawnSync("gh", ["api", apiPath, "-H", "Accept: application/vnd.github+json"], {
     encoding: "utf8",
     timeout: 60_000,
+    maxBuffer: GITHUB_JSON_MAX_BUFFER,
   });
   if (result.status !== 0) {
     if (/404|not found/i.test(`${result.stdout}\n${result.stderr}`)) return fallback;
@@ -52,6 +59,7 @@ function githubJsonReadLimited(apiPath, label, fallback) {
   const result = spawnSync("gh", ["api", apiPath, "-H", "Accept: application/vnd.github+json"], {
     encoding: "utf8",
     timeout: 60_000,
+    maxBuffer: GITHUB_JSON_MAX_BUFFER,
   });
   if (result.status !== 0) {
     if (/401|403|404|unauthorized|forbidden|not found/i.test(`${result.stdout}\n${result.stderr}`)) return fallback;
@@ -355,9 +363,6 @@ function main() {
       review.user?.login !== mergedPullRequest?.user?.login &&
       String(review.commit_id || "").toLowerCase() === pullRequestHeadSha
     );
-    const checkRuns = /^[0-9a-f]{40}$/.test(pullRequestHeadSha)
-      ? githubJson(`repos/${repository}/commits/${pullRequestHeadSha}/check-runs?per_page=100`, "merged pull-request head check runs")
-      : { check_runs: [] };
     const requiredStatusCheckPolicy = branchState.protection?.required_status_checks || {};
     const requiredStatusChecks = [...new Set([
       ...(requiredStatusCheckPolicy.contexts || []),
@@ -372,6 +377,9 @@ function main() {
     const resolvedRequiredStatusCheck = exactRequiredStatusCheck ||
       (prefixedRequiredStatusChecks.length === 1 ? prefixedRequiredStatusChecks[0] : requiredStatusCheck);
     const requiredStatusCheckMatchCount = exactRequiredStatusCheck ? 1 : prefixedRequiredStatusChecks.length;
+    const checkRuns = /^[0-9a-f]{40}$/.test(pullRequestHeadSha)
+      ? githubJson(`repos/${repository}/commits/${pullRequestHeadSha}/check-runs?check_name=${encodeURIComponent(resolvedRequiredStatusCheck)}&filter=latest&per_page=100`, "merged pull-request required check runs")
+      : { check_runs: [] };
     const requiredCheckSource = (requiredStatusCheckPolicy.checks || []).find((entry) =>
       entry.context === resolvedRequiredStatusCheck
     );

package/scripts/check-inventory.mjs

@@ -276,16 +276,25 @@ if (channelPromotionWorkflow !== generateChannelPromotionWorkflow(advancedPromot
 }
 for (const requiredSnippet of [
   "buildchain-channel:",
-  `/.github/workflows/.release-candidate-promote.yml@v${selfDogfoodMajor}-alpha`,
+  `/${promotionShellRouting.alpha.workflowPath}@${promotionShellRouting.alpha.callRef}`,
   `/${promotionShellRouting.stable.workflowPath}@${promotionShellRouting.stable.callRef}`,
   `STABLE_SHELL_REF: v${selfDogfoodMajor}`,
   "promotion-contract-lock-digest:",
   "authorize-promotion-runtime-override.cjs",
+  "BUILDCHAIN_ROUTER_REPOSITORY: ${{ inputs.buildchain-repository }}",
+  "BUILDCHAIN_RESUME_RUNTIME_SHA: ${{ inputs.resume-buildchain-runtime-sha }}",
+  "git ls-remote",
+  "Recovery router ref does not match resume-buildchain-runtime-sha",
 ]) {
   if (!channelPromotionWorkflow.includes(requiredSnippet)) {
     throw new Error(`channel promotion workflow missing routing contract: ${requiredSnippet}`);
   }
 }
+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}`);
+  }
+}
 const promotionOverrideAuthorization = fs.readFileSync(
   path.join(root, "scripts/authorize-promotion-runtime-override.cjs"),
   "utf8",

package/scripts/generate-channel-promotion-workflow.mjs

@@ -130,8 +130,8 @@ function validateWorkflowRoute(name, route, expectedLogicalRef) {
   if (!/^\.github\/workflows\/[.a-z0-9-]+\.ya?ml$/.test(route.workflowPath || "")) {
     throw new Error(`promotion shell ${name} workflowPath must name a reusable workflow`);
   }
-  if (!/^(?:v[0-9]+(?:-alpha)?|[0-9a-f]{40})$/.test(route.callRef || "")) {
-    throw new Error(`promotion shell ${name} callRef must be an official channel ref or exact SHA`);
+  if (!/^(?:v[0-9]+(?:-alpha)?|train\/[A-Za-z0-9._+\/-]+|[0-9a-f]{40})$/.test(route.callRef || "")) {
+    throw new Error(`promotion shell ${name} callRef must be an official channel ref, trusted train, or exact SHA`);
   }
   if (typeof route.forwardInternalInputs !== "boolean") {
     throw new Error(`promotion shell ${name} forwardInternalInputs must be boolean`);
@@ -240,29 +240,45 @@ jobs:
         id: router
         shell: bash
         env:
-          BUILDCHAIN_ROUTER_WORKFLOW_REF: \${{ job.workflow_ref }}
-          BUILDCHAIN_ROUTER_WORKFLOW_REPOSITORY: \${{ job.workflow_repository }}
-          BUILDCHAIN_ROUTER_WORKFLOW_SHA: \${{ job.workflow_sha }}
+          BUILDCHAIN_ROUTER_REPOSITORY: \${{ inputs.buildchain-repository }}
+          BUILDCHAIN_ROUTER_REF: \${{ inputs.buildchain-ref }}
+          BUILDCHAIN_RESUME_RUN_ID: \${{ inputs.resume-candidate-run-id }}
+          BUILDCHAIN_RESUME_RUNTIME_SHA: \${{ inputs.resume-buildchain-runtime-sha }}
         run: |
           set -euo pipefail
-          workflow_ref="\${BUILDCHAIN_ROUTER_WORKFLOW_REF}"
-          repository="\${BUILDCHAIN_ROUTER_WORKFLOW_REPOSITORY}"
-          ref="\${workflow_ref##*@}"
+          repository="\${BUILDCHAIN_ROUTER_REPOSITORY}"
+          ref="\${BUILDCHAIN_ROUTER_REF}"
           ref="\${ref#refs/heads/}"
           ref="\${ref#refs/tags/}"
-          parsed_repository="\${workflow_ref%%/.github/workflows/*}"
-          if [[ -z "\${repository}" || "\${repository}" != "\${parsed_repository}" || -z "\${ref}" ]]; then
-            echo "::error::Unable to resolve promotion router source from job.workflow_ref=\${workflow_ref}"
+          if [[ ! "\${repository}" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ || -z "\${ref}" || "\${ref}" = /* || "\${ref}" = *..* ]]; then
+            echo "::error::Unable to resolve promotion router source from repository/ref inputs"
             exit 1
           fi
-          if [[ ! "\${BUILDCHAIN_ROUTER_WORKFLOW_SHA}" =~ ^[0-9a-fA-F]{40}$ ]]; then
-            echo "::error::job.workflow_sha is not an exact commit SHA"
+
+          remote_url="https://github.com/\${repository}.git"
+          refs="$(git ls-remote "\${remote_url}" "refs/heads/\${ref}" "refs/tags/\${ref}" "refs/tags/\${ref}^{}")"
+          head_sha="$(printf '%s\\n' "\${refs}" | awk -v name="refs/heads/\${ref}" '$2 == name { print tolower($1) }')"
+          tag_sha="$(printf '%s\\n' "\${refs}" | awk -v peeled="refs/tags/\${ref}^{}" -v name="refs/tags/\${ref}" '$2 == peeled { print tolower($1); found=1 } $2 == name && !found { fallback=tolower($1) } END { if (!found && fallback != "") print fallback }')"
+          if [[ -n "\${head_sha}" && -n "\${tag_sha}" && "\${head_sha}" != "\${tag_sha}" ]]; then
+            echo "::error::Promotion router ref is ambiguous between branch and tag"
+            exit 1
+          fi
+          sha="\${head_sha:-\${tag_sha}}"
+          if [[ ! "\${sha}" =~ ^[0-9a-f]{40}$ ]]; then
+            echo "::error::Promotion router ref did not resolve to one exact commit SHA"
             exit 1
           fi
+          if [[ -n "\${BUILDCHAIN_RESUME_RUN_ID}" ]]; then
+            expected_sha="\${BUILDCHAIN_RESUME_RUNTIME_SHA,,}"
+            if [[ ! "\${expected_sha}" =~ ^[0-9a-f]{40}$ || "\${sha}" != "\${expected_sha}" ]]; then
+              echo "::error::Recovery router ref does not match resume-buildchain-runtime-sha"
+              exit 1
+            fi
+          fi
           {
             echo "repository=\${repository}"
             echo "ref=\${ref}"
-            echo "sha=\${BUILDCHAIN_ROUTER_WORKFLOW_SHA,,}"
+            echo "sha=\${sha}"
           } >> "\${GITHUB_OUTPUT}"
 
       - name: Checkout promotion router

package/scripts/release-candidate-resolver.mjs

@@ -4,6 +4,8 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { execFileSync } from "node:child_process";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
 import { pathToFileURL } from "node:url";
 import { createResolvedPublicationSealedBundle } from "./publication-candidate-sealer.mjs";
 import { writeGitHubOutputs } from "./build-contract-core.mjs";
@@ -38,6 +40,9 @@ function assertSha(value, label = "sha") {
   return sha;
 }
 
+export const releaseCandidateRuntimeSha = (passport) =>
+  assertSha(passport?.buildchain?.sha, "release candidate Passport Buildchain runtime SHA").toLowerCase();
+
 function githubHeaders(token) {
   const headers = {
     accept: "application/vnd.github+json",
@@ -77,10 +82,32 @@ export async function githubDownload({ apiUrl, token, path: requestPath, outputP
     }
     throw new Error(`GitHub artifact download ${requestPath} failed with ${response.status}${detail ? `: ${detail}` : ""}`);
   }
-  fs.writeFileSync(outputPath, Buffer.from(await response.arrayBuffer()));
+  try {
+    if (response.body && typeof response.body.getReader === "function") {
+      await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(outputPath));
+    } else {
+      fs.writeFileSync(outputPath, Buffer.from(await response.arrayBuffer()));
+    }
+  } catch (error) {
+    fs.rmSync(outputPath, { force: true });
+    throw error;
+  }
   return outputPath;
 }
 
+function digestFileSync(filePath, algorithm, encoding) {
+  const hash = crypto.createHash(algorithm);
+  const descriptor = fs.openSync(filePath, "r");
+  const chunk = Buffer.allocUnsafe(8 * 1024 * 1024);
+  try {
+    let bytesRead = 0;
+    while ((bytesRead = fs.readSync(descriptor, chunk, 0, chunk.length, null)) > 0) hash.update(chunk.subarray(0, bytesRead));
+  } finally {
+    fs.closeSync(descriptor);
+  }
+  return hash.digest(encoding);
+}
+
 export function selectMergedChannelPullRequest({ pullRequests = [], targetRef, repository }) {
   const normalizedTarget = normalizeBranch(targetRef);
   const candidates = pullRequests.filter((pr) => {
@@ -256,7 +283,7 @@ function packageNameFromArtifactPath(filePath) {
 }
 
 function npmIntegrity(filePath) {
-  return `sha512-${crypto.createHash("sha512").update(fs.readFileSync(filePath)).digest("base64")}`;
+  return `sha512-${digestFileSync(filePath, "sha512", "base64")}`;
 }
 
 function readNpmPackageJsonFromTarball(tarballPath) {
@@ -360,9 +387,8 @@ export function selectReleaseCandidateArtifacts({ artifacts = [], artifactName =
 }
 
 export function verifyArtifactArchive({ artifact, archivePath } = {}) {
-  const bytes = fs.readFileSync(archivePath);
-  const size = bytes.length;
-  const digest = `sha256:${crypto.createHash("sha256").update(bytes).digest("hex")}`;
+  const size = fs.statSync(archivePath).size;
+  const digest = `sha256:${digestFileSync(archivePath, "sha256", "hex")}`;
   if (!artifact || artifact.expired === true) {
     throw new Error(`candidate artifact is missing or expired: ${artifact?.name || "<unknown>"}`);
   }
@@ -676,7 +702,7 @@ export async function resolveReleaseCandidateArtifacts({
         repository: repoInfo.fullName,
         sourceSha: passport.source?.headSha,
         sourceTreeSha: passport.source?.treeHash,
-        runtimeSha: runtimeSha || sha,
+        runtimeSha: releaseCandidateRuntimeSha(passport),
         releaseCandidateRoot: passport.candidateHash,
         npmArtifacts: npmTarballPaths.map((tarballPath) => ({
           path: tarballPath,

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

@@ -19,6 +19,7 @@ import {
 } from "./release-candidate-resolver.mjs";
 import {
   recoveryFailure,
+  validateRecoveryTargetRef,
   verifyReleaseCandidateRecovery,
 } from "../packages/core/release-candidate-recovery.js";
 import {
@@ -58,7 +59,16 @@ function safeName(value) {
 }
 
 function sha256File(filePath) {
-  return `sha256:${crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex")}`;
+  const hash = crypto.createHash("sha256");
+  const descriptor = fs.openSync(filePath, "r");
+  const chunk = Buffer.allocUnsafe(8 * 1024 * 1024);
+  try {
+    let bytesRead = 0;
+    while ((bytesRead = fs.readSync(descriptor, chunk, 0, chunk.length, null)) > 0) hash.update(chunk.subarray(0, bytesRead));
+  } finally {
+    fs.closeSync(descriptor);
+  }
+  return `sha256:${hash.digest("hex")}`;
 }
 
 function collectFiles(root) {
@@ -123,7 +133,11 @@ async function downloadArtifact({ artifact, repoInfo, apiUrl, token, archiveDir,
     path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/artifacts/${artifact.id}/zip`,
   });
   const archive = verifyArtifactArchive({ artifact, archivePath });
-  unzip(archivePath, artifactRoot);
+  try {
+    unzip(archivePath, artifactRoot);
+  } finally {
+    fs.rmSync(archivePath, { force: true });
+  }
   const files = collectFiles(artifactRoot);
   return {
     artifact,
@@ -164,9 +178,11 @@ function candidateArtifactNames({ passport, selected, artifacts, artifactPattern
   return names;
 }
 
-function normalizePlatformManifests(downloads, passport) {
+export function normalizePlatformManifests(downloads, passport) {
   const manifests = [];
   const evidenceByArtifact = new Map();
+  const platformById = new Map((passport.platformMatrix || []).map((entry) => [String(entry.platformId || ""), entry]));
+  const seenPlatformIds = new Set();
   function addEvidence(artifactName, files) {
     if (!artifactName) return;
     const evidenceFiles = evidenceByArtifact.get(artifactName) || new Map();
@@ -182,10 +198,15 @@ function normalizePlatformManifests(downloads, passport) {
   for (const download of downloads) {
     if (String(download.artifact.name).includes("-manifest-")) for (const file of download.files.filter((entry) => path.basename(entry.path) === "manifest.json")) {
       const manifest = JSON.parse(fs.readFileSync(file.absolutePath, "utf8"));
-      if (!manifest.artifactName) {
-        const platformId = String(manifest.platform?.id || manifest.platformId || "");
-        manifest.artifactName = (passport.platformMatrix || []).find((entry) => entry.platformId === platformId)?.artifactName || "";
+      const platformId = String(manifest.platform?.id || manifest.platformId || "");
+      const expectedPlatform = platformById.get(platformId);
+      if (!expectedPlatform) continue;
+      if (seenPlatformIds.has(platformId)) throw new Error(`candidate recovery found duplicate platform manifest for ${platformId}`);
+      if (manifest.artifactName && manifest.artifactName !== expectedPlatform.artifactName) {
+        throw new Error(`candidate recovery platform manifest ${platformId} names unexpected artifact ${manifest.artifactName}`);
       }
+      manifest.artifactName = expectedPlatform.artifactName;
+      seenPlatformIds.add(platformId);
       manifests.push(manifest);
       addEvidence(manifest.artifactName, download.record.files);
     }
@@ -223,42 +244,87 @@ function normalizeProductPayloadManifests(downloads) {
     .map((file) => JSON.parse(fs.readFileSync(file.absolutePath, "utf8"))));
 }
 
-function createSealedBundle({ downloads, bundleRoot, repository, passport, runtimeSha, publishPackageMain, releasePatterns }) {
+export function createRecoveredPublicationCandidate({
+  allFiles,
+  repository,
+  passport,
+  candidateRuntimeSha,
+}) {
+  if (passport.buildchain?.sha !== candidateRuntimeSha) {
+    throw new Error(
+      `recovered publication candidate runtime mismatch: passport=${passport.buildchain?.sha || "<empty>"} expected=${candidateRuntimeSha || "<empty>"}`,
+    );
+  }
+  const payload = {
+    schemaVersion: 1,
+    contract: PUBLICATION_ARTIFACT_CANDIDATE_CONTRACT,
+    repository,
+    sourceSha: passport.source.headSha,
+    sourceTreeSha: passport.source.treeHash,
+    runtimeSha: candidateRuntimeSha,
+    releaseCandidateRoot: `sha256:${passport.candidateHash}`,
+    files: allFiles.map(({ path: filePath, size, sha256 }) => ({ path: filePath, size, sha256 })),
+  };
+  return { ...payload, candidateDigest: publicationArtifactCandidateDigest(payload) };
+}
+
+export function createRecoveredPublication({ downloads, bundleRoot, repository, passport, candidateRuntimeSha, publishArtifactKind, publishPackageMain, releasePatterns, platformManifests }) {
   const allFiles = downloads.flatMap((download) => download.files.map((file) => ({
     path: path.relative(bundleRoot, file.absolutePath).split(path.sep).join("/"),
     size: file.size,
     sha256: file.sha256.replace(/^sha256:/, ""),
     absolutePath: file.absolutePath,
   }))).sort((left, right) => left.path.localeCompare(right.path));
+  const kind = String(publishArtifactKind || "npm");
+  const releaseMatchers = splitPatterns(releasePatterns).map(patternMatcher);
+  const releaseAssets = allFiles.filter((file) => releaseMatchers.some((matcher) => matcher.test(path.basename(file.path))));
+  if (kind !== "npm") {
+    createRecoveredPublicationCandidate({ allFiles, repository, passport, candidateRuntimeSha });
+    const version = String(passport.target?.version || "").trim();
+    if (!version) throw new Error("candidate recovery requires a passport publication version");
+    return {
+      manifest: undefined,
+      npmArtifacts: [],
+      allFiles,
+      releaseAssets,
+      version,
+      publishRequiredArtifacts: generatePublishRequiredArtifacts({ manifests: platformManifests, version, kind }),
+    };
+  }
   const tarballs = allFiles.filter((file) => file.path.toLowerCase().endsWith(".tgz"));
   if (tarballs.length === 0) throw new Error("candidate recovery for npm publication requires at least one exact .tgz payload artifact");
   const npmArtifacts = tarballs.map((file) => ({ file, metadata: readNpmPackageArtifact({ tarballPath: file.absolutePath, mainPackage: publishPackageMain }) }));
   const main = npmArtifacts.find((entry) => entry.metadata.role === "main") || (npmArtifacts.length === 1 ? npmArtifacts[0] : undefined);
   if (!main) throw new Error("candidate npm payload set has no unique main package tarball");
-  const releaseMatchers = splitPatterns(releasePatterns).map(patternMatcher);
-  const releaseAssets = allFiles.filter((file) => releaseMatchers.length
+  const npmReleaseAssets = allFiles.filter((file) => releaseMatchers.length
     ? releaseMatchers.some((matcher) => matcher.test(path.basename(file.path)))
     : file.path.toLowerCase().endsWith(".tgz"));
-  const payload = {
-    schemaVersion: 1,
-    contract: PUBLICATION_ARTIFACT_CANDIDATE_CONTRACT,
+  const candidate = createRecoveredPublicationCandidate({
+    allFiles,
     repository,
-    sourceSha: passport.source.headSha,
-    sourceTreeSha: passport.source.treeHash,
-    runtimeSha,
-    releaseCandidateRoot: `sha256:${passport.candidateHash}`,
-    files: allFiles.map(({ path: filePath, size, sha256 }) => ({ path: filePath, size, sha256 })),
-  };
-  const candidate = { ...payload, candidateDigest: publicationArtifactCandidateDigest(payload) };
+    passport,
+    candidateRuntimeSha,
+  });
   const manifest = createPublicationSealedBundle({
     candidate,
     packageName: main.metadata.name,
     packageVersion: main.metadata.ref,
     npmTarballPath: main.file.path,
     npmIntegrity: main.metadata.integrity,
-    releaseAssetPaths: releaseAssets.map((file) => file.path),
+    releaseAssetPaths: npmReleaseAssets.map((file) => file.path),
   });
-  return { manifest, npmArtifacts, allFiles };
+  return {
+    manifest,
+    npmArtifacts,
+    allFiles,
+    releaseAssets: npmReleaseAssets,
+    version: manifest.npm.version,
+    publishRequiredArtifacts: generatePublishRequiredArtifacts({
+      kind: "npm",
+      tarballPaths: npmArtifacts.map((entry) => entry.file.absolutePath),
+      mainPackage: publishPackageMain,
+    }),
+  };
 }
 
 async function recoverCandidateEvidence({
@@ -301,30 +367,24 @@ async function recoverCandidateEvidence({
   };
 }
 
+async function resolveTargetAdvance({ observedTargetSha, targetSha, transactionId, existingTransaction, repoInfo, apiUrl, token, fetchImpl }) {
+  if (observedTargetSha === targetSha || !transactionId || existingTransaction?.id !== transactionId) return undefined;
+  const comparison = await githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/compare/${targetSha}...${observedTargetSha}` });
+  return { status: comparison.status, mergeIsAncestor: ["ahead", "identical"].includes(comparison.status) };
+}
+
 export async function resumeFromCandidateRun({
-  repository,
-  targetRepository = repository,
-  candidateRunId,
-  expectedWorkflowFile,
-  expectedWorkflowName,
-  channel,
-  targetRef,
-  targetSha,
-  expectedSourceTree = "",
-  expectedCandidateRoot = "",
-  candidateRuntimeSha,
-  runtimeSha,
-  transactionId = "",
-  artifactName = "",
-  artifactPatterns = "",
-  releasePatterns = "",
+  repository, targetRepository = repository, candidateRunId,
+  expectedWorkflowFile, expectedWorkflowName,
+  channel, targetRef, targetSha,
+  expectedSourceTree = "", expectedCandidateRoot = "",
+  candidateRuntimeSha, runtimeSha,
+  transactionId = "", artifactName = "", artifactPatterns = "", releasePatterns = "",
   requiredArtifactCount = 0,
-  publishPackageMain = "",
+  publishArtifactKind = "npm", publishPackageMain = "",
   outputDir = ".buildchain/release-candidate-recovery",
-  token = env("GITHUB_TOKEN"),
-  apiUrl = env("GITHUB_API_URL", "https://api.github.com"),
-  recoveryRunId = env("GITHUB_RUN_ID"),
-  fetchImpl = globalThis.fetch,
+  token = env("GITHUB_TOKEN"), apiUrl = env("GITHUB_API_URL", "https://api.github.com"),
+  recoveryRunId = env("GITHUB_RUN_ID"), fetchImpl = globalThis.fetch,
 } = {}) {
   const repoInfo = splitRepository(repository);
   const runId = String(candidateRunId || "").trim();
@@ -346,22 +406,35 @@ export async function resumeFromCandidateRun({
     const pullRequest = await githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/pulls/${prNumber}` });
     const targetCommit = await githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/git/commits/${targetSha}` });
     const targetRefState = await githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/git/ref/heads/${targetRef.replace(/^refs\/heads\//, "")}` });
-    if (targetRefState.object?.sha !== targetSha) throw new Error(`target ref ${targetRef} no longer points at ${targetSha}`);
+    const observedTargetSha = String(targetRefState.object?.sha || "");
     const compare = await githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/compare/${pullRequest.merge_commit_sha}...${targetSha}` });
     const platformManifestEvidence = normalizePlatformManifests(downloads, passport);
     const controllerReceipts = normalizeControllerReceipts(downloads, passport);
     const productPayloadManifests = normalizeProductPayloadManifests(downloads);
-    const sealed = createSealedBundle({
+    const publication = createRecoveredPublication({
       downloads,
       bundleRoot,
       repository: repoInfo.fullName,
       passport,
-      runtimeSha,
+      candidateRuntimeSha,
+      publishArtifactKind,
       publishPackageMain,
       releasePatterns,
+      platformManifests: platformManifestEvidence.manifests,
     });
-    const candidateVersion = sealed.manifest.npm.version;
+    const candidateVersion = publication.version;
     const existingTransaction = await readExistingTransaction({ repoInfo, apiUrl, token, fetchImpl, version: candidateVersion });
+    const targetAdvance = await resolveTargetAdvance({
+      observedTargetSha, targetSha, transactionId, existingTransaction,
+      repoInfo, apiUrl, token, fetchImpl,
+    });
+    validateRecoveryTargetRef({
+      targetSha,
+      observedTargetSha,
+      expectedTransactionId: transactionId,
+      existingTransaction,
+      ancestry: targetAdvance,
+    });
     const recovery = verifyReleaseCandidateRecovery({
       candidateRepository: repoInfo.fullName,
       targetRepository,
@@ -371,6 +444,7 @@ export async function resumeFromCandidateRun({
       channel,
       targetRef,
       targetSha,
+      targetRefSha: observedTargetSha,
       targetTree: targetCommit.tree?.sha,
       expectedSourceTree,
       expectedCandidateRoot,
@@ -417,14 +491,10 @@ export async function resumeFromCandidateRun({
     const sealedManifestPath = path.join(resolvedOutput, "sealed-bundle.json");
     const requiredArtifactsPath = path.join(resolvedOutput, "publish-required-artifacts.json");
     fs.writeFileSync(recoveryReceiptPath, `${JSON.stringify(recovery.receipt, null, 2)}\n`);
-    fs.writeFileSync(sealedManifestPath, `${JSON.stringify(sealed.manifest, null, 2)}\n`);
-    const publishRequiredArtifacts = generatePublishRequiredArtifacts({
-      kind: "npm",
-      tarballPaths: sealed.npmArtifacts.map((entry) => entry.file.absolutePath),
-      mainPackage: publishPackageMain,
-    });
+    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 tarballs = sealed.npmArtifacts.map((entry) => outputPath(entry.file.absolutePath));
+    const tarballs = publication.npmArtifacts.map((entry) => outputPath(entry.file.absolutePath));
     return {
       enabled: true,
       action: "reused",
@@ -442,10 +512,10 @@ export async function resumeFromCandidateRun({
         payloads: outputPath(path.join(bundleRoot, "artifacts")),
         platformManifests: downloads.flatMap((download) => download.files.filter((file) => path.basename(file.path) === "manifest.json").map((file) => outputPath(file.absolutePath))),
         npmTarballs: tarballs,
-        releaseAssets: sealed.manifest.releaseAssets.map((asset) => outputPath(path.join(bundleRoot, asset.path))),
+        releaseAssets: publication.releaseAssets.map((asset) => outputPath(asset.absolutePath)),
         publishRequiredArtifacts: outputPath(requiredArtifactsPath),
-        sealedBundleRoot: outputPath(bundleRoot),
-        sealedBundleManifest: outputPath(sealedManifestPath),
+        sealedBundleRoot: publication.manifest ? outputPath(bundleRoot) : "",
+        sealedBundleManifest: publication.manifest ? outputPath(sealedManifestPath) : "",
         recoveryReceipt: outputPath(recoveryReceiptPath),
       },
     };
@@ -474,6 +544,7 @@ export async function resumeFromCandidateRunCli() {
       artifactPatterns: env("BUILDCHAIN_ARTIFACT_PATTERNS"),
       releasePatterns: env("BUILDCHAIN_GITHUB_RELEASE_PAYLOAD_PATTERNS"),
       requiredArtifactCount: env("BUILDCHAIN_REQUIRED_ARTIFACT_COUNT", "0"),
+      publishArtifactKind: env("BUILDCHAIN_PUBLISH_ARTIFACT_KIND", "npm"),
       publishPackageMain: env("BUILDCHAIN_PUBLISH_PACKAGE_MAIN"),
       outputDir: env("BUILDCHAIN_RC_OUTPUT_DIR", ".buildchain/release-candidate-recovery"),
     });