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

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

@@ -115,13 +115,22 @@ async function main() {
     manifests,
     payloads: manifests.map((manifest) => payloadFor(manifest, path.join(evidenceRoot, "payloads"))),
   });
-  const gateAggregate = createPublicationGateDecision({
-    sourceSha,
-    profile: process.env.BUILDCHAIN_GATE_PROFILE || "buildchain-self-publication",
-    required: false,
-    rationale: process.env.BUILDCHAIN_GATE_RATIONALE || "Buildchain self-publication has no consumer-owned Shifu Gate registry.",
-    policy: { scope: "buildchain-self-publication", repository },
-  });
+  const suppliedGateAggregate = String(process.env.BUILDCHAIN_GATE_AGGREGATE_JSON || "").trim();
+  let gateAggregate;
+  if (suppliedGateAggregate) {
+    gateAggregate = JSON.parse(suppliedGateAggregate);
+  } else {
+    if (process.env.BUILDCHAIN_ALLOW_NO_GATE !== "true") {
+      throw new Error("managed release-candidate admission requires a Gate aggregate or explicit no-Gate decision");
+    }
+    gateAggregate = createPublicationGateDecision({
+      sourceSha,
+      profile: process.env.BUILDCHAIN_GATE_PROFILE || "managed-release-candidate-no-gate",
+      required: false,
+      rationale: process.env.BUILDCHAIN_GATE_RATIONALE || "The consumer explicitly declared no Shifu Gate registry for this publication transaction.",
+      policy: { scope: "managed-release-candidate", repository },
+    });
+  }
   const runnerProvenance = createRunnerProvenance({
     runnerClass: "ephemeral",
     os: required("RUNNER_OS"),
@@ -137,6 +146,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 +164,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}`,
@@ -177,6 +187,6 @@ async function main() {
 }
 
 main().catch((error) => {
-  console.error(`assemble self publication admission: ${error.message}`);
+  console.error(`assemble release-candidate admission: ${error.message}`);
   process.exitCode = 1;
 });

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,9 @@ 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",

package/scripts/locked-source-checkout.mjs

@@ -6,6 +6,7 @@ import path from "node:path";
 import { pathToFileURL } from "node:url";
 
 export const LOCKED_SOURCE_CHECKOUT_CONTRACT = "kungfu-buildchain-locked-source-checkout-cache";
+export const ISOLATED_GIT_GLOBAL_CONFIG = process.platform === "win32" ? "NUL" : "/dev/null";
 
 const GIT_SHA_PATTERN = /^[0-9a-f]{40}$/i;
 
@@ -133,6 +134,24 @@ function githubAuthEnv(token = "") {
   };
 }
 
+function isolatedGitFetchEnv(env = {}, targetPath) {
+  const configuredCount = Number.parseInt(env.GIT_CONFIG_COUNT || "0", 10);
+  const safeDirectoryIndex = Number.isInteger(configuredCount) && configuredCount >= 0
+    ? configuredCount
+    : 0;
+  return {
+    ...env,
+    // Runner-global URL rewrites are shared mutable state. A concurrent job
+    // may point the same repository URL at a different single-SHA bundle, so
+    // network fetches must not consult the account-level Git config.
+    GIT_CONFIG_GLOBAL: ISOLATED_GIT_GLOBAL_CONFIG,
+    GIT_CONFIG_NOSYSTEM: "1",
+    GIT_CONFIG_COUNT: String(safeDirectoryIndex + 1),
+    [`GIT_CONFIG_KEY_${safeDirectoryIndex}`]: "safe.directory",
+    [`GIT_CONFIG_VALUE_${safeDirectoryIndex}`]: path.resolve(targetPath),
+  };
+}
+
 function markSafeDirectory(targetPath, timeoutMs) {
   try {
     git(["config", "--global", "--add", "safe.directory", path.resolve(targetPath)], {
@@ -206,6 +225,7 @@ export function fetchSourceCommit({
   runGit = git,
   containsCommit = hasCommit,
 }) {
+  const fetchEnv = isolatedGitFetchEnv(env, targetPath);
   try {
     runGit(["remote", "remove", remoteName], { cwd: targetPath, timeoutMs, stdio: "ignore" });
   } catch {
@@ -222,7 +242,7 @@ export function fetchSourceCommit({
       runGit(["fetch", "--no-tags", "--depth=1", remoteName, `+${fetchRef}:refs/buildchain/source-ref`], {
         cwd: targetPath,
         timeoutMs,
-        env,
+        env: fetchEnv,
       });
       if (containsCommit(targetPath, sha, timeoutMs)) {
         return { selector: "ref", checkoutSha: sha };
@@ -252,7 +272,7 @@ export function fetchSourceCommit({
   runGit(["fetch", "--no-tags", "--depth=1", remoteName, `+${sha}:refs/buildchain/source`], {
     cwd: targetPath,
     timeoutMs,
-    env,
+    env: fetchEnv,
   });
   if (!containsCommit(targetPath, sha, timeoutMs)) {
     throw new Error(`fetched ${fetchRef || sha}, but ${sha} is not available`);

package/scripts/publication-artifact-candidate.mjs

@@ -0,0 +1,122 @@
+#!/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 exactJson(root, relativePath) {
+  const absoluteRoot = path.resolve(root);
+  const absolutePath = path.resolve(absoluteRoot, relativePath);
+  if (!absolutePath.startsWith(`${absoluteRoot}${path.sep}`)) {
+    throw new Error(`publication evidence path escapes artifact root: ${relativePath}`);
+  }
+  if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+    throw new Error(`expected publication evidence at ${relativePath}`);
+  }
+  return JSON.parse(fs.readFileSync(absolutePath, "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: exactJson(
+      resolvedArtifactRoot,
+      ".buildchain/publication/publication-artifact.json",
+    ),
+    passport: exactJson(
+      resolvedArtifactRoot,
+      ".buildchain/publication/publication-artifact-passport.json",
+    ),
+    controllerReceipt: exactJson(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({