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

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

@@ -4,7 +4,7 @@
   "status": "passed",
   "summary": {
     "cliCommandCount": 83,
-    "workflowCount": 48,
+    "workflowCount": 49,
     "actionCount": 4,
     "sitePageCount": 50,
     "docCommandRefCount": 258,
@@ -674,6 +674,108 @@
         ],
         "outputCount": 5
       },
+      {
+        "id": ".release-candidate-promote",
+        "path": ".github/workflows/.release-candidate-promote.yml",
+        "reusable": true,
+        "inputs": [
+          "allow-repository",
+          "artifact-name",
+          "artifact-patterns",
+          "branch-protection-bypass-apps",
+          "branch-protection-bypass-teams",
+          "branch-protection-bypass-users",
+          "buildchain-contract-compatibility-policy",
+          "buildchain-contract-drift-issue-mode",
+          "buildchain-contract-lock-path",
+          "buildchain-ref",
+          "buildchain-repository",
+          "channel",
+          "dry-run",
+          "github-release",
+          "github-release-notes",
+          "github-release-title",
+          "package-manager",
+          "promotion-contract-lock-digest",
+          "promotion-contract-lock-path",
+          "promotion-override-used",
+          "promotion-publication-channel",
+          "promotion-router-ref",
+          "promotion-router-sha",
+          "promotion-runtime-ref",
+          "promotion-runtime-sha",
+          "promotion-shell-ref",
+          "promotion-shell-sha",
+          "promotion-target-ref",
+          "publication-admission-json",
+          "publication-auto-admission",
+          "publication-auto-no-gate",
+          "publication-consumer-predicate-id",
+          "publication-consumer-qualification-command",
+          "publication-control-plane-audit-json",
+          "publication-expected-json",
+          "publication-gate-aggregate-json",
+          "publication-package-name",
+          "publication-product",
+          "publication-publisher-workflow-path",
+          "publication-runner-provenance-json",
+          "publication-target",
+          "publication-used-nonces-json",
+          "publication-used-qualification-nonces-json",
+          "publish-artifact-kind",
+          "publish-command",
+          "publish-dist-tag",
+          "publish-mode",
+          "publish-package-main",
+          "publish-package-set-order",
+          "publish-required-artifacts-json",
+          "publish-target",
+          "release-candidate-workflow-file",
+          "release-candidate-workflow-name",
+          "release-passport",
+          "release-passport-buildchain-self-kfd",
+          "release-passport-impact-json",
+          "release-passport-kfd-1-witness-jsons",
+          "release-passport-kfd-2-claim-jsons",
+          "release-passport-kfd-3-artifact-verify-command",
+          "release-passport-kfd-3-artifact-witness-jsons",
+          "release-passport-kfd-3-prebuild-witness-jsons",
+          "release-passport-output-dir",
+          "release-passport-platform-manifest-paths",
+          "release-passport-product-name",
+          "required-artifact-count",
+          "required-status-check",
+          "runner-preset",
+          "target-ref",
+          "target-sha",
+          "trusted-publishing"
+        ],
+        "inputCount": 70,
+        "secrets": [
+          "BUILDCHAIN_ISSUE_APP_ID",
+          "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
+          "BUILDCHAIN_ISSUE_TOKEN",
+          "BUILDCHAIN_PROMOTION_TOKEN",
+          "buildchain-issue-app-id",
+          "buildchain-issue-app-private-key",
+          "buildchain-issue-token"
+        ],
+        "secretCount": 7,
+        "outputs": [
+          "built-source-sha",
+          "controller-plan-artifact",
+          "controller-plan-digest",
+          "controller-plan-json",
+          "controller-receipt-artifact",
+          "controller-receipt-digest",
+          "controller-receipt-json",
+          "controller-receipt-status",
+          "promoted-sha",
+          "publication-capability-digest",
+          "release-candidate-artifact"
+        ],
+        "outputCount": 11
+      },
       {
         "id": ".release-docker",
         "path": ".github/workflows/.release-docker.yml",
@@ -1633,11 +1735,14 @@
           "branch-protection-bypass-apps",
           "branch-protection-bypass-teams",
           "branch-protection-bypass-users",
+          "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",
           "channel",
           "dry-run",
           "github-release",
@@ -1687,7 +1792,7 @@
           "target-sha",
           "trusted-publishing"
         ],
