@kungfu-tech/buildchain 2.11.14-alpha.7 → 2.12.0-alpha.1

package/dist/site/public-surface-audit.json

@@ -4,7 +4,7 @@
   "status": "passed",
   "summary": {
     "cliCommandCount": 75,
-    "workflowCount": 38,
+    "workflowCount": 39,
     "actionCount": 4,
     "sitePageCount": 45,
     "docCommandRefCount": 237,
@@ -684,6 +684,66 @@
         ],
         "inputCount": 1
       },
+      {
+        "id": "build",
+        "path": ".github/workflows/build.yml",
+        "inputs": [
+          "artifact-name",
+          "artifact-name-template",
+          "artifact-paths",
+          "artifact-relay-s3-bucket",
+          "artifact-relay-s3-download-role-arn",
+          "artifact-relay-s3-oidc-audience",
+          "artifact-relay-s3-prefix",
+          "artifact-relay-s3-region",
+          "artifact-relay-s3-role-arn",
+          "artifact-relay-s3-upload-role-arn",
+          "artifact-retention-days",
+          "artifact-transfer-mode",
+          "build-command",
+          "buildchain-alpha-contract-lock-path",
+          "buildchain-channel",
+          "buildchain-contract-compatibility-policy",
+          "buildchain-contract-drift-issue-mode",
+          "buildchain-contract-lock-path",
+          "buildchain-ref",
+          "buildchain-repository",
+          "buildchain-stable-contract-lock-path",
+          "checkout-cache-fallback",
+          "checkout-cache-fetch-attempts",
+          "checkout-cache-github-timeout-seconds",
+          "checkout-cache-mirror-url-template",
+          "checkout-cache-mode",
+          "checkout-cache-reference-repository-template",
+          "checkout-cache-timeout-seconds",
+          "expected-artifacts-json",
+          "install-command",
+          "linux-container-image",
+          "linux-container-preset",
+          "node-version",
+          "platforms-json",
+          "process-sample-interval-ms",
+          "process-summary-path",
+          "publish-anchor-request-json",
+          "publish-channel",
+          "publish-refs-json",
+          "publish-registry",
+          "publish-source-ref",
+          "release-candidate",
+          "requested-parallelism",
+          "require-build",
+          "require-install",
+          "require-trusted-event",
+          "require-verify",
+          "runner-preset",
+          "sample-process-tree",
+          "setup-node",
+          "untrusted-policy",
+          "verify-command",
+          "working-directory"
+        ],
+        "inputCount": 53
+      },
       {
         "id": "buildchain-alpha-self-dogfood",
         "path": ".github/workflows/buildchain-alpha-self-dogfood.yml",
@@ -2546,8 +2606,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "3c0729f5351eb82fe26625fa5aabf30903f45f68af2431e02860f85ada468ac9",
-    "workflowRegistryDigest": "5875dd6440e9585dc8ce86fc61af8546a60ae1140ed25789199adead2846d4fe",
-    "pageRegistryDigest": "de7377d68eb8b3069b83a2096de8ea24153090e746649015388224b9997e2340"
+    "workflowRegistryDigest": "2bd177fe6e3cbcd382ba30d90c96f35865ef17fc29e451715696cb076d7da933",
+    "pageRegistryDigest": "17127300ab99cd1040b864e77c49ccacfb2a79cff7ced00cda5651faf60223b1"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-11T00:08:19.877Z",
-  "publishedAt": "2026-07-11T00:08:19.877Z",
+  "generatedAt": "2026-07-11T03:14:59.432Z",
+  "publishedAt": "2026-07-11T03:14:59.432Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "7d3f049ffc8b567c3afad9fa9f8e974b50fd3b90",
+  "sourceRevision": "a17107b60f4b7c8e25acedb33432b1f576b8f585",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.11.14-alpha.7",
+    "version": "2.12.0-alpha.1",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-11T00:08:19.877Z",
-  "publishedAt": "2026-07-11T00:08:19.877Z",
+  "generatedAt": "2026-07-11T03:14:59.432Z",
+  "publishedAt": "2026-07-11T03:14:59.432Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "7d3f049ffc8b567c3afad9fa9f8e974b50fd3b90",
+  "sourceRevision": "a17107b60f4b7c8e25acedb33432b1f576b8f585",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.11.14-alpha.7",
+    "version": "2.12.0-alpha.1",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:02987c6bf99441eddc630fa4050fd109c15923047a4591e26d54a714c124539a"
+      "digest": "sha256:bad18d05d3d03b77bf64d8697fc351d58b1372a355a4f25c6719bf08984a79a2"
     },
     {
       "id": "install",
@@ -205,7 +205,7 @@
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:4611e4ae47091687f50b489ccc6caba911f13bb1f73b27a5d44581d8a6450d06"
+      "digest": "sha256:9d7b29135c2665882ae09754c47fe5ffb75e86ec2a8d539c48ffc5045dac802b"
     },
     {
       "id": "publish-transaction",
@@ -221,7 +221,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:69c4146640626bc03b93ac178e250745e45939ba9443f3ba27207a35522036c4"
+      "digest": "sha256:db9077f3748954dee3d28cd1e418dd537fec498df31155c560f7929b622888cb"
     },
     {
       "id": "release-flow",
@@ -245,7 +245,7 @@
       "path": "docs/versioning.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:2c79f7d1a072a40c75d889beac38ae843b2170587fc570ce40722d3968b6506e"
+      "digest": "sha256:400027d5e34d5c22752f7664bb9ca9ce99c04e7be298183d0303f3fb04fa7747"
     },
     {
       "id": "web-surface-deployments",

package/dist/site/workflow-registry.json

@@ -59,7 +59,7 @@
         "working-directory"
       ],
       "inputCount": 50,
