@kungfu-tech/buildchain 2.4.6-alpha.0 → 2.4.6-alpha.1

package/README.md

@@ -122,6 +122,8 @@ Buildchain repository with a scoped issue-write token:
 
 The action deduplicates by fingerprint, comments on existing open reports, and
 is fail-soft by default so issue reporting does not hide the original failure.
+Use `report-kind: workflow-friction` when Buildchain workflows should report
+their own repeated release friction back to the Buildchain issue tracker.
 
 ## Use Buildchain
 
@@ -252,6 +254,7 @@ npm pack --dry-run --json --registry=https://registry.npmjs.org/
 - [Site bundle contract](docs/site-bundle-contract.md)
 - [Lifecycle protocol](docs/lifecycle-protocol.md)
 - [Reusable build surface](docs/reusable-build-surface.md)
+- [Release candidate passport](docs/release-candidate.md)
 - [Consumer issue reporting](docs/consumer-issue-reporting.md)
 - [Publish transaction](docs/publish-transaction.md)
 - [Release governance](docs/release-governance.md)

package/actions/promote-buildchain-ref/README.md

@@ -131,6 +131,26 @@ channel ref such as `alpha/v22/v22.22` or `release/v22/v22.22` to already point
 at the locked `publish-source-sha`. If not, maintainers should merge the source
 commit through the channel PR first.
 
+For promote-only release candidates, attach the PR-stage reusable build evidence
+and fail before publish-gate side effects if it no longer matches:
+
+```yaml
+- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2
+  with:
+    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
+    sha: ${{ needs.build.outputs.publish-source-sha }}
+    target-ref: alpha/v22/v22.22
+    promote-only-release-candidate: "true"
+    release-candidate-passport-path: .buildchain/artifacts/release-candidate-passport.json
+    release-candidate-build-summary-path: .buildchain/artifacts/build-summary.json
+```
+
+The action validates repository, channel, source SHA, platform matrix, and the
+aggregate build-summary hash before it writes version state, opens release-state,
+runs publish transaction logic, or moves tags/branches. If validation fails, run
+or attach the verified channel PR build first instead of promoting a stale or
+unproven artifact set.
+
 When enabled, the action creates or resumes a release transaction keyed by
 repository, version, source SHA, and target ref. It persists that transaction to
 a machine-managed branch under `buildchain/release-state/<version>`, with

package/actions/report-buildchain-issue/README.md

@@ -1,6 +1,7 @@
 # report-buildchain-issue
 
-Create or update a Buildchain repository issue from a consumer workflow.
+Create or update a Buildchain repository issue from a consumer workflow or from
+Buildchain's own workflow-friction feedback loop.
 
 This action is intended for consumer repositories that need to report
 Buildchain-owned failures with enough evidence for maintainers to act. It
@@ -44,3 +45,33 @@ By default issue reporting is fail-soft:
 
 Use `dry-run: "true"` to verify the computed fingerprint and body shape without
 calling GitHub.
+
+For Buildchain-owned workflow friction, use `report-kind: workflow-friction`.
+This uses a separate marker and default labels so duplicate PRs, duplicate
+builds, transient API failures, stale release-state, or missing RC evidence can
+be grouped without mixing with consumer failure reports:
+
+```yaml
+permissions:
+  issues: write
+
+steps:
+  - uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v2
+    if: failure()
+    with:
+      token: ${{ github.token }}
+      report-kind: workflow-friction
+      target-repository: ${{ github.repository }}
+      repository: ${{ github.repository }}
+      workflow: ${{ github.workflow }}
+      run-id: ${{ github.run_id }}
+      run-attempt: ${{ github.run_attempt }}
+      channel: alpha/v2/v2.4
+      source-sha: ${{ github.sha }}
+      friction-class: duplicate-build
+      comment-cooldown-hours: "24"
+```
+
+`comment-cooldown-hours` is optional. When it is greater than zero, Buildchain
+still deduplicates by fingerprint but skips adding another comment if the
+existing issue already received a recent update.

package/dist/site/release-provenance.json

@@ -13,6 +13,7 @@
       "./diagnostics": "./packages/core/diagnostics.js",
       "./issue-reporting": "./packages/core/issue-reporting.js",
       "./logging": "./packages/core/logging.js",