-        "inputCount": 59,
+        "inputCount": 62,
         "secrets": [
           "BUILDCHAIN_ISSUE_APP_ID",
           "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
@@ -1699,6 +1804,7 @@
         ],
         "secretCount": 7,
         "outputs": [
+          "buildchain-channel",
           "built-source-sha",
           "controller-plan-artifact",
           "controller-plan-digest",
@@ -1708,10 +1814,21 @@
           "controller-receipt-json",
           "controller-receipt-status",
           "promoted-sha",
+          "promotion-contract-lock-digest",
+          "promotion-contract-lock-path",
+          "promotion-override-used",
+          "promotion-publication-channel",
+          "promotion-router-ref",
+          "promotion-router-sha",
+          "promotion-runtime-ref",
+          "promotion-runtime-sha",
+          "promotion-shell-ref",
+          "promotion-shell-sha",
+          "promotion-target-ref",
           "publication-capability-digest",
           "release-candidate-artifact"
         ],
-        "outputCount": 11
+        "outputCount": 23
       },
       {
         "id": "release-line-bootstrap",
@@ -1908,6 +2025,7 @@
           "release-passport-output-dir",
           "release-passport-platform-manifest-paths",
           "release-passport-product-name",
+          "release-passport-promotion-routing-json",
           "require-governance",
           "require-publication-qualification",
           "require-publish-source-lock",
@@ -1920,7 +2038,7 @@
           "transaction-state-path",
           "verification-command"
         ],
-        "inputCount": 59
+        "inputCount": 60
       },
       {
         "id": "report-buildchain-issue",
@@ -3511,8 +3629,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "b469949f77ed7777f23fe68c54daf6d2c20d3afc97f3bbd5a178a91202a068d0",
-    "workflowRegistryDigest": "822624c70c801b19f537335a451b240f4e82cc4435ad89f0298621d3a817a710",
-    "pageRegistryDigest": "4598f3d80d638f6aa5ed8541b9ddd47b2052408c1245fcc4b776e36a297ef99f"
+    "workflowRegistryDigest": "4812aea118585c3f527834090569f02cf66c142d2f9a0f8b3d3882e9a614a361",
+    "pageRegistryDigest": "e68b12261716c3ef857d14a327dce77de8ea9f5a7052406c55b86db60e84301c"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-authority-registry.json

@@ -44,6 +44,23 @@
       "runnerPolicy": "unqualified",
       "notes": ""
     },
+    {
+      "workflowPath": ".github/workflows/.release-candidate-promote.yml",
+      "authorityClass": "product-publication",
+      "publicationCapable": true,
+      "capabilityIds": [
+        "channel-ref",
+        "github-release",
+        "npm-publish"
+      ],
+      "credentialMode": "trusted-publishing",
+      "publisherWorkflowMode": "caller-bound",
+      "publisherWorkflowPath": ".github/workflows/.release-candidate-promote.yml",
+      "environment": "none",
+      "environmentMode": "fixed",
+      "runnerPolicy": "qualified-measured",
+      "notes": ""
+    },
     {
       "workflowPath": ".github/workflows/.release-verify.yml",
       "authorityClass": "governance-write",
@@ -507,6 +524,14 @@
       "signals": [],
       "classified": true
     },
+    {
+      "path": ".github/workflows/.release-candidate-promote.yml",
+      "signals": [
+        "write-permission",
+        "oidc"
+      ],
+      "classified": true
+    },
     {
       "path": ".github/workflows/.release-docker.yml",
       "signals": [],
@@ -792,5 +817,5 @@
       "classified": false
     }
   ],
-  "registryDigest": "24c7f5210da277b79ce13356c439c14ea49f6c54ba9e083f42ce47fdfdacc55c"
+  "registryDigest": "ac085131119085cfc02e37913ec5eabc9f38b04100c58d797ede3b8e2b7e3046"
 }

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-07-18T22:57:23.219Z",
-  "publishedAt": "2026-07-18T22:57:23.219Z",
+  "generatedAt": "2026-07-19T00:00:09.045Z",
+  "publishedAt": "2026-07-19T00:00:09.045Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "8b0423396f09f29e2ea05c38896228751767ab21",
+  "sourceRevision": "cb4ea966786d561d5f6e9c53d55bba5e951bdb24",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.3-alpha.0",
+    "version": "2.14.3-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-18T22:57:23.219Z",
-  "publishedAt": "2026-07-18T22:57:23.219Z",
+  "generatedAt": "2026-07-19T00:00:09.045Z",
+  "publishedAt": "2026-07-19T00:00:09.045Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "8b0423396f09f29e2ea05c38896228751767ab21",
+  "sourceRevision": "cb4ea966786d561d5f6e9c53d55bba5e951bdb24",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.3-alpha.0",
+    "version": "2.14.3-alpha.1",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -93,7 +93,7 @@
       "path": "docs/release-candidate.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:1fc581cf1b4e4a202464c8d6671b3bff12d0b349760246a951e88ef524f99e6b"
