@kungfu-tech/buildchain 2.12.7-alpha.1 → 2.12.7-alpha.11

package/packages/core/publication-artifact-candidate.js

@@ -0,0 +1,128 @@
+import crypto from "node:crypto";
+
+import { validateControllerReceipt } from "./controller-evidence.js";
+
+export const PUBLICATION_ARTIFACT_CANDIDATE_CONTRACT =
+  "kungfu-buildchain-publication-artifact-candidate";
+
+const MANIFEST_CONTRACT = "kungfu-buildchain-publication-artifact-manifest";
+const PASSPORT_CONTRACT = "kungfu-buildchain-publication-artifact-passport";
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(",")}]`;
+  if (value && typeof value === "object") {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+export function publicationArtifactCandidateDigest(value) {
+  return crypto.createHash("sha256").update(stableJson(value)).digest("hex");
+}
+
+export function resolvePublicationCandidateFile(files = [], candidatePath) {
+  const normalizedPath = requiredString(candidatePath, "candidatePath").replaceAll("\\", "/");
+  if (normalizedPath.startsWith("/") || normalizedPath.split("/").includes("..")) {
+    throw new Error(`publication artifact candidate contains an unsafe path: ${normalizedPath}`);
+  }
+  const matches = files.filter((entry) => entry.path === normalizedPath);
+  if (matches.length !== 1) {
+    throw new Error(`expected exactly one publication candidate file at ${normalizedPath}, found ${matches.length}`);
+  }
+  return matches[0].path;
+}
+
+function requiredString(value, label) {
+  const normalized = String(value || "").trim();
+  if (!normalized) throw new Error(`${label} must be a non-empty string`);
+  return normalized;
+}
+
+function normalizeDigest(value, label) {
+  const normalized = requiredString(value, label).replace(/^sha256:/, "").toLowerCase();
+  if (!/^[0-9a-f]{64}$/.test(normalized)) throw new Error(`${label} must be a sha256 digest`);
+  return normalized;
+}
+
+function normalizeGitSha(value, label) {
+  const normalized = requiredString(value, label).toLowerCase();
+  if (!/^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(normalized)) {
+    throw new Error(`${label} must be a 40- or 64-character Git SHA`);
+  }
+  return normalized;
+}
+
+export function createPublicationArtifactCandidate({
+  repository,
+  sourceSha,
+  sourceTreeSha,
+  runtimeSha,
+  manifest,
+  passport,
+  controllerReceipt,
+  files = [],
+} = {}) {
+  const normalizedRepository = requiredString(repository, "repository");
+  const normalizedSourceSha = normalizeGitSha(sourceSha, "sourceSha");
+  const normalizedSourceTreeSha = normalizeGitSha(sourceTreeSha, "sourceTreeSha");
+  const normalizedRuntimeSha = normalizeGitSha(runtimeSha, "runtimeSha");
+  if (manifest?.contract !== MANIFEST_CONTRACT) throw new Error("publication artifact manifest contract mismatch");
+  if (passport?.contract !== PASSPORT_CONTRACT || passport.status !== "passed") {
+    throw new Error("publication artifact passport is not qualifying");
+  }
+  if (manifest.source?.sha !== normalizedSourceSha || passport.source?.sha !== normalizedSourceSha) {
+    throw new Error("publication artifact source SHA mismatch");
+  }
+  if (manifest.source?.treeSha !== normalizedSourceTreeSha || passport.source?.treeSha !== normalizedSourceTreeSha) {
+    throw new Error("publication artifact source tree mismatch");
+  }
+  const manifestDigest = crypto.createHash("sha256").update(JSON.stringify(manifest, null, 2)).digest("hex");
+  if (normalizeDigest(passport.manifestDigest, "passport.manifestDigest") !== manifestDigest) {
+    throw new Error("publication artifact passport manifest digest mismatch");
+  }
+  const controllerValidation = validateControllerReceipt(controllerReceipt, {
+    expectedSourceSha: normalizedSourceSha,
+    expectedRuntimeSha: normalizedRuntimeSha,
+  });
+  if (!controllerValidation.ok || !controllerValidation.qualifying) {
+    throw new Error(`publication artifact controller receipt did not qualify: ${controllerValidation.issues.join("; ")}`);
+  }
+  const evidenceKinds = new Set((controllerReceipt.evidence || []).map((entry) => entry.kind));
+  for (const kind of ["publication-manifest", "publication-passport"]) {
+    if (!evidenceKinds.has(kind)) throw new Error(`publication artifact controller receipt is missing ${kind} evidence`);
+  }
+  const normalizedFiles = files.map((entry, index) => {
+    const filePath = requiredString(entry.path, `files[${index}].path`).replaceAll("\\", "/");
+    if (filePath.startsWith("/") || filePath.split("/").includes("..")) {
+      throw new Error(`publication artifact candidate contains an unsafe path: ${filePath}`);
+    }
+    const size = Number(entry.size ?? entry.bytes);
+    if (!Number.isSafeInteger(size) || size < 0) throw new Error(`files[${index}].size must be a non-negative safe integer`);
+    return { path: filePath, size, sha256: normalizeDigest(entry.sha256, `files[${index}].sha256`) };
+  }).sort((left, right) => left.path.localeCompare(right.path));
+  if (new Set(normalizedFiles.map((entry) => entry.path)).size !== normalizedFiles.length) {
+    throw new Error("publication artifact candidate file paths must be unique");
+  }
+  const byPath = new Map(normalizedFiles.map((entry) => [entry.path, entry]));
+  for (const [index, artifact] of (manifest.artifacts || []).entries()) {
+    const artifactPath = requiredString(artifact.path, `manifest.artifacts[${index}].path`);
+    const actual = byPath.get(artifactPath);
+    if (!actual) throw new Error(`publication artifact candidate is missing declared artifact: ${artifactPath}`);
+    if (actual.size !== Number(artifact.bytes) || actual.sha256 !== normalizeDigest(artifact.sha256, `manifest.artifacts[${index}].sha256`)) {
+      throw new Error(`publication artifact candidate bytes do not match manifest: ${artifactPath}`);
+    }
+  }
+  const payload = {
+    schemaVersion: 1,
+    contract: PUBLICATION_ARTIFACT_CANDIDATE_CONTRACT,
+    repository: normalizedRepository,
+    sourceSha: normalizedSourceSha,
+    sourceTreeSha: normalizedSourceTreeSha,
+    runtimeSha: normalizedRuntimeSha,
+    manifestDigest,
+    passportDigest: publicationArtifactCandidateDigest(passport),
+    controllerReceiptDigest: normalizeDigest(controllerReceipt.digest, "controllerReceipt.digest"),
+    files: normalizedFiles,
+  };
+  return { ...payload, candidateDigest: publicationArtifactCandidateDigest(payload) };
+}

package/packages/core/publication-authority.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 
 import { validateControllerReceipt } from "./controller-evidence.js";
+import { createPublicationArtifactCandidate } from "./publication-artifact-candidate.js";
 import { sha256Json, validateReleaseCandidatePassport } from "./release-candidate.js";
 
 export const PUBLICATION_AUTHORITY_REGISTRY_CONTRACT =
@@ -381,6 +382,7 @@ export function createPublicationArtifactManifestSet({
 }
 
 function validateGateAggregate(gateAggregate, { admission, passport }) {
+  const passportSourceSha = passport.source?.headSha || passport.source?.sha;
   if (gateAggregate?.contract === "buildchain.shifu-gate-aggregate/v1") {
     const { digest, ...payload } = gateAggregate;
     const actualDigest = sha256Json(payload);
@@ -390,7 +392,7 @@ function validateGateAggregate(gateAggregate, { admission, passport }) {
     if (gateAggregate.status !== "pass" || gateAggregate.qualifying !== true) {
       throw new Error("gate aggregate is not qualifying");
     }
-    if (![admission.sourceSha, passport.source?.headSha].includes(gateAggregate.sourceSha)) {
+    if (![admission.sourceSha, passportSourceSha].includes(gateAggregate.sourceSha)) {
       throw new Error("gate aggregate source SHA mismatch");
     }
     normalizeDigest(gateAggregate.registry?.digest, "gateAggregate.registry.digest");
@@ -408,7 +410,7 @@ function validateGateAggregate(gateAggregate, { admission, passport }) {
   if (gateAggregate.required !== false) {
     throw new Error("a required Gate policy must supply a qualifying Shifu Gate aggregate");
   }
-  if (![admission.sourceSha, passport.source?.headSha].includes(gateAggregate.sourceSha)) {
+  if (![admission.sourceSha, passportSourceSha].includes(gateAggregate.sourceSha)) {
     throw new Error("publication Gate decision source SHA mismatch");
   }
   const normalizedPolicy = {
@@ -428,6 +430,43 @@ function validatePublicationEvidence(publicationEvidence, admission) {
   if (!publicationEvidence || typeof publicationEvidence !== "object" || Array.isArray(publicationEvidence)) {
     throw new Error("independent publication evidence is required");
   }
+  if (publicationEvidence.publicationArtifactCandidate) {
+    const candidate = createPublicationArtifactCandidate(publicationEvidence.publicationArtifactCandidate);
+    const passport = publicationEvidence.publicationArtifactCandidate.passport;
+    const controllerReceipt = publicationEvidence.publicationArtifactCandidate.controllerReceipt;
+    const controllerReceiptDigest = normalizeDigest(controllerReceipt.digest, "controllerReceipt.digest");
+    if (controllerReceiptDigest !== normalizeDigest(admission.controllerReceiptDigest, "admission.controllerReceiptDigest")) {
+      throw new Error("controller receipt evidence binding mismatch");
+    }
+    const contractDigest = normalizeDigest(controllerReceipt.runtime?.contractDigest, "controllerReceipt.runtime.contractDigest");
+    if (contractDigest !== normalizeDigest(admission.contractDigest, "admission.contractDigest")) {
+      throw new Error("runtime contract evidence binding mismatch");
+    }
+    const gate = validateGateAggregate(publicationEvidence.gateAggregate, { admission, passport });
+    if (gate.gateAggregateDigest !== normalizeDigest(admission.gateAggregateDigest, "admission.gateAggregateDigest")) {
+      throw new Error("Gate aggregate evidence binding mismatch");
+    }
+    if (gate.policyDigest !== normalizeDigest(admission.policyDigest, "admission.policyDigest")) {
+      throw new Error("Gate policy evidence binding mismatch");
+    }
+    if (candidate.candidateDigest !== normalizeDigest(admission.artifactDigest, "admission.artifactDigest")) {
+      throw new Error("publication artifact candidate evidence binding mismatch");
+    }
+    return {
+      sourceTreeSha: candidate.sourceTreeSha,
+      controllerReceiptDigest,
+      contractDigest,
+      gateAggregateDigest: gate.gateAggregateDigest,
+      policyDigest: gate.policyDigest,
+      artifactDigest: candidate.candidateDigest,
+      evidenceDigest: publicationAuthorityDigest({
+        sourceTreeSha: candidate.sourceTreeSha,
+        controllerReceiptDigest,
+        gateAggregateDigest: gate.gateAggregateDigest,
+        artifactDigest: candidate.candidateDigest,
+      }),
+    };
+  }
   const passport = publicationEvidence.releaseCandidatePassport;
   const buildSummary = publicationEvidence.buildSummary;
   const passportValidation = validateReleaseCandidatePassport({

package/packages/core/publication-control-plane-audit.js

@@ -16,6 +16,7 @@ export function evaluatePublicationControlPlaneSnapshot({
   branch,
   packageName,
   publisherMode = "npm-trusted-publisher",
+  requiredStatusCheck = "check",
   snapshot,
   observedAt,
   expiresAt,
@@ -72,7 +73,8 @@ export function evaluatePublicationControlPlaneSnapshot({
     branchPolicy.protected === true &&
     branchPolicy.enforcementLevel === "everyone" &&
     Array.isArray(branchPolicy.requiredStatusChecks) &&
-    branchPolicy.requiredStatusChecks.includes("check") &&
+    branchPolicy.requiredStatusCheck === requiredStatusCheck &&
+    branchPolicy.requiredStatusChecks.includes(requiredStatusCheck) &&
     branchPolicy.requiredCheckPassed === true &&
     branchPolicy.sourceSha === branchPolicy.headSha &&
     branchPolicy.mergedPullRequest === true &&

package/scripts/assemble-publication-artifact-admission.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+
+import {
+  createPublicationAdmission,
+  createPublicationGateDecision,
+  createRunnerProvenance,
+} from "../packages/core/publication-authority.js";
+import { buildPublicationArtifactCandidate } from "./publication-artifact-candidate.mjs";
+
+function required(name) {
+  const value = String(process.env[name] || "").trim();
+  if (!value) throw new Error(`${name} is required`);
+  return value;
+}
+
+function sha256(value) {
+  return crypto.createHash("sha256").update(String(value)).digest("hex");
+}
+
+async function sourceTree(repository, sourceSha, token) {
+  const response = await fetch(
+    `${required("GITHUB_API_URL")}/repos/${repository}/git/commits/${sourceSha}`,
+    {
+      headers: {
+        accept: "application/vnd.github+json",
+        authorization: `Bearer ${token}`,
+        "x-github-api-version": "2022-11-28",
+      },
+    },
+  );
+  if (!response.ok)
+    throw new Error(
+      `could not resolve admitted source tree: GitHub API ${response.status}`,
+    );
+  const commit = await response.json();
+  return String(commit.tree?.sha || "").toLowerCase();
+}
+
+function writeBundle(outputDir, values) {
+  fs.mkdirSync(outputDir, { recursive: true });
+  for (const [name, value] of Object.entries(values)) {
+    fs.writeFileSync(
+      path.join(outputDir, `${name}.json`),
+      `${JSON.stringify(value, null, 2)}\n`,
+    );
+  }
+  if (process.env.GITHUB_OUTPUT) {
+    const output = fs.createWriteStream(process.env.GITHUB_OUTPUT, {
+      flags: "a",
+    });
+    for (const [name, value] of Object.entries(values)) {
+      if (name === "candidate") continue;
+      output.write(
+        `${name.replaceAll("_", "-")}-json=${JSON.stringify(value)}\n`,
+      );
+    }
+    output.end();
+  }
+}
+
+async function main() {
+  const repository = required("BUILDCHAIN_REPOSITORY");
+  const sourceSha = required("BUILDCHAIN_SOURCE_SHA").toLowerCase();
+  const runtimeRoot =
+    process.env.BUILDCHAIN_RUNTIME_ROOT || ".buildchain/authority-runtime";
+  const runtimeSha = execFileSync(
+    "git",
+    ["-C", runtimeRoot, "rev-parse", "HEAD"],
+    { encoding: "utf8" },
+  )
+    .trim()
+    .toLowerCase();
+  const token = required("GITHUB_TOKEN");
+  const treeSha = await sourceTree(repository, sourceSha, token);
+  const candidateBundle = buildPublicationArtifactCandidate({
+    artifactRoot:
+      process.env.BUILDCHAIN_ARTIFACT_ROOT ||
+      ".buildchain/publication-evidence/artifact",
+    controllerRoot:
+      process.env.BUILDCHAIN_CONTROLLER_ROOT ||
+      ".buildchain/publication-evidence/controller",
+    repository,
+    sourceSha,
+    sourceTreeSha: treeSha,
+    runtimeSha,
+  });
+  const controllerReceipt = candidateBundle.evidence.controllerReceipt;
+  const controlPlaneAudit = JSON.parse(
+    fs.readFileSync(required("BUILDCHAIN_CONTROL_PLANE_AUDIT_PATH"), "utf8"),
+  );
+  const registry = JSON.parse(
+    fs.readFileSync(
+      path.join(runtimeRoot, "dist/site/publication-authority-registry.json"),
+      "utf8",
+    ),
+  );
+  const gateAggregate = createPublicationGateDecision({
+    sourceSha,
+    profile: process.env.BUILDCHAIN_GATE_PROFILE || "managed-paper-publication",
+    required: false,
+    rationale:
+      process.env.BUILDCHAIN_GATE_RATIONALE ||
+      "The managed paper repository declares no project-specific Shifu Gate registry.",
+    policy: { scope: "managed-paper-publication", repository },
+  });
+  const runnerProvenance = createRunnerProvenance({
+    runnerClass: "ephemeral",
+    os: required("RUNNER_OS"),
+    architecture: required("RUNNER_ARCH"),
+    imageDigest: sha256(
+      `${process.env.ImageOS || "unknown"}|${process.env.ImageVersion || "unknown"}`,
+    ),
+    measurementDigest: sha256(
+      [
+        process.env.GITHUB_WORKFLOW,
+        process.env.GITHUB_JOB,
+        process.env.GITHUB_RUN_ID,
+        process.env.GITHUB_RUN_ATTEMPT,
+        process.env.RUNNER_ENVIRONMENT,
+      ].join("|"),
+    ),
+    isolation: "github-hosted-single-job",
+  });
+  const issuedAt = new Date();
+  const admission = createPublicationAdmission({
+    registryDigest: registry.registryDigest,
+    workflowPath:
+      process.env.BUILDCHAIN_AUTHORITY_WORKFLOW_PATH ||
+      ".github/workflows/paper-release-sealed.yml",
+    publisherWorkflowPath: required("BUILDCHAIN_PUBLISHER_WORKFLOW_PATH"),
+    repository,
+    sourceSha,
+    runtimeSha,
+    contractDigest: controllerReceipt.runtime?.contractDigest,
+    policyDigest: gateAggregate.policyDigest,
+    controllerReceiptDigest: controllerReceipt.digest,
+    runnerProvenanceDigest: runnerProvenance.receiptDigest,
+    controlPlaneAuditDigest: controlPlaneAudit.receiptDigest,
+    gateAggregateDigest: gateAggregate.digest,
+    environment: "none",
+    product: required("BUILDCHAIN_PUBLICATION_PRODUCT"),
+    target: required("BUILDCHAIN_PUBLICATION_TARGET"),
+    version: required("BUILDCHAIN_PUBLICATION_VERSION"),
+    channel: required("BUILDCHAIN_PUBLICATION_CHANNEL"),
+    artifactDigest: candidateBundle.candidate.candidateDigest,
+    nonce: `${required("GITHUB_RUN_ID")}:${required("GITHUB_RUN_ATTEMPT")}:${sourceSha}:paper`,
+    issuedAt: issuedAt.toISOString(),
+    expiresAt: new Date(issuedAt.getTime() + 10 * 60 * 1000).toISOString(),
+  });
+  const bindingNames = [
+    "repository",
+    "publisherWorkflowPath",
+    "sourceSha",
+    "runtimeSha",
+    "contractDigest",
+    "policyDigest",
+    "controllerReceiptDigest",
+    "gateAggregateDigest",
+    "environment",
+    "product",
+    "target",
+    "version",
+    "channel",
+    "artifactDigest",
+  ];
+  const expected = Object.fromEntries(
+    bindingNames.map((name) => [name, admission[name]]),
+  );
+  writeBundle(
+    process.env.BUILDCHAIN_OUTPUT_DIR ||
+      ".buildchain/publication-authority/auto",
+    {
+      admission,
+      runner_provenance: runnerProvenance,
+      control_plane_audit: controlPlaneAudit,
+      gate_aggregate: gateAggregate,
+      expected,
+      candidate: candidateBundle.candidate,
+    },
+  );
+}
+
+main().catch((error) => {
+  console.error(`assemble publication artifact admission: ${error.message}`);
+  process.exitCode = 1;
+});

package/scripts/assemble-self-publication-admission.mjs

@@ -137,6 +137,7 @@ async function main() {
     isolation: "github-hosted-single-job",
   });
   const packageJson = JSON.parse(fs.readFileSync(path.join(runtimeRoot, "package.json"), "utf8"));
+  const publicationVersion = required("BUILDCHAIN_PUBLICATION_VERSION");
   const issuedAt = new Date();
   const admission = createPublicationAdmission({
     registryDigest: registry.registryDigest,
@@ -154,7 +155,7 @@ async function main() {
     environment: process.env.BUILDCHAIN_PUBLICATION_ENVIRONMENT || "none",
     product: process.env.BUILDCHAIN_PUBLICATION_PRODUCT || "Buildchain",
     target: process.env.BUILDCHAIN_PUBLICATION_TARGET || `npm:${packageJson.name}`,
-    version: process.env.BUILDCHAIN_PUBLICATION_VERSION || packageJson.version,
+    version: publicationVersion,
     channel: required("BUILDCHAIN_PUBLICATION_CHANNEL"),
     artifactDigest: artifactSet.manifestSetDigest,
     nonce: `${required("GITHUB_RUN_ID")}:${required("GITHUB_RUN_ATTEMPT")}:${sourceSha}`,

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

@@ -191,6 +191,7 @@ function main() {
   const workflowPath = flag("workflow", ".github/workflows/release-candidate-promote.yml");
   const workflowRef = flag("workflow-ref");
   const publisherWorkflowPath = flag("publisher-workflow", workflowPath);
+  const requiredStatusCheck = flag("required-status-check", "check");
   const jobId = flag("job", "promote");
   const environment = flag("environment", "none");
   const providerEnvironment = environment === "none" ? "" : environment;
@@ -280,15 +281,16 @@ function main() {
     const checkRuns = githubJson(`repos/${repository}/commits/${sourceSha}/check-runs?per_page=100`, "source check runs");
     const requiredStatusCheckPolicy = branchState.protection?.required_status_checks || {};
     const requiredStatusChecks = requiredStatusCheckPolicy.contexts || [];
-    const requiredCheckSource = (requiredStatusCheckPolicy.checks || []).find((entry) => entry.context === "check");
+    const requiredCheckSource = (requiredStatusCheckPolicy.checks || []).find((entry) => entry.context === requiredStatusCheck);
     branchPolicy = {
       ref: branch,
       policyMode: "provider-enforced-transaction",
       protected: branchState.protected === true,
       enforcementLevel: branchState.protection?.required_status_checks?.enforcement_level || "",
       requiredStatusChecks,
+      requiredStatusCheck,
       requiredCheckPassed: (checkRuns.check_runs || []).some((entry) =>
-        entry.name === "check" &&
+        entry.name === requiredStatusCheck &&
         entry.conclusion === "success" &&
         (!requiredCheckSource?.app_id || entry.app?.id === requiredCheckSource.app_id)
       ),
@@ -350,6 +352,7 @@ function main() {
     branch,
     packageName,
     publisherMode,
+    requiredStatusCheck,
     observedAt: observedAt.toISOString(),
     expiresAt: expiresAt.toISOString(),
     snapshot: {

package/scripts/check-inventory.mjs

@@ -840,6 +840,11 @@ for (const requiredSnippet of [
   "publish-source-ref: ${{ steps.publish-gate.outputs.ref }}",
   "publish-source-sha: ${{ steps.publish-gate.outputs.sha }}",
   "publish-source-locked: ${{ steps.publish-gate.outputs.locked }}",
+  "expected-publication-version: ${{ needs.publication-plan.outputs.version }}",
+  "publication-version: ${{ needs.publication-plan.outputs.version }}",
+  "name: Plan exact publication version",
+  "DRY_RUN: ${{ inputs.dry-run }}",
+  "if (dryRun) {",
   "Enforce Buildchain stable release canary gate",
   "BUILDCHAIN_STABLE_RELEASE_POLICY: .buildchain/stable-release-policy.json",
 ]) {

package/scripts/publication-artifact-candidate.mjs

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import {
+  createPublicationArtifactCandidate,
+  resolvePublicationCandidateFile,
+} from "../packages/core/publication-artifact-candidate.js";
+
+export { resolvePublicationCandidateFile };
+
+function flag(name, fallback = "") {
+  const index = process.argv.indexOf(`--${name}`);
+  return index === -1 ? fallback : String(process.argv[index + 1] || "");
+}
+
+function requiredFlag(name) {
+  const value = flag(name).trim();
+  if (!value) throw new Error(`--${name} is required`);
+  return value;
+}
+
+function filesNamed(root, name) {
+  const matches = [];
+  const pending = [path.resolve(root)];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) pending.push(full);
+      else if (entry.isFile() && entry.name === name) matches.push(full);
+    }
+  }
+  return matches.sort();
+}
+
+function oneJson(root, name) {
+  const matches = filesNamed(root, name);
+  if (matches.length !== 1)
+    throw new Error(
+      `expected exactly one ${name} under ${root}, found ${matches.length}`,
+    );
+  return JSON.parse(fs.readFileSync(matches[0], "utf8"));
+}
+
+function collectFiles(root) {
+  const absoluteRoot = path.resolve(root);
+  const files = [];
+  const pending = [absoluteRoot];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+      const full = path.join(current, entry.name);
+      if (entry.isDirectory()) pending.push(full);
+      else if (entry.isFile()) {
+        files.push({
+          path: path.relative(absoluteRoot, full).split(path.sep).join("/"),
+          size: fs.statSync(full).size,
+          sha256: crypto
+            .createHash("sha256")
+            .update(fs.readFileSync(full))
+            .digest("hex"),
+        });
+      }
+    }
+  }
+  return files.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+export function buildPublicationArtifactCandidate({
+  artifactRoot,
+  controllerRoot,
+  repository,
+  sourceSha,
+  sourceTreeSha,
+  runtimeSha,
+} = {}) {
+  const resolvedArtifactRoot = path.resolve(artifactRoot);
+  const resolvedControllerRoot = path.resolve(controllerRoot);
+  const evidence = {
+    repository,
+    sourceSha,
+    sourceTreeSha,
+    runtimeSha,
+    manifest: oneJson(resolvedArtifactRoot, "publication-artifact.json"),
+    passport: oneJson(
+      resolvedArtifactRoot,
+      "publication-artifact-passport.json",
+    ),
+    controllerReceipt: oneJson(resolvedControllerRoot, "receipt.json"),
+    files: collectFiles(resolvedArtifactRoot),
+  };
+  const candidate = createPublicationArtifactCandidate(evidence);
+  return { schemaVersion: 1, candidate, evidence };
+}
+
+function main() {
+  const result = buildPublicationArtifactCandidate({
+    artifactRoot: requiredFlag("artifact-root"),
+    controllerRoot: requiredFlag("controller-root"),
+    repository: requiredFlag("repository"),
+    sourceSha: requiredFlag("source-sha"),
+    sourceTreeSha: requiredFlag("source-tree-sha"),
+    runtimeSha: requiredFlag("runtime-sha"),
+  });
+  const output = flag("output");
+  if (output) {
+    fs.mkdirSync(path.dirname(path.resolve(output)), { recursive: true });
+    fs.writeFileSync(
+      path.resolve(output),
+      `${JSON.stringify(result, null, 2)}\n`,
+    );
+  }
+  if (process.argv.includes("--json") || !output)
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(process.argv[1]).href
+) {
+  try {
+    main();
+  } catch (error) {
+    console.error(`publication artifact candidate: ${error.message}`);
+    process.exitCode = 1;
+  }
+}

package/scripts/workflow-friction-report.mjs

@@ -202,6 +202,8 @@ export async function classifyWorkflowFriction({
   buildWorkflowName = DEFAULT_BUILD_WORKFLOW_NAME,
   releaseCandidateOutcome = env("BUILDCHAIN_RC_RESOLVE_OUTCOME"),
   releaseCandidateDiagnosis = env("BUILDCHAIN_RC_DIAGNOSIS"),
+  promotionOutcome = env("BUILDCHAIN_PROMOTION_OUTCOME"),
+  promotionDiagnosis = env("BUILDCHAIN_PROMOTION_DIAGNOSIS"),
   runUrl = env("BUILDCHAIN_WORKFLOW_RUN_URL"),
   outputDir = ".buildchain/workflow-friction",
   fetchImpl = globalThis.fetch,
@@ -256,14 +258,23 @@ export async function classifyWorkflowFriction({
   if (releaseCandidateOutcome === "failure") {
     diagnosisParts.push("Promotion reached the post-Verify workflow before required PR-stage RC evidence could be resolved.");
   }
-  if (releaseCandidateDiagnosis) {
+  if (releaseCandidateOutcome === "failure" && releaseCandidateDiagnosis) {
     diagnosisParts.push(releaseCandidateDiagnosis);
   }
+  if (promotionOutcome === "failure") {
+    diagnosisParts.push(
+      promotionDiagnosis
+        ? `Promotion failed: ${promotionDiagnosis}`
+        : "Promotion failed after PR-stage release-candidate evidence resolved successfully.",
+    );
+  }
   diagnosisParts.push(...workflowRunDiagnostics);
   const diagnosis = diagnosisParts.join(" ") || "Buildchain ref promotion failed after Verify succeeded; inspect the classified evidence and keep the fix in Buildchain.";
   const nextAction = frictionClass === "late-fail-fast"
     ? "Move the missing/stale RC evidence check earlier or make the promotion workflow consume the exact PR-stage RC passport before any publish side effect."
-    : "Deduplicate the PR/build path or tighten Buildchain workflow gates so the next channel promotion reaches publish exactly once.";
+    : ["duplicate-channel-pr", "duplicate-heavy-build"].includes(frictionClass)
+      ? "Deduplicate the PR/build path or tighten Buildchain workflow gates so the next channel promotion reaches publish exactly once."
+      : "Fix the concrete promotion failure above, then rerun through the protected channel workflow; do not treat successful RC resolution as the failure diagnosis.";
   fs.mkdirSync(outputDir, { recursive: true });
   const bodyFile = path.join(outputDir, "issue-body.md");
   const body = buildWorkflowFrictionBody({