+      "./release-candidate": "./packages/core/release-candidate.js",
       "./release-passport": "./packages/core/release-passport.js",
       "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
       "./site/site-manifest.json": "./dist/site/site-manifest.json",

package/docs/MAP.md

@@ -31,6 +31,7 @@ running artifact), *use* (consume / extend) - and a **status**:
 | How do I declare version files and custom lifecycle commands? | [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |
 | How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |
 | How do I publish or verify release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |
+| How do I prove a PR-stage reusable build is the artifact source promoted later? | [`release-candidate.md`](release-candidate.md) + [`reusable-build-surface.md`](reusable-build-surface.md) | verify | stable |
 | Why are binary release assets archived by platform, and where is the single bundle? | [`binary-distribution.md`](binary-distribution.md) | verify | stable |
 | How do I add timestamped logs inside build scripts? | [`toolkit-observability.md`](toolkit-observability.md) | use | stable |
 | What package-owned facts should buildchain.libkungfu.dev render? | [`site-bundle-contract.md`](site-bundle-contract.md) | use | stable |
@@ -67,6 +68,9 @@ running artifact), *use* (consume / extend) - and a **status**:
   [`reusable-build-surface.md`](reusable-build-surface.md).
 - **consumer workflow feedback / automatic Buildchain GitHub issues** ->
   [`consumer-issue-reporting.md`](consumer-issue-reporting.md).
+- **PR-stage RC artifacts / promote-only release candidates** ->
+  [`release-candidate.md`](release-candidate.md) and
+  [`reusable-build-surface.md`](reusable-build-surface.md).
 - **infra contract / observed infrastructure outputs / downstream contract propagation** ->
   [`infra-contract.md`](infra-contract.md).
 - **standalone binary install / platform archives / GitHub Release bundle** ->

package/docs/release-candidate.md

@@ -0,0 +1,62 @@
+# Release Candidate Passport
+
+The release-candidate passport is the pre-promotion evidence contract produced
+after a reusable build matrix succeeds and before any publish-gate side effects
+run. It is different from the release passport:
+
+- `release-candidate-passport.json` proves which source SHA, channel, runtime,
+  workflow run, and platform artifacts were verified before promotion.
+- `buildchain.release.json` is generated after publish finalization and remains
+  the durable audit entrypoint for the published release.
+
+Enable it on the reusable build workflow:
+
+```yaml
+jobs:
+  build:
+    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v2
+    with:
+      artifact-name: libnode
+      release-candidate: true
+      publish-channel: alpha
+      publish-source-ref: publish-gate/alpha/v22/v22.22/22.22.3-kf.3-alpha.7
+```
+
+When the platform matrix and aggregate summaries complete, Buildchain uploads:
+
+```text
+<artifact-name>-release-candidate-<publish-source-sha>
+```
+
+The passport contract is `kungfu-buildchain-release-candidate-passport`. It
+contains:
+
+- repository and pull request context;
+- target channel, target ref, and product version or a non-publish
+  `source-<shortSha>` candidate label;
+- source head SHA, merge ref SHA, and source tree hash;
+- Buildchain runtime ref/SHA and workflow shell ref;
+- workflow run id/attempt/url;
+- normalized platform matrix and artifact summaries;
+- the hash of the aggregate `build-summary.json`.
+
+Promotion workflows that should not rebuild artifacts can enable:
+
+```yaml
+- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v2
+  with:
+    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
+    sha: ${{ needs.build.outputs.publish-source-sha }}
+    target-ref: alpha/v22/v22.22
+    promote-only-release-candidate: "true"
+    release-candidate-passport-path: .buildchain/artifacts/release-candidate-passport.json
+    release-candidate-build-summary-path: .buildchain/artifacts/build-summary.json
+```
+
+With `promote-only-release-candidate: "true"`, promotion fails before
+version-state, publish transaction, tag, or branch side effects when the
+passport does not match the repository, channel, source SHA, platform matrix,
+or build-summary hash. The diagnostic tells maintainers to run or attach the
+verified channel PR build first instead of allowing publish-gate to discover
+the mismatch late.
+

package/docs/reusable-build-surface.md

@@ -25,6 +25,7 @@ jobs:
       expected-artifacts-json: >-
         {"minFiles":2,"requiredPaths":["dist/libnode.tar.gz","dist/checksums.txt"]}
       process-summary-path: .buildchain/diagnostics/process-summary.json