+      "digest": "sha256:81463a74dfe3d337768797b5b47f8cb3a22389312a917447f9b0e6096ab4f90a"
     },
     {
       "id": "release-propagation",
@@ -165,7 +165,7 @@
       "path": "docs/migration-inventory.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:80018cf78785431e67bbc5278d82dda80d0baa320cdb5e4abda26a0b05e5c0bc"
+      "digest": "sha256:08daa7d0b42543c1d1dacf1f56f461f0e7a7ca9e25d0859e39599ceb97054ee0"
     },
     {
       "id": "ownership",
@@ -221,7 +221,7 @@
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:a2092c8064332cec9a4be852b24d94f90625cb45f885c4c3208f7068a643a3f0"
+      "digest": "sha256:7b745037fedafa1bc2f8ce65f32bb7e887988df2bfe2439694da418d482f6929"
     },
     {
       "id": "publish-transaction",
@@ -237,7 +237,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:e64ffd6183eaa7b73f8c0c133a645ced22212bca70c9609ad5f667cf3830aaae"
+      "digest": "sha256:d25a2ceb6cdc1a1db321e7d2a6aa8a454fb4d7a10560177604f8ecb5801a6e66"
     },
     {
       "id": "release-flow",

package/dist/site/workflow-registry.json

@@ -263,6 +263,111 @@
       "capabilityGroup": "api-cli-reference",
       "status": "active"
     },
+    {
+      "id": ".release-candidate-promote",
+      "path": ".github/workflows/.release-candidate-promote.yml",
+      "reusable": true,
+      "inputs": [
+        "allow-repository",
+        "artifact-name",
+        "artifact-patterns",
+        "branch-protection-bypass-apps",
+        "branch-protection-bypass-teams",
+        "branch-protection-bypass-users",
+        "buildchain-contract-compatibility-policy",
+        "buildchain-contract-drift-issue-mode",
+        "buildchain-contract-lock-path",
+        "buildchain-ref",
+        "buildchain-repository",
+        "channel",
+        "dry-run",
+        "github-release",
+        "github-release-notes",
+        "github-release-title",
+        "package-manager",
+        "promotion-contract-lock-digest",
+        "promotion-contract-lock-path",
+        "promotion-override-used",
+        "promotion-publication-channel",
+        "promotion-router-ref",
+        "promotion-router-sha",
+        "promotion-runtime-ref",
+        "promotion-runtime-sha",
+        "promotion-shell-ref",
+        "promotion-shell-sha",
+        "promotion-target-ref",
+        "publication-admission-json",
+        "publication-auto-admission",
+        "publication-auto-no-gate",
+        "publication-consumer-predicate-id",
+        "publication-consumer-qualification-command",
+        "publication-control-plane-audit-json",
+        "publication-expected-json",
+        "publication-gate-aggregate-json",
+        "publication-package-name",
+        "publication-product",
+        "publication-publisher-workflow-path",
+        "publication-runner-provenance-json",
+        "publication-target",
+        "publication-used-nonces-json",
+        "publication-used-qualification-nonces-json",
+        "publish-artifact-kind",
+        "publish-command",
+        "publish-dist-tag",
+        "publish-mode",
+        "publish-package-main",
+        "publish-package-set-order",
+        "publish-required-artifacts-json",
+        "publish-target",
+        "release-candidate-workflow-file",
+        "release-candidate-workflow-name",
+        "release-passport",
+        "release-passport-buildchain-self-kfd",
+        "release-passport-impact-json",
+        "release-passport-kfd-1-witness-jsons",
+        "release-passport-kfd-2-claim-jsons",
+        "release-passport-kfd-3-artifact-verify-command",
+        "release-passport-kfd-3-artifact-witness-jsons",
+        "release-passport-kfd-3-prebuild-witness-jsons",
+        "release-passport-output-dir",
+        "release-passport-platform-manifest-paths",
+        "release-passport-product-name",
+        "required-artifact-count",
+        "required-status-check",
+        "runner-preset",
+        "target-ref",
+        "target-sha",
+        "trusted-publishing"
+      ],
+      "inputCount": 70,
+      "secrets": [
+        "BUILDCHAIN_ISSUE_APP_ID",
+        "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
+        "BUILDCHAIN_ISSUE_TOKEN",
+        "BUILDCHAIN_PROMOTION_TOKEN",
+        "buildchain-issue-app-id",
+        "buildchain-issue-app-private-key",
+        "buildchain-issue-token"
+      ],
+      "secretCount": 7,
+      "outputs": [
+        "built-source-sha",
+        "controller-plan-artifact",
+        "controller-plan-digest",
+        "controller-plan-json",
+        "controller-receipt-artifact",
+        "controller-receipt-digest",
+        "controller-receipt-json",
+        "controller-receipt-status",
+        "promoted-sha",
+        "publication-capability-digest",
+        "release-candidate-artifact"
+      ],
+      "outputCount": 11,
+      "surface": "reusable-workflow",
+      "capabilityGroup": "api-cli-reference",
+      "status": "active"
+    },
     {
       "id": ".release-docker",
       "path": ".github/workflows/.release-docker.yml",
@@ -1324,11 +1429,14 @@
         "branch-protection-bypass-apps",
         "branch-protection-bypass-teams",
         "branch-protection-bypass-users",
+        "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",
         "channel",
         "dry-run",
         "github-release",
@@ -1378,7 +1486,7 @@
         "target-sha",
         "trusted-publishing"
       ],
