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

package/dist/site/schemas/release-passport-v1.schema.json

@@ -0,0 +1,198 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://buildchain.libkungfu.dev/schemas/release-passport-v1.schema.json",
+  "title": "Buildchain Release Passport v1",
+  "description": "Standalone structural schema for the Buildchain-owned release-passport envelope. KFD subsection semantics remain owned by their canonical KFD schemas.",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "contract",
+    "product",
+    "release",
+    "artifacts",
+    "evidence",
+    "recovery"
+  ],
+  "properties": {
+    "schemaVersion": {
+      "const": 1
+    },
+    "contract": {
+      "const": "kungfu-buildchain-release-passport"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "product": {
+      "type": "object",
+      "required": [
+        "name",
+        "repository",
+        "mechanism"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "repository": {
+          "type": "string",
+          "minLength": 1
+        },
+        "mechanism": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": true
+    },
+    "release": {
+      "type": "object",
+      "required": [
+        "tag"
+      ],
+      "properties": {
+        "tag": {
+          "type": "string",
+          "minLength": 1
+        },
+        "sourceSha": {
+          "type": "string"
+        },
+        "releaseSha": {
+          "type": "string"
+        },
+        "releaseMaterialSha": {
+          "type": "string"
+        },
+        "targetRef": {
+          "type": "string"
+        },
+        "channel": {
+          "type": "string"
+        },
+        "line": {
+          "type": "string"
+        },
+        "package": {
+          "type": "object"
+        }
+      },
+      "additionalProperties": true
+    },
+    "artifacts": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": [
+          "name"
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "additionalProperties": true
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "required": [
+        "artifactEvidence",
+        "impact",
+        "agentIndex"
+      ],
+      "properties": {
+        "artifactEvidence": {
+          "type": "string",
+          "minLength": 1
+        },
+        "impact": {
+          "type": "string",
+          "minLength": 1
+        },
+        "agentIndex": {
+          "type": "string",
+          "minLength": 1
+        },
+        "publishEvidence": {
+          "type": "string"
+        },
+        "transactionState": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    },
+    "recovery": {
+      "type": "object"
+    },
+    "workflow": {
+      "type": "object"
+    },
+    "runnerPolicy": {
+      "type": "object"
+    },
+    "versionImpact": {
+      "type": "object"
+    },
+    "surfaceImpacts": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "packageSet": {
+      "type": "object"
+    },
+    "anchorManifest": {
+      "type": "object"
+    },
+    "trustedPublishing": {
+      "type": "object"
+    },
+    "transaction": {
+      "type": "object"
+    },
+    "surfaceTimestampPolicy": {
+      "type": "object"
+    },
+    "buildFacts": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "buildSummary": {
+      "type": "object"
+    },
+    "platformArtifactManifests": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "distTagPromotion": {
+      "type": "object"
+    },
+    "controllerReceipts": {
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "kfd-1": {
+      "type": "object"
+    },
+    "kfd-2": {
+      "type": "object"
+    },
+    "kfd-3": {
+      "type": "object"
+    }
+  },
+  "additionalProperties": true
+}

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-07-18T01:00:00.995Z",
-  "publishedAt": "2026-07-18T01:00:00.995Z",
+  "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": "ae16e640bf2f21c8f981ffa8b3523c8aae9200b2",
+  "sourceRevision": "cb4ea966786d561d5f6e9c53d55bba5e951bdb24",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "2.14.2",
+    "version": "2.14.3-alpha.1",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -69,7 +69,7 @@
       "path": "docs/release-passport.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:2421e3e9f2dd892971bea5deb605492dfec38f3a83e539229442b55380bebe25"
+      "digest": "sha256:0029014ffab7d7228a12d8b92326b78cf6757a41f481b661c5997e2cef06d3cc"
     },
     {
       "id": "controller-evidence",
@@ -93,7 +93,7 @@
       "path": "docs/release-candidate.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:1fc581cf1b4e4a202464c8d6671b3bff12d0b349760246a951e88ef524f99e6b"
+      "digest": "sha256:81463a74dfe3d337768797b5b47f8cb3a22389312a917447f9b0e6096ab4f90a"
     },
     {
       "id": "release-propagation",
@@ -101,7 +101,7 @@
       "path": "docs/release-propagation.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:d5877075eb41a3d41e531549da113756d29d6f34c91e3b68b8ce650753d5ca1d"
+      "digest": "sha256:fc2b743e3d76c4f90cdd8c6560cf9d619ad25d74c15c074be96db7bcb6cc2a29"
     },
     {
       "id": "readme-badges",
@@ -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"
@@ -1444,17 +1564,20 @@
         "buildchain-repository",
         "downstream-base-ref",
         "downstream-branch",
+        "downstream-prepare-command",
         "downstream-repository",
         "downstream-target",
+        "downstream-verify-command",
         "dry-run",
         "graph-json",
         "lock-path",
         "pr-body",
         "pr-title",
+        "refresh-managed-readme-badges",
         "source-node",
         "upstream-release-json"
       ],
-      "inputCount": 13,
+      "inputCount": 16,
       "secrets": [
         "propagation-token"
       ],
@@ -1624,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",
@@ -1636,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/release-passport.md

@@ -19,6 +19,25 @@ do not infer execution evidence from a green job. See
 The release passport surface is a welded contract. Additive fields are allowed;
 breaking semantic changes require a new major line.
 
+Independent verifiers can pin two package-owned, standalone files without
+scraping this implementation:
+
+- `dist/site/schemas/release-passport-v1.schema.json` is the self-contained
+  JSON Schema for the Buildchain-owned envelope;
+- `dist/site/release-passport-check-manifest.json` names the normative checker,
+  required and conditional sibling evidence, local-resolution rules,
+  Buildchain aggregation fields, canonical KFD subsection schema authorities,
+  and forward-compatibility policy.
+
+The same files are exported as
+`@kungfu-tech/buildchain/site/schemas/release-passport-v1.schema.json` and
+`@kungfu-tech/buildchain/site/release-passport-check-manifest.json`. The schema
+checks the envelope shape. `buildchain verify release-passport` remains the
+normative semantic checker: it resolves sibling evidence relative to the
+passport and fails closed on missing evidence, digest drift, or inconsistent
+release facts. Buildchain owns envelope aggregation; KFD retains schema and
+compatibility authority for the `kfd-1`, `kfd-2`, and `kfd-3` subsections.
+
 P0 protocol artifacts:
 
 - `product-mechanism.json`

package/docs/release-propagation.md

@@ -182,6 +182,8 @@ jobs:
       downstream-target: site-libkungfu-dev
       downstream-repository: kungfu-systems/site-libkungfu-dev
       downstream-base-ref: dev/v2/v2.7
+      downstream-prepare-command: pnpm install --frozen-lockfile --ignore-scripts
+      downstream-verify-command: pnpm run check
       dry-run: false
     secrets:
       propagation-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
@@ -199,13 +201,23 @@ open PR.
 The workflow checks out the Buildchain runtime selected by
 `buildchain-repository` and `buildchain-ref` into `.buildchain/runtime`, invokes
 that runtime for the propagation plan and lock write, then checks out the
-downstream repository, writes the exact lock, and opens or updates a PR. It does
-not publish the downstream release directly. The downstream repository keeps its
-normal Buildchain governance: the PR updates source-of-truth facts, then
-downstream alpha or release publication runs through its own protected channel.
-The workflow stages the declared lock path before checking the index, so the
-first propagation creates a PR even when the lock did not previously exist; a
-byte-identical rerun is an explicit successful no-op.
+downstream repository and writes the exact lock. A consumer that must pin the
+exact upstream package or regenerate deterministic files declares
+`downstream-prepare-command`. The command receives
+`BUILDCHAIN_UPSTREAM_PACKAGE_NAME`, `BUILDCHAIN_UPSTREAM_PACKAGE_VERSION`, and
+`BUILDCHAIN_UPSTREAM_RELEASE_LOCK`. After preparation, Buildchain refreshes an
+existing `<!-- buildchain:badges:start -->` README block by default. Consumers
+can disable that step with `refresh-managed-readme-badges: false`.
+
+`downstream-verify-command` runs against the final tree before any commit or
+push, so consumers can use the same check as their PR workflow. Preparation,
+badge refresh, and verification failures all fail closed. The workflow stages
+the complete deterministic result, signs the propagation commit with DCO, and
+then opens or updates the PR. It does not publish the downstream release
+directly. The downstream repository keeps its normal Buildchain governance: the
+PR updates source-of-truth facts, then downstream alpha or release publication
+runs through its own protected channel. A byte-identical rerun is an explicit
+successful no-op.
 For unreleased runtime validation, keep the caller's reusable workflow reference
 on `@v2` and pass a temporary train ref through `buildchain-ref`.
 

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