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

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/publication-control-plane-audit.js

@@ -76,6 +76,8 @@ export function evaluatePublicationControlPlaneSnapshot({
     branchPolicy.requiredStatusCheck === requiredStatusCheck &&
     branchPolicy.requiredStatusChecks.includes(requiredStatusCheck) &&
     branchPolicy.requiredCheckPassed === true &&
+    /^[0-9a-f]{40}$/i.test(String(branchPolicy.requiredCheckSha || "")) &&
+    branchPolicy.requiredCheckSha === branchPolicy.pullRequestHeadSha &&
     branchPolicy.sourceSha === branchPolicy.headSha &&
     branchPolicy.mergedPullRequest === true &&
     branchPolicy.baseRef === branch &&

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/audit-publication-control-plane.mjs

@@ -278,7 +278,10 @@ function main() {
     const independentApprovals = [...latestReviews.values()].filter((review) =>
       review.state === "APPROVED" && review.user?.login !== mergedPullRequest?.user?.login
     );
-    const checkRuns = githubJson(`repos/${repository}/commits/${sourceSha}/check-runs?per_page=100`, "source check runs");
+    const pullRequestHeadSha = String(mergedPullRequest?.head?.sha || "").toLowerCase();
+    const checkRuns = /^[0-9a-f]{40}$/.test(pullRequestHeadSha)
+      ? githubJson(`repos/${repository}/commits/${pullRequestHeadSha}/check-runs?per_page=100`, "merged pull-request head check runs")
+      : { check_runs: [] };
     const requiredStatusCheckPolicy = branchState.protection?.required_status_checks || {};
     const requiredStatusChecks = requiredStatusCheckPolicy.contexts || [];
     const requiredCheckSource = (requiredStatusCheckPolicy.checks || []).find((entry) => entry.context === requiredStatusCheck);
@@ -295,10 +298,12 @@ function main() {
         (!requiredCheckSource?.app_id || entry.app?.id === requiredCheckSource.app_id)
       ),
       requiredCheckAppId: requiredCheckSource?.app_id || 0,
+      requiredCheckSha: pullRequestHeadSha,
       sourceSha,
       headSha: String(branchState.commit?.sha || "").toLowerCase(),
       mergedPullRequest: Boolean(mergedPullRequest),
       pullRequestNumber: mergedPullRequest?.number || 0,
+      pullRequestHeadSha,
       baseRef: mergedPullRequest?.base?.ref || "",
       headRepository: mergedPullRequest?.head?.repo?.full_name || "",
       approvalCount: independentApprovals.length,

package/scripts/check-inventory.mjs

@@ -6,6 +6,10 @@ 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,
+  parsePromotionShellRouting,
+} 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 +48,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 +87,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 +181,36 @@ 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",
+);
+const promotionShellRouting = parsePromotionShellRouting(
+  fs.readFileSync(path.join(root, ".buildchain/promotion-shell-routing.json"), "utf8"),
+  { major: Number(selfDogfoodMajor) },
+);
+if (channelPromotionWorkflow !== generateChannelPromotionWorkflow(advancedPromotionWorkflow, {
+  major: Number(selfDogfoodMajor),
+  shellRouting: promotionShellRouting,
+})) {
+  throw new Error("generated channel promotion workflow is stale");
+}
+for (const requiredSnippet of [
+  "buildchain-channel:",
+  `/.github/workflows/.release-candidate-promote.yml@v${selfDogfoodMajor}-alpha`,
+  `/release-candidate-promote.yml@${promotionShellRouting.stable.callRef}`,
+  `STABLE_SHELL_REF: 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 +851,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 +865,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 }}",