-      "inputCount": 59,
+      "inputCount": 62,
       "secrets": [
         "BUILDCHAIN_ISSUE_APP_ID",
         "BUILDCHAIN_ISSUE_APP_PRIVATE_KEY",
@@ -1390,6 +1498,7 @@
       ],
       "secretCount": 7,
       "outputs": [
+        "buildchain-channel",
         "built-source-sha",
         "controller-plan-artifact",
         "controller-plan-digest",
@@ -1399,10 +1508,21 @@
         "controller-receipt-json",
         "controller-receipt-status",
         "promoted-sha",
+        "promotion-contract-lock-digest",
+        "promotion-contract-lock-path",
+        "promotion-override-used",
+        "promotion-publication-channel",
+        "promotion-router-ref",
+        "promotion-router-sha",
+        "promotion-runtime-ref",
+        "promotion-runtime-sha",
+        "promotion-shell-ref",
+        "promotion-shell-sha",
+        "promotion-target-ref",
         "publication-capability-digest",
         "release-candidate-artifact"
       ],
-      "outputCount": 11,
+      "outputCount": 23,
       "surface": "release-governance",
       "capabilityGroup": "reusable-build",
       "status": "active"
@@ -1627,6 +1747,7 @@
         "release-passport-output-dir",
         "release-passport-platform-manifest-paths",
         "release-passport-product-name",
+        "release-passport-promotion-routing-json",
         "require-governance",
         "require-publication-qualification",
         "require-publish-source-lock",
@@ -1639,7 +1760,7 @@
         "transaction-state-path",
         "verification-command"
       ],
-      "inputCount": 59,
+      "inputCount": 60,
       "capabilityGroup": "release-passport-trust",
       "status": "active"
     },

package/docs/migration-inventory.md

@@ -37,6 +37,14 @@ migrate to `release-candidate-promote.yml@v2` or a project-owned
 `lifecycle.publish` command behind a publish-gate source lock, so floating
 `@v2` consumers cannot bypass source-lock drift protection.
 
+The public promotion workflow is now a generated dual-channel router. Existing
+callers remain source-compatible, while callers that want alpha workflow-shell
+fixes before stable promotion should add `buildchain-channel: auto` plus
+`buildchain-alpha-contract-lock-path` and
+`buildchain-stable-contract-lock-path`. Keep one common promotion declaration;
+do not duplicate alpha and stable jobs or call
+`.release-candidate-promote.yml` directly.
+
 ## Migrated Actions
 
 No standalone `action-*` repository is shipped as a Buildchain action anymore.

