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

package/scripts/project-cut-merge-queue-admission.mjs

@@ -0,0 +1,394 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+const GIT_OID = /^[0-9a-f]{40}$/u;
+const CONTENT_ROOT = /^sha256:[0-9a-f]{64}$/u;
+const FAMILY_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$/u;
+const FAMILY_MARKER =
+  /<!-- kungfu-family-queue-lease:v1 ([A-Za-z0-9_-]+) -->/gu;
+const FAMILY_LEASE_SCHEMA = "kungfu.project-cut.family-queue-lease/v1";
+
+export class ProjectCutAdmissionError extends Error {
+  constructor(reasonCode, message) {
+    super(message);
+    this.name = "ProjectCutAdmissionError";
+    this.reasonCode = reasonCode;
+  }
+}
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => [key, stableValue(entry)]),
+    );
+  }
+  return value;
+}
+
+function canonicalBytes(value) {
+  return Buffer.from(`${JSON.stringify(stableValue(value))}\n`, "utf8");
+}
+
+function contentRoot(value) {
+  return `sha256:${crypto.createHash("sha256").update(canonicalBytes(value)).digest("hex")}`;
+}
+
+function exactRoot(value, label) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase();
+  if (!CONTENT_ROOT.test(normalized))
+    throw new Error(`${label} must be an exact SHA-256 root`);
+  return normalized;
+}
+
+function familyId(value, label) {
+  const normalized = String(value || "").trim();
+  if (!FAMILY_ID.test(normalized)) throw new Error(`${label} is invalid`);
+  return normalized;
+}
+
+function git(
+  cwd,
+  args,
+  {
+    env = {},
+    input = undefined,
+    encoding = "utf8",
+    reason = "git-failed",
+  } = {},
+) {
+  const result = spawnSync("git", args, {
+    cwd,
+    env: { ...process.env, ...env },
+    input,
+    encoding,
+    maxBuffer: 64 * 1024 * 1024,
+  });
+  if (result.status !== 0) {
+    const detail = String(result.stderr || result.stdout || "").trim();
+    throw new ProjectCutAdmissionError(
+      reason,
+      `git ${args.join(" ")} failed${detail ? `: ${detail}` : ""}`,
+    );
+  }
+  return encoding === null ? result.stdout : String(result.stdout || "").trim();
+}
+
+function resolveCommit(cwd, revision, label) {
+  const oid = git(cwd, ["rev-parse", "--verify", `${revision}^{commit}`], {
+    reason: `${label}-unresolved`,
+  });
+  if (!GIT_OID.test(oid))
+    throw new ProjectCutAdmissionError(
+      `${label}-unresolved`,
+      `${label} is not an exact commit`,
+    );
+  return oid;
+}
+
+function linearSourceCommits(cwd, fork, head) {
+  const commits = git(
+    cwd,
+    ["rev-list", "--reverse", "--topo-order", `${fork}..${head}`],
+    {
+      reason: "source-history-unreadable",
+    },
+  )
+    .split(/\s+/u)
+    .filter(Boolean);
+  if (commits.length === 0)
+    throw new ProjectCutAdmissionError(
+      "empty-source-range",
+      "source range is empty",
+    );
+  let expectedParent = fork;
+  for (const commit of commits) {
+    const [observed, ...parents] = git(
+      cwd,
+      ["rev-list", "--parents", "-n", "1", commit],
+      {
+        reason: "source-history-unreadable",
+      },
+    ).split(/\s+/u);
+    if (
+      observed !== commit ||
+      parents.length !== 1 ||
+      parents[0] !== expectedParent
+    ) {
+      throw new ProjectCutAdmissionError(
+        "nonlinear-source-range",
+        "source range is not one immutable linear patch series",
+      );
+    }
+    expectedParent = commit;
+  }
+  return commits;
+}
+
+function patchId(cwd, patch) {
+  const output = git(cwd, ["patch-id", "--stable"], {
+    input: patch,
+    encoding: "utf8",
+    reason: "patch-id-failed",
+  });
+  const id = output.split(/\s+/u)[0] || "";
+  if (!GIT_OID.test(id))
+    throw new ProjectCutAdmissionError(
+      "patch-id-failed",
+      "patch has no stable identity",
+    );
+  return id;
+}
+
+function virtualCommitOid(cwd, tree, base, head) {
+  const body = [
+    `tree ${tree}`,
+    `parent ${base}`,
+    "author Buildchain Project Cut <project-cut@kungfu.tech> 0 +0000",
+    "committer Buildchain Project Cut <project-cut@kungfu.tech> 0 +0000",
+    "",
+    `Replay ${head} onto ${base}`,
+    "",
+  ].join("\n");
+  return git(cwd, ["hash-object", "-t", "commit", "--stdin"], {
+    input: body,
+    reason: "candidate-commit-hash-failed",
+  });
+}
+
+function replayProjectCut(cwd, base, head) {
+  const fork = git(cwd, ["merge-base", base, head], {
+    reason: "no-common-fork",
+  });
+  if (!GIT_OID.test(fork))
+    throw new ProjectCutAdmissionError(
+      "no-common-fork",
+      "base and head have no exact fork",
+    );
+  const commits = linearSourceCommits(cwd, fork, head);
+  const temporary = fs.mkdtempSync(
+    path.join(os.tmpdir(), "buildchain-project-cut-"),
+  );
+  const indexPath = path.join(temporary, "index");
+  const indexEnvironment = { GIT_INDEX_FILE: indexPath };
+  try {
+    git(cwd, ["read-tree", base], {
+      env: indexEnvironment,
+      reason: "base-tree-unreadable",
+    });
+    const sourcePatch = git(
+      cwd,
+      ["diff", "--binary", "--full-index", "--no-ext-diff", fork, head],
+      {
+        encoding: null,
+        reason: "source-patch-unreadable",
+      },
+    );
+    const emptySourcePatch = sourcePatch.length === 0;
+    if (emptySourcePatch && commits.length !== 1)
+      throw new ProjectCutAdmissionError("empty-source-composition", "an empty source composition must be exactly one linear commit");
+    if (!emptySourcePatch) git(cwd, ["apply", "--cached", "--3way", "--whitespace=nowarn", "-"], {
+        env: indexEnvironment, input: sourcePatch, encoding: "utf8", reason: "project-cut-conflict",
+      });
+    const candidateTreeOid = git(cwd, ["write-tree"], {
+      env: indexEnvironment,
+      reason: "candidate-tree-unreadable",
+    });
+    const replayPatch = git(
+      cwd,
+      ["diff", "--cached", "--binary", "--full-index", "--no-ext-diff", base],
+      {
+        env: indexEnvironment,
+        encoding: null,
+        reason: "replay-patch-unreadable",
+      },
+    );
+    const sourceNames = git(
+      cwd,
+      ["diff", "--name-status", "--no-renames", fork, head],
+      {
+        reason: "source-paths-unreadable",
+      },
+    );
+    const replayNames = git(
+      cwd,
+      ["diff", "--cached", "--name-status", "--no-renames", base],
+      {
+        env: indexEnvironment,
+        reason: "replay-paths-unreadable",
+      },
+    );
+    const compositionDrifted = emptySourcePatch ? replayPatch.length !== 0 ||
+      sourceNames !== "" || replayNames !== "" : patchId(cwd, sourcePatch) !==
+      patchId(cwd, replayPatch) || sourceNames !== replayNames;
+    if (compositionDrifted) {
+      throw new ProjectCutAdmissionError(
+        "composition-drift",
+        "latest-base replay changes the immutable source composition",
+      );
+    }
+    return {
+      baseCommitOid: base,
+      headCommitOid: head,
+      forkCommitOid: fork,
+      candidateCommitOid: virtualCommitOid(cwd, candidateTreeOid, base, head),
+      candidateTreeOid,
+      replayedCommitCount: commits.length,
+    };
+  } finally {
+    fs.rmSync(temporary, { recursive: true, force: true });
+  }
+}
+
+function encodeMarker(payload) {
+  return canonicalBytes(payload)
+    .toString("base64")
+    .replace(/\+/gu, "-")
+    .replace(/\//gu, "_")
+    .replace(/=+$/gu, "");
+}
+
+function decodeMarker(token) {
+  const padded = `${token}${"=".repeat((4 - (token.length % 4)) % 4)}`
+    .replace(/-/gu, "+")
+    .replace(/_/gu, "/");
+  return JSON.parse(Buffer.from(padded, "base64").toString("utf8"));
+}
+
+function familyLease(input, replay) {
+  const binding = {
+    schema: FAMILY_LEASE_SCHEMA,
+    state: "active",
+    initiativeId: familyId(input.initiativeId, "initiativeId"),
+    assignmentId: familyId(input.assignmentId, "assignmentId"),
+    deliveryClass: familyId(input.deliveryClass, "deliveryClass"),
+    admissionProofRoot: exactRoot(
+      input.admissionProofRoot,
+      "admissionProofRoot",
+    ),
+    queueAttempt: String(input.queueAttempt || "").trim(),
+    pullRequestHead: replay.headCommitOid,
+    baseCommitOid: replay.baseCommitOid,
+    forkCommitOid: replay.forkCommitOid,
+    candidateTreeOid: replay.candidateTreeOid,
+  };
+  const expectedAttempt = `${replay.headCommitOid}@${replay.baseCommitOid}`;
+  if (binding.queueAttempt !== expectedAttempt) {
+    throw new ProjectCutAdmissionError(
+      "queue-attempt-drift",
+      `queueAttempt must equal ${expectedAttempt}`,
+    );
+  }
+  const bindingRoot = contentRoot(binding);
+  const statusContext = `Queue family lease/${bindingRoot.slice(7, 23)}`;
+  const payload = { ...binding, bindingRoot, statusContext };
+  const leaseRoot = contentRoot(payload);
+  const sealed = { ...payload, leaseRoot };
+  return {
+    marker: `<!-- kungfu-family-queue-lease:v1 ${encodeMarker(sealed)} -->`,
+    leaseRoot,
+    statusContext,
+    pullRequestHead: replay.headCommitOid,
+  };
+}
+
+export function parseFamilyQueueLeaseMarker(text) {
+  const matches = [...String(text || "").matchAll(FAMILY_MARKER)];
+  if (matches.length !== 1) return null;
+  try {
+    const payload = decodeMarker(matches[0][1]);
+    const { leaseRoot, bindingRoot, statusContext, ...binding } = payload;
+    if (payload.schema !== FAMILY_LEASE_SCHEMA || payload.state !== "active")
+      return null;
+    if (contentRoot(binding) !== bindingRoot) return null;
+    if (statusContext !== `Queue family lease/${bindingRoot.slice(7, 23)}`)
+      return null;
+    if (contentRoot({ ...binding, bindingRoot, statusContext }) !== leaseRoot)
+      return null;
+    if (encodeMarker(payload) !== matches[0][1]) return null;
+    exactRoot(leaseRoot, "leaseRoot");
+    exactRoot(payload.admissionProofRoot, "admissionProofRoot");
+    for (const field of [
+      "pullRequestHead",
+      "baseCommitOid",
+      "forkCommitOid",
+      "candidateTreeOid",
+    ]) {
+      if (!GIT_OID.test(String(payload[field] || ""))) return null;
+    }
+    return payload;
+  } catch {
+    return null;
+  }
+}
+
+export function releaseFamilyQueueLease(markerText, input = {}) {
+  const lease = parseFamilyQueueLeaseMarker(markerText);
+  if (!lease) throw new Error("family queue lease marker is invalid");
+  const expectedHead = String(input.expectedPullRequestHead || "")
+    .trim()
+    .toLowerCase();
+  if (!GIT_OID.test(expectedHead) || expectedHead !== lease.pullRequestHead) {
+    throw new Error("family queue lease pull request head drifted");
+  }
+  const terminalReason = String(input.terminalReason || "").trim();
+  if (!["controller-failed", "merged"].includes(terminalReason))
+    throw new Error("terminalReason is invalid");
+  const evidenceRoot = input.evidenceRoot
+    ? exactRoot(input.evidenceRoot, "evidenceRoot")
+    : null;
+  if (terminalReason === "merged" && !evidenceRoot)
+    throw new Error("merged family lease requires evidenceRoot");
+  const receipt = {
+    schema: "project.cut.family-queue-release/v1",
+    state: "released",
+    leaseRoot: lease.leaseRoot,
+    pullRequestHead: lease.pullRequestHead,
+    terminalReason,
+    evidenceRoot,
+  };
+  return { ...receipt, releaseRoot: contentRoot(receipt) };
+}
+
+export function qualifyProjectCut(input = {}) {
+  const cwd = path.resolve(input.cwd || process.cwd());
+  const base = resolveCommit(cwd, input.base, "base");
+  const head = resolveCommit(cwd, input.head, "head");
+  const replay = replayProjectCut(cwd, base, head);
+  const familyInputs = [
+    input.initiativeId,
+    input.assignmentId,
+    input.deliveryClass,
+    input.queueAttempt,
+    input.admissionProofRoot,
+  ];
+  const familyCount = familyInputs.filter((value) =>
+    String(value || "").trim(),
+  ).length;
+  if (familyCount !== 0 && familyCount !== familyInputs.length) {
+    throw new ProjectCutAdmissionError(
+      "partial-family-binding",
+      "family admission inputs must be all present or all absent",
+    );
+  }
+  return {
+    schema: "project.cut.merge-queue-admission/v1",
+    ok: true,
+    decision: "qualified",
+    retryable: false,
+    compositionChanged: false,
+    reasonCodes: [],
+    ...replay,
+    ...(familyCount === familyInputs.length
+      ? { familyLease: familyLease(input, replay) }
+      : {}),
+  };
+}

package/scripts/promotion-channel-router.mjs

@@ -66,8 +66,8 @@ export function resolvePromotionChannel({
   }
   const shellRef = intent.shellChannel === "alpha" ? `v${selected.major}-alpha` : `v${selected.major}`;
   return {
-    targetRef: intent.targetRef,
-    publicationChannel: intent.publicationChannel,
+    targetRef: intent.targetRef, publicationChannel: intent.publicationChannel,
+    routerRef: normalized(routerRef), routerSha: normalized(routerSha).toLowerCase(),
     channel: intent.shellChannel,
     major: selected.major,
     shellRef,
@@ -99,8 +99,8 @@ function readPackageVersion(cwd) {
 
 function writeOutputs(file, result) {
   const outputs = {
-    "target-ref": result.targetRef,
-    "publication-channel": result.publicationChannel,
+    "target-ref": result.targetRef, "publication-channel": result.publicationChannel,
+    "router-ref": result.routerRef, "router-sha": result.routerSha,
     channel: result.channel,
     major: String(result.major),
     "shell-ref": result.shellRef,

package/scripts/promotion-routing-evidence.mjs

@@ -1,9 +1,7 @@
 #!/usr/bin/env node
-
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-
 function createPromotionRoutingEvidence({
   env = process.env,
   cwd = process.cwd(),
@@ -55,13 +53,45 @@ function createPromotionRoutingEvidence({
   }
   return { routing, routingPath, candidatePath };
 }
-
+function bundlePromotionControllerEvidence({
+  env = process.env,
+  cwd = process.cwd(),
+} = {}) {
+  const finalizationNeeded = env.FINALIZATION_NEEDED === "true";
+  const files = [
+    [env.RELEASE_CANDIDATE_PASSPORT, "release-candidate-passport.json"],
+    [env.PUBLISH_EVIDENCE, "publish-evidence.json"],
+    ...(!finalizationNeeded
+      ? [[env.RELEASE_PASSPORT, "release-passport.json"]]
+      : []),
+    ...(env.PUBLICATION_COMMIT_ENABLED === "true" && !finalizationNeeded
+      ? [[env.PUBLICATION_COMMIT_EVIDENCE, "publication-commit-evidence.json"]]
+      : []),
+    ...(!finalizationNeeded ? [
+      [env.RELEASE_ACTIVATION_RECEIPTS, "release-activation-receipt-set.json"],
+      [env.RELEASED_PRODUCT_EVIDENCE, "released-product-evidence.json"],
+      [env.RELEASE_PROPAGATION_CAPTURE, "release-propagation-capture.json"],
+    ].filter(([source]) => source) : []),
+  ];
+  const outputDir = path.join(cwd, ".buildchain/controller/promotion-evidence");
+  fs.mkdirSync(outputDir, { recursive: true });
+  for (const [source, name] of files) {
+    if (!source || !fs.existsSync(path.resolve(cwd, source)))
+      throw new Error(`promotion controller evidence is missing: ${source || name}`);
+    fs.copyFileSync(path.resolve(cwd, source), path.join(outputDir, name));
+  }
+  return { files: files.map(([, name]) => name), outputDir };
+}
 if (
   process.argv[1] &&
   import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href
 ) {
   try {
-    createPromotionRoutingEvidence();
+    if (process.argv[2] === "bundle-controller-evidence") {
+      bundlePromotionControllerEvidence();
+    } else {
+      createPromotionRoutingEvidence();
+    }
   } catch (error) {
     console.error(
       `promotion routing evidence failed: ${error instanceof Error ? error.message : String(error)}`,
@@ -69,5 +99,4 @@ if (
     process.exitCode = 1;
   }
 }
-
-export { createPromotionRoutingEvidence };
+export { bundlePromotionControllerEvidence, createPromotionRoutingEvidence };

package/scripts/release-candidate-anchor-provenance.mjs

@@ -0,0 +1,99 @@
+import path from "node:path";
+
+export function resolveAnchorRecoveryRequest({ passport, buildSummary, transactionId = "" } = {}) {
+  if (Number(passport?.pullRequest?.number || 0)) return undefined;
+  if (passport?.target?.channel !== "anchor" || passport?.target?.ref !== "publish-gate/anchor") {
+    throw new Error("Release Candidate Passport has no PR identity");
+  }
+  let releaseManifest;
+  try {
+    releaseManifest = JSON.parse(buildSummary?.publishSource?.releaseManifest || "");
+  } catch {
+    throw new Error("anchored candidate release manifest is invalid");
+  }
+  const request = releaseManifest?.anchorRequest;
+  if (
+    releaseManifest?.sourceRef !== "publish-gate/anchor" ||
+    releaseManifest?.sourceSha !== passport.source?.headSha ||
+    request?.schema !== 1 ||
+    request?.contract !== "kungfu-buildchain-explicit-publish-anchor-request/v1" ||
+    !request.assignmentId ||
+    !/^native:[0-9a-f-]+$/u.test(String(request.attemptId || "")) ||
+    request.transactionId !== transactionId ||
+    request.source?.sha !== passport.source?.headSha ||
+    request.source?.tree !== passport.source?.treeHash ||
+    !/^\d+$/u.test(String(request.supersededCandidate?.workflowRunId || "")) ||
+    !/^[0-9a-f]{40}$/u.test(String(request.supersededCandidate?.sha || "")) ||
+    !/^sha256:[0-9a-f]{64}$/u.test(String(request.supersededCandidate?.root || "")) ||
+    request.runtime?.sha !== passport.buildchain?.sha
+  ) {
+    throw new Error("anchored candidate request does not bind the sealed recovery identity");
+  }
+  return request;
+}
+
+function normalizeRun(run, repository) {
+  return {
+    id: String(run.id), repository,
+    headRepository: run.head_repository?.full_name || "",
+    status: run.status, conclusion: run.conclusion,
+    event: run.event, path: run.path, name: run.name,
+    headSha: run.head_sha || "", headBranch: run.head_branch || "",
+    pullRequestNumbers: (run.pull_requests || []).map((entry) => Number(entry.number)),
+  };
+}
+
+export function normalizeCandidateRun(run, repository) {
+  return normalizeRun(run, repository);
+}
+
+export function normalizeAnchorProvenance(anchorProvenance, repository) {
+  if (!anchorProvenance) return undefined;
+  return {
+    request: anchorProvenance.request,
+    run: normalizeRun(anchorProvenance.run, repository),
+    workflow: {
+      path: anchorProvenance.workflow.path,
+      name: anchorProvenance.workflow.name,
+      state: anchorProvenance.workflow.state,
+    },
+    passport: anchorProvenance.passport,
+    buildSummary: anchorProvenance.buildSummary,
+  };
+}
+
+export async function recoverCandidateProvenance({
+  passport, buildSummary, transactionId, repoInfo, artifactName,
+  expectedWorkflowFile, expectedWorkflowName, channel, apiUrl, token,
+  fetchImpl, archiveDir, bundleRoot, githubJson, selectReleaseCandidateArtifacts,
+  downloadArtifact, readOnlyJson,
+}) {
+  const request = resolveAnchorRecoveryRequest({ passport, buildSummary, transactionId });
+  if (!request) {
+    return { anchorProvenance: undefined, provenancePassport: passport };
+  }
+  const runId = String(request.supersededCandidate.workflowRunId);
+  const run = await githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/runs/${runId}` });
+  const workflow = await githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/workflows/${run.workflow_id}` });
+  const artifactResponse = await githubJson({ apiUrl, token, fetchImpl, path: `/repos/${repoInfo.owner}/${repoInfo.repo}/actions/runs/${runId}/artifacts?per_page=100` });
+  const artifacts = Array.isArray(artifactResponse.artifacts) ? artifactResponse.artifacts : [];
+  if (Number(artifactResponse.total_count || artifacts.length) !== artifacts.length) throw new Error("superseded candidate run has more than 100 artifacts; complete pagination is required before recovery");
+  const selected = selectReleaseCandidateArtifacts({ artifacts, artifactName });
+  const provenanceRoot = path.join(bundleRoot, "anchored-provenance");
+  const passportDownload = await downloadArtifact({ artifact: selected.passport, repoInfo, apiUrl, token, archiveDir, bundleRoot: provenanceRoot, fetchImpl });
+  const summaryDownload = await downloadArtifact({ artifact: selected.summary, repoInfo, apiUrl, token, archiveDir, bundleRoot: provenanceRoot, fetchImpl });
+  const recoveredPassport = readOnlyJson(passportDownload.files.filter((file) => path.basename(file.path) === "release-candidate-passport.json"), "superseded release-candidate-passport.json");
+  const recoveredBuildSummary = readOnlyJson(summaryDownload.files.filter((file) => path.basename(file.path) === "build-summary.json"), "superseded build-summary.json");
+  if (
+    String(run.id) !== runId ||
+    recoveredPassport.workflow?.runId !== runId ||
+    recoveredPassport.workflow?.name !== expectedWorkflowName ||
+    String(workflow.path || run.path || "").split("@")[0].replace(/^\.github\/workflows\//u, "") !== expectedWorkflowFile.replace(/^\.github\/workflows\//u, "") ||
+    recoveredPassport.target?.channel !== channel ||
+    recoveredPassport.source?.headSha !== request.supersededCandidate.sha ||
+    recoveredPassport.source?.treeHash !== request.source.tree ||
+    `sha256:${recoveredPassport.candidateHash}` !== request.supersededCandidate.root
+  ) throw new Error("superseded candidate provenance does not match the anchored request");
+  const anchorProvenance = { request, run, workflow, passport: recoveredPassport, buildSummary: recoveredBuildSummary };
+  return { anchorProvenance, provenancePassport: recoveredPassport };
+}

package/scripts/release-candidate-resolver.mjs

@@ -9,6 +9,8 @@ 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";
+import { v4ContentRoot } from "../packages/core/v4-canonical-contracts.js";
+import { v4PublicationQualificationRoot, validateV4PublicationQualificationReceipt } from "../packages/core/v4-publication-qualification.js";
 
 const DEFAULT_WORKFLOW_FILE = "build-surface-fixture.yml";
 
@@ -434,6 +436,42 @@ function findDownloadedFile(root, filename) {
   return "";
 }
 
+function resolveV4PublicationEvidence(passportDir, passport, outputPath) {
+  const stageCapsulesPath = findDownloadedFile(passportDir, "release-candidate-stage-capsules.json");
+  const publicationQualificationPath = findDownloadedFile(passportDir, "release-candidate-publication-qualification.json");
+  if (!passport.consumerPolicy?.receiptRoot) {
+    return {
+      paths: {
+        stageCapsules: stageCapsulesPath ? outputPath(stageCapsulesPath) : "",
+        publicationQualification: publicationQualificationPath ? outputPath(publicationQualificationPath) : "",
+      },
+      publicationQualificationRoot: "",
+    };
+  }
+  if (!stageCapsulesPath || !publicationQualificationPath) {
+    throw new Error("v4 release candidate is missing Stage Capsules or publication qualification receipt");
+  }
+  const stageCapsules = JSON.parse(fs.readFileSync(stageCapsulesPath, "utf8"));
+  const qualification = JSON.parse(fs.readFileSync(publicationQualificationPath, "utf8"));
+  validateV4PublicationQualificationReceipt(qualification, {
+    repository: passport.repository,
+    candidateRoot: `sha256:${passport.candidateHash}`,
+    sourceSha: passport.source.headSha,
+    sourceRoot: v4ContentRoot("candidate-identity", passport.source),
+    artifactRoot: v4PublicationQualificationRoot(stageCapsules.capsules.map(({ publicationArtifact }) => publicationArtifact)),
+    policyDigest: passport.consumerPolicy.receiptRoot,
+  });
+  if (stageCapsules.publicationQualificationRoot !== qualification.receiptRoot) throw new Error("Stage Capsules do not bind the publication qualification receipt");
+  if (stageCapsules.capsules.some(({ capsule }) => capsule.identity.qualificationRoot !== qualification.receiptRoot)) throw new Error("a Stage Capsule does not bind the publication qualification receipt");
+  return {
+    paths: {
+      stageCapsules: outputPath(stageCapsulesPath),
+      publicationQualification: outputPath(publicationQualificationPath),
+    },
+    publicationQualificationRoot: qualification.receiptRoot,
+  };
+}
+
 export async function resolveReleaseCandidateArtifacts({
   repository,
   targetRef,
@@ -667,6 +705,7 @@ export async function resolveReleaseCandidateArtifacts({
     throw new Error("downloaded release-candidate artifacts did not contain release-candidate-passport.json and build-summary.json");
   }
   const passport = JSON.parse(fs.readFileSync(passportPath, "utf8"));
+  const v4Publication = resolveV4PublicationEvidence(passportDir, passport, outputPath);
   const platformManifestPaths = findDownloadedFiles(payloadDir, "manifest.json");
   const githubArtifactAttestationPolicyPaths = findDownloadedFiles(
     payloadDir,
@@ -722,6 +761,7 @@ export async function resolveReleaseCandidateArtifacts({
     paths: {
       passport: outputPath(passportPath),
       buildSummary: outputPath(buildSummaryPath),
+      ...v4Publication.paths,
       payloads: outputPath(payloadDir),
       platformManifests: platformManifestPaths.map(outputPath),
       githubArtifactAttestationPolicies: githubArtifactAttestationPolicyPaths.map(outputPath),
@@ -738,6 +778,7 @@ export async function resolveReleaseCandidateArtifacts({
     githubArtifactAttestationPolicyCount: githubArtifactAttestationPolicyPaths.length,
     npmTarballCount: npmTarballPaths.length,
     publishRequiredArtifacts: generatedRequiredArtifacts,
+    publicationQualificationRoot: v4Publication.publicationQualificationRoot,
   };
 }
 
@@ -766,6 +807,9 @@ export async function resolveReleaseCandidateArtifactsCli() {
     "promote-only-release-candidate": String(result.enabled === true),
     "release-candidate-passport-path": result.paths?.passport || "",
     "release-candidate-build-summary-path": result.paths?.buildSummary || "",
+    "release-candidate-stage-capsules-path": result.paths?.stageCapsules || "",
+    "release-candidate-publication-qualification-path": result.paths?.publicationQualification || "",
+    "release-candidate-publication-qualification-root": result.publicationQualificationRoot || "",
     "release-candidate-version": result.version || "",
     "release-candidate-source-sha": result.artifacts?.sourceSha || "",
     "release-candidate-artifact": result.artifacts?.passport || "",