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

package/packages/core/paper-agent-entry.js

@@ -12,6 +12,7 @@ import {
   stableJson,
   workCheck,
 } from "./paper-repository.js";
+import { mergeNextDevelopmentAgentInstructions } from "./next-development-projection.js";
 
 export const PAPER_AGENT_ENTRY_CONTRACT = "kungfu-buildchain-paper-agent-entry";
 export const PAPER_AGENT_ENTRY_SCHEMA_VERSION = 1;
@@ -167,9 +168,11 @@ export function paperAgentEntryFiles({
     [PAPER_PATHS.agentEntry, jsonText(entry)],
     [
       PAPER_PATHS.agentInstructions,
-      mergePaperAgentEntryInstructions(currentAgents, {
-        developmentRef: resolvedDevelopmentRef,
-      }),
+      mergeNextDevelopmentAgentInstructions(
+        mergePaperAgentEntryInstructions(currentAgents, {
+          developmentRef: resolvedDevelopmentRef,
+        }),
+      ),
     ],
   ]);
 }
@@ -205,8 +208,11 @@ function ciContext({ env, developmentRef }) {
     sourceBranch.startsWith(versionStatePrefix) &&
     /^[0-9a-f]{12}$/i.test(sourceBranch.slice(versionStatePrefix.length));
   const branchOk = pullRequest
-    ? (PAPER_WORK_BRANCH_PATTERN.test(sourceBranch) && targetBranch === developmentRef) ||
-      (channelIndex > 0 && sourceBranch === channelBranches[channelIndex - 1]) || generatedVersionState
+    ? (PAPER_WORK_BRANCH_PATTERN.test(sourceBranch) &&
+        targetBranch === developmentRef) ||
+      (channelIndex > 0 &&
+        sourceBranch === channelBranches[channelIndex - 1]) ||
+      generatedVersionState
     : channelBranches.includes(refName);
   return {
     mode: "ci",

package/packages/core/paper.js

@@ -46,6 +46,11 @@ import {
   scaffoldReadme,
 } from "./paper-scaffold-content.js";
 import { executePaperNpmBootstrap as executePaperNpmBootstrapOperation } from "./paper-npm-bootstrap.js";
+import {
+  appendNextDevelopmentToml,
+  nextDevelopmentWorkflowHeader,
+  projectNextDevelopmentToml,
+} from "./next-development-projection.js";
 
 export { PAPER_PATHS, resolvePaperRepository } from "./paper-repository.js";
 export {
@@ -350,7 +355,7 @@ immutable_base_url = ${tomlString(joinUrl(siteBaseUrl, "archive").replace(/\/$/,
 registry_path = ".buildchain/publication/publication-registry.json"
 `
     : "";
-  return `schema = 1
+  return appendNextDevelopmentToml(`schema = 1
 
 [project]
 type = "publication-artifact"
@@ -384,14 +389,14 @@ command = "make pdf"
 
 [lifecycle.verify]
 command = "make check"
-`;
+`);
 }
 
 function scaffoldBuildWorkflow(
   buildchainSha,
   { artifactName = "paper-publication" } = {},
 ) {
-  return `name: Build
+  return `${nextDevelopmentWorkflowHeader()}name: Build
 
 on:
   workflow_dispatch:
@@ -419,7 +424,7 @@ jobs:
 }
 
 function scaffoldVerifyWorkflow(buildchainSha) {
-  return `name: Verify
+  return `${nextDevelopmentWorkflowHeader()}name: Verify
 
 on:
   pull_request:
@@ -450,7 +455,7 @@ function scaffoldReleaseWorkflow(
   const passportInput = releasePassportProductName
     ? `      release-passport-product-name: ${JSON.stringify(releasePassportProductName)}\n`
     : "";
-  return `name: Paper Release
+  return `${nextDevelopmentWorkflowHeader()}name: Paper Release
 
 on:
   workflow_dispatch:
@@ -997,6 +1002,12 @@ function migrationFiles({
     runtimeIdentity.version,
   );
   const files = new Map([
+    [
+      PAPER_PATHS.config,
+      projectNextDevelopmentToml(
+        fs.readFileSync(path.resolve(cwd, PAPER_PATHS.config), "utf8"),
+      ),
+    ],
     [PAPER_PATHS.contractLock, contractLockText],
     [PAPER_PATHS.versionPin, `${runtimeIdentity.version}\n`],
     [PAPER_PATHS.buildWorkflow, buildWorkflow],

package/packages/core/published-delivery-authority.js

@@ -0,0 +1,266 @@
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+import {
+  copyFile,
+  mkdir,
+  mkdtemp,
+  readFile,
+  realpath,
+  rm,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+import { pathToFileURL } from "node:url";
+import { execFile } from "node:child_process";
+
+import { adopterDeliveryGateDigest } from "./adopter-delivery-gate.js";
+
+export const PUBLISHED_DELIVERY_AUTHORITY_CONTRACT =
+  "kungfu-buildchain-published-delivery-authority/v1";
+
+const execFileAsync = promisify(execFile);
+const ROOT_PATTERN = /^sha256:[0-9a-f]{64}$/;
+const PACKAGES = [
+  {
+    key: "buildchain",
+    name: "@kungfu-tech/buildchain",
+    packageRoot: "archive",
+    modules: {
+      adopterDeliveryGate: "packages/core/adopter-delivery-gate.js",
+      bootstrap: "packages/core/buildchain-delivery-bootstrap.js",
+      infrastructure: "packages/core/buildchain-delivery-infrastructure.js",
+      kfdCategoryDriver: "packages/core/kfd-adopter-category-driver.js",
+    },
+  },
+  {
+    key: "kfd",
+    name: "@kungfu-tech/kfd",
+    packageRoot: "profiles/adopter-conformance/adopters/kfd/manifest.json",
+    modules: {},
+  },
+];
+
+async function sha256File(file) {
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(file)) hash.update(chunk);
+  return `sha256:${hash.digest("hex")}`;
+}
+
+function exactDeclaration(value, expectedName, label) {
+  if (
+    value?.name !== expectedName ||
+    typeof value.version !== "string" ||
+    value.version.length === 0 ||
+    typeof value.archivePath !== "string" ||
+    value.archivePath.length === 0 ||
+    !ROOT_PATTERN.test(value.archiveRoot ?? "") ||
+    !ROOT_PATTERN.test(value.artifactRoot ?? "")
+  ) {
+    throw new TypeError(`${label} package declaration is incomplete`);
+  }
+  return structuredClone(value);
+}
+
+function safeArchiveEntries(listing, verboseListing, label) {
+  const entries = listing.split("\n").filter(Boolean);
+  const types = verboseListing.split("\n").filter(Boolean);
+  if (entries.length === 0 || entries.length !== types.length) {
+    throw new Error(`${label} archive listing is incomplete`);
+  }
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index];
+    const parts = entry.split("/");
+    if (
+      parts[0] !== "package" ||
+      parts.some((part, partIndex) =>
+        partIndex === parts.length - 1 && part === ""
+          ? false
+          : part === "" || part === "." || part === "..",
+      )
+    ) {
+      throw new Error(`${label} archive contains an unsafe path`);
+    }
+    if (!["-", "d"].includes(types[index][0])) {
+      throw new Error(`${label} archive contains a non-file entry`);
+    }
+  }
+}
+
+async function extractPackage(declaration, destination, definition, label) {
+  const archivePath = path.resolve(declaration.archivePath);
+  const observedRoot = await sha256File(archivePath);
+  if (observedRoot !== declaration.archiveRoot) {
+    throw new Error(`${label} archive bytes do not match archiveRoot`);
+  }
+  await mkdir(destination, { recursive: true });
+  const stagedArchiveName = `.buildchain-${definition.key}-authority.tgz`;
+  const stagedArchivePath = path.join(
+    path.dirname(destination),
+    stagedArchiveName,
+  );
+  const stagedArchiveFile = `../${stagedArchiveName}`;
+  await copyFile(archivePath, stagedArchivePath);
+  try {
+    if ((await sha256File(stagedArchivePath)) !== declaration.archiveRoot) {
+      throw new Error(`${label} staged archive bytes do not match archiveRoot`);
+    }
+    const [{ stdout: listing }, { stdout: verboseListing }] = await Promise.all(
+      [
+        execFileAsync("tar", ["-tzf", stagedArchiveFile], {
+          cwd: destination,
+          maxBuffer: 16 * 1024 * 1024,
+        }),
+        execFileAsync("tar", ["-tvzf", stagedArchiveFile], {
+          cwd: destination,
+          maxBuffer: 16 * 1024 * 1024,
+        }),
+      ],
+    );
+    safeArchiveEntries(listing, verboseListing, label);
+    await execFileAsync(
+      "tar",
+      ["-xzf", stagedArchiveFile, "--strip-components", "1"],
+      { cwd: destination, maxBuffer: 16 * 1024 * 1024 },
+    );
+  } finally {
+    await rm(stagedArchivePath, { force: true });
+  }
+  const packageJsonPath = path.join(destination, "package.json");
+  const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+  if (
+    packageJson.name !== declaration.name ||
+    packageJson.version !== declaration.version
+  ) {
+    throw new Error(`${label} extracted package identity does not match`);
+  }
+  if (definition.packageRoot === "archive") {
+    if (declaration.artifactRoot !== declaration.archiveRoot) {
+      throw new Error(`${label} package artifactRoot must match archiveRoot`);
+    }
+  } else {
+    const packageManifest = JSON.parse(
+      await readFile(path.join(destination, definition.packageRoot), "utf8"),
+    );
+    const packageCut = packageManifest?.kfdCut?.package;
+    if (
+      packageCut?.name !== declaration.name ||
+      packageCut?.version !== declaration.version ||
+      packageCut?.artifactRoot !== declaration.artifactRoot
+    ) {
+      throw new Error(`${label} semantic package identity does not match`);
+    }
+  }
+  const destinationRoot = await realpath(destination);
+  if (!destinationRoot.endsWith(path.join(...declaration.name.split("/")))) {
+    throw new Error(`${label} extraction escaped its package coordinate`);
+  }
+  return {
+    name: declaration.name,
+    version: declaration.version,
+    archiveRoot: declaration.archiveRoot,
+    artifactRoot: declaration.artifactRoot,
+  };
+}
+
+async function importAuthorityRuntime(buildchainRoot) {
+  const definition = PACKAGES[0];
+  const imported = {};
+  for (const [key, relativePath] of Object.entries(definition.modules)) {
+    imported[key] = await import(
+      pathToFileURL(path.join(buildchainRoot, relativePath)).href
+    );
+  }
+  const runtime = {
+    createAdopterDeliveryGate:
+      imported.adopterDeliveryGate.createAdopterDeliveryGate,
+    createPackageArtifactProfile:
+      imported.adopterDeliveryGate.createPackageArtifactProfile,
+    qualifyBuildchainDeliveryInfrastructureBootstrap:
+      imported.bootstrap.qualifyBuildchainDeliveryInfrastructureBootstrap,
+    createBuildchainDeliveryInfrastructureInstanceManifest:
+      imported.infrastructure
+        .createBuildchainDeliveryInfrastructureInstanceManifest,
+    verifyBuildchainDeliveryInfrastructureInstance:
+      imported.infrastructure.verifyBuildchainDeliveryInfrastructureInstance,
+    createKfdAdopterCategoryProtocolDriver:
+      imported.kfdCategoryDriver.createKfdAdopterCategoryProtocolDriver,
+  };
+  for (const [name, implementation] of Object.entries(runtime)) {
+    if (typeof implementation !== "function") {
+      throw new Error(`published Buildchain authority is missing ${name}`);
+    }
+  }
+  return runtime;
+}
+
+export async function loadPublishedBuildchainDeliveryAuthority({
+  buildchain,
+  kfd,
+} = {}) {
+  const declarations = {
+    buildchain: exactDeclaration(
+      buildchain,
+      "@kungfu-tech/buildchain",
+      "Buildchain authority",
+    ),
+    kfd: exactDeclaration(kfd, "@kungfu-tech/kfd", "KFD authority"),
+  };
+  const temporaryRoot = await mkdtemp(
+    path.join(tmpdir(), "buildchain-published-delivery-authority-"),
+  );
+  let retained = false;
+  try {
+    const identities = {};
+    for (const definition of PACKAGES) {
+      identities[definition.key] = await extractPackage(
+        declarations[definition.key],
+        path.join(temporaryRoot, "node_modules", ...definition.name.split("/")),
+        definition,
+        `${definition.key} authority`,
+      );
+    }
+    const authorityRuntime = await importAuthorityRuntime(
+      path.join(temporaryRoot, "node_modules", ...PACKAGES[0].name.split("/")),
+    );
+    const authority = {
+      schemaVersion: 1,
+      contract: PUBLISHED_DELIVERY_AUTHORITY_CONTRACT,
+      packages: identities,
+      moduleCoordinates: structuredClone(PACKAGES[0].modules),
+      qualifying: false,
+      selfCertified: false,
+      releaseAuthorized: false,
+      finalAuthority:
+        "caller-bound-public-npm-archive-bytes-and-package-identity",
+    };
+    authority.authorityRoot = adopterDeliveryGateDigest(authority);
+    retained = true;
+    return {
+      ...authority,
+      authorityRuntime,
+      temporaryRoot,
+      async dispose() {
+        await rm(temporaryRoot, { recursive: true, force: true });
+      },
+    };
+  } finally {
+    if (!retained) await rm(temporaryRoot, { recursive: true, force: true });
+  }
+}
+
+export async function withPublishedBuildchainDeliveryAuthority(
+  declarations,
+  operation,
+) {
+  if (typeof operation !== "function") {
+    throw new TypeError("published authority operation must be a function");
+  }
+  const authority =
+    await loadPublishedBuildchainDeliveryAuthority(declarations);
+  try {
+    return await operation(authority);
+  } finally {
+    await authority.dispose();
+  }
+}

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

@@ -308,6 +308,42 @@ function validateProductPayloads({ passport, artifacts, productPayloadManifests,
   }
 }
 
+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,
@@ -318,29 +354,36 @@ function validateCandidateProvenance({
   run,
   workflow,
   pullRequest,
-  ancestry,
+  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.");
-  if (run?.status !== "completed" || run?.conclusion !== "success" || run?.event !== "pull_request") {
-    fail("untrusted-build-run", "candidate run must be a successful completed pull_request build", "Choose a successful allowed Build workflow run.");
-  }
   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(run?.pullRequestNumbers) && run.pullRequestNumbers.includes(Number(pullRequest?.number));
-  const boundByHead = run?.headSha === pullRequest?.headSha && normalizedRef(run?.headBranch) === normalizedRef(pullRequest?.headRef);
+  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") fail("ancestry-invalid", "candidate merge is not an ancestor of the promotion SHA", "Promote a descendant of the verified merged candidate identity.");
+  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 };
 }
 
@@ -354,12 +397,13 @@ function validateCandidateIdentity({
   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: channel, buildSummary });
+  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,
@@ -369,6 +413,7 @@ function validateCandidateIdentity({
     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.");
@@ -378,18 +423,18 @@ function validateCandidateIdentity({
   return { sha, tree, runtimeSha, toolingSha };
 }
 
-function validateRecoveryTransaction({ existingTransaction, expectedTransactionId, repository, version, passport, sha, targetRef, candidateRoot }) {
+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: sha, targetRef: normalizedRef(targetRef) });
+    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.");
-    assertEqual(existingTransaction.source_sha, sha, "transaction-identity-conflict", "durable transaction source SHA", "Resume with the transaction's exact promotion SHA or enter repair_required.");
+    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, passport.target.channel, "transaction-identity-conflict", "durable transaction channel", "Enter repair_required; never move a transaction between channels.");
+    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;
@@ -415,6 +460,7 @@ export function verifyReleaseCandidateRecovery({
   workflow,
   pullRequest,
   ancestry,
+  anchorProvenance = undefined,
   passport,
   buildSummary,
   controllerReceipts = [],
@@ -430,10 +476,11 @@ export function verifyReleaseCandidateRecovery({
   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,
+    expectedRuntimeSha, currentToolingSha, passport, buildSummary, anchorProvenance,
   });
 
   const recoveredArtifacts = artifacts.map(normalizeArtifact).sort((left, right) => left.name.localeCompare(right.name));
@@ -478,7 +525,7 @@ export function verifyReleaseCandidateRecovery({
 
   const version = required(publicationVersion || passport.target?.version, "publicationVersion");
   const actualTransactionId = validateRecoveryTransaction({
-    existingTransaction, expectedTransactionId, repository, version, passport, sha, targetRef, candidateRoot,
+    existingTransaction, expectedTransactionId, repository, version, passport, channel, sha, targetRef, candidateRoot,
   });
 
   const receipt = {
@@ -496,9 +543,17 @@ export function verifyReleaseCandidateRecovery({
       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: passport.target.channel,
+      channel,
       ref: normalizedRef(targetRef),
       sha,
       observedRefSha: exactSha(targetRefSha, "targetRefSha"),

package/packages/core/release-candidate.js

@@ -206,7 +206,7 @@ function validateConsumerPolicyEvidence(passport, check) {
     receipt: passport.consumerPolicy.receipt,
     receiptRoot: passport.consumerPolicy.receiptRoot,
     repository: passport.repository,
-    sourceSha: passport.source?.headSha,
+    sourceSha: passport.target?.ref === "publish-gate/anchor" ? passport.consumerPolicy.receipt?.caller?.sourceSha : passport.source?.headSha,
     resolvedRuntimeSha: passport.buildchain?.sha,
   });
   for (const failure of verification.failures) {
@@ -403,7 +403,7 @@ export function createReleaseCandidatePassport({
   };
   const normalizedConsumerPolicy = normalizeConsumerPolicyEvidence(consumerPolicyReceipt, {
     repository: repository || normalizedSummary.git?.repository || "",
-    sourceSha,
+    sourceSha: normalizedSummary.publishSource?.ref === "publish-gate/anchor" ? (consumerPolicyReceipt?.receipt || consumerPolicyReceipt)?.caller?.sourceSha : sourceSha,
     runtimeSha: resolvedBuildchain.sha,
   });
   if (isV4BuildchainRuntime(resolvedBuildchain) && !normalizedConsumerPolicy) {