package/docs/release-candidate.md

@@ -108,6 +108,9 @@ jobs:
   promote:
     uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v2
     with:
+      buildchain-channel: auto
+      buildchain-alpha-contract-lock-path: .buildchain/alpha-contract-lock.json
+      buildchain-stable-contract-lock-path: .buildchain/contract-lock.json
       channel: alpha
       artifact-name: libnode
       release-passport-kfd-1-witness-jsons: .buildchain/kfd/kfd-1/standard-contract.witness.json

package/docs/release-governance.md

@@ -729,7 +729,7 @@ but does not read, create, or move that ref.
 
 Semver GitHub Release publication is owned by `promote-buildchain-ref`, not by
 consumer shell glue. Consumers normally use the `release-candidate-promote.yml`
-wrapper, where GitHub Release publication is enabled by default and can be
+generated channel router, where GitHub Release publication is enabled by default and can be
 disabled with `github-release: false`; the wrapper passes that declaration to
 the action. After the publish transaction reaches `complete`, Buildchain creates
 or updates the public GitHub Release and uploads the generated
@@ -764,9 +764,10 @@ When debugging or extending release behavior, read in this order:
 2. `.github/workflows/release-verify.yml`
 3. `.github/workflows/buildchain-ref-promotion.yml`
 4. `.github/workflows/release-candidate-promote.yml`
-5. `actions/promote-buildchain-ref/README.md`
-6. `actions/promote-buildchain-ref/src/`
-7. `docs/migration-inventory.md`
+5. `.github/workflows/.release-candidate-promote.yml`
+6. `actions/promote-buildchain-ref/README.md`
+7. `actions/promote-buildchain-ref/src/`
+8. `docs/migration-inventory.md`
 
 That path gives the policy first, the workflow trigger second, and the action
 implementation last.

package/docs/reusable-build-surface.md

@@ -743,6 +743,23 @@ It does not call `.build.yml`, does not create a matrix, and must fail before
 publish if the RC evidence, payload set, or source-lock ref is missing or
 ambiguous.
 
+The public `release-candidate-promote.yml` is a generated channel router. It
+derives the publication lane from `target-ref`, then selects the matching
+advanced workflow shell, runtime, and consumer lock before the advanced
+promotion starts:
+
+- alpha targets use `.release-candidate-promote.yml@vN-alpha`, runtime
+  `vN-alpha`, and `buildchain-alpha-contract-lock-path`;
+- release and major targets use `.release-candidate-promote.yml@vN`, runtime
+  `vN`, and `buildchain-stable-contract-lock-path`.
+
+The router resolves immutable SHAs and the selected lock digest before candidate
+download. The advanced shell verifies the same router, shell, runtime, lock,
+channel, and target binding again. Train and exact-SHA runtime overrides remain
+restricted to trusted `workflow_dispatch` actors with write, maintain, or admin
+permission. Promotion controller evidence, the promotion copy of the release
+candidate passport, and the final release passport record these identities.
+
 ```yaml
 jobs:
   promote:
@@ -751,6 +768,9 @@ jobs:
       buildchain-issue-app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}
       buildchain-issue-app-private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}
     with:
+      buildchain-channel: auto
+      buildchain-alpha-contract-lock-path: .buildchain/alpha-contract-lock.json
+      buildchain-stable-contract-lock-path: .buildchain/contract-lock.json
       channel: alpha
       target-ref: alpha/v22/v22.22
       artifact-name: libnode
@@ -769,10 +789,15 @@ jobs:
       publish-package-set-order: platforms-first-main-last
       publish-package-main: "@kungfu-tech/libnode"
       release-passport-product-name: Libnode
-      buildchain-contract-lock-path: .buildchain/contract-lock.json
       buildchain-contract-drift-issue-mode: compatible-and-breaking
 ```
 
+Existing callers may keep `buildchain-contract-lock-path`; a non-empty explicit
+path overrides channel-specific selection for compatibility. Migration only
+requires adding the two channel lock inputs and may retain the remaining common
+promotion declaration unchanged. Consumers must not call the dot-prefixed
+advanced workflow directly.
+
 `buildchain-issue-app-id` and `buildchain-issue-app-private-key` are optional
 but recommended for cross-repository consumers. They should identify a GitHub
 App installation with `issues: write` on `kungfu-systems/buildchain`; the

package/package.json

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