+      release-candidate: true
       publish-channel: release
       publish-source-ref: publish-gate/release/v22/v22.22/22.22.3-kf.0
 ```
@@ -190,6 +191,8 @@ The reusable workflow exposes the resolved contract:
 | `linux-container-image`           | Resolved digest-pinned Linux job container image                                |
 | `build-summary-artifact`          | Uploaded aggregate summary artifact name                                        |
 | `build-diagnostics-summary-artifact` | Uploaded aggregate diagnostics summary artifact name                         |
+| `release-candidate-passport-artifact` | Uploaded PR-stage release-candidate passport artifact name when `release-candidate` is enabled |
+| `release-candidate-passport-json` | Compact release-candidate passport JSON when `release-candidate` is enabled     |
 | `build-summary-json`              | Compact aggregate JSON with platform count, file count, and byte total          |
 | `build-diagnostics-summary-json`  | Compact aggregate diagnostics JSON with platform, lifecycle warning/error, diagnostics contract warning, and sidecar manifest warning totals |
 | `trusted-event`                   | `true` when the event is trusted enough to reach build runners                  |
@@ -233,6 +236,14 @@ release jobs can detect drifting diagnostics JSON contracts and missing or
 drifting diagnostics sidecar manifests without downloading the per-platform
 diagnostics artifacts first.
 
+Set `release-candidate: true` when the successful reusable build is meant to be
+the artifact source promoted later. Buildchain then uploads
+`release-candidate-passport.json` under the
+`<artifact-name>-release-candidate-<publish-source-sha>` artifact name. Promotion
+jobs can pass that passport to `promote-buildchain-ref` with
+`promote-only-release-candidate: "true"` so source, channel, platforms, and the
+aggregate build-summary hash are checked before publish-gate side effects.
+
 ## Publish Gate
 
 Buildchain separates "may build/verify" from "may publish." A same-repository

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.4.6-alpha.0",
+  "version": "2.4.6-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -16,6 +16,7 @@
     "./diagnostics": "./packages/core/diagnostics.js",
     "./issue-reporting": "./packages/core/issue-reporting.js",
     "./logging": "./packages/core/logging.js",
+    "./release-candidate": "./packages/core/release-candidate.js",
     "./release-passport": "./packages/core/release-passport.js",
     "./site/buildchain-site.json": "./dist/site/buildchain-site.json",
     "./site/site-manifest.json": "./dist/site/site-manifest.json",
@@ -50,6 +51,7 @@
     "docs/product-mechanism.md",
     "docs/publish-transaction.md",
     "docs/release-passport.md",
+    "docs/release-candidate.md",
     "docs/release-flow.md",
     "docs/release-governance.md",
     "docs/reusable-build-surface.md",

package/packages/core/index.js

@@ -85,6 +85,13 @@ export {
   writeDiagnosticsArtifact,
 } from "./diagnostics.js";
 
+export {
+  RELEASE_CANDIDATE_PASSPORT_CONTRACT,
+  createReleaseCandidatePassport,
+  sha256Json,
+  validateReleaseCandidatePassport,
+} from "./release-candidate.js";
+
 export {
   AGENT_INDEX_CONTRACT,
   ARTIFACT_EVIDENCE_CONTRACT,
@@ -107,9 +114,11 @@ export {
 
 export {
   BUILDCHAIN_CONSUMER_ISSUE_CONTRACT,
+  BUILDCHAIN_WORKFLOW_FRICTION_ISSUE_CONTRACT,
   DEFAULT_BUILDCHAIN_ISSUE_REPOSITORY,
   GitHubIssueRequestError,
   buildConsumerIssueReport,
+  buildWorkflowFrictionIssueReport,
   computeConsumerIssueFingerprint,
   consumerIssueMarker,
   createGitHubIssueRequest,
@@ -118,5 +127,7 @@ export {
   readOptionalIssueBodyFile,
   redactIssueText,
   reportBuildchainIssue,
+  reportWorkflowFrictionIssue,
   truncateUtf8,
+  workflowFrictionMarker,
 } from "./issue-reporting.js";

package/packages/core/issue-reporting.js

@@ -2,9 +2,11 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 
 export const BUILDCHAIN_CONSUMER_ISSUE_CONTRACT = "kungfu-buildchain-consumer-issue";
+export const BUILDCHAIN_WORKFLOW_FRICTION_ISSUE_CONTRACT = "kungfu-buildchain-workflow-friction-issue";
 export const DEFAULT_BUILDCHAIN_ISSUE_REPOSITORY = "kungfu-systems/buildchain";
 
 const DEFAULT_LABELS = ["buildchain-consumer-feedback"];
+const DEFAULT_FRICTION_LABELS = ["buildchain-feedback", "workflow-friction"];
 const DEFAULT_MAX_BODY_BYTES = 60_000;
 const DEFAULT_RETRY_DELAYS_MS = [500, 1_500, 3_000];
 
@@ -75,6 +77,10 @@ export function consumerIssueMarker(fingerprint) {
   return `buildchain-consumer-issue:fingerprint=${fingerprint}`;
 }
 
+export function workflowFrictionMarker(fingerprint) {
+  return `buildchain-workflow-friction:fingerprint=${fingerprint}`;
+}
+
 export function truncateUtf8(text, maxBytes = DEFAULT_MAX_BODY_BYTES) {
   const value = String(text ?? "");
   if (!Number.isFinite(maxBytes) || maxBytes <= 0 || Buffer.byteLength(value, "utf8") <= maxBytes) {
@@ -185,8 +191,95 @@ export function buildConsumerIssueReport(options = {}) {
   };
 }
 
+export function buildWorkflowFrictionIssueReport(options = {}) {
+  const target = normalizeIssueRepository(options.targetRepository);
+  const env = options.env || process.env;
+  const repository = options.repository || env.GITHUB_REPOSITORY || "";
+  const workflow = options.workflow || env.GITHUB_WORKFLOW || "";
+  const runId = options.runId || env.GITHUB_RUN_ID || "";
+  const runAttempt = options.runAttempt || env.GITHUB_RUN_ATTEMPT || "";
+  const runUrl = options.runUrl || githubRunUrl(env, repository, runId);
+  const channel = options.channel || "";
+  const releaseIntent = options.releaseIntent || options.version || "";
+  const sourceRef = options.sourceRef || env.GITHUB_REF || "";
+  const sourceSha = options.sourceSha || env.GITHUB_SHA || "";
+  const frictionClass = options.frictionClass || "workflow-friction";
+  const fingerprint = options.fingerprint || computeConsumerIssueFingerprint({
+    targetRepository: target.fullName,
+    repository,
+    workflow,
+    channel,
+    releaseIntent,
+    sourceRef,
+    sourceSha,
+    frictionClass,
+  });
+  const marker = workflowFrictionMarker(fingerprint);
+  const heavyBuilds = Array.isArray(options.heavyBuilds) ? options.heavyBuilds : [];
+  const relatedRuns = Array.isArray(options.relatedRuns) ? options.relatedRuns : [];
+  const title = redactIssueText(
+    options.title || `[Buildchain feedback] ${frictionClass}: ${repository || "unknown repository"}`,
+  );
+  const body = truncateUtf8(
+    redactIssueText(
+      [
+        `<!-- ${marker} -->`,
+        `# Buildchain workflow friction`,
+        ``,
+        options.summary ? `## Summary\n\n${options.summary}` : "",
+        `## Context`,
+        ``,
+        `- Repository: ${repository || "(unknown)"}`,
+        `- Workflow: ${workflow || "(unknown)"}`,
+        `- Run: ${runUrl || runId || "(unknown)"}`,
+        `- Attempt: ${runAttempt || "(unknown)"}`,
+        `- Pull request: ${options.pullRequest || "(unknown)"}`,
+        `- Channel: ${channel || "(unknown)"}`,
+        `- Release intent: ${releaseIntent || "(unknown)"}`,
+        `- Source ref: ${sourceRef || "(unknown)"}`,
+        `- Source SHA: ${sourceSha || "(unknown)"}`,
+        `- Source tree: ${options.sourceTreeHash || "(unknown)"}`,
+        `- Friction class: ${frictionClass}`,
+        `- Fingerprint: ${fingerprint}`,
+        ``,
+        relatedRuns.length ? `## Related runs\n\n${relatedRuns.map((run) => `- ${run}`).join("\n")}` : "",
+        heavyBuilds.length ? `## Heavy build jobs\n\n${heavyBuilds.map((job) => `- ${job.name || job}: ${job.durationMs || ""}`).join("\n")}` : "",
+        options.diagnosis ? `## Diagnosis\n\n${options.diagnosis}` : "",
+        options.nextAction ? `## Suggested next action\n\n${options.nextAction}` : "",
+      ].filter(Boolean).join("\n"),
+    ),
+    Number(options.maxBodyBytes || DEFAULT_MAX_BODY_BYTES),
+  );
+  const commentBody = truncateUtf8(
+    redactIssueText(
+      [
+        `New matching Buildchain workflow friction observed.`,
+        ``,
+        `- Repository: ${repository || "(unknown)"}`,
+        `- Workflow: ${workflow || "(unknown)"}`,
+        `- Run: ${runUrl || runId || "(unknown)"}`,
+        `- Attempt: ${runAttempt || "(unknown)"}`,
+        `- Friction class: ${frictionClass}`,
+        `- Fingerprint: ${fingerprint}`,
+        options.summary ? `\n${options.summary}` : "",
+      ].join("\n"),
+    ),
+    Number(options.maxBodyBytes || DEFAULT_MAX_BODY_BYTES),
+  );
+  return {
+    contract: BUILDCHAIN_WORKFLOW_FRICTION_ISSUE_CONTRACT,
+    targetRepository: target.fullName,
+    fingerprint,
+    marker,
+    title,
+    body,
+    commentBody,
+    labels: parseIssueLabels(options.labels ?? DEFAULT_FRICTION_LABELS),
+  };
+}
+
 export async function reportBuildchainIssue(options = {}) {
-  const report = buildConsumerIssueReport(options);
+  const report = options.report || buildConsumerIssueReport(options);
   const target = normalizeIssueRepository(report.targetRepository);
   const mode = options.mode || "create-or-comment";
   if (options.dryRun) {
@@ -219,6 +312,26 @@ export async function reportBuildchainIssue(options = {}) {
         report,
       };
     }
+    const cooldown = await evaluateCommentCooldown({
+      request,
+      target,
+      issueNumber: existing.number,
+      cooldownHours: options.commentCooldownHours,
+      now: options.now,
+    });
+    if (cooldown.active) {
+      return {
+        ok: true,
+        action: "cooldown",
+        created: false,
+        commented: false,
+        issueNumber: existing.number,
+        issueUrl: existing.html_url || existing.url || "",
+        fingerprint: report.fingerprint,
+        report,
+        cooldown,
+      };
+    }
     await request({
       method: "POST",
       path: `/repos/${target.owner}/${target.repo}/issues/${existing.number}/comments`,
@@ -251,6 +364,13 @@ export async function reportBuildchainIssue(options = {}) {
   };
 }
 
+export async function reportWorkflowFrictionIssue(options = {}) {
+  return reportBuildchainIssue({
+    ...options,
+    report: buildWorkflowFrictionIssueReport(options),
+  });
+}
+
 export function readOptionalIssueBodyFile(filePath) {
   const resolved = String(filePath || "").trim();
   if (!resolved) {
@@ -321,13 +441,47 @@ export function createGitHubIssueRequest({
 
 async function findOpenConsumerIssue({ request, target, report }) {
   const query = encodeURIComponent(
-    `repo:${target.fullName} is:issue is:open "${consumerIssueMarker(report.fingerprint)}"`,
+    `repo:${target.fullName} is:issue is:open "${report.marker || consumerIssueMarker(report.fingerprint)}"`,
   );
   const result = await request({ method: "GET", path: `/search/issues?q=${query}&per_page=1` });
   const items = Array.isArray(result.items) ? result.items : [];
   return items[0];
 }
 
+async function evaluateCommentCooldown({
+  request,
+  target,
+  issueNumber,
+  cooldownHours = 0,
+  now = new Date(),
+}) {
+  const hours = Number(cooldownHours || 0);
+  if (!Number.isFinite(hours) || hours <= 0) {
+    return { active: false, cooldownHours: 0 };
+  }
+  const result = await request({
+    method: "GET",
+    path: `/repos/${target.owner}/${target.repo}/issues/${issueNumber}/comments?per_page=100`,
+  });
+  const comments = Array.isArray(result) ? result : [];
+  const latest = comments[comments.length - 1]?.created_at || "";
+  if (!latest) {
+    return { active: false, cooldownHours: hours };
+  }
+  const latestMs = Date.parse(latest);
+  const nowMs = now instanceof Date ? now.getTime() : Date.parse(String(now));
+  if (!Number.isFinite(latestMs) || !Number.isFinite(nowMs)) {
+    return { active: false, cooldownHours: hours, latestCommentAt: latest };
+  }
+  const elapsedHours = (nowMs - latestMs) / 3_600_000;
+  return {
+    active: elapsedHours >= 0 && elapsedHours < hours,
+    cooldownHours: hours,
+    latestCommentAt: latest,
+    elapsedHours,
+  };
+}
+
 async function createIssueWithLabelFallback({ request, target, report }) {
   const payload = {
     title: report.title,

package/packages/core/release-candidate.js

@@ -0,0 +1,183 @@
+import crypto from "node:crypto";
+
+export const RELEASE_CANDIDATE_PASSPORT_CONTRACT = "kungfu-buildchain-release-candidate-passport";
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function optionalString(value) {
+  return value === undefined || value === null ? "" : String(value);
+}
+
+function nonEmptyString(value, label) {
+  const normalized = optionalString(value).trim();
+  if (!normalized) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return normalized;
+}
+
+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 sha256Json(value) {
+  return crypto.createHash("sha256").update(stableJson(value)).digest("hex");
+}
+
+function normalizePlatformEntry(platform = {}, index = 0) {
+  const platformId = optionalString(platform.platform?.id || platform.platformId || platform.platform || `platform-${index}`);
+  const artifacts = Array.isArray(platform.summary?.files)
+    ? platform.summary.files
+    : Array.isArray(platform.artifacts)
+      ? platform.artifacts
+      : [];
+  return {
+    platformId,
+    artifactName: optionalString(platform.artifactName),
+    runner: {
+      labels: Array.isArray(platform.runner?.labels) ? platform.runner.labels.map(String) : [],
+      os: optionalString(platform.runner?.os),
+      arch: optionalString(platform.runner?.arch),
+    },
+    lifecycle: platform.observability?.lifecycle?.stages || {},
+    summary: {
+      fileCount: Number(platform.summary?.fileCount || 0),
+      totalBytes: Number(platform.summary?.totalBytes || 0),
+    },
+    artifacts: artifacts.map((artifact, artifactIndex) => ({
+      name: optionalString(artifact.name || artifact.path || `artifact-${artifactIndex}`),
+      path: optionalString(artifact.path),
+      size: Number(artifact.size || artifact.sizeBytes || 0),
+      sha256: optionalString(artifact.sha256 || artifact.digest || artifact.checksum).replace(/^sha256:/, ""),
+    })),
+    manifestPath: optionalString(platform.manifestPath),
+  };
+}
+
+export function createReleaseCandidatePassport({
+  repository = "",
+  pullRequest = {},
+  targetChannel = "",
+  version = "",
+  sourceHeadSha = "",
+  baseSha = "",
+  mergeRefSha = "",
+  sourceTreeHash = "",
+  buildSummary = {},
+  buildchain = {},
+  workflow = {},
+  createdAt = nowIso(),
+} = {}) {
+  const normalizedSummary = buildSummary && typeof buildSummary === "object" ? buildSummary : {};
+  const sourceSha = sourceHeadSha || normalizedSummary.publishSource?.sha || normalizedSummary.git?.sha || "";
+  const channel = targetChannel || normalizedSummary.publishSource?.channel || normalizedSummary.publishGate?.channel || "";
+  const candidate = {
+    schemaVersion: 1,
+    contract: RELEASE_CANDIDATE_PASSPORT_CONTRACT,
+    createdAt,
+    repository: nonEmptyString(repository || normalizedSummary.git?.repository, "repository"),
+    pullRequest: {
+      number: optionalString(pullRequest.number),
+      url: optionalString(pullRequest.url),
+      headRef: optionalString(pullRequest.headRef),
+      baseRef: optionalString(pullRequest.baseRef),
+    },
+    target: {
+      channel: nonEmptyString(channel, "targetChannel"),
+      ref: optionalString(normalizedSummary.publishSource?.ref || normalizedSummary.git?.ref),
+      version: nonEmptyString(version || normalizedSummary.publishSource?.consumerVersion, "version"),
+    },
+    source: {
+      headSha: nonEmptyString(sourceSha, "sourceHeadSha"),
+      baseSha: optionalString(baseSha),
+      mergeRefSha: optionalString(mergeRefSha || sourceSha),
+      treeHash: optionalString(sourceTreeHash || sha256Json(normalizedSummary.platforms || [])),
+    },
+    buildchain: {
+      ref: optionalString(buildchain.ref || normalizedSummary.runtime?.ref),
+      sha: optionalString(buildchain.sha || normalizedSummary.runtime?.sha),
+      version: optionalString(buildchain.version),
+      workflowShellRef: optionalString(buildchain.workflowShellRef || normalizedSummary.runtime?.workflowShellRef),
+    },
+    workflow: {
+      name: optionalString(workflow.name),
+      runId: optionalString(workflow.runId || normalizedSummary.git?.runId),
+      runAttempt: optionalString(workflow.runAttempt || normalizedSummary.git?.runAttempt),
+      url: optionalString(workflow.url),
+    },
+    platformMatrix: (Array.isArray(normalizedSummary.platforms) ? normalizedSummary.platforms : [])
+      .map((platform, index) => normalizePlatformEntry(platform, index)),
+    diagnostics: {
+      buildSummaryContract: optionalString(normalizedSummary.contract),
+      buildSummaryHash: sha256Json(normalizedSummary),
+    },
+  };
+  candidate.candidateHash = sha256Json({
+    repository: candidate.repository,
+    target: candidate.target,
+    source: candidate.source,
+    platformMatrix: candidate.platformMatrix,
+    buildchain: candidate.buildchain,
+  });
+  return candidate;
+}
+
+export function validateReleaseCandidatePassport({
+  passport,
+  repository = "",
+  targetChannel = "",
+  version = "",
+  sourceHeadSha = "",
+  buildSummary = undefined,
+  requirePlatforms = true,
+} = {}) {
+  const errors = [];
+  const check = (condition, message) => {
+    if (!condition) {
+      errors.push(message);
+    }
+  };
+  check(passport && typeof passport === "object" && !Array.isArray(passport), "passport must be an object");
+  if (!passport || typeof passport !== "object" || Array.isArray(passport)) {
+    return { ok: false, errors };
+  }
+  check(passport.contract === RELEASE_CANDIDATE_PASSPORT_CONTRACT, `contract must be ${RELEASE_CANDIDATE_PASSPORT_CONTRACT}`);
+  check(Number(passport.schemaVersion) === 1, "schemaVersion must be 1");
+  if (repository) {
+    check(passport.repository === repository, `repository mismatch: expected ${repository}, got ${passport.repository || "<empty>"}`);
+  }
+  if (targetChannel) {
+    check(passport.target?.channel === targetChannel, `target channel mismatch: expected ${targetChannel}, got ${passport.target?.channel || "<empty>"}`);
+  }
+  if (version) {
+    check(passport.target?.version === version, `version mismatch: expected ${version}, got ${passport.target?.version || "<empty>"}`);
+  }
+  if (sourceHeadSha) {
+    check(passport.source?.headSha === sourceHeadSha, `source head mismatch: expected ${sourceHeadSha}, got ${passport.source?.headSha || "<empty>"}`);
+  }
+  check(Boolean(passport.source?.mergeRefSha || passport.source?.treeHash), "source mergeRefSha or treeHash is required");
+  check(Array.isArray(passport.platformMatrix), "platformMatrix must be an array");
+  if (requirePlatforms) {
+    check((passport.platformMatrix || []).length > 0, "platformMatrix must include at least one platform");
+  }
+  for (const [index, platform] of (passport.platformMatrix || []).entries()) {
+    check(Boolean(platform.platformId), `platformMatrix[${index}].platformId is required`);
+    check(Boolean(platform.artifactName), `platformMatrix[${index}].artifactName is required`);
+  }
+  if (buildSummary) {
+    const expectedHash = sha256Json(buildSummary);
+    check(passport.diagnostics?.buildSummaryHash === expectedHash, "build summary hash mismatch");
+  }
+  return { ok: errors.length === 0, errors };
+}

package/scripts/generate-release-candidate-passport.mjs

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  createReleaseCandidatePassport,
+  validateReleaseCandidatePassport,
+} from "../packages/core/release-candidate.js";
+import { writeGitHubOutputs } from "./build-contract-core.mjs";
+
+function env(name, fallback = "") {
+  return process.env[name] || fallback;
+}
+
+function readJsonFile(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+
+export function generateReleaseCandidatePassportCli() {
+  const buildSummaryPath = path.resolve(env("BUILDCHAIN_BUILD_SUMMARY_PATH", ".buildchain/artifacts/build-summary.json"));
+  const outputPath = path.resolve(env("BUILDCHAIN_RC_PASSPORT_PATH", ".buildchain/artifacts/release-candidate-passport.json"));
+  const buildSummary = readJsonFile(buildSummaryPath);
+  const sourceSha = env("BUILDCHAIN_RC_SOURCE_HEAD_SHA", buildSummary.publishSource?.sha || buildSummary.git?.sha || "");
+  const version = env(
+    "BUILDCHAIN_RC_VERSION",
+    buildSummary.publishSource?.consumerVersion || `source-${String(sourceSha).slice(0, 12)}`,
+  );
+  const passport = createReleaseCandidatePassport({
+    repository: env("GITHUB_REPOSITORY", buildSummary.git?.repository || ""),
+    pullRequest: {
+      number: env("BUILDCHAIN_PULL_REQUEST_NUMBER"),
+      url: env("BUILDCHAIN_PULL_REQUEST_URL"),
+      headRef: env("BUILDCHAIN_PULL_REQUEST_HEAD_REF"),
+      baseRef: env("BUILDCHAIN_PULL_REQUEST_BASE_REF"),
+    },
+    targetChannel: env("BUILDCHAIN_RC_TARGET_CHANNEL", buildSummary.publishSource?.channel || buildSummary.publishGate?.channel || ""),
+    version,
+    sourceHeadSha: sourceSha,
+    baseSha: env("BUILDCHAIN_RC_BASE_SHA"),
+    mergeRefSha: env("BUILDCHAIN_RC_MERGE_REF_SHA", buildSummary.git?.sha || ""),
+    sourceTreeHash: env("BUILDCHAIN_RC_SOURCE_TREE_HASH"),
+    buildSummary,
+    buildchain: {
+      ref: env("BUILDCHAIN_RUNTIME_REF", buildSummary.runtime?.ref || ""),
+      sha: env("BUILDCHAIN_RUNTIME_SHA", buildSummary.runtime?.sha || ""),
+      version: env("BUILDCHAIN_RUNTIME_VERSION"),
+      workflowShellRef: env("BUILDCHAIN_WORKFLOW_SHELL_REF", buildSummary.runtime?.workflowShellRef || ""),
+    },
+    workflow: {
+      name: env("GITHUB_WORKFLOW"),
+      runId: env("GITHUB_RUN_ID", buildSummary.git?.runId || ""),
+      runAttempt: env("GITHUB_RUN_ATTEMPT", buildSummary.git?.runAttempt || ""),
+      url: env("BUILDCHAIN_WORKFLOW_RUN_URL"),
+    },
+  });
+  const validation = validateReleaseCandidatePassport({
+    passport,
+    repository: env("GITHUB_REPOSITORY", buildSummary.git?.repository || ""),
+    sourceHeadSha: sourceSha,
+    buildSummary,
+  });
+  if (!validation.ok) {
+    throw new Error(`release candidate passport invalid: ${validation.errors.join("; ")}`);
+  }
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, `${JSON.stringify(passport, null, 2)}\n`);
+  writeGitHubOutputs({
+    "release-candidate-passport-path": path.relative(process.cwd(), outputPath).split(path.sep).join("/"),
+    "release-candidate-passport-json": JSON.stringify({
+      contract: passport.contract,
+      repository: passport.repository,
+      target: passport.target,
+      source: passport.source,
+      candidateHash: passport.candidateHash,
+      platformCount: passport.platformMatrix.length,
+    }),
+  });
+  return passport;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  try {
+    generateReleaseCandidatePassportCli();
+  } catch (error) {
+    console.error(`::error::${String(error.message || error).replace(/\r?\n/g, "%0A")}`);
+    process.exitCode = 1;
+  }
+}