@kungfu-tech/buildchain 4.0.9 → 4.1.0-alpha.0

package/packages/core/release-candidate-recovery.js

@@ -1,595 +0,0 @@
-import {
-  createControllerReceiptReference,
-  validateControllerReceipt,
-} from "./controller-evidence.js";
-import {
-  sha256Json,
-  validateReleaseCandidatePassport,
-} from "./release-candidate.js";
-import { releaseTransactionId } from "./publish-transaction.js";
-import {
-  publicationAuthorityDigest,
-  publicationGateAggregateBindings,
-} from "./publication-authority.js";
-
-export const RELEASE_CANDIDATE_RECOVERY_CONTRACT =
-  "kungfu-buildchain-release-candidate-recovery/v1";
-
-export function rebindPublicationGateAggregateForEquivalentTree(
-  gateAggregate,
-  { evidenceSourceSha = "", targetSourceSha = "", targetSourceTreeSha = "", expectedSourceTreeSha = "" } = {},
-) {
-  const bindings = publicationGateAggregateBindings(gateAggregate);
-  const evidenceSource = exactSha(evidenceSourceSha, "evidenceSourceSha");
-  const targetSource = exactSha(targetSourceSha, "targetSourceSha");
-  if (bindings.sourceSha !== evidenceSource) {
-    throw new Error("consumer Gate aggregate evidence source SHA mismatch");
-  }
-  if (evidenceSource === targetSource) return gateAggregate;
-  const targetTree = exactSha(targetSourceTreeSha, "targetSourceTreeSha");
-  const expectedTree = exactSha(expectedSourceTreeSha, "expectedSourceTreeSha");
-  if (targetTree !== expectedTree) throw new Error("consumer Gate aggregate source tree mismatch");
-  if (gateAggregate.candidateReuse !== undefined) {
-    throw new Error("consumer Gate aggregate already declares candidate reuse");
-  }
-  const { digest: _digest, ...payload } = gateAggregate;
-  const rebound = {
-    ...payload,
-    sourceSha: targetSource,
-    candidateReuse: { action: "reused", evidenceSourceSha: evidenceSource, sourceTreeSha: expectedTree },
-  };
-  return { ...rebound, digest: `sha256:${publicationAuthorityDigest(rebound)}` };
-}
-
-const SHA_PATTERN = /^[0-9a-f]{40}$/;
-const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
-const TRUSTED_ASSOCIATIONS = new Set(["COLLABORATOR", "MEMBER", "OWNER"]);
-const RESUMABLE_TRANSACTION_STATES = new Set([
-  "sealed",
-  "publishing",
-  "publish_failed",
-  "published",
-  "package-published",
-  "finalizing",
-  "complete",
-]);
-
-export class ReleaseCandidateRecoveryError extends Error {
-  constructor(code, message, nextAction) {
-    super(message);
-    this.name = "ReleaseCandidateRecoveryError";
-    this.code = code;
-    this.nextAction = nextAction;
-  }
-}
-
-function fail(code, message, nextAction) {
-  throw new ReleaseCandidateRecoveryError(code, message, nextAction);
-}
-
-function required(value, label, code = "invalid-recovery-input") {
-  const normalized = String(value || "").trim();
-  if (!normalized) fail(code, `${label} is required`, "Correct the recovery dispatch inputs and run a fresh recovery event.");
-  return normalized;
-}
-
-function exactSha(value, label) {
-  const normalized = required(value, label).toLowerCase();
-  if (!SHA_PATTERN.test(normalized)) {
-    fail("invalid-recovery-input", `${label} must be a 40-character Git SHA`, "Supply the exact immutable Git SHA.");
-  }
-  return normalized;
-}
-
-function contentRoot(value, label) {
-  const normalized = required(value, label).toLowerCase();
-  if (!SHA256_PATTERN.test(normalized)) {
-    fail("invalid-recovery-input", `${label} must be a sha256 content root`, "Supply the exact sha256 root from the sealed candidate evidence.");
-  }
-  return normalized;
-}
-
-function normalizeArtifact(record, index) {
-  const name = required(record?.name, `artifacts[${index}].name`);
-  if (record?.expired === true) {
-    fail("artifact-expired", `candidate artifact is expired: ${name}`, "Create a new candidate explicitly; recovery never falls back to rebuilding.");
-  }
-  if (record?.missing === true) {
-    fail("artifact-missing", `candidate artifact is missing: ${name}`, "Restore the immutable artifact if possible or explicitly create a new candidate.");
-  }
-  const size = Number(record?.size);
-  const downloadedSize = Number(record?.downloadedSize);
-  if (!Number.isSafeInteger(size) || size < 0 || !Number.isSafeInteger(downloadedSize) || downloadedSize < 0) {
-    fail("artifact-metadata-invalid", `candidate artifact size is invalid: ${name}`, "Inspect the candidate run artifact metadata and retry with a complete artifact set.");
-  }
-  const digest = contentRoot(record?.digest, `artifacts[${index}].digest`);
-  const downloadedDigest = contentRoot(record?.downloadedDigest, `artifacts[${index}].downloadedDigest`);
-  if (size !== downloadedSize || digest !== downloadedDigest) {
-    fail("artifact-digest-mismatch", `candidate artifact archive differs from GitHub metadata: ${name}`, "Do not publish; preserve the run and investigate artifact corruption or replacement.");
-  }
-  const files = (record?.files || []).map((file, fileIndex) => {
-    const fileSize = Number(file?.size);
-    if (!Number.isSafeInteger(fileSize) || fileSize < 0) {
-      fail("artifact-manifest-mismatch", `${name} file ${fileIndex} has an invalid size`, "Inspect the platform manifest and product payload bytes.");
-    }
-    return {
-      path: required(file?.path, `${name}.files[${fileIndex}].path`),
-      size: fileSize,
-      sha256: contentRoot(file?.sha256, `${name}.files[${fileIndex}].sha256`),
-    };
-  }).sort((left, right) => left.path.localeCompare(right.path));
-  if (new Set(files.map((file) => file.path)).size !== files.length) {
-    fail("artifact-manifest-mismatch", `candidate artifact contains duplicate file paths: ${name}`, "Regenerate a valid candidate explicitly.");
-  }
-  return { name, size, digest, files, kind: String(record?.kind || "payload") };
-}
-
-function assertEqual(actual, expected, code, label, nextAction) {
-  if (actual !== expected) fail(code, `${label} mismatch: expected ${expected}, got ${actual || "<empty>"}`, nextAction);
-}
-
-function normalizedRef(value) {
-  return String(value || "").replace(/^refs\/heads\//, "").trim();
-}
-
-export function validateRecoveryTargetRef({
-  targetSha,
-  observedTargetSha,
-  expectedTransactionId = "",
-  existingTransaction = undefined,
-  ancestry = undefined,
-} = {}) {
-  const expected = exactSha(targetSha, "targetSha");
-  const observed = exactSha(observedTargetSha, "observedTargetSha");
-  if (observed === expected) return { advanced: false, observedSha: observed };
-  if (!expectedTransactionId) {
-    fail(
-      "target-ref-moved",
-      `target ref advanced from ${expected} to ${observed} without an explicit durable transaction identity`,
-      "Resume with the exact existing transaction identity, or select a new candidate explicitly; never rebuild implicitly.",
-    );
-  }
-  if (!existingTransaction || existingTransaction.id !== expectedTransactionId) {
-    fail(
-      "transaction-identity-conflict",
-      `target ref advanced but durable transaction ${expectedTransactionId} was not found exactly`,
-      "Enter repair_required and inspect the durable transaction before any retry.",
-    );
-  }
-  const state = String(existingTransaction.state || existingTransaction.publication_state || "");
-  if (!RESUMABLE_TRANSACTION_STATES.has(state)) {
-    fail(
-      "transaction-state-conflict",
-      `target ref advanced while durable transaction ${expectedTransactionId} is in non-resumable state ${state || "<empty>"}`,
-      "Preserve the transaction evidence and enter repair_required; do not republish or rebuild automatically.",
-    );
-  }
-  if (ancestry?.mergeIsAncestor !== true || !["ahead", "identical"].includes(String(ancestry?.status || ""))) {
-    fail(
-      "target-ancestry-mismatch",
-      `observed target ${observed} is not an ancestry-bound continuation of transaction source ${expected}`,
-      "Preserve the candidate and transaction evidence; inspect the target ref for unrelated advancement before retrying.",
-    );
-  }
-  return { advanced: true, observedSha: observed };
-}
-
-export function validateReleaseCandidateRecoveryReceipt({
-  receipt,
-  passport,
-  repository = "",
-  targetChannel = "",
-  targetRef = "",
-  targetSha = "",
-  targetTree = "",
-  version = "",
-} = {}) {
-  const receiptObject = Boolean(receipt && typeof receipt === "object" && !Array.isArray(receipt));
-  const passportObject = Boolean(passport && typeof passport === "object" && !Array.isArray(passport));
-  const rootedReceipt = Object.assign({}, receipt);
-  delete rootedReceipt.root;
-  const candidateHash = String(passport?.candidateHash || "");
-  const candidateRoot = `sha256:${candidateHash}`;
-  const checks = [
-    [receiptObject, "receipt must be an object"],
-    [passportObject, "passport must be an object"],
-    [receipt?.contract === RELEASE_CANDIDATE_RECOVERY_CONTRACT, `contract must be ${RELEASE_CANDIDATE_RECOVERY_CONTRACT}`],
-    [Number(receipt?.schemaVersion) === 1, "schemaVersion must be 1"],
-    [receipt?.action === "reused", "action must be reused"],
-    [receipt?.payloadBytes === "unchanged", "payloadBytes must be unchanged"],
-    [JSON.stringify(receipt?.skippedBuildStages) === JSON.stringify(["install", "build", "verify", "platform-matrix"]), "skippedBuildStages must record the complete skipped product build matrix"],
-    [receipt?.root === `sha256:${sha256Json(rootedReceipt)}`, "receipt root mismatch"],
-    [!repository || receipt?.repository === repository, `repository mismatch: expected ${repository}, got ${receipt?.repository || "<empty>"}`],
-    [!targetChannel || receipt?.target?.channel === targetChannel, `target channel mismatch: expected ${targetChannel}, got ${receipt?.target?.channel || "<empty>"}`],
-    [!targetRef || normalizedRef(receipt?.target?.ref) === normalizedRef(targetRef), `target ref mismatch: expected ${normalizedRef(targetRef)}, got ${normalizedRef(receipt?.target?.ref) || "<empty>"}`],
-    [!targetSha || receipt?.target?.sha === targetSha, `target SHA mismatch: expected ${targetSha}, got ${receipt?.target?.sha || "<empty>"}`],
-    [!targetTree || receipt?.target?.tree === targetTree, `target tree mismatch: expected ${targetTree}, got ${receipt?.target?.tree || "<empty>"}`],
-    [!version || receipt?.target?.version === version, `publication version mismatch: expected ${version}, got ${receipt?.target?.version || "<empty>"}`],
-    [passportObject && /^[0-9a-f]{64}$/.test(candidateHash), "passport candidateHash must be a sha256 digest"],
-    [passportObject && receipt?.recovered?.candidateRoot === candidateRoot, `candidate root mismatch: expected ${candidateRoot}, got ${receipt?.recovered?.candidateRoot || "<empty>"}`],
-    [passportObject && receipt?.originalCandidate?.sourceSha === passport?.source?.headSha, "original candidate source SHA mismatch"],
-    [passportObject && receipt?.originalCandidate?.tree === passport?.source?.treeHash, "original candidate tree mismatch"],
-  ];
-  const errors = checks.filter(([ok]) => !ok).map(([, message]) => message);
-  return {
-    ok: errors.length === 0,
-    errors,
-    publicationVersion: String(receipt?.target?.version || ""),
-    candidateRoot: String(receipt?.recovered?.candidateRoot || ""),
-  };
-}
-
-function sameArtifactFile(left, right) {
-  return Boolean(left && right && left.size === right.size && left.sha256 === right.sha256);
-}
-
-function validatePlatformPayloads(passport, artifacts, platformManifests, platformManifestEvidence) {
-  const byName = new Map(artifacts.map((artifact) => [artifact.name, artifact]));
-  const manifestsByArtifact = new Map((platformManifests || []).map((manifest) => [manifest.artifactName, manifest]));
-  const evidenceByArtifact = new Map((platformManifestEvidence || []).map((evidence) => [evidence.artifactName, evidence]));
-  if (manifestsByArtifact.size !== (passport.platformMatrix || []).length) {
-    fail("platform-matrix-mismatch", "platform manifest count differs from the Passport platform matrix", "Restore every exact platform manifest from the candidate run.");
-  }
-  for (const platform of passport.platformMatrix || []) {
-    const payload = byName.get(platform.artifactName);
-    if (!payload) {
-      fail("artifact-missing", `platform payload artifact is missing: ${platform.artifactName}`, "Restore the exact candidate artifact or explicitly create a new candidate.");
-    }
-    const passportFiles = (platform.artifacts || []).map((file) => ({
-      path: String(file.path || file.name || ""),
-      size: Number(file.size),
-      sha256: `sha256:${String(file.sha256 || "").replace(/^sha256:/, "")}`,
-    })).sort((left, right) => left.path.localeCompare(right.path));
-    const manifest = manifestsByArtifact.get(platform.artifactName);
-    if (!manifest) {
-      fail("artifact-missing", `platform manifest is missing for ${platform.artifactName}`, "Restore the exact platform manifest artifact.");
-    }
-    const manifestFiles = (manifest.files || []).map((file) => ({
-      path: String(file.path || file.name || ""),
-      size: Number(file.size ?? file.bytes),
-      sha256: `sha256:${String(file.sha256 || "").replace(/^sha256:/, "")}`,
-    })).sort((left, right) => left.path.localeCompare(right.path));
-    const platformId = required(platform.platformId, `${platform.artifactName}.platformId`);
-    const buildchainEvidencePrefix = `.buildchain/artifacts/${platformId}/`;
-    const manifestByPath = new Map(manifestFiles.map((file) => [file.path, file]));
-    const evidenceFiles = new Map((evidenceByArtifact.get(platform.artifactName)?.files || []).map((file) => [file.path, file]));
-    const payloadPaths = new Set(payload.files.map((file) => file.path));
-    for (const manifestFile of manifestFiles) {
-      if (!payloadPaths.has(manifestFile.path)) {
-        fail("artifact-manifest-mismatch", `platform payload omits a manifest-declared file: ${platform.artifactName}/${manifestFile.path}`, "Do not publish; preserve the mismatched manifest and payload evidence.");
-      }
-    }
-    for (const payloadFile of payload.files) {
-      const manifestFile = manifestByPath.get(payloadFile.path);
-      if (sameArtifactFile(payloadFile, manifestFile)) continue;
-      const evidencePath = payloadFile.path.startsWith(buildchainEvidencePrefix)
-        ? payloadFile.path.slice(buildchainEvidencePrefix.length)
-        : "";
-      const evidenceFile = evidencePath ? evidenceFiles.get(evidencePath) : undefined;
-      if (!sameArtifactFile(payloadFile, evidenceFile)) {
-        fail("artifact-manifest-mismatch", `platform payload contains unbound bytes or evidence drift: ${platform.artifactName}/${payloadFile.path}`, "Do not publish; preserve the platform payload, manifest, and independently uploaded evidence.");
-      }
-    }
-    if (passportFiles.length > 0 && JSON.stringify(manifestFiles) !== JSON.stringify(passportFiles)) {
-      fail("artifact-manifest-mismatch", `platform manifest differs from Passport inventory: ${platform.artifactName}`, "Do not publish; preserve the mismatched manifest and Passport evidence.");
-    }
-    if (
-      Number(platform.summary?.fileCount) !== manifestFiles.length ||
-      Number(platform.summary?.totalBytes) !== manifestFiles.reduce((total, file) => total + file.size, 0)
-    ) {
-      fail("platform-matrix-mismatch", `platform summary differs from manifest inventory: ${platform.artifactName}`, "Use the exact summary, manifest, and payload uploaded by the successful candidate run.");
-    }
-  }
-}
-
-function validateProductPayloads({ passport, artifacts, productPayloadManifests, candidateRoot, buildSummaryRoot, runtimeSha }) {
-  const byName = new Map(artifacts.map((artifact) => [artifact.name, artifact]));
-  for (const [index, manifest] of (productPayloadManifests || []).entries()) {
-    if (manifest?.contract !== "kungfu-buildchain-product-payload-manifest/v1") {
-      fail("artifact-manifest-mismatch", `product payload manifest ${index} has an invalid contract`, "Use the exact Buildchain-produced product payload manifest.");
-    }
-    const { root: _root, ...rootInput } = manifest;
-    assertEqual(manifest.root, `sha256:${sha256Json(rootInput)}`, "artifact-manifest-mismatch", "product payload manifest root", "Use an untampered product payload manifest from the candidate run.");
-    assertEqual(manifest.candidateRoot, candidateRoot, "candidate-root-mismatch", "product payload candidate root", "Use the product payload sealed for this exact candidate.");
-    assertEqual(manifest.buildSummaryRoot, buildSummaryRoot, "build-summary-root-mismatch", "product payload build summary root", "Use the payload produced from the exact candidate summary.");
-    assertEqual(manifest.source?.tree, passport.source?.treeHash, "source-tree-mismatch", "product payload source tree", "Use payload bytes produced from the exact candidate tree.");
-    assertEqual(manifest.runtimeSha, runtimeSha, "runtime-mismatch", "product payload candidate runtime", "Use payload evidence created by the candidate runtime.");
-    const artifact = byName.get(manifest.artifactName);
-    if (!artifact) fail("artifact-missing", `product payload artifact is missing: ${manifest.artifactName}`, "Restore the exact product payload artifact.");
-    const manifestName = String(manifest.manifestPath || "product-payload-manifest.json");
-    const payloadFiles = artifact.files.filter((file) => file.path !== manifestName);
-    const expectedFiles = (manifest.files || []).map((file) => ({
-      path: String(file.path || ""),
-      size: Number(file.size),
-      sha256: String(file.sha256 || ""),
-    })).sort((left, right) => left.path.localeCompare(right.path));
-    if (JSON.stringify(payloadFiles) !== JSON.stringify(expectedFiles)) {
-      fail("artifact-manifest-mismatch", `product payload bytes differ from their manifest: ${manifest.artifactName}`, "Do not publish; preserve the manifest and uploaded product bytes.");
-    }
-  }
-}
-
-function assertAnchorEqual(actual, expected, label) {
-  assertEqual(actual, expected, "anchored-provenance-invalid", label, "Preserve both candidate runs and repair the explicit anchor provenance before retrying.");
-}
-
-function validateAnchorProvenance({ run, passport, anchorProvenance, expectedTransactionId, workflowFile, expectedWorkflowName, repository, targetRef }) {
-  const request = anchorProvenance.request;
-  const provenanceRun = anchorProvenance.run;
-  const provenanceWorkflow = anchorProvenance.workflow;
-  const provenancePassport = anchorProvenance.passport;
-  assertAnchorEqual(run?.status, "completed", "anchored candidate run status");
-  assertAnchorEqual(run?.conclusion, "success", "anchored candidate run conclusion");
-  assertAnchorEqual(run?.event, "workflow_dispatch", "anchored candidate run event");
-  assertAnchorEqual(passport?.target?.channel, "anchor", "anchored candidate channel");
-  assertAnchorEqual(passport?.target?.ref, "publish-gate/anchor", "anchored candidate ref");
-  assertAnchorEqual(run?.headSha, passport?.buildchain?.sha, "anchored candidate runtime");
-  assertAnchorEqual(request?.schema, 1, "anchor request schema");
-  assertAnchorEqual(request?.contract, "kungfu-buildchain-explicit-publish-anchor-request/v1", "anchor request contract");
-  assertAnchorEqual(Boolean(request?.assignmentId), true, "anchor request Assignment");
-  assertAnchorEqual(/^native:[0-9a-f-]+$/u.test(String(request?.attemptId || "")), true, "anchor request Attempt");
-  assertAnchorEqual(request?.transactionId, expectedTransactionId, "anchor request transaction");
-  assertAnchorEqual(String(provenanceRun?.id || ""), String(request?.supersededCandidate?.workflowRunId || ""), "superseded candidate run");
-  assertAnchorEqual(provenancePassport?.workflow?.runId, String(request?.supersededCandidate?.workflowRunId || ""), "superseded candidate Passport run");
-  assertAnchorEqual(request?.source?.sha, passport?.source?.headSha, "anchor request source SHA");
-  assertAnchorEqual(request?.source?.tree, passport?.source?.treeHash, "anchor request source tree");
-  assertAnchorEqual(request?.supersededCandidate?.sha, provenancePassport?.source?.headSha, "superseded candidate source SHA");
-  assertAnchorEqual(request?.supersededCandidate?.root, `sha256:${provenancePassport?.candidateHash || ""}`, "superseded candidate root");
-  assertAnchorEqual(request?.runtime?.sha, passport?.buildchain?.sha, "anchor request runtime");
-  const provenanceWorkflowPath = String(provenanceWorkflow?.path || provenanceRun?.path || "").split("@")[0].replace(/^\.github\/workflows\//, "");
-  assertEqual(provenanceWorkflowPath, workflowFile, "workflow-mismatch", "superseded candidate workflow file", "Use the exact trusted original candidate workflow.");
-  assertEqual(String(provenanceWorkflow?.name || provenanceRun?.name || ""), expectedWorkflowName, "workflow-mismatch", "superseded candidate workflow name", "Use the exact trusted original candidate workflow.");
-  if (provenanceWorkflow?.state && provenanceWorkflow.state !== "active") fail("untrusted-build-run", `superseded candidate workflow is not active: ${provenanceWorkflow.state}`, "Restore or select an allowed active Build workflow.");
-  const validation = validateReleaseCandidatePassport({ passport: provenancePassport, repository, targetChannel: normalizedRef(targetRef).split("/")[0], buildSummary: anchorProvenance.buildSummary });
-  if (!validation.ok) fail("anchored-provenance-invalid", `superseded candidate Passport validation failed: ${validation.errors.join("; ")}`, "Preserve both candidate runs and repair the explicit anchor provenance before retrying.");
-  return { provenanceRun, provenanceWorkflow, provenancePassport };
-}
-
-function validateCandidateProvenance({
-  candidateRepository,
-  targetRepository,
-  expectedRunId,
-  expectedWorkflowFile,
-  expectedWorkflowName,
-  targetRef,
-  run,
-  workflow,
-  pullRequest,
-  ancestry, targetTree,
-  passport,
-  anchorProvenance,
-  expectedTransactionId,
-}) {
-  const repository = required(candidateRepository, "candidateRepository");
-  assertEqual(repository, required(targetRepository, "targetRepository"), "repository-mismatch", "candidate repository", "Dispatch recovery in the repository that created the candidate.");
-  assertEqual(String(run?.id || ""), required(expectedRunId, "expectedRunId"), "run-mismatch", "candidate run ID", "Select the exact successful candidate run.");
-  assertEqual(run?.repository, repository, "repository-mismatch", "run repository", "Use a candidate run from the target repository.");
-  assertEqual(run?.headRepository, repository, "provenance-insufficient", "run head repository", "Fork candidates are not recoverable; create a same-repository candidate.");
-  const workflowFile = required(expectedWorkflowFile, "expectedWorkflowFile").replace(/^\.github\/workflows\//, "");
-  const actualWorkflowPath = String(workflow?.path || run?.path || "").split("@")[0].replace(/^\.github\/workflows\//, "");
-  assertEqual(actualWorkflowPath, workflowFile, "workflow-mismatch", "candidate workflow file", "Select a run from the documented trusted Build workflow.");
-  assertEqual(String(workflow?.name || run?.name || ""), required(expectedWorkflowName, "expectedWorkflowName"), "workflow-mismatch", "candidate workflow name", "Select a run from the documented trusted Build workflow.");
-  if (workflow?.state && workflow.state !== "active") fail("untrusted-build-run", `candidate workflow is not active: ${workflow.state}`, "Restore or select an allowed active Build workflow.");
-  const anchor = anchorProvenance ? validateAnchorProvenance({ run, passport, anchorProvenance, expectedTransactionId, workflowFile, expectedWorkflowName: required(expectedWorkflowName, "expectedWorkflowName"), repository, targetRef }) : undefined;
-  const provenanceRun = anchor?.provenanceRun || run;
-  if (provenanceRun?.status !== "completed" || provenanceRun?.conclusion !== "success" || provenanceRun?.event !== "pull_request") {
-    fail("untrusted-build-run", "candidate provenance run must be a successful completed pull_request build", "Choose a successful allowed Build workflow run.");
-  }
-  assertEqual(provenanceRun?.repository, repository, "repository-mismatch", "provenance run repository", "Use a candidate run from the target repository.");
-  assertEqual(provenanceRun?.headRepository, repository, "provenance-insufficient", "provenance run head repository", "Fork candidates are not recoverable; create a same-repository candidate.");
-  if (!TRUSTED_ASSOCIATIONS.has(String(pullRequest?.authorAssociation || ""))) fail("permission-evidence-insufficient", "candidate PR author lacks trusted repository association evidence", "Have a repository member create or approve a same-repository candidate PR.");
-  assertEqual(pullRequest?.headRepository, repository, "provenance-insufficient", "candidate PR head repository", "Fork candidates are outside the recovery permission boundary.");
-  if (!pullRequest?.merged) fail("pr-identity-invalid", "candidate PR is not merged", "Use a merged channel candidate PR.");
-  assertEqual(normalizedRef(pullRequest?.baseRef), normalizedRef(targetRef), "target-mismatch", "candidate PR target ref", "Use the original release channel target.");
-  const boundByNumber = Array.isArray(provenanceRun?.pullRequestNumbers) && provenanceRun.pullRequestNumbers.includes(Number(pullRequest?.number));
-  const boundByHead = provenanceRun?.headSha === pullRequest?.headSha && normalizedRef(provenanceRun?.headBranch) === normalizedRef(pullRequest?.headRef);
-  if (!boundByNumber && !boundByHead) fail("pr-identity-invalid", "candidate run is not bound to the merged candidate PR", "Select the exact PR-stage Build run.");
-  if (!ancestry?.mergeIsAncestor && ancestry?.status !== "identical" && exactSha(targetTree, "targetTree") !== exactSha(passport?.source?.treeHash, "passport.source.treeHash")) fail("ancestry-invalid", "candidate merge is neither an ancestor nor tree-equivalent to the promotion SHA", "Promote a descendant of the verified merged candidate identity or its exact tree-equivalent protected merge result.");
-  return { repository, workflowFile };
-}
-
-function validateCandidateIdentity({
-  repository,
-  channel,
-  targetSha,
-  targetTree,
-  expectedSourceTree,
-  expectedRuntimeSha,
-  currentToolingSha,
-  passport,
-  buildSummary,
-  anchorProvenance,
-}) {
-  const sha = exactSha(targetSha, "targetSha");
-  const tree = exactSha(targetTree, "targetTree");
-  const runtimeSha = exactSha(expectedRuntimeSha, "expectedRuntimeSha");
-  const toolingSha = exactSha(currentToolingSha, "currentToolingSha");
-  const validation = validateReleaseCandidatePassport({ passport, repository, targetChannel: anchorProvenance ? "" : channel, buildSummary });
-  if (!validation.ok) fail("passport-invalid", `Release Candidate Passport validation failed: ${validation.errors.join("; ")}`, "Preserve the candidate evidence and explicitly create a new candidate after fixing the producer.");
-  const expectedPassportHash = sha256Json({
-    repository: passport.repository,
-    target: passport.target,
-    source: passport.source,
-    platformMatrix: passport.platformMatrix,
-    buildchain: passport.buildchain,
-    ...(passport.gateProfileEvidence ? { gateProfileEvidence: passport.gateProfileEvidence } : {}),
-    ...(passport.familyEvidence ? { familyEvidence: passport.familyEvidence } : {}),
-    ...(passport.consumerPolicy ? { consumerPolicy: passport.consumerPolicy } : {}),
-    ...(passport.controllerReceipts ? { controllerReceipts: passport.controllerReceipts } : {}),
-  });
-  if (passport.candidateHash !== expectedPassportHash) fail("candidate-root-mismatch", "Release Candidate Passport candidate hash does not match its content", "Preserve the run evidence and explicitly create a new candidate after fixing the producer.");
-  assertEqual(passport.source?.treeHash, tree, "source-tree-mismatch", "promotion Git tree", "Select a promotion SHA with the exact candidate Git tree or create a new candidate explicitly.");
-  if (expectedSourceTree) assertEqual(passport.source?.treeHash, exactSha(expectedSourceTree, "expectedSourceTree"), "source-tree-mismatch", "expected source tree", "Correct the expected tree or create a new candidate.");
-  assertEqual(passport.buildchain?.sha, runtimeSha, "runtime-mismatch", "candidate Buildchain runtime SHA", "Run recovery with the exact trusted Buildchain runtime recorded by the candidate.");
-  return { sha, tree, runtimeSha, toolingSha };
-}
-
-function validateRecoveryTransaction({ existingTransaction, expectedTransactionId, repository, version, passport, channel, sha, targetRef, candidateRoot }) {
-  const actualTransactionId = String(existingTransaction?.id || "");
-  if (expectedTransactionId && !actualTransactionId) fail("transaction-identity-conflict", `expected transaction ${expectedTransactionId} does not exist`, "Remove the stale transaction identity only if no durable transaction was ever sealed; otherwise preserve evidence and enter repair_required.");
-  if (expectedTransactionId && expectedTransactionId !== actualTransactionId) fail("transaction-identity-conflict", `existing transaction ${actualTransactionId} conflicts with expected ${expectedTransactionId}`, "Enter repair_required and inspect the durable transaction before any retry.");
-  if (existingTransaction) {
-    const expectedIdentity = releaseTransactionId({ repository, version, sourceSha: exactSha(existingTransaction.source_sha, "existingTransaction.source_sha"), targetRef: normalizedRef(targetRef) });
-    assertEqual(existingTransaction.id, expectedIdentity, "transaction-identity-conflict", "durable transaction identity", "Enter repair_required; the durable transaction does not belong to this exact publication target.");
-    assertEqual(existingTransaction.repository, repository, "transaction-identity-conflict", "durable transaction repository", "Enter repair_required; never cross repository transaction boundaries.");
-    assertEqual(normalizedRef(existingTransaction.target_ref), normalizedRef(targetRef), "transaction-identity-conflict", "durable transaction target ref", "Enter repair_required; never retarget a sealed transaction.");
-    if (![existingTransaction.source_sha, existingTransaction.release_sha, existingTransaction.release_material_sha].filter(Boolean).includes(sha)) fail("transaction-identity-conflict", "recovery promotion SHA is not bound to the durable transaction", "Resume with the transaction's exact source, release, or release material SHA, or enter repair_required.");
-    assertEqual(existingTransaction.version, version, "transaction-identity-conflict", "durable transaction version", "Enter repair_required; never change a sealed publication version.");
-    assertEqual(existingTransaction.channel, channel || passport.target.channel, "transaction-identity-conflict", "durable transaction channel", "Enter repair_required; never move a transaction between channels.");
-  }
-  if (existingTransaction?.candidateRoot && existingTransaction.candidateRoot !== candidateRoot) fail("transaction-identity-conflict", "existing transaction is sealed to a different candidate root", "Enter repair_required; never reuse the conflicting transaction.");
-  return actualTransactionId;
-}
-
-export function verifyReleaseCandidateRecovery({
-  candidateRepository,
-  targetRepository,
-  expectedRunId,
-  expectedWorkflowFile,
-  expectedWorkflowName,
-  channel,
-  targetRef,
-  targetSha,
-  targetRefSha = targetSha,
-  targetTree,
-  expectedSourceTree = "",
-  expectedCandidateRoot = "",
-  expectedRuntimeSha,
-  expectedTransactionId = "",
-  existingTransaction = undefined,
-  run,
-  workflow,
-  pullRequest,
-  ancestry,
-  anchorProvenance = undefined,
-  passport,
-  buildSummary,
-  controllerReceipts = [],
-  platformManifests = [],
-  platformManifestEvidence = [],
-  productPayloadManifests = [],
-  artifacts = [],
-  publicationVersion = "",
-  currentToolingSha,
-  recoveryRunId = "",
-  createdAt = new Date().toISOString(),
-} = {}) {
-  const { repository, workflowFile } = validateCandidateProvenance({
-    candidateRepository, targetRepository, expectedRunId, expectedWorkflowFile,
-    expectedWorkflowName, targetRef, run, workflow, pullRequest, ancestry,
-    targetTree, passport, anchorProvenance, expectedTransactionId,
-  });
-  const { sha, tree, runtimeSha, toolingSha } = validateCandidateIdentity({
-    repository, channel, targetSha, targetTree, expectedSourceTree,
-    expectedRuntimeSha, currentToolingSha, passport, buildSummary, anchorProvenance,
-  });
-
-  const recoveredArtifacts = artifacts.map(normalizeArtifact).sort((left, right) => left.name.localeCompare(right.name));
-  if (recoveredArtifacts.length === 0) fail("artifact-missing", "candidate artifact set is empty", "Select a retained run with the complete candidate artifact set.");
-  if (new Set(recoveredArtifacts.map((artifact) => artifact.name)).size !== recoveredArtifacts.length) {
-    fail("artifact-count-mismatch", "candidate artifact names are not unique", "Inspect the candidate run and remove ambiguity by creating a new candidate.");
-  }
-  validatePlatformPayloads(passport, recoveredArtifacts, platformManifests, platformManifestEvidence);
-
-  const references = new Map((passport.controllerReceipts || []).map((reference) => [reference.controllerId, reference]));
-  for (const receipt of controllerReceipts) {
-    const receiptValidation = validateControllerReceipt(receipt, {
-      expectedSourceSha: passport.source?.headSha,
-      expectedRuntimeSha: runtimeSha,
-    });
-    if (!receiptValidation.ok || !receiptValidation.qualifying) {
-      fail("controller-receipt-invalid", `controller receipt is not qualifying: ${receiptValidation.issues.join("; ")}`, "Use a successful candidate with complete controller evidence.");
-    }
-    const actualReference = createControllerReceiptReference(receipt);
-    const expectedReference = references.get(actualReference.controllerId);
-    if (!expectedReference || sha256Json(actualReference) !== sha256Json(expectedReference)) {
-      fail("controller-receipt-mismatch", `controller receipt does not match Passport reference: ${actualReference.controllerId}`, "Use the exact controller receipt artifact uploaded by the candidate run.");
-    }
-  }
-  if (references.size !== controllerReceipts.length) {
-    fail("controller-receipt-missing", "not every Passport controller receipt was recovered", "Restore every referenced controller receipt artifact before recovery.");
-  }
-
-  const candidateRoot = `sha256:${passport.candidateHash}`;
-  if (expectedCandidateRoot) assertEqual(candidateRoot, contentRoot(expectedCandidateRoot, "expectedCandidateRoot"), "candidate-root-mismatch", "candidate root", "Use the exact candidate root recorded by the original run.");
-  const artifactInventory = recoveredArtifacts.map(({ name, size, digest, files }) => ({ name, size, digest, files }));
-  const artifactRoot = `sha256:${sha256Json(artifactInventory)}`;
-  const artifactArchiveRoot = `sha256:${sha256Json(recoveredArtifacts.map(({ name, size, digest }) => ({ name, size, digest })))}`;
-  validateProductPayloads({
-    passport,
-    artifacts: recoveredArtifacts,
-    productPayloadManifests,
-    candidateRoot,
-    buildSummaryRoot: `sha256:${passport.diagnostics.buildSummaryHash}`,
-    runtimeSha,
-  });
-
-  const version = required(publicationVersion || passport.target?.version, "publicationVersion");
-  const actualTransactionId = validateRecoveryTransaction({
-    existingTransaction, expectedTransactionId, repository, version, passport, channel, sha, targetRef, candidateRoot,
-  });
-
-  const receipt = {
-    schemaVersion: 1,
-    contract: RELEASE_CANDIDATE_RECOVERY_CONTRACT,
-    action: "reused",
-    createdAt,
-    repository,
-    recoveryRunId: String(recoveryRunId || ""),
-    originalCandidate: {
-      runId: String(run.id),
-      workflowFile,
-      workflowName: String(workflow?.name || run?.name || ""),
-      pullRequest: Number(pullRequest.number),
-      sourceSha: passport.source.headSha,
-      mergeSha: String(pullRequest.mergeSha || ""),
-      tree: passport.source.treeHash,
-      ...(anchorProvenance ? {
-        provenance: "anchored-rematerialization",
-        supersededCandidate: {
-          runId: String(anchorProvenance.run.id),
-          candidateRoot: String(anchorProvenance.request.supersededCandidate.root),
-          sourceSha: String(anchorProvenance.request.supersededCandidate.sha),
-        },
-      } : {}),
-    },
-    target: {
-      channel,
-      ref: normalizedRef(targetRef),
-      sha,
-      observedRefSha: exactSha(targetRefSha, "targetRefSha"),
-      tree,
-      version,
-    },
-    recovered: {
-      candidateRoot,
-      buildSummaryRoot: `sha256:${passport.diagnostics.buildSummaryHash}`,
-      artifactRoot,
-      artifactArchiveRoot,
-      artifactCount: recoveredArtifacts.length,
-      artifacts: recoveredArtifacts.map(({ name, size, digest }) => ({ name, size, digest })),
-    },
-    skippedBuildStages: ["install", "build", "verify", "platform-matrix"],
-    payloadBytes: "unchanged",
-    buildchainToolingSha: toolingSha,
-    transaction: {
-      identity: expectedTransactionId || actualTransactionId || "",
-      state: String(existingTransaction?.state || "absent"),
-      publicationState: String(existingTransaction?.publication_state || existingTransaction?.state || "absent"),
-    },
-  };
-  receipt.root = `sha256:${sha256Json(receipt)}`;
-  return { receipt, artifacts: recoveredArtifacts };
-}
-
-export function recoveryFailure(error) {
-  if (error instanceof ReleaseCandidateRecoveryError) {
-    return { ok: false, code: error.code, reason: error.message, nextAction: error.nextAction };
-  }
-  return {
-    ok: false,
-    code: "recovery-internal-error",
-    reason: String(error?.message || error),
-    nextAction: "Preserve the run logs and candidate evidence; do not rebuild automatically.",
-  };
-}