-      "surface": "reusable-workflow",
+      "surface": "reusable-build",
       "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
@@ -343,6 +343,69 @@
       "capabilityGroup": "api-cli-reference",
       "status": "repository-internal"
     },
+    {
+      "id": "build",
+      "path": ".github/workflows/build.yml",
+      "inputs": [
+        "artifact-name",
+        "artifact-name-template",
+        "artifact-paths",
+        "artifact-relay-s3-bucket",
+        "artifact-relay-s3-download-role-arn",
+        "artifact-relay-s3-oidc-audience",
+        "artifact-relay-s3-prefix",
+        "artifact-relay-s3-region",
+        "artifact-relay-s3-role-arn",
+        "artifact-relay-s3-upload-role-arn",
+        "artifact-retention-days",
+        "artifact-transfer-mode",
+        "build-command",
+        "buildchain-alpha-contract-lock-path",
+        "buildchain-channel",
+        "buildchain-contract-compatibility-policy",
+        "buildchain-contract-drift-issue-mode",
+        "buildchain-contract-lock-path",
+        "buildchain-ref",
+        "buildchain-repository",
+        "buildchain-stable-contract-lock-path",
+        "checkout-cache-fallback",
+        "checkout-cache-fetch-attempts",
+        "checkout-cache-github-timeout-seconds",
+        "checkout-cache-mirror-url-template",
+        "checkout-cache-mode",
+        "checkout-cache-reference-repository-template",
+        "checkout-cache-timeout-seconds",
+        "expected-artifacts-json",
+        "install-command",
+        "linux-container-image",
+        "linux-container-preset",
+        "node-version",
+        "platforms-json",
+        "process-sample-interval-ms",
+        "process-summary-path",
+        "publish-anchor-request-json",
+        "publish-channel",
+        "publish-refs-json",
+        "publish-registry",
+        "publish-source-ref",
+        "release-candidate",
+        "requested-parallelism",
+        "require-build",
+        "require-install",
+        "require-trusted-event",
+        "require-verify",
+        "runner-preset",
+        "sample-process-tree",
+        "setup-node",
+        "untrusted-policy",
+        "verify-command",
+        "working-directory"
+      ],
+      "inputCount": 53,
+      "surface": "channel-build-router",
+      "capabilityGroup": "reusable-build",
+      "status": "active"
+    },
     {
       "id": "buildchain-alpha-self-dogfood",
       "path": ".github/workflows/buildchain-alpha-self-dogfood.yml",

package/docs/MAP.md

@@ -95,6 +95,7 @@ replace them.
 | 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 |
 | How do I call the reusable build workflow? | [`reusable-build-surface.md`](reusable-build-surface.md) | use | stable |
+| How do I use one build job that follows alpha during development and stable for releases? | [`reusable-build-surface.md`](reusable-build-surface.md#automatic-channel-router) | use | preview |
 | How do self-hosted runners relay large artifacts through S3 before GitHub artifacts? | [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay) | use | stable |
 | How do self-hosted runners reuse local Git checkout caches without weakening source locks? | [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache) | use | stable |
 | How do I validate an unreleased Buildchain runtime train while keeping `@v2`? | [`runtime-train-validation.md`](runtime-train-validation.md) | use | stable |

package/docs/release-governance.md

@@ -170,21 +170,24 @@ while exact tags and SHAs remain the reproducible audit choice.
 ### Buildchain Alpha Self-Dogfood
 
 Buildchain continuously consumes its own current major alpha through
-`.github/workflows/buildchain-alpha-self-dogfood.yml`. The workflow calls the
-released outer reusable workflow at `@v2-alpha` without a runtime override, so
-both the workflow shell and its default runtime must resolve through the same
-floating alpha channel. A parallel stable lane checks out `v2` and runs the
-same declared install, build, and verify lifecycle directly. The direct stable
-lane is intentional: it preserves stable-runtime compatibility without
-requiring the previous stable outer workflow to understand a self-call identity
-fix that has not reached stable yet. Both lanes use a single GitHub-hosted Linux
-fixture to keep the recurring check bounded.
+`.github/workflows/buildchain-alpha-self-dogfood.yml`. Both lanes call the
+released channel router at `build.yml@v2-alpha`. The auto lane must resolve
+`v2-alpha`; the explicit stable lane must resolve `v2`. Both execute the same
+declared install, build, and verify fixture, proving that a single consumer
+surface routes to distinct released runtimes without duplicating lifecycle
+configuration in the consumer.
 
 The reusable build trust gate reads `job.workflow_ref`, which identifies the
 called workflow and its selected ref. It does not infer the runtime from
 `github.workflow_ref`, because GitHub defines that context as the caller
 workflow identity during a reusable call.
 
+The router selects `.buildchain/alpha-contract-lock.json` for alpha and
+`.buildchain/contract-lock.json` for stable. The alpha lock records the exact
+reviewed alpha SHA and compatibility digest; it does not replace the stable
+consumer lock. A later alpha with only compatible additive drift continues,
+while a changed breaking digest fails until the new alpha contract is reviewed.
+
 The evidence job resolves `v2-alpha` and `v2` through the GitHub refs API,
 compares those immutable SHAs with the reusable workflow outputs, verifies the
 `alpha` and `stable` classifications, and uploads a JSON evidence artifact.

package/docs/reusable-build-surface.md

@@ -5,9 +5,69 @@ Buildchain's release semantics but cannot be described as a simple Node package.
 The first target shape is `libnode`: expensive native builds, multiple operating
 systems, self-hosted runner labels, and release artifacts that must be auditable.
 
-## Workflow
+## Automatic Channel Router
 
-Stable consumers call:
+The preferred consumer surface is one reusable workflow call. After v2.12
+reaches the stable major ref, consumers keep this configuration for both alpha
+development and stable release work:
+
+```yaml
+jobs:
+  build:
+    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v2
+    permissions:
+      contents: read
+      issues: write
+      id-token: write
+    with:
+      working-directory: .
+      artifact-name: libnode
+      runner-preset: kungfu-v4-self-hosted
+      publish-channel: none
+    secrets: inherit
+```
+
+`buildchain-channel` defaults to `auto`. Selection uses this precedence:
+
+1. an explicit `buildchain-ref` train, SHA, or official channel;
+2. an explicit `buildchain-channel: alpha|stable`;
+3. `publish-channel: alpha|release|major`;
+4. GitHub release prerelease metadata;
+5. a canonical semver tag;
+6. non-release PR, push, dispatch, schedule, and workflow-run events default to
+   alpha.
+
+The resolved runtime is `vN-alpha` for development and prerelease intent and
+`vN` for stable release intent. Unknown custom publish channels, malformed
+release events, and non-semver release-like tags fail before the build matrix;
+they never guess alpha for a stable release.
+
+The router automatically selects `.buildchain/alpha-contract-lock.json` for
+alpha and `.buildchain/contract-lock.json` for stable. A repository can override
+the common path with `buildchain-contract-lock-path`, or override one channel
+with `buildchain-alpha-contract-lock-path` /
+`buildchain-stable-contract-lock-path`.
+
+Only repositories changing the default policy need extra routing input:
+
+```yaml
+with:
+  buildchain-channel: stable
+```
+
+During the v2.12 prerelease evaluation window, canaries use
+`build.yml@v2-alpha`. The same router then selects `v2-alpha` or stable `v2` as
+the runtime. Production consumers should adopt `build.yml@v2` after the router
+has reached stable; this keeps the routing shell itself on a stable ref.
+
+The router is generated from `.build.yml`'s input/output surface. Run
+`node scripts/generate-channel-build-workflow.mjs` after changing the advanced
+build workflow; inventory and unit tests reject a stale generated router.
+
+## Advanced Workflow
+
+Consumers that need direct workflow-shell or runtime control call the advanced
+surface:
 
 ```yaml
 jobs:
@@ -214,7 +274,7 @@ The lock is intentionally small. It does not copy the full contract. The full
 contract remains in the Buildchain ref and package; the consumer records only
 what it accepted and the policy used to compare future floating-ref movement.
 
-Alpha-channel consumers select the matching workflow shell:
+Advanced alpha-channel consumers select the matching workflow shell:
 
 ```yaml
 jobs:
@@ -231,10 +291,11 @@ refs and exact SHAs remain trusted manual overrides.
 
 ## Locked Source Checkout Cache
 
-Self-hosted runners that build large repositories can opt into a locked source
-checkout cache. This changes only the Git object transport. Buildchain still
-resolves `publish-source-sha` before any build runner starts, checks out that
-exact commit, and verifies `HEAD` plus the resolved source tree SHA before
+Self-hosted runners that build large repositories can opt into a locked checkout
+cache for both the consumer source and the Buildchain runtime. This changes only
+the Git object transport. Buildchain still resolves `publish-source-sha` and the
+runtime SHA before any build runner starts, checks out those exact commits, and
+verifies each final `HEAD` plus the resolved consumer source tree SHA before
 lifecycle commands run.
 
 ```yaml
@@ -268,6 +329,14 @@ repository or organization variables named
 `BUILDCHAIN_CHECKOUT_CACHE_REFERENCE_REPOSITORY_TEMPLATE`, so consumers can keep
 private LAN topology out of repository YAML.
 
+The GitHub-hosted trust gate uploads the exact runtime version's small checkout
+bootstrap script. Native and Linux-container build jobs download that bootstrap,
+then use the same cache policy to obtain the Buildchain runtime at the already
+resolved immutable SHA. This prevents a large direct `actions/checkout` runtime
+clone from becoming a separate timeout path on constrained self-hosted uplinks.
+The bootstrap artifact does not contain the runtime repository and cannot move
+the selected ref.
+
 Do not read cache URLs or reference paths from PR-controlled files such as
 `.buildchain/buildchain.toml`. These values are trusted workflow inputs or repo/org
 variables. Buildchain does not pass GitHub credentials to cache mirrors or
@@ -288,6 +357,9 @@ compact `sourceCheckout` summary in `diagnostics.json`: mode, transport,
 hit/miss, fallback reason, duration, final HEAD verification, and tree
 verification. Remote URLs are sanitized and local reference paths are represented
 by a short display name plus fingerprint, not by secret-bearing credentials.
+Runtime checkout evidence is uploaded separately as `runtime-checkout.json`,
+including cache transport, fallback attempts, and exact runtime `HEAD`
+verification, even when a later lifecycle step fails.
 
 When a Buildchain maintainer asks for downstream validation, the expected
 request is:

package/docs/versioning.md

@@ -61,6 +61,7 @@ repository changes are patch".
 
 | Date | Action | Line | Faces | Class | Rationale | PR |
 | --- | --- | --- | --- | --- | --- | --- |
+| 2026-07-11 | open-minor | `v2.12` | channel-build-router, channel-selection-protocol | additive | The public `build.yml` reusable workflow lets consumers declare one build job while Buildchain selects generic major alpha for development/prerelease intent and stable major for production release intent, with explicit overrides, separate locks, and fail-closed ambiguity handling. | |
 | 2026-07-08 | open-minor | `v2.9` | build-facts-contract | additive | Build Facts add a public CLI command family, Node API export, config protocol, module/product fact contracts, release-passport evidence section, and Kungfu legacy buildinfo projection from the same source facts. | |
 | 2026-07-06 | open-minor | `v2.8` | kfd-1-contract-world-release-gate, kfd-2-release-trust-passport-audit, kfd-3-collaboration-interface-trust-proof, publish-source-lock-enforcement, required-check-protection | additive | KFD release gates add KFD-1 self contract verification, KFD-2 public release trust claim audit, KFD-3 collaboration-interface trust proofs, publish-side source-lock enforcement for promote-only wrappers, and protected channel required checks repaired to bind GitHub Actions check runs instead of legacy commit status contexts. | |
 | 2026-07-04 | open-minor | `v2.5` | scheduled-integration-governance | additive | Scheduled integration governance adds scheduled feature-branch discovery, conflict-free integration, reporting, and agent-visible governance automation for dev-line maintenance. | |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "2.11.14-alpha.7",
+  "version": "2.12.0-alpha.1",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",

package/packages/core/buildchain-contract.js

@@ -111,6 +111,36 @@ export function createBuildchainContractWorld({ root = process.cwd(), packageJso
         "retryable GitHub fallback fetches use a bounded attempt budget before exact source SHA and tree verification",
       ],
     }),
+    surface(root, {
+      id: "channel-build-router",
+      kind: "workflow",
+      path: ".github/workflows/build.yml",
+      publicRef: `${pkg.repository ? "kungfu-systems/buildchain" : "buildchain"}/.github/workflows/build.yml@${majorLine}`,
+      requiredInputs: [],
+      requiredOutputs: ["buildchain-channel", "buildchain-runtime-sha", "build-summary-artifact"],
+      breakingDefaults: {
+        channelDefault: "auto",
+        developmentDefault: "alpha",
+        prereleaseDefault: "alpha",
+        stableReleaseDefault: "stable",
+        ambiguousReleasePolicy: "fail-closed",
+      },
+      optionalInputs: [
+        "buildchain-channel",
+        "buildchain-ref",
+        "buildchain-alpha-contract-lock-path",
+        "buildchain-stable-contract-lock-path",
+        "buildchain-contract-lock-path",
+      ],
+      guarantees: [
+        "consumers declare one build job while Buildchain selects the matching generic major channel",
+        "development and prerelease intent select vN-alpha",
+        "stable release intent selects vN",
+        "ambiguous release-like intent fails before build jobs",
+        "explicit train and exact-SHA overrides retain the reusable build trust gate",
+        "alpha and stable channel selections use separate consumer contract locks by default",
+      ],
+    }),
     surface(root, {
       id: "release-candidate-promote",
       kind: "workflow",
@@ -489,7 +519,19 @@ export function readBuildchainContractWorld(filePath) {
   if (!value || value.contract !== BUILDCHAIN_RUNTIME_CONTRACT_WORLD) {
     throw new Error(`Buildchain contract world is missing or invalid: ${filePath}`);
   }
-  return finalizeBuildchainContractWorld(value);
+  const computed = finalizeBuildchainContractWorld(value);
+  for (const digestName of ["compatibilityDigest", "contractDigest"]) {
+    const published = String(value[digestName] || "").trim();
+    if (published && published !== computed[digestName]) {
+      throw new Error(
+        `published ${digestName} mismatch in ${filePath}: expected ${published}, recomputed ${computed[digestName]}`,
+      );
+    }
+    if (published) {
+      computed[digestName] = published;
+    }
+  }
+  return computed;
 }
 
 export function readBuildchainContractLock(filePath) {