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

package/packages/core/buildchain-contract.js

@@ -89,6 +89,7 @@ export function createBuildchainContractWorld({
     "publication-artifact",
     "paper-release",
     "release-candidate-promote",
+    ".release-candidate-promote",
     "release-propagation",
   ]);
   const hasCompleteControllerSource = [...controllerWorkflowIds]
@@ -173,11 +174,17 @@ export function createBuildchainContractWorld({
       requiredInputs: ["channel"],
       requiredOutputs: ["promoted-sha", "built-source-sha", "release-candidate-artifact"],
       breakingDefaults: {
+        channelDefault: "auto",
+        alphaShellDefault: `${majorLine}-alpha`,
+        stableShellDefault: majorLine,
         promoteOnlyReleaseCandidate: true,
         requiredStatusCheck: "check / check",
       },
       optionalInputs: [
+        "buildchain-channel",
         "buildchain-ref",
+        "buildchain-alpha-contract-lock-path",
+        "buildchain-stable-contract-lock-path",
         "release-candidate-workflow-file",
         "release-candidate-workflow-name",
         "publish-required-artifacts-json",
@@ -210,6 +217,9 @@ export function createBuildchainContractWorld({
         ],
       },
       guarantees: [
+        "one declarative promotion job selects matching alpha or stable workflow shell, runtime, and contract lock",
+        "router, shell, runtime, lock, publication channel, target ref, and override identities are bound before candidate download",
+        "train and exact-SHA runtime overrides remain limited to trusted workflow_dispatch actors",
         "promotion reuses PR-stage release-candidate artifacts",
         "promotion does not run the heavy native build matrix",
         "built source and promotion channel SHA are recorded separately",
@@ -218,6 +228,37 @@ export function createBuildchainContractWorld({
         "GitHub Release passport and evidence publication is delegated to promote-buildchain-ref after the semver release transaction completes",
       ],
     }),
+    surface(root, {
+      id: "advanced-release-candidate-promote",
+      kind: "workflow",
+      path: ".github/workflows/.release-candidate-promote.yml",
+      publicRef: `${pkg.repository ? "kungfu-systems/buildchain" : "buildchain"}/.github/workflows/.release-candidate-promote.yml@${majorLine}`,
+      requiredInputs: ["channel"],
+      requiredOutputs: ["promoted-sha", "built-source-sha", "release-candidate-artifact"],
+      breakingDefaults: {
+        promoteOnlyReleaseCandidate: true,
+        requiredStatusCheck: "check / check",
+      },
+      optionalInputs: [
+        "buildchain-ref",
+        "buildchain-contract-lock-path",
+        "promotion-router-ref",
+        "promotion-router-sha",
+        "promotion-shell-ref",
+        "promotion-shell-sha",
+        "promotion-runtime-ref",
+        "promotion-runtime-sha",
+        "promotion-contract-lock-path",
+        "promotion-contract-lock-digest",
+        "promotion-publication-channel",
+        "promotion-target-ref",
+        "promotion-override-used",
+      ],
+      guarantees: [
+        "advanced promotion verifies routed shell, runtime, lock, publication channel, and target bindings before candidate resolution",
+        "promotion reuses PR-stage release-candidate artifacts and does not run the heavy native build matrix",
+      ],
+    }),
     surface(root, {
       id: "web-surface",
       kind: "workflow",

package/packages/core/buildchain-kfd-claims.js

@@ -82,6 +82,7 @@ const SCHEMA_AND_STANDARD_FILES = Object.freeze([
 
 const WORKFLOW_AND_ACTION_FILES = Object.freeze([
   ".github/workflows/.build.yml",
+  ".github/workflows/.release-candidate-promote.yml",
   ".github/workflows/release-candidate-promote.yml",
   ".github/workflows/buildchain-ref-promotion.yml",
   ".github/workflows/release-propagation.yml",
@@ -372,6 +373,7 @@ export function createBuildchainPublicClaimDefinitions() {
         "packages/core/buildchain-contract.js",
         "scripts/buildchain-contract-lock.mjs",
         ".github/workflows/.build.yml",
+        ".github/workflows/.release-candidate-promote.yml",
         ".github/workflows/release-candidate-promote.yml",
         "docs/reusable-build-surface.md",
       ],
@@ -387,6 +389,7 @@ export function createBuildchainPublicClaimDefinitions() {
         "actions/promote-buildchain-ref/index.js",
         "actions/promote-buildchain-ref/action.yml",
         "scripts/ensure-github-release.mjs",
+        ".github/workflows/.release-candidate-promote.yml",
         ".github/workflows/release-candidate-promote.yml",
         "docs/release-governance.md",
       ],
@@ -415,6 +418,7 @@ export function createBuildchainPublicClaimDefinitions() {
       sourcePaths: [
         "scripts/npm-publish-transaction.mjs",
         "actions/promote-buildchain-ref/index.js",
+        ".github/workflows/.release-candidate-promote.yml",
         ".github/workflows/release-candidate-promote.yml",
         "docs/publish-transaction.md",
       ],

package/packages/core/buildchain-publication-authority.js

@@ -5,6 +5,7 @@ import { createPublicationAuthorityRegistry } from "./publication-authority.js";
 
 const DESCRIPTORS = Object.freeze([
   [".github/workflows/.build.yml", "non-publication-oidc"],
+  [".github/workflows/.release-candidate-promote.yml", "product-publication", true, ["npm-publish", "github-release", "channel-ref"], "trusted-publishing", "none", "fixed", "caller-bound"],
   [".github/workflows/.publication-authority.yml", "evidence-publication"],
   [".github/workflows/.release-verify.yml", "governance-write"],
   [".github/workflows/.sam-release.yml", "retired-deny"],

package/packages/core/controller-evidence.js

@@ -72,7 +72,7 @@ const CONTROLLER_SPECS = [
   },
   {
     id: "release-candidate-promotion",
-    workflowId: "release-candidate-promote",
+    workflowId: ".release-candidate-promote",
     version: 1,
     capabilities: ["promotion-preflight", "artifact-admission", "publication-authority", "publish-transaction", "release-passport"],
     stages: ["preflight", "admit-release-candidate", "publication-authority", "publish", "passport", "aggregate"],

package/packages/core/release-passport.js

@@ -926,6 +926,43 @@ function normalizeTransaction(value = undefined) {
   };
 }
 
+function normalizePromotionRouting(value = undefined) {
+  if (value === undefined) return undefined;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("release.promotionRouting must be a JSON object");
+  }
+  if (value.contract !== "buildchain.promotion-routing/v1") {
+    throw new Error("release.promotionRouting contract must be buildchain.promotion-routing/v1");
+  }
+  for (const [label, field] of [
+    ["router.ref", value.router?.ref],
+    ["router.sha", value.router?.sha],
+    ["shell.ref", value.shell?.ref],
+    ["shell.sha", value.shell?.sha],
+    ["runtime.requestedRef", value.runtime?.requestedRef],
+    ["runtime.resolvedSha", value.runtime?.resolvedSha],
+    ["contractLock.path", value.contractLock?.path],
+    ["contractLock.digest", value.contractLock?.digest],
+    ["publication.channel", value.publication?.channel],
+    ["publication.targetRef", value.publication?.targetRef],
+  ]) {
+    if (!String(field || "").trim()) throw new Error(`release.promotionRouting.${label} is required`);
+  }
+  for (const [label, sha] of [
+    ["router.sha", value.router.sha],
+    ["shell.sha", value.shell.sha],
+    ["runtime.resolvedSha", value.runtime.resolvedSha],
+  ]) {
+    if (!/^[0-9a-f]{40}$/i.test(String(sha))) {
+      throw new Error(`release.promotionRouting.${label} must be a 40-character Git SHA`);
+    }
+  }
+  if (!/^sha256:[0-9a-f]{64}$/i.test(String(value.contractLock.digest))) {
+    throw new Error("release.promotionRouting.contractLock.digest must be a sha256 digest");
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+
 export function createArtifactEvidence({ assets = [], repository = "", tag = "", sourceSha = "", workflow = {} } = {}) {
   const normalizedAssets = assets.map((asset, index) => normalizeAsset(asset, index));
   return {
@@ -1002,6 +1039,7 @@ export function createReleasePassport({
   const normalizedPackageSet = normalizePackageSet(packageSet, { packageName, packageVersion, publish });
   const normalizedTrustedPublishing = normalizeTrustedPublishing(trustedPublishing, { workflow, publish });
   const normalizedTransaction = normalizeTransaction(transaction);
+  const normalizedPromotionRouting = normalizePromotionRouting(release.promotionRouting);
   const normalizedBuildSummary = buildSummary ? normalizeEvidenceDocument(buildSummary, "buildSummary") : undefined;
   const normalizedBuildFacts = (buildFacts || [])
     .map((fact, index) => normalizeEvidenceDocument(fact, `buildFacts[${index}]`))
@@ -1150,6 +1188,7 @@ export function createReleasePassport({
     ...(anchorManifest ? { anchorManifest } : {}),
     ...(normalizedTrustedPublishing ? { trustedPublishing: normalizedTrustedPublishing } : {}),
     ...(normalizedTransaction ? { transaction: normalizedTransaction } : {}),
+    ...(normalizedPromotionRouting ? { promotionRouting: normalizedPromotionRouting } : {}),
     ...(normalizedBuildSummary ? { buildSummary: normalizedBuildSummary } : {}),
     ...(normalizedBuildFacts.length > 0 ? { buildFacts: normalizedBuildFacts } : {}),
     ...(normalizedPlatformArtifactManifests.length > 0 ? { platformArtifactManifests: normalizedPlatformArtifactManifests } : {}),

package/scripts/check-inventory.mjs

@@ -6,6 +6,7 @@ import {
 } from "../packages/core/public-surface-audit.js";
 import { evaluateBuildchainContractLock } from "../packages/core/buildchain-contract.js";
 import { generateChannelBuildWorkflow } from "./generate-channel-build-workflow.mjs";
+import { generateChannelPromotionWorkflow } from "./generate-channel-promotion-workflow.mjs";
 
 const root = process.cwd();
 const sharedActionTsupConfig = fs.readFileSync(path.join(root, "scripts/tsup-action.config.mjs"), "utf8");
@@ -44,6 +45,8 @@ const requiredPaths = [
   "scripts/release-line-dry-run.mjs",
   "scripts/buildchain-channel-router.mjs",
   "scripts/generate-channel-build-workflow.mjs",
+  "scripts/promotion-channel-router.mjs",
+  "scripts/generate-channel-promotion-workflow.mjs",
   "scripts/build-standalone-binary.mjs",
   "scripts/create-release-bundle.mjs",
   "scripts/ensure-github-release.mjs",
@@ -81,6 +84,7 @@ const requiredPaths = [
   ".github/workflows/buildchain-patrol-monthly.yml",
   ".github/workflows/buildchain-alpha-self-dogfood.yml",
   ".github/workflows/release-candidate-promote.yml",
+  ".github/workflows/.release-candidate-promote.yml",
   ".github/workflows/release-propagation.yml",
   ".github/workflows/npm-publish.yml",
   ".github/workflows/paper-release.yml",
@@ -174,6 +178,30 @@ const channelBuildWorkflow = fs.readFileSync(
 if (channelBuildWorkflow !== generateChannelBuildWorkflow(reusableBuildWorkflow)) {
   throw new Error("generated channel build workflow is stale");
 }
+const advancedPromotionWorkflow = fs.readFileSync(
+  path.join(root, ".github/workflows/.release-candidate-promote.yml"),
+  "utf8",
+);
+const channelPromotionWorkflow = fs.readFileSync(
+  path.join(root, ".github/workflows/release-candidate-promote.yml"),
+  "utf8",
+);
+if (channelPromotionWorkflow !== generateChannelPromotionWorkflow(advancedPromotionWorkflow, {
+  major: Number(selfDogfoodMajor),
+})) {
+  throw new Error("generated channel promotion workflow is stale");
+}
+for (const requiredSnippet of [
+  "buildchain-channel:",
+  `/.github/workflows/.release-candidate-promote.yml@v${selfDogfoodMajor}-alpha`,
+  `/.github/workflows/.release-candidate-promote.yml@v${selfDogfoodMajor}`,
+  "promotion-contract-lock-digest:",
+  "promotion runtime override is only allowed for trusted workflow_dispatch runs",
+]) {
+  if (!channelPromotionWorkflow.includes(requiredSnippet)) {
+    throw new Error(`channel promotion workflow missing routing contract: ${requiredSnippet}`);
+  }
+}
 for (const requiredSnippet of [
   "buildchain-channel:",
   "uses: ./.github/workflows/.build.yml",
@@ -814,7 +842,7 @@ for (const forbiddenSnippet of [
 for (const requiredSnippet of [
   "id-token: write",
   "actions: read",
-  "uses: ./.github/workflows/release-candidate-promote.yml",
+  "uses: ./.github/workflows/.release-candidate-promote.yml",
   "github.event.workflow_run.event == 'push'",
   "!startsWith(github.event.workflow_run.display_title, 'chore(release): prepare v')",
   "!startsWith(github.event.workflow_run.display_title, 'chore(release): release v')",
@@ -828,7 +856,7 @@ for (const requiredSnippet of [
     throw new Error(`buildchain ref promotion workflow missing npm transaction snippet: ${requiredSnippet}`);
   }
 }
-const releaseCandidatePromoteWorkflow = fs.readFileSync(path.join(root, ".github/workflows/release-candidate-promote.yml"), "utf8");
+const releaseCandidatePromoteWorkflow = fs.readFileSync(path.join(root, ".github/workflows/.release-candidate-promote.yml"), "utf8");
 for (const requiredSnippet of [
   "release-passport-kfd-1-witness-jsons:",
   "release-passport-kfd-1-witness-jsons: ${{ inputs.release-passport-kfd-1-witness-jsons }}",

package/scripts/generate-channel-promotion-workflow.mjs

@@ -0,0 +1,331 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const sourcePath = path.join(root, ".github/workflows/.release-candidate-promote.yml");
+const targetPath = path.join(root, ".github/workflows/release-candidate-promote.yml");
+const internalInputs = new Set([
+  "promotion-router-ref",
+  "promotion-router-sha",
+  "promotion-shell-ref",
+  "promotion-shell-sha",
+  "promotion-runtime-ref",
+  "promotion-runtime-sha",
+  "promotion-contract-lock-path",
+  "promotion-contract-lock-digest",
+  "promotion-publication-channel",
+  "promotion-target-ref",
+  "promotion-override-used",
+]);
+
+function blockBetween(source, start, end) {
+  const startIndex = source.indexOf(start);
+  const endIndex = source.indexOf(end, startIndex + start.length);
+  if (startIndex < 0 || endIndex < 0) throw new Error(`unable to locate workflow block: ${start.trim()}`);
+  return source.slice(startIndex + start.length, endIndex);
+}
+
+function entries(block, indent = 6) {
+  const pattern = new RegExp(`^ {${indent}}([a-z0-9-]+):$`, "gm");
+  const matches = [...block.matchAll(pattern)];
+  return matches.map((match, index) => ({
+    name: match[1],
+    source: block.slice(match.index, matches[index + 1]?.index ?? block.length).trimEnd(),
+  }));
+}
+
+function publicInputs(inputBlock) {
+  const retained = entries(inputBlock)
+    .filter((entry) => !internalInputs.has(entry.name))
+    .map((entry) => entry.name === "buildchain-contract-lock-path"
+      ? entry.source.replace('        default: ".buildchain/contract-lock.json"', '        default: ""')
+      : entry.source);
+  return [
+    "      buildchain-channel:",
+    '        description: "Promotion workflow-shell/runtime channel: auto, alpha, or stable"',
+    '        default: "auto"',
+    "        type: string",
+    "        required: false",
+    "      buildchain-alpha-contract-lock-path:",
+    '        description: "Consumer-owned contract lock selected for alpha promotion"',
+    '        default: ".buildchain/alpha-contract-lock.json"',
+    "        type: string",
+    "        required: false",
+    "      buildchain-stable-contract-lock-path:",
+    '        description: "Consumer-owned contract lock selected for stable promotion"',
+    '        default: ".buildchain/contract-lock.json"',
+    "        type: string",
+    "        required: false",
+    ...retained,
+  ].join("\n");
+}
+
+function publicOutputs(outputBlock) {
+  const forwarded = entries(outputBlock).map((entry) => entry.source.replace(
+    /^        value:.*$/m,
+    `        value: \${{ jobs.alpha.outputs.${entry.name} || jobs.stable.outputs.${entry.name} }}`,
+  ));
+  const routed = [
+    ["buildchain-channel", "Selected promotion workflow-shell channel", "channel"],
+    ["promotion-router-ref", "Router workflow ref", "router-ref"],
+    ["promotion-router-sha", "Resolved router workflow SHA", "router-sha"],
+    ["promotion-shell-ref", "Selected advanced promotion workflow-shell ref", "shell-ref"],
+    ["promotion-shell-sha", "Resolved advanced promotion workflow-shell SHA", "shell-sha"],
+    ["promotion-runtime-ref", "Selected Buildchain runtime ref", "runtime-ref"],
+    ["promotion-runtime-sha", "Resolved Buildchain runtime SHA", "runtime-sha"],
+    ["promotion-contract-lock-path", "Selected consumer contract-lock path", "contract-lock-path"],
+    ["promotion-contract-lock-digest", "Selected consumer contract-lock sha256 digest", "contract-lock-digest"],
+    ["promotion-publication-channel", "Derived publication channel", "publication-channel"],
+    ["promotion-target-ref", "Derived promotion target ref", "target-ref"],
+    ["promotion-override-used", "Whether a trusted runtime override was used", "override-used"],
+  ].map(([name, description, output]) => [
+    `      ${name}:`,
+    `        description: "${description}"`,
+    `        value: \${{ jobs.resolve-promotion.outputs.${output} }}`,
+  ].join("\n"));
+  return [...routed, ...forwarded].join("\n");
+}
+
+function forwardedInputs(inputNames) {
+  return inputNames.map((name) => {
+    const routed = {
+      "buildchain-ref": "runtime-ref",
+      "buildchain-contract-lock-path": "contract-lock-path",
+      channel: "publication-channel",
+      "target-ref": "target-ref",
+      "promotion-router-ref": "router-ref",
+      "promotion-router-sha": "router-sha",
+      "promotion-shell-ref": "shell-ref",
+      "promotion-shell-sha": "shell-sha",
+      "promotion-runtime-ref": "runtime-ref",
+      "promotion-runtime-sha": "runtime-sha",
+      "promotion-contract-lock-path": "contract-lock-path",
+      "promotion-contract-lock-digest": "contract-lock-digest",
+      "promotion-publication-channel": "publication-channel",
+      "promotion-target-ref": "target-ref",
+      "promotion-override-used": "override-used",
+    }[name];
+    return routed
+      ? `      ${name}: \${{ needs.resolve-promotion.outputs.${routed} }}`
+      : `      ${name}: \${{ inputs.${name} }}`;
+  }).join("\n");
+}
+
+export function generateChannelPromotionWorkflow(source, { major = 2 } = {}) {
+  const inputs = blockBetween(source, "    inputs:\n", "    secrets:\n");
+  const secrets = blockBetween(source, "    secrets:\n", "    outputs:\n");
+  const outputs = blockBetween(source, "    outputs:\n", "\nconcurrency:\n");
+  const inputNames = entries(inputs).map((entry) => entry.name);
+  for (const required of ["buildchain-ref", "buildchain-contract-lock-path", "channel", "target-ref", ...internalInputs]) {
+    if (!inputNames.includes(required)) throw new Error(`advanced promotion workflow missing input: ${required}`);
+  }
+  const forwarded = forwardedInputs(inputNames);
+  return `# Generated by scripts/generate-channel-promotion-workflow.mjs. Do not edit directly.
+name: Release Candidate Promote
+
+on:
+  workflow_call:
+    inputs:
+${publicInputs(inputs)}
+    secrets:
+${secrets.trimEnd()}
+    outputs:
+${publicOutputs(outputs)}
+
+permissions:
+  actions: read
+  checks: write
+  contents: write
+  id-token: write
+  issues: write
+
+jobs:
+  resolve-promotion:
+    name: Resolve promotion workflow shell and runtime
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+    outputs:
+      channel: \${{ steps.route.outputs.channel }}
+      publication-channel: \${{ steps.route.outputs.publication-channel }}
+      target-ref: \${{ steps.route.outputs.target-ref }}
+      router-ref: \${{ steps.router.outputs.ref }}
+      router-sha: \${{ steps.identities.outputs.router-sha }}
+      shell-ref: \${{ steps.route.outputs.shell-ref }}
+      shell-sha: \${{ steps.identities.outputs.shell-sha }}
+      runtime-ref: \${{ steps.route.outputs.runtime-ref }}
+      runtime-sha: \${{ steps.identities.outputs.runtime-sha }}
+      contract-lock-path: \${{ steps.lock.outputs.path }}
+      contract-lock-digest: \${{ steps.lock.outputs.digest }}
+      override-used: \${{ steps.route.outputs.override-used }}
+      selection-source: \${{ steps.route.outputs.selection-source }}
+      reason: \${{ steps.route.outputs.reason }}
+    steps:
+      - name: Resolve promotion router source
+        id: router
+        shell: bash
+        env:
+          BUILDCHAIN_ROUTER_WORKFLOW_REF: \${{ job.workflow_ref }}
+        run: |
+          set -euo pipefail
+          workflow_ref="\${BUILDCHAIN_ROUTER_WORKFLOW_REF}"
+          repository="\${workflow_ref%%/.github/workflows/*}"
+          ref="\${workflow_ref##*@}"
+          ref="\${ref#refs/heads/}"
+          ref="\${ref#refs/tags/}"
+          if [[ -z "\${repository}" || "\${repository}" = "\${workflow_ref}" || -z "\${ref}" ]]; then
+            echo "::error::Unable to resolve promotion router source from job.workflow_ref=\${workflow_ref}"
+            exit 1
+          fi
+          echo "repository=\${repository}" >> "\${GITHUB_OUTPUT}"
+          echo "ref=\${ref}" >> "\${GITHUB_OUTPUT}"
+
+      - name: Checkout promotion router
+        uses: actions/checkout@v7.0.0
+        with:
+          repository: \${{ steps.router.outputs.repository }}
+          ref: \${{ steps.router.outputs.ref }}
+          path: .buildchain/router
+          persist-credentials: false
+
+      - name: Resolve promotion channel
+        id: route
+        shell: bash
+        run: >-
+          node .buildchain/router/scripts/promotion-channel-router.mjs
+          --cwd .buildchain/router
+          --channel "\${{ inputs.buildchain-channel }}"
+          --buildchain-ref "\${{ inputs.buildchain-ref }}"
+          --publication-channel "\${{ inputs.channel }}"
+          --target-ref "\${{ inputs.target-ref || github.ref_name }}"
+          --router-ref "\${{ steps.router.outputs.ref }}"
+
+      - name: Authorize trusted runtime override
+        if: \${{ steps.route.outputs.override-used == 'true' }}
+        uses: actions/github-script@v8
+        with:
+          script: |
+            if (context.eventName !== "workflow_dispatch") {
+              throw new Error("promotion runtime override is only allowed for trusted workflow_dispatch runs");
+            }
+            const permission = await github.rest.repos.getCollaboratorPermissionLevel({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              username: context.actor,
+            });
+            const level = permission.data.user?.permissions || permission.data.permission || "none";
+            if (!["write", "maintain", "admin"].includes(level)) {
+              throw new Error(\`promotion runtime override requires write, maintain, or admin permission; actor has \${level}\`);
+            }
+
+      - name: Checkout selected promotion workflow shell
+        uses: actions/checkout@v7.0.0
+        with:
+          repository: \${{ steps.router.outputs.repository }}
+          ref: \${{ steps.route.outputs.shell-ref }}
+          path: .buildchain/shell
+          persist-credentials: false
+
+      - name: Checkout selected Buildchain runtime
+        uses: actions/checkout@v7.0.0
+        with:
+          repository: \${{ steps.router.outputs.repository }}
+          ref: \${{ steps.route.outputs.runtime-ref }}
+          path: .buildchain/runtime
+          persist-credentials: false
+
+      - name: Checkout promotion source
+        uses: actions/checkout@v7.0.0
+        with:
+          ref: \${{ inputs.target-sha || github.sha }}
+          path: .buildchain/source
+          persist-credentials: false
+
+      - name: Select and verify consumer contract lock
+        id: lock
+        shell: bash
+        env:
+          EXPLICIT_PATH: \${{ inputs.buildchain-contract-lock-path }}
+          ALPHA_PATH: \${{ inputs.buildchain-alpha-contract-lock-path }}
+          STABLE_PATH: \${{ inputs.buildchain-stable-contract-lock-path }}
+          CHANNEL: \${{ steps.route.outputs.channel }}
+        run: |
+          set -euo pipefail
+          path="\${EXPLICIT_PATH}"
+          if [[ -z "\${path}" ]]; then
+            if [[ "\${CHANNEL}" = "alpha" ]]; then path="\${ALPHA_PATH}"; else path="\${STABLE_PATH}"; fi
+          fi
+          if [[ -z "\${path}" || ! -f ".buildchain/source/\${path}" ]]; then
+            echo "::error::Selected promotion contract lock is missing: \${path:-<empty>}"
+            exit 1
+          fi
+          digest="sha256:$(shasum -a 256 ".buildchain/source/\${path}" | awk '{print $1}')"
+          echo "path=\${path}" >> "\${GITHUB_OUTPUT}"
+          echo "digest=\${digest}" >> "\${GITHUB_OUTPUT}"
+
+      - name: Resolve immutable promotion identities
+        id: identities
+        shell: bash
+        run: |
+          set -euo pipefail
+          test -f .buildchain/shell/.github/workflows/.release-candidate-promote.yml
+          {
+            echo "router-sha=$(git -C .buildchain/router rev-parse HEAD)"
+            echo "shell-sha=$(git -C .buildchain/shell rev-parse HEAD)"
+            echo "runtime-sha=$(git -C .buildchain/runtime rev-parse HEAD)"
+          } >> "\${GITHUB_OUTPUT}"
+
+  alpha:
+    name: Promote with alpha workflow shell
+    needs: resolve-promotion
+    if: \${{ needs.resolve-promotion.outputs.channel == 'alpha' }}
+    uses: kungfu-systems/buildchain/.github/workflows/.release-candidate-promote.yml@v${major}-alpha
+    permissions:
+      actions: read
+      checks: write
+      contents: write
+      id-token: write
+      issues: write
+    with:
+${forwarded}
+    secrets: inherit
+
+  stable:
+    name: Promote with stable workflow shell
+    needs: resolve-promotion
+    if: \${{ needs.resolve-promotion.outputs.channel == 'stable' }}
+    uses: kungfu-systems/buildchain/.github/workflows/.release-candidate-promote.yml@v${major}
+    permissions:
+      actions: read
+      checks: write
+      contents: write
+      id-token: write
+      issues: write
+    with:
+${forwarded}
+    secrets: inherit
+`;
+}
+
+function main() {
+  const source = fs.readFileSync(sourcePath, "utf8");
+  const version = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).version;
+  const major = Number(String(version).match(/^(\d+)\./)?.[1]);
+  if (!Number.isInteger(major)) throw new Error("package version must expose a numeric major");
+  const generated = generateChannelPromotionWorkflow(source, { major });
+  if (process.argv.includes("--check")) {
+    const current = fs.existsSync(targetPath) ? fs.readFileSync(targetPath, "utf8") : "";
+    if (current !== generated) {
+      console.error(".github/workflows/release-candidate-promote.yml is stale; run node scripts/generate-channel-promotion-workflow.mjs");
+      process.exitCode = 1;
+    }
+    return;
+  }
+  fs.writeFileSync(targetPath, generated);
+}
+
+const isMain = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) main();