@kungfu-tech/buildchain 3.0.2 → 3.0.3-alpha.1

package/dist/site/buildchain-site.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-bundle",
-  "generatedAt": "2026-07-30T07:24:06.316Z",
-  "publishedAt": "2026-07-30T07:24:06.316Z",
+  "generatedAt": "2026-07-31T13:41:52.861Z",
+  "publishedAt": "2026-07-31T13:41:52.861Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "1aeb9191f607a7223f8ab63c96427b605ecda9be",
+  "sourceRevision": "b8e84bcb51e131207896c426fb8e79fd0f46b5ac",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "3.0.2",
+    "version": "3.0.3-alpha.1",
     "versionSource": "package.json#version"
   },
   "source": {
@@ -106,7 +106,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "README.md",
-      "digest": "sha256:ef2a364dbb816b3cb8b9ab3ab24ab45283c6ff1d9aba089be4e4cb42edb8cd6c",
+      "digest": "sha256:dd536115d31c861df240260ced64887039c85d71a4afab5f013c5ce7395b4f99",
       "headings": [
         {
           "level": 1,
@@ -164,7 +164,7 @@
           "anchor": "read-next"
         }
       ],
-      "markdown": "# Buildchain\n\n<!-- buildchain:badges:start -->\n\n[![KFD-1: passed](https://buildchain.libkungfu.dev/badges/v1/kfd-1/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![KFD-2: passed](https://buildchain.libkungfu.dev/badges/v1/kfd-2/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![KFD-3: passed](https://buildchain.libkungfu.dev/badges/v1/kfd-3/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![KFD-4: declared](https://buildchain.libkungfu.dev/badges/v1/kfd-4/declared.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![Buildchain Release Passport: passed](https://buildchain.libkungfu.dev/badges/v1/buildchain-release-passport/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-0969da.svg)](https://github.com/kungfu-systems/buildchain/blob/HEAD/LICENSE)\n[![Platform: macOS | Linux | Windows](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-6e7781.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![Verify](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml)\n[![Buildchain Ref Promotion](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml)\n[![Binary Distribution](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml)\n<!-- buildchain:badges:end -->\n\nBuildchain Release Passport is a mature product release record for artifacts\nthat users or agents depend on.\n\nBuildchain by Kungfu uses GitHub as the execution and trust substrate: protected\nrefs, reviewed promotion PRs, exact tags, GitHub Releases, npm Trusted\nPublishing, and machine-readable evidence. Its job is to turn release intent\ninto an auditable product record, not to ask a repository to migrate away from\nits existing CI.\n\nThe same mechanism releases Buildchain itself.\n\n## Where Buildchain sits in the Agent Supply Chain\n\nBuildchain binds a product's declarations to the exact source cut, build,\nartifacts, checks, and promotion record that produced a release. In the wider\nAgent Supply Chain it sits between KFD-3 product discovery and KFD-2\npurpose-bound assessment:\n\n```text\nKFD-3 declaration -> Buildchain exact-artifact evidence -> KFD-2 assessment\n```\n\nBuildchain can prove that a declared claim and an exact artifact remain\nconsistent, or fail/downgrade when their evidence drifts. It does not invent\nthe product fact, decide whether a receiver should trust it for a purpose,\ncertify every platform, or prove external adoption. Receivers and downstream\nKFD-2 assessors retain the admission decision and residual risk.\n\nTo evaluate the layer, inspect a release's `buildchain.release.json` and\n`artifact-evidence.json`, verify them with the CLI, and report missing product\nor protocol evidence through the repository issue tracker.\n\n## Install and Verify\n\nFor v3, use the published npm package and verify the release passport before\ntrusting release evidence:\n\n```bash\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v3.0.0/buildchain.release.json\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v3.0.0/artifact-evidence.json\nnpx @kungfu-tech/buildchain@3.0.0 verify release-passport buildchain.release.json\nnpx @kungfu-tech/buildchain@3.0.0 version\n```\n\nThe v3.0.0 release publishes evidence assets but no standalone platform archives.\nThe names below describe the optional archive contract used by legacy release\nlines:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n- `checksums.txt`\n- `buildchain.release.json`\n- `artifact-evidence.json`\n- `product-mechanism.json`\n- `impact.json`\n- `agent-index.json`\n- `check-report.json`\n- `llms.txt`\n- `buildchain-release-bundle.tar.gz`\n- `buildchain-release-bundle.json`\n\nLoose top-level `buildchain` and `buildchain.exe` assets are intentionally not\npublished. The executable lives inside each platform archive, which prevents\nLinux and macOS artifacts from overwriting each other in a merged release lane.\n\nFor npm consumers:\n\n```bash\nnpm install -D @kungfu-tech/buildchain\nnpx buildchain version\nnpx buildchain doctor --json\n```\n\nThe npm package is also the Buildchain toolkit. Use the command when a workflow\nor shell step needs an executable; use the ESM APIs directly from JavaScript\nbuild scripts. JavaScript callers should import the package instead of spawning\nthe CLI or unpacking the standalone binary:\n\n```js\nimport {\n  createBuildchainLogger,\n  verifyBuildchainLogEvents,\n} from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n  path: \".buildchain/logs/native-build.jsonl\",\n  source: \"user\",\n  component: \"native-build\",\n});\n\nawait logger.span(\"native.compile\", { phase: \"build\" }, async () => {\n  await compileNativeTargets();\n});\n\nconst report = verifyBuildchainLogEvents({\n  path: logger.path,\n  requireEvents: [\"native.compile.start\", \"native.compile.end\"],\n});\n```\n\nThe package also ships `dist/site/` as the Buildchain-owned fact source for\n`buildchain.libkungfu.dev`.\n\nRepositories can also generate README status badges from Buildchain-owned facts\ninstead of hand-maintaining badge Markdown:\n\n```bash\nbuildchain badges bundle --check\nbuildchain badges bundle --write\nbuildchain badges readme --check\nbuildchain badges readme --write\n```\n\n## Project Governance\n\n- [`LICENSE-POLICY.md`](LICENSE-POLICY.md) explains the Apache-2.0 project\n  license, DCO-based contributions, and third-party notice boundary.\n- [`TRADEMARK.md`](TRADEMARK.md) explains official project marks and fork\n  identity boundaries.\n- [`ACCEPTABLE_USE.md`](ACCEPTABLE_USE.md) explains acceptable use of official\n  services and maintainer-operated infrastructure.\n- [`PROVIDER_COMPLIANCE.md`](PROVIDER_COMPLIANCE.md) explains the official\n  posture for GitHub, npm, cloud, credential, release evidence, and other\n  provider integrations.\n- [`SECURITY.md`](SECURITY.md) explains private vulnerability reporting.\n\nNative build consumers can import the diagnostics toolkit instead of copying\nrepository-local probes:\n\n```js\nimport {\n  collectBuildchainDiagnostics,\n  collectRunnerDiagnostics,\n  writeDiagnosticsArtifact,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n\nwriteDiagnosticsArtifact(\".buildchain/artifacts/diagnostics.json\", {\n  contract: \"consumer-build-diagnostics\",\n  buildchain: collectBuildchainDiagnostics({ cwd: process.cwd() }),\n  runner: collectRunnerDiagnostics(),\n});\n```\n\n`buildchain lifecycle run` writes a small `diagnostics.json` next to the\nplatform manifest. It includes lifecycle-wide observability, runner/tool/cache\nsnapshots, Git state, and links to the larger manifest and artifact outputs.\n\nConsumers can report Buildchain-owned workflow failures directly to the\nBuildchain repository with a scoped issue-write token:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v3\n  if: failure()\n  with:\n    token: ${{ steps.buildchain-issue-token.outputs.token }}\n    summary: \"Reusable build failed before artifact finalization\"\n    failure-code: reusable-build-failed\n    buildchain-ref: v3\n    diagnostics-path: .buildchain/artifacts/diagnostics.json\n```\n\nThe action deduplicates by fingerprint, comments on existing open reports, and\nis fail-soft by default so issue reporting does not hide the original failure.\nUse `report-kind: workflow-friction` when Buildchain workflows should report\ntheir own repeated release friction back to the Buildchain issue tracker.\n\n## Use Buildchain\n\nBootstrap a repository:\n\n```bash\nnpx @kungfu-tech/buildchain init --type package --package-manager pnpm\nnpx @kungfu-tech/buildchain validate --require-version-state\nnpx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v3/v3.0\n```\n\nBuildchain supports package and non-package projects through\n`.buildchain/buildchain.toml`. Legacy root `buildchain.toml` files remain\nreadable, but new consumers should keep Buildchain-owned files under\n`.buildchain/`:\n\n```text\n.buildchain/buildchain.toml\n.buildchain/contract-lock.json\n.buildchain/kfd/kfd-3/surfaces.json\n.buildchain/release-passport/buildchain.release.json\n```\n\nLifecycle commands can call pnpm, npm, yarn, pip, Conan, CMake, Make, custom\nscripts, or any other command that can run in the repository checkout.\n\nThe KFD entrypoint is `buildchain kfd`. Buildchain provides concrete KFD-1\ncontract-world, KFD-2 trust-claim, and KFD-3 collaboration-surface workflows,\nplus fail-closed product-evidence gates for KFD-4, KFD-5, and KFD-7. These\ngates preserve product-owned qualification and support decisions; they do not\nturn a schema-valid record into certification or shipped support.\n\nBuildchain's active GitHub Action surface is deliberately small:\n\n- `actions/validate-config`\n- `actions/run-lifecycle`\n- `actions/promote-buildchain-ref`\n- `actions/report-buildchain-issue`\n\nThe active reusable workflow surfaces are:\n\n- `.github/workflows/.gate-profile.yml` for project-neutral Shifu Gate profile\n  planning, capability-aware runner dispatch, receipt validation, and one\n  stable aggregate check;\n- `.github/workflows/.auditable-demo.yml` for exact-artifact demo\n  qualification, transcript-bound renderer smoke, optional media rendering\n  from the exact passing Gate bundle, and opt-in content-addressed web-delivery\n  profiles with independently verified rendition roles;\n- `.github/workflows/.build.yml` for deterministic multi-platform build and\n  artifact contracts;\n- `.github/workflows/build.yml` for the single-config channel router that uses\n  `vN-alpha` during development/prerelease work and `vN` for stable releases;\n- `.github/workflows/release-candidate-promote.yml` for post-merge\n  promote-only publication from a PR-stage release candidate, without a second\n  heavy build;\n- `.github/workflows/.web-surface.yml` for preview, staging, production, and\n  cleanup plans for site/app repositories;\n- `.github/workflows/buildchain-ref-promotion.yml` for protected release\n  promotion and version-state transactions;\n- `.github/workflows/binary-distribution.yml` for Buildchain's own release\n  passport proof case.\n\nStable consumers should reference actions and workflows through floating major\nrefs after reviewing the exact release passport:\n\n```yaml\nuses: kungfu-systems/buildchain/actions/validate-config@v3\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/build.yml@v3\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v3\n```\n\n## Release Model\n\nBuildchain treats a reviewed branch merge as release intent:\n\n| Merge path                              | Meaning                                                | Exact tag        | Floating refs                                        |\n| --------------------------------------- | ------------------------------------------------------ | ---------------- | ---------------------------------------------------- |\n| `dev/vX/vX.Y -> alpha/vX/vX.Y`          | publish the next testable alpha for a minor line       | `vX.Y.Z-alpha.N` | `vX.Y-alpha`, `alpha/vX/vX.Y`, `dev/vX/vX.Y`         |\n| `alpha/vX/vX.Y -> release/vX/vX.Y`      | publish production for that minor line                 | `vX.Y.Z`         | `vX.Y`, usually `vX`, `release/vX/vX.Y`              |\n| `release/vX/vX.Y -> publish-gate/major` | publish the next major from a reviewed production line | `v(X+1).0.0`     | `v(X+1)`, `v(X+1).0`, new dev/alpha/release branches |\n\nExact tags are immutable. Floating channel tags and branches are machine-updated\nby Buildchain and must remain writable by the release authority.\n\nAfter a production release, Buildchain prepares the next alpha source commit for\nthe same minor line. That keeps production consumers pinned to the production\npassport while development can continue on the next testable patch.\n\n`publish-gate/major` is not an active development trunk. It is a reviewed\npromotion gate used when maintainers decide that the next production release\nshould open a new major line.\n\n## Toolkit Observability\n\nBuildchain includes a logging toolkit for release and build steps. Inside\nJavaScript build code, prefer the package API:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"conan\" });\nlogger.mark(\"conan.profile.ready\", { phase: \"configure\" });\nawait logger.span(\"conan.install\", { phase: \"dependencies\" }, runConanInstall);\n```\n\nIn workflows or shell scripts, use the equivalent CLI:\n\n```bash\nbuildchain mark --event native.configure --phase configure --component cmake\nbuildchain span --event native.build --phase build -- cmake --build build\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4\n```\n\nEvery event records a timestamp. `span` records duration. The API form can be\nimported from repository scripts so heavy builds can mark phases from inside\ntheir own code.\n\n## Site Fact Source\n\n`@kungfu-tech/buildchain` publishes `dist/site/`:\n\n- `buildchain-site.json`\n- `site-manifest.json`\n- `page-registry.json`\n- `cli-registry.json`\n- `workflow-registry.json`\n- `release-model.json`\n- `artifact-schemas.json`\n- `product-mechanism.json`\n- `release-provenance.json`\n- `agent-index.json`\n\n`buildchain.libkungfu.dev` should render from these package-owned facts, then\nlayer presentation around them. The site should not hand-write Buildchain's\ncurrent release mechanics. `page-registry.json` is the complete markdown page\nsource for the public site: README homepage content, all packaged `docs/*.md`\nmanuals, action READMEs, the Node API package overview, and fixture guides.\n\n## Homepage Content Contract\n\nThis README is also the homepage text source for `buildchain.libkungfu.dev`.\nWhen a site repository consumes the `@kungfu-tech/buildchain` npm package, it\nshould use the generated `dist/site/buildchain-site.json` homepage fields\ninstead of parsing this README or maintaining separate homepage copy.\n\nThe first screen should be derived from:\n\n- Page identity: the top-level heading.\n- Lead: the opening paragraph that defines Buildchain Release Passport.\n- Trust signal: the start of `Install and Verify`, especially passport-first\n  binary verification.\n- Use signal: the start of `Use Buildchain`, especially the reusable workflow\n  and action surfaces.\n\nThe package-owned site bundle exposes ordered `homepage.sections`,\n`homepage.displayPlan`, `homepage.rendererContract`, and a complete\n`pages` collection mirrored from `page-registry.json`. A site renderer may adapt\nlayout, navigation, typography, examples, and visual assets, but it should not\nmaintain separate wording for Buildchain's release mechanics, workflow surface,\noperation manuals, Node API overview, fixture guides, or release-passport trust\nmodel. Renderer-contract text is machine/implementation metadata, not ordinary\nhomepage content.\n\n## Local Verification\n\n```bash\ncorepack enable pnpm\npnpm install --frozen-lockfile\npnpm run generate:site\npnpm run check\nnpm pack --dry-run --json --registry=https://registry.npmjs.org/\n```\n\n## Read Next\n\n- [Install and verify](docs/install.md)\n- [Documentation map](docs/MAP.md)\n- [Product mechanism](docs/product-mechanism.md)\n- [Release Passport and binary distribution](docs/release-passport.md)\n- [GitHub governance authority](docs/github-governance-authority.md)\n- [GitHub-native Linux artifact attestation](docs/github-artifact-attestation.md)\n- [Binary distribution details](docs/binary-distribution.md)\n- [Toolkit observability](docs/toolkit-observability.md)\n- [Site bundle contract](docs/site-bundle-contract.md)\n- [Lifecycle protocol](docs/lifecycle-protocol.md)\n- [Reusable build surface](docs/reusable-build-surface.md)\n- [Shifu Gate profile orchestration](docs/shifu-gate-profiles.md)\n- [Release candidate passport](docs/release-candidate.md)\n- [Consumer issue reporting](docs/consumer-issue-reporting.md)\n- [Publish transaction](docs/publish-transaction.md)\n- [Release governance](docs/release-governance.md)",
+      "markdown": "# Buildchain\n\n<!-- buildchain:badges:start -->\n\n[![KFD-1: passed](https://buildchain.libkungfu.dev/badges/v1/kfd-1/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![KFD-2: passed](https://buildchain.libkungfu.dev/badges/v1/kfd-2/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![KFD-3: passed](https://buildchain.libkungfu.dev/badges/v1/kfd-3/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![KFD-4: declared](https://buildchain.libkungfu.dev/badges/v1/kfd-4/declared.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![Buildchain Release Passport: passed](https://buildchain.libkungfu.dev/badges/v1/buildchain-release-passport/passed.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-0969da.svg)](https://github.com/kungfu-systems/buildchain/blob/HEAD/LICENSE)\n[![Platform: macOS | Linux | Windows](https://img.shields.io/badge/platform-macOS%20%7C%20Linux%20%7C%20Windows-6e7781.svg)](https://github.com/kungfu-systems/buildchain/releases/latest/download/buildchain.release.json)\n[![Verify](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/verify.yml)\n[![Buildchain Ref Promotion](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/buildchain-ref-promotion.yml)\n[![Binary Distribution](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml/badge.svg)](https://github.com/kungfu-systems/buildchain/actions/workflows/binary-distribution.yml)\n<!-- buildchain:badges:end -->\n\nBuildchain Release Passport is a mature product release record for artifacts\nthat users or agents depend on.\n\nBuildchain by Kungfu uses GitHub as the execution and trust substrate: protected\nrefs, reviewed promotion PRs, exact tags, GitHub Releases, npm Trusted\nPublishing, and machine-readable evidence. Its job is to turn release intent\ninto an auditable product record, not to ask a repository to migrate away from\nits existing CI.\n\nThe same mechanism releases Buildchain itself.\n\n## Where Buildchain sits in the Agent Supply Chain\n\nBuildchain binds a product's declarations to the exact source cut, build,\nartifacts, checks, and promotion record that produced a release. In the wider\nAgent Supply Chain it sits between KFD-3 product discovery and KFD-2\npurpose-bound assessment:\n\n```text\nKFD-3 declaration -> Buildchain exact-artifact evidence -> KFD-2 assessment\n```\n\nBuildchain can prove that a declared claim and an exact artifact remain\nconsistent, or fail/downgrade when their evidence drifts. It does not invent\nthe product fact, decide whether a receiver should trust it for a purpose,\ncertify every platform, or prove external adoption. Receivers and downstream\nKFD-2 assessors retain the admission decision and residual risk.\n\nTo evaluate the layer, inspect a release's `buildchain.release.json` and\n`artifact-evidence.json`, verify them with the CLI, and report missing product\nor protocol evidence through the repository issue tracker.\n\n## Install and Verify\n\nFor v3, use the published npm package and verify the release passport before\ntrusting release evidence:\n\n```bash\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v3.0.0/buildchain.release.json\ncurl -LO https://github.com/kungfu-systems/buildchain/releases/download/v3.0.0/artifact-evidence.json\nnpx @kungfu-tech/buildchain@3.0.0 verify release-passport buildchain.release.json\nnpx @kungfu-tech/buildchain@3.0.0 version\n```\n\nThe v3.0.0 release publishes evidence assets but no standalone platform archives.\nThe names below describe the optional archive contract used by legacy release\nlines:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n- `checksums.txt`\n- `buildchain.release.json`\n- `artifact-evidence.json`\n- `product-mechanism.json`\n- `impact.json`\n- `agent-index.json`\n- `check-report.json`\n- `llms.txt`\n- `buildchain-release-bundle.tar.gz`\n- `buildchain-release-bundle.json`\n\nLoose top-level `buildchain` and `buildchain.exe` assets are intentionally not\npublished. The executable lives inside each platform archive, which prevents\nLinux and macOS artifacts from overwriting each other in a merged release lane.\n\nFor npm consumers:\n\n```bash\nnpm install -D @kungfu-tech/buildchain\nnpx buildchain version\nnpx buildchain doctor --json\n```\n\nThe npm package is also the Buildchain toolkit. Use the command when a workflow\nor shell step needs an executable; use the ESM APIs directly from JavaScript\nbuild scripts. JavaScript callers should import the package instead of spawning\nthe CLI or unpacking the standalone binary:\n\n```js\nimport {\n  createBuildchainLogger,\n  verifyBuildchainLogEvents,\n} from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n  path: \".buildchain/logs/native-build.jsonl\",\n  source: \"user\",\n  component: \"native-build\",\n});\n\nawait logger.span(\"native.compile\", { phase: \"build\" }, async () => {\n  await compileNativeTargets();\n});\n\nconst report = verifyBuildchainLogEvents({\n  path: logger.path,\n  requireEvents: [\"native.compile.start\", \"native.compile.end\"],\n});\n```\n\nThe package also ships `dist/site/` as the Buildchain-owned fact source for\n`buildchain.libkungfu.dev`.\n\nRepositories can also generate README status badges from Buildchain-owned facts\ninstead of hand-maintaining badge Markdown:\n\n```bash\nbuildchain badges bundle --check\nbuildchain badges bundle --write\nbuildchain badges readme --check\nbuildchain badges readme --write\n```\n\n## Project Governance\n\n- [`LICENSE-POLICY.md`](LICENSE-POLICY.md) explains the Apache-2.0 project\n  license, DCO-based contributions, and third-party notice boundary.\n- [`TRADEMARK.md`](TRADEMARK.md) explains official project marks and fork\n  identity boundaries.\n- [`ACCEPTABLE_USE.md`](ACCEPTABLE_USE.md) explains acceptable use of official\n  services and maintainer-operated infrastructure.\n- [`PROVIDER_COMPLIANCE.md`](PROVIDER_COMPLIANCE.md) explains the official\n  posture for GitHub, npm, cloud, credential, release evidence, and other\n  provider integrations.\n- [`SECURITY.md`](SECURITY.md) explains private vulnerability reporting.\n\nNative build consumers can import the diagnostics toolkit instead of copying\nrepository-local probes:\n\n```js\nimport {\n  collectBuildchainDiagnostics,\n  collectRunnerDiagnostics,\n  writeDiagnosticsArtifact,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n\nwriteDiagnosticsArtifact(\".buildchain/artifacts/diagnostics.json\", {\n  contract: \"consumer-build-diagnostics\",\n  buildchain: collectBuildchainDiagnostics({ cwd: process.cwd() }),\n  runner: collectRunnerDiagnostics(),\n});\n```\n\n`buildchain lifecycle run` writes a small `diagnostics.json` next to the\nplatform manifest. It includes lifecycle-wide observability, runner/tool/cache\nsnapshots, Git state, and links to the larger manifest and artifact outputs.\n\nConsumers can report Buildchain-owned workflow failures directly to the\nBuildchain repository with a scoped issue-write token:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v3\n  if: failure()\n  with:\n    token: ${{ steps.buildchain-issue-token.outputs.token }}\n    summary: \"Reusable build failed before artifact finalization\"\n    failure-code: reusable-build-failed\n    buildchain-ref: v3\n    diagnostics-path: .buildchain/artifacts/diagnostics.json\n```\n\nThe action deduplicates by fingerprint, comments on existing open reports, and\nis fail-soft by default so issue reporting does not hide the original failure.\nUse `report-kind: workflow-friction` when Buildchain workflows should report\ntheir own repeated release friction back to the Buildchain issue tracker.\n\n## Use Buildchain\n\nBootstrap a repository:\n\n```bash\nnpx @kungfu-tech/buildchain init --type package --package-manager pnpm\nnpx @kungfu-tech/buildchain validate --require-version-state\nnpx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v3/v3.0\n```\n\nBootstrap and inspect a governed paper repository through one interface:\n\n```bash\nnpx @kungfu-tech/buildchain paper scaffold \\\n  --package @kungfu-tech/paper-example \\\n  --repository kungfu-systems/paper-example\nnpx @kungfu-tech/buildchain paper preflight --offline\nnpx @kungfu-tech/buildchain paper status\n```\n\nThe paper surface is dry-run first. Add `--write` only to create missing\nscaffold files; external mutations such as npm bootstrap, Alpha PR creation,\nand release resumption require `--execute`. See\n[`docs/publication-artifacts.md`](docs/publication-artifacts.md) for the\nevidence-state model and operator flow.\n\nBuildchain supports package and non-package projects through\n`.buildchain/buildchain.toml`. Legacy root `buildchain.toml` files remain\nreadable, but new consumers should keep Buildchain-owned files under\n`.buildchain/`:\n\n```text\n.buildchain/buildchain.toml\n.buildchain/contract-lock.json\n.buildchain/kfd/kfd-3/surfaces.json\n.buildchain/release-passport/buildchain.release.json\n```\n\nLifecycle commands can call pnpm, npm, yarn, pip, Conan, CMake, Make, custom\nscripts, or any other command that can run in the repository checkout.\n\nThe KFD entrypoint is `buildchain kfd`. Buildchain provides concrete KFD-1\ncontract-world, KFD-2 trust-claim, and KFD-3 collaboration-surface workflows,\nplus fail-closed product-evidence gates for KFD-4, KFD-5, and KFD-7. These\ngates preserve product-owned qualification and support decisions; they do not\nturn a schema-valid record into certification or shipped support.\n\nBuildchain's action registry currently contains six active entries. Four are\ndirect consumer integration actions:\n\n- `actions/validate-config`\n- `actions/run-lifecycle`\n- `actions/promote-buildchain-ref`\n- `actions/report-buildchain-issue`\n\nTwo additional release-authority components are also registered and versioned:\n\n- `actions/github-artifact-attestation`\n- `actions/macos-credential-island`\n\n`dist/site/workflow-registry.json#actions` is the machine-readable inventory;\nthis split keeps the older four-action consumer list from being mistaken for\nthe complete current registry.\n\nThe active reusable workflow surfaces are:\n\n- `.github/workflows/.gate-profile.yml` for project-neutral Shifu Gate profile\n  planning, capability-aware runner dispatch, receipt validation, and one\n  stable aggregate check;\n- `.github/workflows/.auditable-demo.yml` for exact-artifact demo\n  qualification, transcript-bound renderer smoke, optional media rendering\n  from the exact passing Gate bundle, and opt-in content-addressed web-delivery\n  profiles with independently verified rendition roles;\n- `.github/workflows/.build.yml` for deterministic multi-platform build and\n  artifact contracts;\n- `.github/workflows/build.yml` for the single-config channel router that uses\n  `vN-alpha` during development/prerelease work and `vN` for stable releases;\n- `.github/workflows/release-candidate-promote.yml` for post-merge\n  promote-only publication from a PR-stage release candidate, without a second\n  heavy build;\n- `.github/workflows/.web-surface.yml` for preview, staging, production, and\n  cleanup plans for site/app repositories;\n- `.github/workflows/buildchain-ref-promotion.yml` for protected release\n  promotion and version-state transactions;\n- `.github/workflows/binary-distribution.yml` for Buildchain's own release\n  passport proof case.\n\nStable consumers should reference actions and workflows through floating major\nrefs after reviewing the exact release passport:\n\n```yaml\nuses: kungfu-systems/buildchain/actions/validate-config@v3\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/build.yml@v3\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v3\n```\n\n## Release Model\n\nBuildchain treats a reviewed branch merge as release intent:\n\n| Merge path                              | Meaning                                                | Exact tag        | Floating refs                                        |\n| --------------------------------------- | ------------------------------------------------------ | ---------------- | ---------------------------------------------------- |\n| `dev/vX/vX.Y -> alpha/vX/vX.Y`          | publish the next testable alpha for a minor line       | `vX.Y.Z-alpha.N` | `vX.Y-alpha`, `alpha/vX/vX.Y`, `dev/vX/vX.Y`         |\n| `alpha/vX/vX.Y -> release/vX/vX.Y`      | publish production for that minor line                 | `vX.Y.Z`         | `vX.Y`, usually `vX`, `release/vX/vX.Y`              |\n| `release/vX/vX.Y -> publish-gate/major` | publish the next major from a reviewed production line | `v(X+1).0.0`     | `v(X+1)`, `v(X+1).0`, new dev/alpha/release branches |\n\nExact tags are immutable. Floating channel tags and branches are machine-updated\nby Buildchain and must remain writable by the release authority.\n\nAfter a production release, Buildchain prepares the next alpha source commit for\nthe same minor line. That keeps production consumers pinned to the production\npassport while development can continue on the next testable patch.\n\n`publish-gate/major` is not an active development trunk. It is a reviewed\npromotion gate used when maintainers decide that the next production release\nshould open a new major line.\n\n## Toolkit Observability\n\nBuildchain includes a logging toolkit for release and build steps. Inside\nJavaScript build code, prefer the package API:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"conan\" });\nlogger.mark(\"conan.profile.ready\", { phase: \"configure\" });\nawait logger.span(\"conan.install\", { phase: \"dependencies\" }, runConanInstall);\n```\n\nIn workflows or shell scripts, use the equivalent CLI:\n\n```bash\nbuildchain mark --event native.configure --phase configure --component cmake\nbuildchain span --event native.build --phase build -- cmake --build build\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4\n```\n\nEvery event records a timestamp. `span` records duration. The API form can be\nimported from repository scripts so heavy builds can mark phases from inside\ntheir own code.\n\n## Site Fact Source\n\n`@kungfu-tech/buildchain` publishes `dist/site/`:\n\n- `buildchain-site.json`\n- `site-manifest.json`\n- `page-registry.json`\n- `cli-registry.json`\n- `workflow-registry.json`\n- `release-model.json`\n- `artifact-schemas.json`\n- `product-mechanism.json`\n- `release-provenance.json`\n- `agent-index.json`\n\n`buildchain.libkungfu.dev` should render from these package-owned facts, then\nlayer presentation around them. The site should not hand-write Buildchain's\ncurrent release mechanics. `page-registry.json` is the complete markdown page\nsource for the public site: README homepage content, all packaged `docs/*.md`\nmanuals, action READMEs, the Node API package overview, and fixture guides.\n\n## Homepage Content Contract\n\nThis README is also the homepage text source for `buildchain.libkungfu.dev`.\nWhen a site repository consumes the `@kungfu-tech/buildchain` npm package, it\nshould use the generated `dist/site/buildchain-site.json` homepage fields\ninstead of parsing this README or maintaining separate homepage copy.\n\nThe first screen should be derived from:\n\n- Page identity: the top-level heading.\n- Lead: the opening paragraph that defines Buildchain Release Passport.\n- Trust signal: the start of `Install and Verify`, especially passport-first\n  binary verification.\n- Use signal: the start of `Use Buildchain`, especially the reusable workflow\n  and action surfaces.\n\nThe package-owned site bundle exposes ordered `homepage.sections`,\n`homepage.displayPlan`, `homepage.rendererContract`, and a complete\n`pages` collection mirrored from `page-registry.json`. A site renderer may adapt\nlayout, navigation, typography, examples, and visual assets, but it should not\nmaintain separate wording for Buildchain's release mechanics, workflow surface,\noperation manuals, Node API overview, fixture guides, or release-passport trust\nmodel. Renderer-contract text is machine/implementation metadata, not ordinary\nhomepage content.\n\n## Local Verification\n\n```bash\ncorepack enable pnpm\npnpm install --frozen-lockfile\npnpm run generate:site\npnpm run check\nnpm pack --dry-run --json --registry=https://registry.npmjs.org/\n```\n\n## Read Next\n\n- [Install and verify](docs/install.md)\n- [Documentation map](docs/MAP.md)\n- [Product mechanism](docs/product-mechanism.md)\n- [Release Passport and binary distribution](docs/release-passport.md)\n- [GitHub governance authority](docs/github-governance-authority.md)\n- [GitHub-native Linux artifact attestation](docs/github-artifact-attestation.md)\n- [Binary distribution details](docs/binary-distribution.md)\n- [Toolkit observability](docs/toolkit-observability.md)\n- [Site bundle contract](docs/site-bundle-contract.md)\n- [Lifecycle protocol](docs/lifecycle-protocol.md)\n- [Reusable build surface](docs/reusable-build-surface.md)\n- [Shifu Gate profile orchestration](docs/shifu-gate-profiles.md)\n- [Release candidate passport](docs/release-candidate.md)\n- [Consumer issue reporting](docs/consumer-issue-reporting.md)\n- [Publish transaction](docs/publish-transaction.md)\n- [Release governance](docs/release-governance.md)",
       "slug": "home"
     },
     {
@@ -223,7 +223,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "actions/promote-buildchain-ref/README.md",
-      "digest": "sha256:c187834a712d2f940a35bc22cde55dc099e220aef66f07da9d98625f6a79fe7d",
+      "digest": "sha256:1f7790cb727eaafd95ba3697a0338c070821abeccf4aae9e7720c2fedcb93b7c",
       "headings": [
         {
           "level": 1,
@@ -241,7 +241,7 @@
           "anchor": "publish-transactions"
         }
       ],
-      "markdown": "# promote-buildchain-ref\n\nInternal buildchain action for promoting verified buildchain release-line and\ncompatibility refs from buildchain release channels:\n\n- `alpha/v2/v2.0` creates or reuses the next exact prerelease tag such as\n  `v2.0.1-alpha.0`, writes that version into package version state, points the\n  alpha and dev channel branches at the version commit, then promotes\n  `v2.0-alpha` and, when this is the highest published alpha minor, `v3-alpha`;\n- `release/v2/v2.0` creates or reuses the next exact release tag such as\n  `v2.0.0`, writes that version into package version state, points the release\n  channel branch and release tags at the release commit, then prepares a second\n  source commit for the next exact prerelease tag such as `v2.0.1-alpha.0` and\n  points the alpha/dev channel branches plus `v2.0-alpha` at that prerelease\n  commit, and moves `v3-alpha` only if no higher v2 minor has published an alpha;\n- `publish-gate/major` accepts a reviewed PR from a production release line such\n  as `release/v2/v2.0`, writes the next major production version such as\n  `v3.0.0`, points `publish-gate/major`, `release/v3/v3.0`, `v3.0`, and `v3`\n  at that release commit, then prepares `v3.0.1-alpha.0` for\n  `alpha/v3/v3.0`, `dev/v3/v3.0`, `v3.0-alpha`, and `v3-alpha`. The older `major-gate`\n  branch name is a compatibility alias only.\n\nThe release branch name defines the minor line. For example,\n`release/v2/v2.1` creates `v2.1.N`, promotes `v2.1`, and promotes `v2` only\nwhen the next minor tag such as `v2.2` does not already exist.\n\nThe action updates version state in `lerna.json`, root `package.json`, and\nworkspace package manifests discovered from package manager metadata\n(`package.json` workspaces, `lerna.json` packages, or `pnpm-workspace.yaml`).\nPackage manager detection is adaptive (`pnpm`, `npm`, or `yarn`) and is recorded\nin logs.\n\nRepositories can also provide `buildchain.toml` to declare version-state files\nand `lifecycle.verify`. TOML-configured version files take precedence over\npackage-manager discovery and can target JSON, TOML, or regex-based files. The\nversion commit itself is written through the GitHub Git Data API so the ref\ngraph is the durable source of truth. Repositories without any supported version\nstate degrade to ref-only promotion only when strict version state is disabled.\n\nJSON and TOML version entries whose declared key already matches the requested\nversion are treated as semantic no-ops. TOML changes use a parser-verified\nlossless key edit, so repository formatting is preserved and formatter-only\nrelease-preparation commits are not created. If a unique lossless edit cannot\nbe proven, promotion fails closed instead of rewriting the full TOML document.\n\n## Dry Run\n\nUse `dry-run: \"true\"` or the CLI `buildchain release --dry-run` before merging a\nchannel PR when you need to understand what Buildchain would do. This dry-run is\nat the Buildchain release-line level. It explains:\n\n- the legal source branch for the target channel;\n- exact release or alpha tags that would be created or reused;\n- floating tags and channel branches that would move;\n- version-state files and verification lifecycle that would apply;\n- branch protection, PR lineage, and release-from-alpha checks;\n- publish transaction behavior when `lifecycle.publish` or\n  `publish-transaction` is enabled.\n\nIt does not move refs, move tags, write package files, run publish commands, or\npublish npm packages. The GitHub action dry-run still calls GitHub APIs to\nresolve the current target SHA and concrete pending ref updates, but every\nwrite is reported as a dry-run update.\n\nRepositories whose package version is anchored to an explicitly selected\nupstream release can opt into manual next-anchor behavior:\n\n```toml\n[version]\nrequired = true\nstrategy = \"anchored\"\nnext = \"manual\"\nmanifest = \"libnode.release.json\"\n```\n\nIn this mode, the action validates the configured version files and anchor\nmanifest through the repository's verify lifecycle, but it does not rewrite the\npackage version to match the Buildchain release tag. After a production\nrelease, it sets `next-anchor-required=true` and does not auto-create the next\nalpha branch or tag. The repository must create the next upstream anchor line\nexplicitly, then run the normal channel promotion flow for that line.\n\nWhen branch protection requires pull requests, generated version-state commits\nstill run through promotion automation first. The action updates\nBuildchain-managed channel protection before generated bookkeeping, admits only\nthe exact `github-actions` App to the target-bound bypass allowlist, creates\nevery configured required check on the exact generated version-state commit, then\ntries to apply that commit directly. If GitHub still rejects release\nfinalization bookkeeping, Buildchain creates or reuses a same-repository\n`buildchain/version-state/*` PR based on the current target channel head and\nreturns `finalization-needed=true`; a later idempotent promotion run can resume\nfrom the durable transaction state. Strict alpha uses the same protected\nversion-state PR recovery for its target and dev bookkeeping, and does not move\ntags until those provider-enforced transactions land. Reusable wrapper callers\nshould allow `checks: write` so the generated checks are owned by GitHub Actions\nand match the managed branch protection rule.\n\nStable promotion also protects concurrent development work. The reusable\nwrapper checks out the exact current `dev/vN/vN.M` head as a reconciliation\nworkspace. If next-alpha bookkeeping cannot fast-forward that branch, the\naction reruns the declared version-state generation and verification from that\ndev tree, creates a two-parent reconciliation commit from the regenerated\nfiles, and fails closed if the checkout moved before the mutation boundary.\nThis prevents generated projections from an older release tree from replacing\ncapabilities that reached dev while the release was in progress.\n\nFor Buildchain-owned automation, callers may pass\n`branch-protection-bypass-apps: github-actions`. The action rejects every other\nApp slug and all user or team bypass actors. It configures managed\n`dev/vN/vN.M`, `alpha/vN/vN.M`, and `release/vN/vN.M` branches with one\nrequired approving review, Code Owner review, stale-review dismissal,\nlatest-push approval, exact App-bound GitHub Actions checks, admin enforcement,\nconversation resolution, no force pushes, and no deletions; the bypass\nallowance only lets the named automation identity apply generated version-state\nor channel bookkeeping without a second human review after the reviewed channel\nPR has already merged.\n\nGitHub may return either `403` or a deliberately opaque `404` when a\nnon-administrator token reads the full branch-protection endpoint. In that\ncase, promotion reads the provider's branch summary and accepts only an\nalready-protected branch that enforces the exact required check for everyone.\nIt does not interpret the opaque response as missing protection or try to\nrewrite policy with a developer token. The independent publication-authority\naudit remains responsible for the complete read-only governance proof.\n\n## Publish Transactions\n\nPromotion can also own external publish side effects. Enable this only from a\ntrusted channel workflow:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    generated-ref-update-token: ${{ github.token }}\n    sha: ${{ github.sha }}\n    target-ref: release/v2/v2.0\n    publish-transaction: \"true\"\n    publish-mode: publish-final-version\n    publish-auth: trusted-publishing\n    publish-required-artifacts-json: >-\n      [\n        {\"kind\":\"npm\",\"name\":\"@kungfu-tech/buildchain\",\"ref\":\"3.0.0\",\"digest\":\"sha256:...\"}\n      ]\n```\n\nFor anchored/manual package repositories that build through the reusable\nworkflow, keep the publish entrypoint on the `publish-gate/*` source-lock\ncontract:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    sha: ${{ needs.build.outputs.publish-source-sha }}\n    target-ref: release/v22/v22.22\n    require-publish-source-lock: \"true\"\n    publish-source-ref: ${{ needs.build.outputs.publish-source-ref }}\n    publish-source-sha: ${{ needs.build.outputs.publish-source-sha }}\n    publish-source-locked: ${{ needs.build.outputs.publish-source-locked }}\n    publish-transaction: \"true\"\n    publish-mode: publish-final-version\n    publish-auth: trusted-publishing\n```\n\n`target-ref` remains the channel promotion target that must point at `sha`.\n`publish-source-ref` is the reviewed source-lock branch that authorized this\nspecific package publication. Direct `alpha/*` or `release/*` channel refs are\nnot valid publish source locks when `require-publish-source-lock` is enabled,\nand a mismatched `publish-source-sha` fails before any promotion or publish side effects begin.\n\nConsumers that opt in to a product-owned final predicate set\n`require-publication-qualification: \"true\"` and pass the exact sealed\n`publication-capability-json`, complete `publication-gate-aggregate-json`, and\n`publication-qualification-receipt-json`. The action validates their canonical\ndigests, predicate identity, freshness, nonce, source, version, channel, target,\nand evidence bindings both before provider access and immediately before the\npublish transaction. Missing or drifted receipts fail before mutation. The\nreusable `release-candidate-promote.yml` workflow creates these values in a\nseparate credentialless consumer job; direct callers must preserve the same\ncontract and may pass previously consumed nonces through\n`publication-used-qualification-nonces-json`.\n\nThe reusable promote workflow serializes non-dry-run promotion intents per\nrepository and re-reads `target-ref` before checkout, dependency installation,\nrelease-candidate resolution, or publish-gate writes. If a queued intent asks\nfor an older SHA after the protected channel has advanced, the workflow records\nthe requested/current SHA pair, verifies that the current target is ahead of\nthe requested commit, and exits successfully as a superseded no-op. Diverged,\nbehind, or unreadable comparisons still fail closed.\nAfter queued-intent revalidation, the reusable workflow runs the canonical\nrelease-candidate resolver in metadata-only mode before installing candidate\ndependencies or starting the full promotion job. The full job resolves and\ndownloads the evidence again before any publish-gate or publication mutation.\nThis preserves the final exact-evidence trust check while making missing or\nstale PR-stage evidence fail early.\nThe action repeats that check at its mutation boundary for governed promotion\ncalls, closing the race between workflow preflight and action start. Direct\nnon-governed calls and dry-runs keep the strict target mismatch error so local\ndiagnostics cannot silently reinterpret a stale request.\nExpected manual dry-run failures remain visible in the workflow result and do\nnot create automated workflow-friction issues; issue reporting is reserved for\nnon-dry-run promotion failures.\nThe reusable build workflow performs the cheaper channel-ref preflight earlier:\nafter source-lock resolution and before the build matrix, it requires the target\nchannel ref such as `alpha/v22/v22.22` or `release/v22/v22.22` to already point\nat the locked `publish-source-sha`. If not, maintainers should merge the source\ncommit through the channel PR first.\n\nFor promote-only release candidates, attach the PR-stage reusable build evidence\nand fail before publish-gate side effects if it no longer matches:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    sha: ${{ needs.build.outputs.publish-source-sha }}\n    target-ref: alpha/v22/v22.22\n    promote-only-release-candidate: \"true\"\n    release-candidate-passport-path: .buildchain/artifacts/release-candidate-passport.json\n    release-candidate-build-summary-path: .buildchain/artifacts/build-summary.json\n```\n\nThe action validates repository, channel, source identity, platform matrix, and\nthe aggregate build-summary hash before it writes version state, opens\nrelease-state, runs publish transaction logic, or moves tags/branches. Source\nidentity accepts the exact source SHA, the PR merge ref SHA, or the promoted\nchannel HEAD's Git tree SHA matching the passport tree hash. If validation\nfails, run or attach the verified channel PR build first instead of promoting a\nstale or unproven artifact set.\n\nWhen enabled, the action creates or resumes a release transaction keyed by\nrepository, version, source SHA, and target ref. It persists that transaction to\na machine-managed branch under `buildchain/release-state/<version>`, with\n`state.json` and, once available, `evidence.json`. Fresh GitHub runners read\nthat durable ref before running publish, so reruns do not depend on a previous\nrunner's local `.buildchain` directory.\n\nConsumers whose publish lifecycle only assembles local release assets or\nPassport inputs may set `publish-rematerialize-on-resume: true`. After\nBuildchain restores and validates durable publish evidence, it replays that\nconsumer-owned lifecycle with the original transaction environment before\nPassport collection. This is explicit opt-in because registry publication and\nother provider mutations must not be replayed blindly; the option rejects\n`promote-existing-version`.\n\nThe action runs `lifecycle.publish` from `buildchain.toml` or the explicit\n`publish-command` input, then validates publish evidence before exact tags and\nfloating refs move. If durable state persistence fails, the action fails closed\nbefore publish or public ref finalization.\n\n`publish-mode` defaults to `publish-final-version`, the token-free path for\nnormal npm Trusted Publishing. Same-version alpha-to-latest recovery must be\ndeclared as `publish-mode: promote-existing-version` and\n`publish-auth: npm-token`; Buildchain runs `npm whoami` before it creates\nrelease-state or moves any `npm dist-tag`. The Trusted Publishing mode is not\nallowed to perform `npm dist-tag add`.\n\nBuildchain itself uses this path for npm. Its `lifecycle.publish` runs\n`node scripts/npm-publish-transaction.mjs`, which publishes\n`@kungfu-tech/buildchain` through npm Trusted Publishing and writes npm\nartifact evidence into the transaction before release refs move. The separate\n`.github/workflows/npm-publish.yml` workflow is dry-run only.\n\nPublish lifecycle environment:\n\n```text\nBUILDCHAIN_VERSION\nBUILDCHAIN_CHANNEL\nBUILDCHAIN_SOURCE_SHA\nBUILDCHAIN_TARGET_REF\nBUILDCHAIN_RELEASE_STATE\nBUILDCHAIN_EVIDENCE_DIR\nBUILDCHAIN_RELEASE_SHA\nBUILDCHAIN_RELEASE_MATERIAL_SHA\nBUILDCHAIN_PUBLISH_TOOLING_SHA\nBUILDCHAIN_PUBLISH_EVIDENCE\nBUILDCHAIN_REQUIRED_ARTIFACTS\n```\n\n`BUILDCHAIN_REQUIRED_ARTIFACTS` is the normalized requirement array after the\naction resolves a missing artifact `ref` to `BUILDCHAIN_VERSION`, or expands an\noptional `ref_template` containing exactly one `{version}`, and binds any\ndeclared provenance to the current release coordinate. Template expansion\nhappens after exact version selection; ambiguous or unsupported templates fail\nbefore `lifecycle.publish`. Requirement descriptors may omit `digest`; final\npublish evidence may not.\n\nThe action outputs `transaction-id`, `transaction-state`,\n`transaction-exact-tag`, `public-release-tag`, `transaction-release-sha`,\n`transaction-state-ref`, `transaction-state-sha`, `transaction-state-path`,\n`publish-evidence-path`, and `release-passport-path`, `release-passport-output-dir`,\n`release-passport-state-sha`, and `finalization-needed`.\n`transaction-state-ref` is the durable recovery location.\n`release-passport-state-sha` is the durable ref commit after the generated\n`release-passport/*` files have been uploaded into that recovery ref.\n`finalization-needed=true` means publish evidence is valid, but protected branch\nor ref finalization needs a later idempotent promotion run. For release\nfinalization, Buildchain may create a same-repository generated version-state\nPR when GitHub rejects the direct protected ref update; that PR is Buildchain\nbookkeeping, not a consumer-authored release change.\nSet `github-release: \"true\"` when the semver promotion should also publish the\npublic GitHub Release. After the release transaction reaches `complete` and\n`finalization-needed` is false, the action creates or updates the GitHub Release\nfor `public-release-tag`, applies deterministic metadata from the authoritative\npublication channel (`alpha` is a prerelease and never latest; `release`,\n`stable`, and `major` are stable and latest), and uploads the publish evidence\nfile plus generated release passport assets. Tag syntax remains the fallback for\nordinary callers that do not supply publication intent. For anchored/manual\npackage releases, `public-release-tag` is derived\nfrom the published package version, while `transaction-exact-tag` remains the\ninternal Buildchain transaction ref for recovery and audit. If the transaction is\nnot complete yet, the action defers GitHub Release publication to the next\nidempotent promotion run.\n\nAfter a publish transaction reaches `complete`, the action generates the unified\n`buildchain-release-passport` in `.buildchain/release-passport` by default and\npersists those files under `release-passport/` in the durable release-state ref.\nSet `release-passport-product-name` to record the consumer product name, for\nexample `Libnode`, instead of the default `Buildchain`.\nSet `release-passport-kfd-1-witness-jsons` to newline-separated KFD-1\ncontract-world witness JSON paths when released artifacts must prove\nbyte-for-byte KFD contract surfaces. Buildchain imports the KFD metadata from\n`@kungfu-tech/kfd`, freezes the witness, verifies artifact bytes, and writes the\nresult under the KFD-provided `kfd-1` passport section.\nSet `release-passport-kfd-2-claim-jsons` to newline-separated KFD-2 public\nrelease trust claim JSON paths when a release makes additional human/agent\nvisible claims. Buildchain requires each public claim to bind declared sources,\nmachine-readable evidence, hashes, artifact coordinates, verification results,\naudit boundary, responsibility state, and residual risk. Unbound claims fail\npassport verification; prose-only claims downgrade the KFD-2 audit.\nSet `release-passport-kfd-3-prebuild-witness-jsons` to newline-separated KFD-3\ncollaboration-interface pre-build witness paths, then provide artifact-side\nevidence with `release-passport-kfd-3-artifact-witness-jsons` or a\nproduct-owned `release-passport-kfd-3-artifact-verify-command` such as\n`kungfu agent verify --json`. Buildchain compares declared shipped public\nsurfaces with artifact-exposed public surfaces and writes the result under the\nKFD-provided `kfd-3` passport section.\nSet `release-passport-kfd-support-matrix-json` to the product-owned KFD-1..13\nsupport matrix and `release-passport-kfd-product-gate-jsons` to the\nnewline-separated KFD-4, KFD-5, and KFD-7 gate results. Buildchain verifies\ntheir exact source, freshness, KFD package revision, matrix barriers, and\ngate/matrix agreement, then writes the immutable `kfd-support.json` sibling and\nembeds the same projection in `buildchain.release.json`. This projection cannot\nself-qualify or widen candidate, unsupported, draft, or non-shipped states.\nSet `release-passport-invariant-passport-jsons` to one or more product-owned\ninvariant Passport paths, or set `release-passport-invariant-passport-command`\nto a command that emits one canonical Passport JSON document. Buildchain does\nnot reinterpret product invariants: it verifies the declared semantic root,\nrequires a `verified` verdict, complete platform coverage, a clean exact source\nrevision, and then binds the result into `buildchain.release.json`. Missing,\nstale, falsified, incomplete, dirty, or tampered Passport evidence fails the\nrelease transaction closed.\nBuildchain's own release workflow sets `release-passport-buildchain-self-kfd:\n\"true\"`. In that mode the action generates Buildchain-owned KFD-1/2/3 witnesses\ninside the final version-state workspace, after the release transaction has\nmaterialized generated files such as `package.json` and `dist/site/*`. This\nkeeps self-hosted KFD witness hashes bound to the exact published package\ninstead of to a pre-promotion checkout.\nSet `release-passport-github-artifact-attestation-policy-jsons` to one or more\nnewline-separated `buildchain.github-artifact-attestation-policy/v1` paths when\nthe Release Passport must require GitHub keyless provenance for Linux release\nartifacts. The higher-level v3 promotion workflow exposes the single-artifact\n`github-artifact-attestation-policy-json` input and owns staging, signing,\nprovider verification, immutable GitHub Release evidence upload, and read-back;\ndirect action callers own those post-Passport steps themselves.\nWhen present, the passport includes the aggregate build summary, platform\nartifact manifests, npm publish evidence, dist-tag promotion evidence, the\nrelease-state ref, trusted publishing metadata, and the Buildchain transaction\nresult. After the first passport upload, Buildchain backfills the durable\nrelease-state SHA into `buildchain.release.json` and persists the passport\nagain, so the consumer-side passport is a complete audit entrypoint. Set\n`release-passport: \"false\"` only for a controlled recovery run that must skip\npassport generation.\n\nFinalization recovery is anchored to the durable transaction, not to a single\nworkflow run SHA. After generated version-state bookkeeping is applied, the\ncurrent channel head can be the generated version-state commit or a historical\nmerge commit that contains or corresponds to the recorded `release_material_sha`;\nit does not have to equal the original `source_sha` or the transaction\n`release_sha`. Reruns accept exact tags that already point at the transaction\nrelease/material SHA or the finalized channel head, and continue moving any\nmissing floating tags or dev/alpha refs before marking the transaction\n`complete`.\n\nNormal reruns accept already-published artifacts only when evidence matches.\nMissing required artifacts can be published on the next run. Conflicting\nrefs, digests, or declared provenance put the transaction into\n`repair_required`; `abandoned` and\n`failed_permanently` also fail closed unless `publish-transaction-override` is\nset for a controlled repair. The same override may replace a stale transaction\nonly when its version, exact tag, target ref, and channel are unchanged, the\ntransaction is not complete, and it contains no published artifacts or\nevidence. This lets a newly admitted source retry a previously failed paper\npublication without weakening already-published facts.\n\nIn strict buildchain promotion, ref movement is also gated by the old ABV\ngovernance semantics:\n\n- when detailed target branch protection is readable, it must enforce\n  protection for administrators and require approving PR review plus the strict\n  `check` job from the `Verify` workflow; when GitHub withholds that\n  administration endpoint from the workflow token, the exact transaction must\n  instead prove a protected current head, same-repository merged PR,\n  independent approval, and the required successful `check` from its configured\n  GitHub App;\n- post-publish channel reconciliation reuses an already qualifying\n  provider-enforced policy when the workflow token cannot read or rewrite the\n  administrative protection document, and fails closed if the public branch\n  summary no longer carries the required check for everyone;\n- alpha promotion must come from a merged same-repository PR\n  `dev/vN/vN.M -> alpha/vN/vN.M`, or from a strict same-line\n  `publish-gate/alpha/vN/vN.M/<version> -> alpha/vN/vN.M` source-lock PR;\n- release promotion must come from a merged same-repository PR\n  `alpha/vN/vN.M -> release/vN/vN.M`, or from a strict same-line\n  `publish-gate/release/vN/vN.M/<version> -> release/vN/vN.M` source-lock PR;\n- major promotion must come from a merged same-repository PR\n  `release/vN/vN.M -> publish-gate/major`;\n- release promotion must have an exact alpha tag for the same patch line, and\n  the release source tree must match that alpha tag tree, so release does not\n  introduce new code after alpha;\n- anchored/manual release promotion may differ from that alpha tree only in\n  declared `version.files` and the configured anchor manifest, and only when the\n  checked-out release material has passed `lifecycle.verify` or the explicit\n  `verification-command`;\n- generated release and next-alpha version-state trees can be verified locally\n  with either the `verification-command` input or `buildchain.toml`\n  `lifecycle.verify` before any tags or channel refs move.\n\nThe reusable promotion workflow keeps governance reads, generated status checks,\nand generated ref updates on the run-scoped `github.token`. When branch\nprotection rejects generated bookkeeping, it supplies `BUILDCHAIN_PROMOTION_TOKEN`\nonly through `generated-pull-request-token` so the same-repository recovery PR can\nbe listed or created without broadening the governance client. Protected branch\nreview and check rules guard human channel merges, while the reusable build trust\ngate checks the source-lock channel HEAD and merged same-repository PR lineage\nbefore heavy build runners start. This action still independently rechecks PR\nlineage, alpha/release tree equivalence, and generated version-state verification\nbefore moving channel refs and tags.\nThe reusable `release-candidate-promote.yml` wrapper defaults\n`branch-protection-bypass-apps` to `github-actions`, so flow-internal promotion\ncan complete generated `dev`/`alpha`/`release` bookkeeping while ordinary human\npushes and PR merges remain governed by the one-review branch protection rule.\nThe promotion action rejects alternate App slugs and every user or team bypass,\nso the mutation path cannot widen the authority descriptor.\n\nThe tag names intentionally follow the old ABV release semantics:\nexact release tags are `vX.Y.Z`, exact alpha tags are `vX.Y.Z-alpha.N`, floating\nrelease tags are minor/major tags such as `v2.0` and `v2`, and floating alpha\ntags are minor-line tags such as `v2.0-alpha` plus cross-minor major tags such\nas `v3-alpha`. A major alpha tag only moves for the highest minor in that major\nwith a published alpha, so older-line maintenance cannot roll consumers back.\nBare tags such as `1.0.0` are not\nmaintained as buildchain release entrypoints.\n\nRepository rulesets should protect exact tags, not every `v*` tag. A ruleset\nsuch as `refs/tags/v*` also protects floating channel tags like `v2.0-alpha` and `v3-alpha`,\nwhich Buildchain must update after exact tags and publish evidence are durable.\nUse an exact-tag rule such as `refs/tags/v*.*.*` for immutable evidence tags and\nleave floating channel tags mutable for the promotion token."
+      "markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-ref-promotion-action\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-31\n  invisible_context: not asserted\n---\n\n# promote-buildchain-ref\n\nInternal buildchain action for promoting verified buildchain release-line and\ncompatibility refs from buildchain release channels:\n\n- `alpha/v3/v3.0` creates or reuses the next exact prerelease tag such as\n  `v3.0.3-alpha.0`, writes that version into package version state, points the\n  alpha and dev channel branches at the version commit, then promotes\n  `v3.0-alpha` and, when this is the highest published alpha minor, `v3-alpha`;\n- `release/v3/v3.0` creates or reuses the next exact release tag such as\n  `v3.0.2`, writes that version into package version state, points the release\n  channel branch and release tags at the release commit, then prepares a second\n  source commit for the next exact prerelease tag such as `v3.0.3-alpha.0` and\n  points the alpha/dev channel branches plus `v3.0-alpha` at that prerelease\n  commit, and moves `v3-alpha` only if no higher v3 minor has published an alpha;\n- `publish-gate/major` accepts a reviewed PR from a production release line such\n  as `release/v3/v3.0`, writes the next major production version such as\n  `v4.0.0`, points `publish-gate/major`, `release/v4/v4.0`, `v4.0`, and `v4`\n  at that release commit, then prepares `v4.0.1-alpha.0` for\n  `alpha/v4/v4.0`, `dev/v4/v4.0`, `v4.0-alpha`, and `v4-alpha`. The older `major-gate`\n  branch name is a compatibility alias only.\n\nThe release branch name defines the minor line. For example,\n`release/v3/v3.1` creates `v3.1.N`, promotes `v3.1`, and promotes `v3` only\nwhen the next minor tag such as `v3.2` does not already exist.\n\nThe action updates version state in `lerna.json`, root `package.json`, and\nworkspace package manifests discovered from package manager metadata\n(`package.json` workspaces, `lerna.json` packages, or `pnpm-workspace.yaml`).\nPackage manager detection is adaptive (`pnpm`, `npm`, or `yarn`) and is recorded\nin logs.\n\nRepositories can also provide `buildchain.toml` to declare version-state files\nand `lifecycle.verify`. TOML-configured version files take precedence over\npackage-manager discovery and can target JSON, TOML, or regex-based files. The\nversion commit itself is written through the GitHub Git Data API so the ref\ngraph is the durable source of truth. Repositories without any supported version\nstate degrade to ref-only promotion only when strict version state is disabled.\n\nJSON and TOML version entries whose declared key already matches the requested\nversion are treated as semantic no-ops. TOML changes use a parser-verified\nlossless key edit, so repository formatting is preserved and formatter-only\nrelease-preparation commits are not created. If a unique lossless edit cannot\nbe proven, promotion fails closed instead of rewriting the full TOML document.\n\n## Dry Run\n\nUse `dry-run: \"true\"` or the CLI `buildchain release --dry-run` before merging a\nchannel PR when you need to understand what Buildchain would do. This dry-run is\nat the Buildchain release-line level. It explains:\n\n- the legal source branch for the target channel;\n- exact release or alpha tags that would be created or reused;\n- floating tags and channel branches that would move;\n- version-state files and verification lifecycle that would apply;\n- branch protection, PR lineage, and release-from-alpha checks;\n- publish transaction behavior when `lifecycle.publish` or\n  `publish-transaction` is enabled.\n\nIt does not move refs, move tags, write package files, run publish commands, or\npublish npm packages. The GitHub action dry-run still calls GitHub APIs to\nresolve the current target SHA and concrete pending ref updates, but every\nwrite is reported as a dry-run update.\n\nRepositories whose package version is anchored to an explicitly selected\nupstream release can opt into manual next-anchor behavior:\n\n```toml\n[version]\nrequired = true\nstrategy = \"anchored\"\nnext = \"manual\"\nmanifest = \"libnode.release.json\"\n```\n\nIn this mode, the action validates the configured version files and anchor\nmanifest through the repository's verify lifecycle, but it does not rewrite the\npackage version to match the Buildchain release tag. After a production\nrelease, it sets `next-anchor-required=true` and does not auto-create the next\nalpha branch or tag. The repository must create the next upstream anchor line\nexplicitly, then run the normal channel promotion flow for that line.\n\nWhen branch protection requires pull requests, generated version-state commits\nstill run through promotion automation first. The action updates\nBuildchain-managed channel protection before generated bookkeeping, admits only\nthe exact `github-actions` App to the target-bound bypass allowlist, creates\nevery configured required check on the exact generated version-state commit, then\ntries to apply that commit directly. If GitHub still rejects release\nfinalization bookkeeping, Buildchain creates or reuses a same-repository\n`buildchain/version-state/*` PR based on the current target channel head and\nreturns `finalization-needed=true`; a later idempotent promotion run can resume\nfrom the durable transaction state. Strict alpha uses the same protected\nversion-state PR recovery for its target and dev bookkeeping, and does not move\ntags until those provider-enforced transactions land. Reusable wrapper callers\nshould allow `checks: write` so the generated checks are owned by GitHub Actions\nand match the managed branch protection rule.\n\nStable promotion also protects concurrent development work. The reusable\nwrapper checks out the exact current `dev/vN/vN.M` head as a reconciliation\nworkspace. If next-alpha bookkeeping cannot fast-forward that branch, the\naction reruns the declared version-state generation and verification from that\ndev tree, creates a two-parent reconciliation commit from the regenerated\nfiles, and fails closed if the checkout moved before the mutation boundary.\nThis prevents generated projections from an older release tree from replacing\ncapabilities that reached dev while the release was in progress.\n\nFor Buildchain-owned automation, callers may pass\n`branch-protection-bypass-apps: github-actions`. The action rejects every other\nApp slug and all user or team bypass actors. It configures managed\n`dev/vN/vN.M`, `alpha/vN/vN.M`, and `release/vN/vN.M` branches with one\nrequired approving review, Code Owner review, stale-review dismissal,\nlatest-push approval, exact App-bound GitHub Actions checks, admin enforcement,\nconversation resolution, no force pushes, and no deletions; the bypass\nallowance only lets the named automation identity apply generated version-state\nor channel bookkeeping without a second human review after the reviewed channel\nPR has already merged.\n\nGitHub may return either `403` or a deliberately opaque `404` when a\nnon-administrator token reads the full branch-protection endpoint. In that\ncase, promotion reads the provider's branch summary and accepts only an\nalready-protected branch that enforces the exact required check for everyone.\nIt does not interpret the opaque response as missing protection or try to\nrewrite policy with a developer token. The independent publication-authority\naudit remains responsible for the complete read-only governance proof.\n\n## Publish Transactions\n\nPromotion can also own external publish side effects. Enable this only from a\ntrusted channel workflow:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    generated-ref-update-token: ${{ github.token }}\n    sha: ${{ github.sha }}\n    target-ref: release/v3/v3.0\n    publish-transaction: \"true\"\n    publish-mode: publish-final-version\n    publish-auth: trusted-publishing\n    publish-required-artifacts-json: >-\n      [\n        {\"kind\":\"npm\",\"name\":\"@kungfu-tech/buildchain\",\"ref\":\"3.0.0\",\"digest\":\"sha256:...\"}\n      ]\n```\n\nFor anchored/manual package repositories that build through the reusable\nworkflow, keep the publish entrypoint on the `publish-gate/*` source-lock\ncontract:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    sha: ${{ needs.build.outputs.publish-source-sha }}\n    target-ref: release/v22/v22.22\n    require-publish-source-lock: \"true\"\n    publish-source-ref: ${{ needs.build.outputs.publish-source-ref }}\n    publish-source-sha: ${{ needs.build.outputs.publish-source-sha }}\n    publish-source-locked: ${{ needs.build.outputs.publish-source-locked }}\n    publish-transaction: \"true\"\n    publish-mode: publish-final-version\n    publish-auth: trusted-publishing\n```\n\n`target-ref` remains the channel promotion target that must point at `sha`.\n`publish-source-ref` is the reviewed source-lock branch that authorized this\nspecific package publication. Direct `alpha/*` or `release/*` channel refs are\nnot valid publish source locks when `require-publish-source-lock` is enabled,\nand a mismatched `publish-source-sha` fails before any promotion or publish side effects begin.\n\nConsumers that opt in to a product-owned final predicate set\n`require-publication-qualification: \"true\"` and pass the exact sealed\n`publication-capability-json`, complete `publication-gate-aggregate-json`, and\n`publication-qualification-receipt-json`. The action validates their canonical\ndigests, predicate identity, freshness, nonce, source, version, channel, target,\nand evidence bindings both before provider access and immediately before the\npublish transaction. Missing or drifted receipts fail before mutation. The\nreusable `release-candidate-promote.yml` workflow creates these values in a\nseparate credentialless consumer job; direct callers must preserve the same\ncontract and may pass previously consumed nonces through\n`publication-used-qualification-nonces-json`.\n\nThe reusable promote workflow serializes non-dry-run promotion intents per\nrepository and re-reads `target-ref` before checkout, dependency installation,\nrelease-candidate resolution, or publish-gate writes. If a queued intent asks\nfor an older SHA after the protected channel has advanced, the workflow records\nthe requested/current SHA pair, verifies that the current target is ahead of\nthe requested commit, and exits successfully as a superseded no-op. Diverged,\nbehind, or unreadable comparisons still fail closed.\nAfter queued-intent revalidation, the reusable workflow runs the canonical\nrelease-candidate resolver in metadata-only mode before installing candidate\ndependencies or starting the full promotion job. The full job resolves and\ndownloads the evidence again before any publish-gate or publication mutation.\nThis preserves the final exact-evidence trust check while making missing or\nstale PR-stage evidence fail early.\nThe action repeats that check at its mutation boundary for governed promotion\ncalls, closing the race between workflow preflight and action start. Direct\nnon-governed calls and dry-runs keep the strict target mismatch error so local\ndiagnostics cannot silently reinterpret a stale request.\nExpected manual dry-run failures remain visible in the workflow result and do\nnot create automated workflow-friction issues; issue reporting is reserved for\nnon-dry-run promotion failures.\nThe reusable build workflow performs the cheaper channel-ref preflight earlier:\nafter source-lock resolution and before the build matrix, it requires the target\nchannel ref such as `alpha/v22/v22.22` or `release/v22/v22.22` to already point\nat the locked `publish-source-sha`. If not, maintainers should merge the source\ncommit through the channel PR first.\n\nFor promote-only release candidates, attach the PR-stage reusable build evidence\nand fail before publish-gate side effects if it no longer matches:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    sha: ${{ needs.build.outputs.publish-source-sha }}\n    target-ref: alpha/v22/v22.22\n    promote-only-release-candidate: \"true\"\n    release-candidate-passport-path: .buildchain/artifacts/release-candidate-passport.json\n    release-candidate-build-summary-path: .buildchain/artifacts/build-summary.json\n    release-candidate-family-evidence-required: \"true\"\n    release-candidate-family-evidence-root: sha256:<initiative-family-root>\n    release-candidate-family-initiative-id: 2026-07-30-example-initiative\n    release-candidate-family-assignment-id: 2026-07-30-example-release\n```\n\nThe action validates repository, channel, source identity, platform matrix, and\nthe aggregate build-summary hash before it writes version state, opens\nrelease-state, runs publish transaction logic, or moves tags/branches. Source\nidentity accepts the exact source SHA, the PR merge ref SHA, or the promoted\nchannel HEAD's Git tree SHA matching the passport tree hash. If validation\nfails, run or attach the verified channel PR build first instead of promoting a\nstale or unproven artifact set.\n\nThe four family-evidence inputs are optional. When enabled, the action requires\nthe candidate passport to carry the exact\n`kungfu-buildchain-initiative-family-release-evidence/v1` envelope and checks\nits family root, Initiative id, and Assignment id before any promotion\nmutation. Buildchain only transports and validates this adapter-edge release\nevidence; Kungfu Work Control remains authoritative for native Family State v1\nand its additive v2 typed envelope.\n\nWhen enabled, the action creates or resumes a release transaction keyed by\nrepository, version, source SHA, and target ref. It persists that transaction to\na machine-managed branch under `buildchain/release-state/<version>`, with\n`state.json` and, once available, `evidence.json`. Fresh GitHub runners read\nthat durable ref before running publish, so reruns do not depend on a previous\nrunner's local `.buildchain` directory.\n\nConsumers whose publish lifecycle only assembles local release assets or\nPassport inputs may set `publish-rematerialize-on-resume: true`. After\nBuildchain restores and validates durable publish evidence, it replays that\nconsumer-owned lifecycle with the original transaction environment before\nPassport collection. This is explicit opt-in because registry publication and\nother provider mutations must not be replayed blindly; the option rejects\n`promote-existing-version`.\n\nBuild-once callers additionally pass `publish-sealed-bundle-root` and\n`publish-sealed-bundle-manifest`. The action verifies the typed manifest and\npersists every declared file below\n`sealed-bundle/<candidate-root>/files/` on the same durable ref before it starts\nthe publish command. A fresh runner can omit both inputs: the action restores\nthe exact binary bundle into `.buildchain/recovered-publication/<version>/`,\nre-verifies it, and exports the recovered npm tarball through\n`BUILDCHAIN_SEALED_NPM_TARBALL` with its exact integrity and SHA-256. This path\nnever repacks the npm tarball.\n\nThe action runs `lifecycle.publish` from `buildchain.toml` or the explicit\n`publish-command` input, then validates publish evidence before exact tags and\nfloating refs move. If durable state persistence fails, the action fails closed\nbefore publish or public ref finalization.\n\n`publish-mode` defaults to `publish-final-version`, the token-free path for\nnormal npm Trusted Publishing. Same-version alpha-to-latest recovery must be\ndeclared as `publish-mode: promote-existing-version` and\n`publish-auth: npm-token`; Buildchain runs `npm whoami` before it creates\nrelease-state or moves any `npm dist-tag`. The Trusted Publishing mode is not\nallowed to perform `npm dist-tag add`.\n\nBuildchain itself uses this path for npm. Its `lifecycle.publish` runs\n`node scripts/npm-publish-transaction.mjs`, which publishes\n`@kungfu-tech/buildchain` through npm Trusted Publishing and writes npm\nartifact evidence into the transaction before release refs move. The separate\n`.github/workflows/npm-publish.yml` workflow is dry-run only.\n\nPublish lifecycle environment:\n\n```text\nBUILDCHAIN_VERSION\nBUILDCHAIN_CHANNEL\nBUILDCHAIN_SOURCE_SHA\nBUILDCHAIN_TARGET_REF\nBUILDCHAIN_RELEASE_STATE\nBUILDCHAIN_EVIDENCE_DIR\nBUILDCHAIN_RELEASE_SHA\nBUILDCHAIN_RELEASE_MATERIAL_SHA\nBUILDCHAIN_PUBLISH_TOOLING_SHA\nBUILDCHAIN_PUBLISH_EVIDENCE\nBUILDCHAIN_SEALED_BUNDLE_ROOT\nBUILDCHAIN_SEALED_NPM_TARBALL\nBUILDCHAIN_SEALED_NPM_INTEGRITY\nBUILDCHAIN_SEALED_NPM_SHA256\nBUILDCHAIN_REQUIRED_ARTIFACTS\n```\n\n`BUILDCHAIN_REQUIRED_ARTIFACTS` is the normalized requirement array after the\naction resolves a missing artifact `ref` to `BUILDCHAIN_VERSION`, or expands an\noptional `ref_template` containing exactly one `{version}`, and binds any\ndeclared provenance to the current release coordinate. Template expansion\nhappens after exact version selection; ambiguous or unsupported templates fail\nbefore `lifecycle.publish`. Requirement descriptors may omit `digest`; final\npublish evidence may not.\n\nThe action outputs `transaction-id`, `transaction-state`,\n`transaction-publication-state`, `transaction-sealed-bundle-root`,\n`transaction-resume-command`,\n`transaction-exact-tag`, `public-release-tag`, `transaction-release-sha`,\n`transaction-state-ref`, `transaction-state-sha`, `transaction-state-path`,\n`publish-evidence-path`, and `release-passport-path`, `release-passport-output-dir`,\n`release-passport-state-sha`, and `finalization-needed`.\n`transaction-state-ref` is the durable recovery location.\n`transaction-publication-state` provides the stable\n`prepared`, `sealed`, `package-published`, `alpha-complete`, or\n`release-complete` operator view. `transaction-resume-command` is the exact\nconsumer-facing resume entrypoint bound into the sealed manifest.\n`release-passport-state-sha` is the durable ref commit after the generated\n`release-passport/*` files have been uploaded into that recovery ref.\n`finalization-needed=true` means publish evidence is valid, but protected branch\nor ref finalization needs a later idempotent promotion run. For release\nfinalization, Buildchain may create a same-repository generated version-state\nPR when GitHub rejects the direct protected ref update; that PR is Buildchain\nbookkeeping, not a consumer-authored release change.\nSet `github-release: \"true\"` when the semver promotion should also publish the\npublic GitHub Release. After the release transaction reaches `complete` and\n`finalization-needed` is false, the action creates or updates the GitHub Release\nfor `public-release-tag`, applies deterministic metadata from the authoritative\npublication channel (`alpha` is a prerelease and never latest; `release`,\n`stable`, and `major` are stable and latest), and uploads the publish evidence\nfile plus generated release passport assets. Tag syntax remains the fallback for\nordinary callers that do not supply publication intent. For anchored/manual\npackage releases, `public-release-tag` is derived\nfrom the published package version, while `transaction-exact-tag` remains the\ninternal Buildchain transaction ref for recovery and audit. If the transaction is\nnot complete yet, the action defers GitHub Release publication to the next\nidempotent promotion run. When sealed release assets are present, those restored\nfiles replace caller-supplied artifact paths. After upload succeeds, the action\nwrites the `github_release` milestone back to the durable transaction; an\ninterruption before that write is safe to retry because release creation and\nasset replacement are idempotent.\n\nAfter a publish transaction reaches `complete`, the action generates the unified\n`buildchain-release-passport` in `.buildchain/release-passport` by default and\npersists those files under `release-passport/` in the durable release-state ref.\nSet `release-passport-product-name` to record the consumer product name, for\nexample `Libnode`, instead of the default `Buildchain`.\nSet `release-passport-kfd-1-witness-jsons` to newline-separated KFD-1\ncontract-world witness JSON paths when released artifacts must prove\nbyte-for-byte KFD contract surfaces. Buildchain imports the KFD metadata from\n`@kungfu-tech/kfd`, freezes the witness, verifies artifact bytes, and writes the\nresult under the KFD-provided `kfd-1` passport section.\nSet `release-passport-kfd-2-claim-jsons` to newline-separated KFD-2 public\nrelease trust claim JSON paths when a release makes additional human/agent\nvisible claims. Buildchain requires each public claim to bind declared sources,\nmachine-readable evidence, hashes, artifact coordinates, verification results,\naudit boundary, responsibility state, and residual risk. Unbound claims fail\npassport verification; prose-only claims downgrade the KFD-2 audit.\nSet `release-passport-kfd-3-prebuild-witness-jsons` to newline-separated KFD-3\ncollaboration-interface pre-build witness paths, then provide artifact-side\nevidence with `release-passport-kfd-3-artifact-witness-jsons` or a\nproduct-owned `release-passport-kfd-3-artifact-verify-command` such as\n`kungfu agent verify --json`. Buildchain compares declared shipped public\nsurfaces with artifact-exposed public surfaces and writes the result under the\nKFD-provided `kfd-3` passport section.\nSet `release-passport-kfd-support-matrix-json` to the product-owned KFD-1..13\nsupport matrix and `release-passport-kfd-product-gate-jsons` to the\nnewline-separated KFD-4, KFD-5, and KFD-7 gate results. Buildchain verifies\ntheir exact source, freshness, KFD package revision, matrix barriers, and\ngate/matrix agreement, then writes the immutable `kfd-support.json` sibling and\nembeds the same projection in `buildchain.release.json`. This projection cannot\nself-qualify or widen candidate, unsupported, draft, or non-shipped states.\nSet `release-passport-invariant-passport-jsons` to one or more product-owned\ninvariant Passport paths, or set `release-passport-invariant-passport-command`\nto a command that emits one canonical Passport JSON document. Buildchain does\nnot reinterpret product invariants: it verifies the declared semantic root,\nrequires a `verified` verdict, complete platform coverage, a clean exact source\nrevision, and then binds the result into `buildchain.release.json`. Missing,\nstale, falsified, incomplete, dirty, or tampered Passport evidence fails the\nrelease transaction closed.\nSet `release-passport-evidence-jsons` to newline-separated product-owned release\nevidence attachment indexes. Each JSON document must declare `schemaVersion`, a\nstable `id`, a product contract, and the exact release source SHA, tag, and\nchannel. Buildchain copies and hashes the documents, verifies their coordinates\nagainst the final Passport, and retains them in the release evidence bundle\nwithout interpreting product-specific or legal claims.\n\nWhen release coordinates are not known until promotion, set\n`release-passport-attachment-command`. Buildchain supplies\n`BUILDCHAIN_RELEASE_SOURCE_SHA`, `BUILDCHAIN_RELEASE_TAG`,\n`BUILDCHAIN_RELEASE_CHANNEL`, `BUILDCHAIN_RELEASE_VERSION`,\n`BUILDCHAIN_RELEASE_DEPLOYMENT_COORDINATE`, `BUILDCHAIN_RELEASE_TARGET_REF`, and\n`BUILDCHAIN_RELEASE_PASSPORT_OUTPUT_DIR`; the command must emit a JSON array or\nan object with a non-empty `files` array. Direct Action callers may still use\nthe v2 alias `release-passport-evidence-command`. Reusable v3 workflows reserve\nthat older name for the distinct post-activation released-evidence command.\n\nBuildchain's own release workflow sets `release-passport-buildchain-self-kfd:\n\"true\"`. In that mode the action generates Buildchain-owned KFD-1/2/3 witnesses\ninside the final version-state workspace, after the release transaction has\nmaterialized generated files such as `package.json` and `dist/site/*`. This\nkeeps self-hosted KFD witness hashes bound to the exact published package\ninstead of to a pre-promotion checkout.\nSet `release-passport-github-artifact-attestation-policy-jsons` to one or more\nnewline-separated `buildchain.github-artifact-attestation-policy/v1` paths when\nthe Release Passport must require GitHub keyless provenance for Linux release\nartifacts. The higher-level v3 promotion workflow exposes the single-artifact\n`github-artifact-attestation-policy-json` input and owns staging, signing,\nprovider verification, immutable GitHub Release evidence upload, and read-back;\ndirect action callers own those post-Passport steps themselves.\nWhen present, the passport includes the aggregate build summary, platform\nartifact manifests, npm publish evidence, dist-tag promotion evidence, the\nrelease-state ref, trusted publishing metadata, and the Buildchain transaction\nresult. After the first passport upload, Buildchain backfills the durable\nrelease-state SHA into `buildchain.release.json` and persists the passport\nagain, so the consumer-side passport is a complete audit entrypoint. Set\n`release-passport: \"false\"` only for a controlled recovery run that must skip\npassport generation.\n\nFinalization recovery is anchored to the durable transaction, not to a single\nworkflow run SHA. After generated version-state bookkeeping is applied, the\ncurrent channel head can be the generated version-state commit or a historical\nmerge commit that contains or corresponds to the recorded `release_material_sha`;\nit does not have to equal the original `source_sha` or the transaction\n`release_sha`. Reruns accept exact tags that already point at the transaction\nrelease/material SHA or the finalized channel head, and continue moving any\nmissing floating tags or dev/alpha refs before marking the transaction\n`complete`.\n\nNormal reruns accept already-published artifacts only when evidence matches.\nMissing required artifacts can be published on the next run. Conflicting\nrefs, digests, or declared provenance put the transaction into\n`repair_required`; `abandoned` and\n`failed_permanently` also fail closed unless `publish-transaction-override` is\nset for a controlled repair. The same override may replace a stale transaction\nonly when its version, exact tag, target ref, and channel are unchanged, the\ntransaction is not complete, and it contains no published artifacts or\nevidence. This lets a newly admitted source retry a previously failed paper\npublication without weakening already-published facts.\n\nIn strict buildchain promotion, ref movement is also gated by the old ABV\ngovernance semantics:\n\n- when detailed target branch protection is readable, it must enforce\n  protection for administrators and require approving PR review plus the strict\n  `check` job from the `Verify` workflow; when GitHub withholds that\n  administration endpoint from the workflow token, the exact transaction must\n  instead prove a protected current head, same-repository merged PR,\n  independent approval, and the required successful `check` from its configured\n  GitHub App;\n- post-publish channel reconciliation reuses an already qualifying\n  provider-enforced policy when the workflow token cannot read or rewrite the\n  administrative protection document, and fails closed if the public branch\n  summary no longer carries the required check for everyone;\n- alpha promotion must come from a merged same-repository PR\n  `dev/vN/vN.M -> alpha/vN/vN.M`, or from a strict same-line\n  `publish-gate/alpha/vN/vN.M/<version> -> alpha/vN/vN.M` source-lock PR;\n- release promotion must come from a merged same-repository PR\n  `alpha/vN/vN.M -> release/vN/vN.M`, or from a strict same-line\n  `publish-gate/release/vN/vN.M/<version> -> release/vN/vN.M` source-lock PR;\n- major promotion must come from a merged same-repository PR\n  `release/vN/vN.M -> publish-gate/major`;\n- release promotion must have an exact alpha tag for the same patch line, and\n  the release source tree must match that alpha tag tree, so release does not\n  introduce new code after alpha;\n- anchored/manual release promotion may differ from that alpha tree only in\n  declared `version.files` and the configured anchor manifest, and only when the\n  checked-out release material has passed `lifecycle.verify` or the explicit\n  `verification-command`;\n- generated release and next-alpha version-state trees can be verified locally\n  with either the `verification-command` input or `buildchain.toml`\n  `lifecycle.verify` before any tags or channel refs move.\n\nThe reusable promotion workflow keeps governance reads, generated status checks,\nand generated ref updates on the run-scoped `github.token`. When branch\nprotection rejects generated bookkeeping, it supplies `BUILDCHAIN_PROMOTION_TOKEN`\nonly through `generated-pull-request-token` so the same-repository recovery PR can\nbe listed or created without broadening the governance client. Protected branch\nreview and check rules guard human channel merges, while the reusable build trust\ngate checks the source-lock channel HEAD and merged same-repository PR lineage\nbefore heavy build runners start. This action still independently rechecks PR\nlineage, alpha/release tree equivalence, and generated version-state verification\nbefore moving channel refs and tags.\nThe reusable `release-candidate-promote.yml` wrapper defaults\n`branch-protection-bypass-apps` to `github-actions`, so flow-internal promotion\ncan complete generated `dev`/`alpha`/`release` bookkeeping while ordinary human\npushes and PR merges remain governed by the one-review branch protection rule.\nThe promotion action rejects alternate App slugs and every user or team bypass,\nso the mutation path cannot widen the authority descriptor.\n\nThe tag names intentionally follow the old ABV release semantics:\nexact release tags are `vX.Y.Z`, exact alpha tags are `vX.Y.Z-alpha.N`, floating\nrelease tags are minor/major tags such as `v3.0` and `v3`, and floating alpha\ntags are minor-line tags such as `v3.0-alpha` plus cross-minor major tags such\nas `v3-alpha`. A major alpha tag only moves for the highest minor in that major\nwith a published alpha, so older-line maintenance cannot roll consumers back.\nBare tags such as `1.0.0` are not\nmaintained as buildchain release entrypoints.\n\nRepository rulesets should protect exact tags, not every `v*` tag. A ruleset\nsuch as `refs/tags/v*` also protects floating channel tags like `v3.0-alpha` and `v3-alpha`,\nwhich Buildchain must update after exact tags and publish evidence are durable.\nUse an exact-tag rule such as `refs/tags/v*.*.*` for immutable evidence tags and\nleave floating channel tags mutable for the promotion token."
     },
     {
       "id": "action:report-buildchain-issue",
@@ -255,7 +255,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "actions/report-buildchain-issue/README.md",
-      "digest": "sha256:8698d41afb3d884c09413ac7dd69035994273da2523cd08ada4d714fd66a8341",
+      "digest": "sha256:6c03ae2b3570ef2f3f8aa3dc42bfa05df3bb7639f85344ebe25f792d21b4276a",
       "headings": [
         {
           "level": 1,
@@ -263,7 +263,7 @@
           "anchor": "report-buildchain-issue"
         }
       ],
-      "markdown": "# report-buildchain-issue\n\nCreate or update a Buildchain repository issue from a consumer workflow or from\nBuildchain's own workflow-friction feedback loop.\n\nThis action is intended for consumer repositories that need to report\nBuildchain-owned failures with enough evidence for maintainers to act. It\nrequires a token that can write issues on the target Buildchain repository.\nFor cross-repository consumers, generate that token with a GitHub App\ninstallation token or another scoped credential owned by the consumer\norganization.\n\n```yaml\n- uses: actions/create-github-app-token@v2\n  id: buildchain-issue-token\n  with:\n    app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}\n    private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}\n    owner: kungfu-systems\n    repositories: buildchain\n\n- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v3\n  if: failure()\n  with:\n    token: ${{ steps.buildchain-issue-token.outputs.token }}\n    summary: \"Reusable build failed before artifact finalization\"\n    failure-code: reusable-build-failed\n    buildchain-ref: ${{ inputs.buildchain-ref || 'v2' }}\n    diagnostics-path: .buildchain/artifacts/diagnostics.json\n```\n\nThe action computes a stable fingerprint from the consumer repository,\nworkflow, job, failure code, and Buildchain ref. When an open issue already\nexists for that fingerprint, it comments with the new run instead of opening a\nduplicate issue.\n\nBy default issue reporting is fail-soft:\n\n- `fail-on-error: \"false\"` prevents a reporting outage from hiding the original\n  build failure.\n- transient GitHub API 429/5xx errors and connection failures are retried.\n- if a configured label is missing, issue creation is retried without labels.\n- if issue creation/commenting is still unavailable, the action writes the full\n  copyable issue title, fingerprint, and body into the workflow summary.\n- common token, private-key, password, and authorization values are redacted\n  before submission.\n\nUse `dry-run: \"true\"` to verify the computed fingerprint and body shape without\ncalling GitHub.\n\nFor Buildchain-owned workflow friction, use `report-kind: workflow-friction`.\nThis uses a separate marker and default labels so duplicate PRs, duplicate\nbuilds, transient API failures, stale release-state, or missing RC evidence can\nbe grouped without mixing with consumer failure reports:\n\n```yaml\npermissions:\n  issues: write\n\nsteps:\n  - uses: actions/create-github-app-token@v2\n    id: buildchain-issue-token\n    with:\n      app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}\n      private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}\n      owner: kungfu-systems\n      repositories: buildchain\n\n  - uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v3\n    if: failure()\n    with:\n      token: ${{ steps.buildchain-issue-token.outputs.token || secrets.BUILDCHAIN_ISSUE_TOKEN || secrets.BUILDCHAIN_PROMOTION_TOKEN || github.token }}\n      report-kind: workflow-friction\n      target-repository: kungfu-systems/buildchain\n      repository: ${{ github.repository }}\n      workflow: ${{ github.workflow }}\n      run-id: ${{ github.run_id }}\n      run-attempt: ${{ github.run_attempt }}\n      channel: alpha/v2/v2.4\n      source-sha: ${{ github.sha }}\n      friction-class: duplicate-build\n      related-runs-json: ${{ steps.classify.outputs.related-runs-json }}\n      heavy-builds-json: ${{ steps.classify.outputs.heavy-builds-json }}\n      comment-cooldown-hours: \"24\"\n```\n\n`comment-cooldown-hours` is optional. When it is greater than zero, Buildchain\nstill deduplicates by fingerprint but skips adding another comment if the\nexisting issue already received a recent update."
+      "markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-consumer-issue-action\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-31\n  invisible_context: not asserted\n---\n\n# report-buildchain-issue\n\nCreate or update a Buildchain repository issue from a consumer workflow or from\nBuildchain's own workflow-friction feedback loop.\n\nThis action is intended for consumer repositories that need to report\nBuildchain-owned failures with enough evidence for maintainers to act. It\nrequires a token that can write issues on the target Buildchain repository.\nFor cross-repository consumers, generate that token with a GitHub App\ninstallation token or another scoped credential owned by the consumer\norganization.\n\n```yaml\n- uses: actions/create-github-app-token@v2\n  id: buildchain-issue-token\n  with:\n    app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}\n    private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}\n    owner: kungfu-systems\n    repositories: buildchain\n\n- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v3\n  if: failure()\n  with:\n    token: ${{ steps.buildchain-issue-token.outputs.token }}\n    summary: \"Reusable build failed before artifact finalization\"\n    failure-code: reusable-build-failed\n    buildchain-ref: ${{ inputs.buildchain-ref || 'v3' }}\n    diagnostics-path: .buildchain/artifacts/diagnostics.json\n```\n\nThe action computes a stable fingerprint from the consumer repository,\nworkflow, job, failure code, and Buildchain ref. When an open issue already\nexists for that fingerprint, it comments with the new run instead of opening a\nduplicate issue.\n\nBy default issue reporting is fail-soft:\n\n- `fail-on-error: \"false\"` prevents a reporting outage from hiding the original\n  build failure.\n- transient GitHub API 429/5xx errors and connection failures are retried.\n- if a configured label is missing, issue creation is retried without labels.\n- if issue creation/commenting is still unavailable, the action writes the full\n  copyable issue title, fingerprint, and body into the workflow summary.\n- common token, private-key, password, and authorization values are redacted\n  before submission.\n\nUse `dry-run: \"true\"` to verify the computed fingerprint and body shape without\ncalling GitHub.\n\nFor Buildchain-owned workflow friction, use `report-kind: workflow-friction`.\nThis uses a separate marker and default labels so duplicate PRs, duplicate\nbuilds, transient API failures, stale release-state, or missing RC evidence can\nbe grouped without mixing with consumer failure reports:\n\n```yaml\npermissions:\n  issues: write\n\nsteps:\n  - uses: actions/create-github-app-token@v2\n    id: buildchain-issue-token\n    with:\n      app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}\n      private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}\n      owner: kungfu-systems\n      repositories: buildchain\n\n  - uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v3\n    if: failure()\n    with:\n      token: ${{ steps.buildchain-issue-token.outputs.token || secrets.BUILDCHAIN_ISSUE_TOKEN || secrets.BUILDCHAIN_PROMOTION_TOKEN || github.token }}\n      report-kind: workflow-friction\n      target-repository: kungfu-systems/buildchain\n      repository: ${{ github.repository }}\n      workflow: ${{ github.workflow }}\n      run-id: ${{ github.run_id }}\n      run-attempt: ${{ github.run_attempt }}\n      channel: alpha/v3/v3.0\n      source-sha: ${{ github.sha }}\n      friction-class: duplicate-build\n      related-runs-json: ${{ steps.classify.outputs.related-runs-json }}\n      heavy-builds-json: ${{ steps.classify.outputs.heavy-builds-json }}\n      comment-cooldown-hours: \"24\"\n```\n\n`comment-cooldown-hours` is optional. When it is greater than zero, Buildchain\nstill deduplicates by fingerprint but skips adding another comment if the\nexisting issue already received a recent update."
     },
     {
       "id": "action:run-lifecycle",
@@ -277,7 +277,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "actions/run-lifecycle/README.md",
-      "digest": "sha256:7aa1448e5e27ddacb0d13647a2169dae8ea4f9448da8ef6c39f070319a9f9ef5",
+      "digest": "sha256:6f0fa7439801d0557e59c6112235b2db0bd4439fcd1660a5cac14994be7c4314",
       "headings": [
         {
           "level": 1,
@@ -285,7 +285,7 @@
           "anchor": "run-lifecycle"
         }
       ],
-      "markdown": "# run-lifecycle\n\nRun a Buildchain lifecycle stage or an explicit command and write a deterministic\nartifact manifest.\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/run-lifecycle@v3\n  with:\n    stage: build\n    required: \"true\"\n    artifact-name: my-product-linux-x64-${{ github.sha }}\n    artifact-paths: |\n      dist\n      build/stage\n```\n\nWhen `command` is provided, it overrides `buildchain.toml` for that invocation.\nWhen `command` is empty, the action loads `buildchain.toml` and runs the named\nstage.\n\n`timeout-minutes` defaults to 120 and bounds either command source. A\nstage-specific `timeout_minutes` in `buildchain.toml` takes precedence. Timeout\nerrors identify the lifecycle stage and platform so a hung self-hosted build can\nbe diagnosed after the runner is released.\n\nThe action writes both a full manifest and a compact summary. It also exposes\nthe summary as outputs for reusable workflow callers:\n\n| Output | Meaning |\n| --- | --- |\n| `manifest-path` | Full manifest path |\n| `summary-path` | Compact summary path |\n| `artifact-name` | Resolved artifact name |\n| `artifact-file-count` | Number of manifest files |\n| `artifact-total-bytes` | Total manifest bytes |\n| `artifact-summary-json` | One-line JSON summary |\n| `expected-artifacts-ok` | `true` when expectations passed |\n\n`expected-artifacts-json` can require exact paths, file count bounds, and a\nminimum byte total:\n\n```yaml\nwith:\n  expected-artifacts-json: >-\n    {\"minFiles\":2,\"requiredPaths\":[\"dist/app.tar.gz\",\"dist/checksums.txt\"]}\n```\n\nFor long native builds, set `sample-process-tree: \"true\"` and pass\n`process-summary-path`. The action wraps either the explicit `command` or the\nconfigured lifecycle stage with `buildchain sample process-tree`, then embeds\nthe produced summary in the lifecycle diagnostics artifact:\n\n```yaml\nwith:\n  stage: build\n  sample-process-tree: \"true\"\n  process-summary-path: .buildchain/diagnostics/process-summary.json\n```\n\nCustom wrappers can still pass an existing sampler report or summary with\n`process-summary-path`; the action reads it after the lifecycle command\nfinishes, so commands may generate the file during the same invocation.\nSet `process-summary-required: \"false\"` when the summary is an optional sidecar,\nfor example when a reusable workflow may skip an optional build stage.\nThe diagnostics directory also includes `diagnostics-manifest.json`, a compact\ninventory of the diagnostics sidecars with byte counts and sha256 hashes."
+      "markdown": "# run-lifecycle\n\nRun a Buildchain lifecycle stage or an explicit command and write a deterministic\nartifact manifest.\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/run-lifecycle@v3\n  with:\n    stage: build\n    required: \"true\"\n    artifact-name: my-product-linux-x64-${{ github.sha }}\n    artifact-paths: |\n      dist\n      build/stage\n```\n\nWhen `command` is provided, it overrides `buildchain.toml` for that invocation.\nWhen `command` is empty, the action loads `buildchain.toml` and runs the named\nstage.\n\n`timeout-minutes` defaults to 120 and bounds either command source. A\nstage-specific `timeout_minutes` in `buildchain.toml` takes precedence. Timeout\nerrors identify the lifecycle stage and platform so a hung self-hosted build can\nbe diagnosed after the runner is released.\n\nThe action writes both a full manifest and a compact summary. It also exposes\nthe summary as outputs for reusable workflow callers:\n\nFor a `build` stage, paths selected by `[[signing.artifacts]]` for the current\n`platform-id` are automatically included in the lifecycle manifest even when\nthey sit outside `artifact-paths`. This binds every byte sent to the signing\nauthority without changing which ordinary product paths the caller uploads.\n\n| Output | Meaning |\n| --- | --- |\n| `manifest-path` | Full manifest path |\n| `summary-path` | Compact summary path |\n| `artifact-name` | Resolved artifact name |\n| `artifact-file-count` | Number of manifest files |\n| `artifact-total-bytes` | Total manifest bytes |\n| `artifact-summary-json` | One-line JSON summary |\n| `expected-artifacts-ok` | `true` when expectations passed |\n\n`expected-artifacts-json` can require exact paths, file count bounds, and a\nminimum byte total:\n\n```yaml\nwith:\n  expected-artifacts-json: >-\n    {\"minFiles\":2,\"requiredPaths\":[\"dist/app.tar.gz\",\"dist/checksums.txt\"]}\n```\n\nFor long native builds, set `sample-process-tree: \"true\"` and pass\n`process-summary-path`. The action wraps either the explicit `command` or the\nconfigured lifecycle stage with `buildchain sample process-tree`, then embeds\nthe produced summary in the lifecycle diagnostics artifact:\n\n```yaml\nwith:\n  stage: build\n  sample-process-tree: \"true\"\n  process-summary-path: .buildchain/diagnostics/process-summary.json\n```\n\nCustom wrappers can still pass an existing sampler report or summary with\n`process-summary-path`; the action reads it after the lifecycle command\nfinishes, so commands may generate the file during the same invocation.\nSet `process-summary-required: \"false\"` when the summary is an optional sidecar,\nfor example when a reusable workflow may skip an optional build stage.\nThe diagnostics directory also includes `diagnostics-manifest.json`, a compact\ninventory of the diagnostics sidecars with byte counts and sha256 hashes."
     },
     {
       "id": "action:validate-config",
@@ -299,7 +299,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "actions/validate-config/README.md",
-      "digest": "sha256:3f97259e5f4bc43cc48b4e134754a618daea92dfa5a8503767150ccafaf07309",
+      "digest": "sha256:ef48cd786973d9b6a1970c73ed780444415369075392f23404cdba5e1f988410",
       "headings": [
         {
           "level": 1,
@@ -312,7 +312,7 @@
           "anchor": "usage"
         }
       ],
-      "markdown": "# validate-config\n\nBuildchain v2 action for validating `buildchain.toml` without running lifecycle\ncommands.\n\nUse this action during repository migration when a heavyweight project needs to\nprove that its Buildchain version state and lifecycle declaration are ready, but\nthe actual build should not run yet.\n\n## Usage\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/validate-config@v3\n  with:\n    require-version-state: \"true\"\n    require-lifecycle-stages: \"install,build,verify\"\n```\n\nThe action checks:\n\n- `buildchain.toml` exists and uses schema `1`;\n- configured version-state files exist and expose a string version;\n- anchored/manual version strategy declarations and JSON/TOML anchor manifests\n  are structurally valid when configured;\n- web-surface project, channel, deploy adapter, retention, and staging security\n  declarations are structurally valid when configured;\n- required lifecycle stages are declared and structurally valid.\n\nIt does not execute `lifecycle.install`, `lifecycle.build`, `lifecycle.verify`,\nor any other lifecycle command.\n\nOutputs include `project-type`, `project-name`, `project-site`, `channels`, and\n`deploy-adapters-json`, so callers can route site workflows without reparsing\nTOML in every repository."
+      "markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-config-validation-action\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-31\n  invisible_context: not asserted\n---\n\n# validate-config\n\nBuildchain v3 action for validating `.buildchain/buildchain.toml` without running lifecycle\ncommands.\n\nUse this action during repository migration when a heavyweight project needs to\nprove that its Buildchain version state and lifecycle declaration are ready, but\nthe actual build should not run yet.\n\n## Usage\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/validate-config@v3\n  with:\n    require-version-state: \"true\"\n    require-lifecycle-stages: \"install,build,verify\"\n```\n\nThe action checks:\n\n- `buildchain.toml` exists and uses schema `1`;\n- configured version-state files exist and expose a string version;\n- anchored/manual version strategy declarations and JSON/TOML anchor manifests\n  are structurally valid when configured;\n- web-surface project, channel, deploy adapter, retention, and staging security\n  declarations are structurally valid when configured;\n- required lifecycle stages are declared and structurally valid.\n\nIt does not execute `lifecycle.install`, `lifecycle.build`, `lifecycle.verify`,\nor any other lifecycle command.\n\nOutputs include `project-type`, `project-name`, `project-site`, `channels`, and\n`deploy-adapters-json`, so callers can route site workflows without reparsing\nTOML in every repository."
     },
     {
       "id": "api:node-package",
@@ -326,7 +326,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "packages/core/README.md",
-      "digest": "sha256:e4d3ebb4933420d213a0d5c4141fbc93b3ff6680dbc8f9ff15786b6794d1d888",
+      "digest": "sha256:62c61aa59e2c0610bc6ca3fed0cfc67d09f5081fc39a70cc5e298d6bb08bf3c3",
       "headings": [
         {
           "level": 1,
@@ -339,7 +339,7 @@
           "anchor": "toolkit-imports"
         }
       ],
-      "markdown": "# Buildchain Core Package\n\nShared code lives here when workflow and action migration shows repeated logic\nthat is worth centralizing.\n\nCurrent shared surfaces:\n\n- `buildchain.toml` loading and normalization;\n- version-state file discovery and update helpers;\n- lifecycle stage normalization and execution;\n- config validation for release-package and `web-surface` projects.\n- toolkit observability logging through `@kungfu-tech/buildchain/logging`;\n- toolkit diagnostics and native profile collection through\n  `@kungfu-tech/buildchain/diagnostics`;\n- source/version/module/product build facts through\n  `@kungfu-tech/buildchain/build-facts`;\n- release passport creation and verification through\n  `@kungfu-tech/buildchain/release-passport`.\n- anchored/manual derived witness preflight and exact-tree evidence through\n  `@kungfu-tech/buildchain/anchored-version-material`.\n- sealed exact-root and KFD assessment inputs for KFX admission through\n  `@kungfu-tech/buildchain/artifact-verification-envelope`.\n- managed KFD / Release Passport badge bundle facts and README marker blocks\n  through `@kungfu-tech/buildchain/badges`.\n- publication artifact manifests, source bundles, and publication artifact\n  passports through `@kungfu-tech/buildchain/publication-artifact`.\n\n## Toolkit Imports\n\nThe npm package exports ESM APIs. JavaScript build scripts should import these\nAPIs directly instead of spawning the `buildchain` CLI:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"native\" });\nawait logger.span(\"native.package\", { phase: \"package\" }, packageArtifacts);\n```\n\nThe CLI remains the right surface for GitHub Actions steps, shell scripts, and\nnon-JavaScript build tools.\n\nDiagnostics consumers should import the published subpath and compare stable\ncontracts through the exported constants instead of hardcoding JSON contract\nnames:\n\n```js\nimport {\n  BUILDCHAIN_DIAGNOSTICS_CONTRACT,\n  BUILDCHAIN_DIAGNOSTICS_SUMMARY_CONTRACT,\n  collectRunnerDiagnostics,\n  summarizeDiagnosticsArtifacts,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n```\n\nCommonJS scripts can use dynamic imports for the same package surfaces:\n\n```js\nconst { createBuildchainLogger } = await import(\"@kungfu-tech/buildchain/logging\");\nconst { collectRunnerDiagnostics } = await import(\"@kungfu-tech/buildchain/diagnostics\");\n```\n\nBuild facts consumers can collect source-bound module/product facts before\npublishing and pass those facts into the release passport:\n\n```js\nimport { collectModuleBuildFacts, writeBuildFacts } from \"@kungfu-tech/buildchain/build-facts\";\n\nconst fact = collectModuleBuildFacts({ moduleId: \"native-core\" });\nwriteBuildFacts({ fact, output: \".buildchain/facts/native-core.json\" });\n```\n\nKFX producers can seal one passing artifact verification with exact roots,\nidentity, lifecycle, revocation, and an existing ADR-0052 assessment. Consumers\nverify or project the same envelope instead of reconstructing bindings:\n\n```js\nimport {\n  projectArtifactVerificationEnvelopeToKfx,\n  verifyArtifactVerificationEnvelope,\n} from \"@kungfu-tech/buildchain/artifact-verification-envelope\";\n```\n\nPublication repositories can produce site-consumable paper/report facts without\nbecoming web-surface repositories. When `[publication.archive]` is configured,\nthe same API also maintains the append-only publication registry used by site\nrepositories for latest and historical version pages. The preferred\n`latex-docker` toolchain records the pinned build-images LaTeX builder digest in\nthe publication artifact passport:\n\n```js\nimport { writePublicationArtifact } from \"@kungfu-tech/buildchain/publication-artifact\";\n\nwritePublicationArtifact({ sourceSha: process.env.GITHUB_SHA });\n```\n\nWeb-surface validation stays in core because both local scripts and GitHub\nActions need the same fail-closed interpretation of project, channel, deploy,\nretention, and staging security declarations.\n\nREADME badge consumers should import the public badge subpath and treat\nMarkdown as a projection of the returned facts:\n\n```js\nimport { collectBadgeBundleFacts, renderBadgeBundleBlock } from \"@kungfu-tech/buildchain/badges\";\n\nconst facts = await collectBadgeBundleFacts({ cwd: process.cwd() });\nconst markdown = renderBadgeBundleBlock(facts);\n```\n\nThe older `@kungfu-tech/buildchain/readme-badges` subpath remains available for\ncallers that need the full README badge surface instead of the default\nKFD-1 / KFD-2 / KFD-3 / Release Passport bundle.",
+      "markdown": "# Buildchain Core Package\n\nShared code lives here when workflow and action migration shows repeated logic\nthat is worth centralizing.\n\nCurrent shared surfaces:\n\n- `buildchain.toml` loading and normalization;\n- version-state file discovery and update helpers;\n- lifecycle stage normalization and execution;\n- config validation for release-package and `web-surface` projects.\n- toolkit observability logging through `@kungfu-tech/buildchain/logging`;\n- toolkit diagnostics and native profile collection through\n  `@kungfu-tech/buildchain/diagnostics`;\n- source/version/module/product build facts through\n  `@kungfu-tech/buildchain/build-facts`;\n- release passport creation and verification through\n  `@kungfu-tech/buildchain/release-passport`.\n- anchored/manual derived witness preflight and exact-tree evidence through\n  `@kungfu-tech/buildchain/anchored-version-material`.\n- sealed exact-root and KFD assessment inputs for KFX admission through\n  `@kungfu-tech/buildchain/artifact-verification-envelope`.\n- managed KFD / Release Passport badge bundle facts and README marker blocks\n  through `@kungfu-tech/buildchain/badges`.\n- publication artifact manifests, source bundles, and publication artifact\n  passports through `@kungfu-tech/buildchain/publication-artifact`.\n- two-clean-build byte reproducibility receipts through\n  `@kungfu-tech/buildchain/publication-reproducibility`.\n- build-once publication bundle manifests and exact-byte verification through\n  `@kungfu-tech/buildchain/publication-sealed-bundle`.\n- governed paper scaffold, preflight, status, npm bootstrap, build, Alpha, and\n  resume plans through `@kungfu-tech/buildchain/paper`.\n\n## Toolkit Imports\n\nThe npm package exports ESM APIs. JavaScript build scripts should import these\nAPIs directly instead of spawning the `buildchain` CLI:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"native\" });\nawait logger.span(\"native.package\", { phase: \"package\" }, packageArtifacts);\n```\n\nThe CLI remains the right surface for GitHub Actions steps, shell scripts, and\nnon-JavaScript build tools.\n\nDiagnostics consumers should import the published subpath and compare stable\ncontracts through the exported constants instead of hardcoding JSON contract\nnames:\n\n```js\nimport {\n  BUILDCHAIN_DIAGNOSTICS_CONTRACT,\n  BUILDCHAIN_DIAGNOSTICS_SUMMARY_CONTRACT,\n  collectRunnerDiagnostics,\n  summarizeDiagnosticsArtifacts,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n```\n\nCommonJS scripts can use dynamic imports for the same package surfaces:\n\n```js\nconst { createBuildchainLogger } =\n  await import(\"@kungfu-tech/buildchain/logging\");\nconst { collectRunnerDiagnostics } =\n  await import(\"@kungfu-tech/buildchain/diagnostics\");\n```\n\nBuild facts consumers can collect source-bound module/product facts before\npublishing and pass those facts into the release passport:\n\n```js\nimport {\n  collectModuleBuildFacts,\n  writeBuildFacts,\n} from \"@kungfu-tech/buildchain/build-facts\";\n\nconst fact = collectModuleBuildFacts({ moduleId: \"native-core\" });\nwriteBuildFacts({ fact, output: \".buildchain/facts/native-core.json\" });\n```\n\nKFX producers can seal one passing artifact verification with exact roots,\nidentity, lifecycle, revocation, and an existing ADR-0052 assessment. Consumers\nverify or project the same envelope instead of reconstructing bindings:\n\n```js\nimport {\n  projectArtifactVerificationEnvelopeToKfx,\n  verifyArtifactVerificationEnvelope,\n} from \"@kungfu-tech/buildchain/artifact-verification-envelope\";\n```\n\nPublication repositories can produce site-consumable paper/report facts without\nbecoming web-surface repositories. When `[publication.archive]` is configured,\nthe same API also maintains the append-only publication registry used by site\nrepositories for latest and historical version pages. The preferred\n`latex-docker` toolchain records the pinned build-images LaTeX builder digest in\nthe publication artifact passport:\n\n```js\nimport { writePublicationArtifact } from \"@kungfu-tech/buildchain/publication-artifact\";\n\nwritePublicationArtifact({ sourceSha: process.env.GITHUB_SHA });\n```\n\nBefore publication admission, prove the exact PDF, source bundle, manifests,\nand npm tarball twice from the same Git commit:\n\n```js\nimport { verifyPublicationReproducibility } from \"@kungfu-tech/buildchain/publication-reproducibility\";\n\nconst receipt = verifyPublicationReproducibility({\n  sourceSha: process.env.GITHUB_SHA,\n  promote: true,\n});\nif (!receipt.qualifying) throw new Error(\"publication is not reproducible\");\n```\n\nBind the promoted bytes into the durable build-once publication envelope:\n\n```js\nimport {\n  createPublicationSealedBundle,\n  verifyPublicationSealedBundle,\n} from \"@kungfu-tech/buildchain/publication-sealed-bundle\";\n```\n\nThe sealed manifest names the exact npm tarball and release assets. Promotion\npersists those binary files before registry publication and verifies them again\nwhen a fresh runner resumes.\n\nPaper automation can use the same typed contracts as the CLI:\n\n```js\nimport {\n  collectPaperPreflight,\n  collectPaperStatus,\n  planPaperMigration,\n  planPaperScaffold,\n  writePaperMigration,\n} from \"@kungfu-tech/buildchain/paper\";\n```\n\nPlanning and observation are side-effect free. `writePaperScaffold()` and\n`writePaperMigration()` perform the bounded local writes, while external\nmutations remain explicit CLI operations guarded by `--execute`.\n\nWeb-surface validation stays in core because both local scripts and GitHub\nActions need the same fail-closed interpretation of project, channel, deploy,\nretention, and staging security declarations.\n\nREADME badge consumers should import the public badge subpath and treat\nMarkdown as a projection of the returned facts:\n\n```js\nimport {\n  collectBadgeBundleFacts,\n  renderBadgeBundleBlock,\n} from \"@kungfu-tech/buildchain/badges\";\n\nconst facts = await collectBadgeBundleFacts({ cwd: process.cwd() });\nconst markdown = renderBadgeBundleBlock(facts);\n```\n\nThe older `@kungfu-tech/buildchain/readme-badges` subpath remains available for\ncallers that need the full README badge surface instead of the default\nKFD-1 / KFD-2 / KFD-3 / Release Passport bundle.",
       "slug": "node-package"
     },
     {
@@ -390,7 +390,7 @@
       ],
       "maturity": "preview",
       "sourcePath": "docs/auditable-demo.md",
-      "digest": "sha256:0e8cf2162c2e1f83cfe3a6171e3055f494cab5f03fdcbec3854e1793678e6908",
+      "digest": "sha256:4b3e529060ba54a439a86159a4dc0fc7fb43c8456a90e4b32579c86b20bc6bab",
       "headings": [
         {
           "level": 1,
@@ -428,7 +428,68 @@
           "anchor": "failure-evidence"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: 2026-07\ntheme: auditable-demo-pipeline\ndoc_type: technical-contract\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-07-28\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-25\n  invisible_context_boundary: No hidden model build, parameter count, or private corpus is asserted.\n---\n\n# Auditable Demo Pipeline\n\nBuildchain's auditable demo workflow turns an exact GitHub build artifact into\ntwo distinct evidence products:\n\n1. a required qualified Gate bundle; and\n2. an optional rendered media bundle that can exist only after that exact Gate\n   bundle passes.\n\nThe public reusable workflow is\n`.github/workflows/.auditable-demo.yml`. It is consumer-neutral: Buildchain\ndoes not know how a Kungfu, library, service, or application artifact should be\ninterpreted. The consumer owns a small checked-in executable adapter.\n\n## Authority Boundary\n\nThe retained build output is authoritative. The adapter reads that exact\nartifact and projects three files:\n\n```text\ncomplete-transcript.txt\npublic-projection.json\nscene.json\n```\n\nThe adapter must not rebuild or rerun the product. It receives:\n\n```text\n--artifact-root PATH\n--output PATH\n--source-coordinate PATH\n```\n\n`--source-coordinate` identifies the caller repository, run, artifact id,\nartifact name, upload digest, expiry, and exact source SHA. The workflow finds\nexactly one live artifact with the requested name in the current caller run and\nrejects a digest mismatch before invoking the adapter. Callers must pass the\ndigest emitted by their own `upload-artifact` step; a name resolved later from\nthe Actions API is discovery evidence, not a substitute for that producer\noutput.\n\nBuildchain's reusable build workflow exposes `artifact-coordinates-json` after\nall resolved platform uploads complete. That producer-owned output binds every\nplatform id to its same-run artifact id, name, upload digest, URL, and expiry,\nso a consumer that delegates its build to Buildchain can pass an exact\ncoordinate without rediscovering authority in a downstream job. The build\naggregate fails closed if any declared platform lacks one live, digest-bearing\nartifact coordinate. The compact coordinate set is sorted by platform id so\ndownstream machine consumers do not depend on matrix completion order.\n\nThe adapter runs with a disposable Home/XDG/npm prefix, a minimal environment,\nand no GitHub, npm, or cloud credential injection. It must be a regular,\nnon-symlink, executable file inside the exact checked-out consumer source.\n\n## Required Gate\n\nThe Gate:\n\n- checks out the exact consumer source and exact called-workflow SHA;\n- resolves and downloads one exact same-run GitHub Artifact;\n- invokes the checked-in adapter by argv, never as an evaluated shell string;\n- rejects undeclared adapter outputs, symlinks, invalid UTF-8, invalid scene or\n  projection schemas, out-of-range transcript references, and oversized input;\n- derives a one-second compatibility scene from the consumer projection;\n- anonymously pulls an immutable `image@sha256:digest` renderer;\n- runs it as non-root with `--network none`, a read-only root filesystem, and a\n  bounded tmpfs;\n- verifies the renderer manifest, media probe, exact input roots, exact output\n  member set, and complete checksums;\n- uploads a content-addressed qualified bundle plus an independent GitHub\n  Artifact id, URL, archive digest, and expiry-bearing source coordinate.\n\nThe Gate bundle contains the complete consumer transcript/projection/scene,\nsource artifact coordinate, adapter identity, bounded renderer evidence, a\npassed gate receipt, and checksums covering every member exactly once.\n\n## Selective Render\n\n`render-media: true` enables the second job. It downloads the just-uploaded Gate\nbundle by its content-addressed name, recomputes the Gate member root, verifies\nthe exact source SHA and renderer digest, and only then renders the complete\nqualified scene.\n\nThe media bundle contains MP4, WebM, GIF, poster, probe, renderer manifest,\nrenderer checksums, passed Gate receipt, a versioned media receipt, and\ndistribution checksums. A web-delivery profile also retains\n`media-inspection.json`, whose content root is bound into the receipt.\n`render-media: false` does not weaken or skip the Gate.\n\n## Media Qualification Profiles\n\nThe single machine-readable source is\n`contracts/auditable-demo-media-profiles-v1.json`. Callers select one reviewed\nprofile through `media-profile`; they cannot pass ffmpeg commands, codec flags,\nshell fragments, arbitrary profile paths, or transcoding instructions.\n\n| Profile | Meaning |\n| --- | --- |\n| `archive-v1` | Default compatibility contract. Retains the exact renderer outputs and classifies GIF as README compatibility evidence without making a browser-delivery claim. |\n| `web-delivery-v1` | Independently qualifies H.264 MP4 and VP9 WebM playback sources, forbids audio, requires exact scene dimensions and bounded duration/frame-rate drift, checks per-rendition byte ceilings, and proves MP4 `moov` precedes `mdat`. PNG remains the lossless evidence poster. |\n| `site-hero-v1` | Extends `web-delivery-v1` and additionally requires a qualified WebP browser poster. The current Build Images v1 renderer does not emit that member, so selecting this profile fails closed until the producer adds it. |\n\nFor web-delivery profiles, Buildchain runs its own fixed `ffprobe` invocation\ninside the same immutable, network-disabled renderer image. That command is\nBuildchain-controlled; the producer cannot inject flags. The resulting witness\nrecords exact roots and byte counts plus container, codec, pixel format,\ndimensions, duration, frame rate, audio stream count, and progressive-download\nevidence. Finalization re-hashes the retained bytes, rechecks the witness root,\nand parses MP4 top-level boxes itself. The producer's `media-probe.json.passed`\nfield remains supporting evidence, never sufficient authority.\n\nThe default `archive-v1` path preserves the existing v1 media receipt exactly.\nAn explicitly selected web-delivery profile emits a v2 media receipt with a\ncontent-addressed rendition list and explicit roles and MIME types. Agents and\nsite builds select `primary-video`,\n`alternate-video`, `browser-poster`, or evidence-only roles from that receipt;\nthey do not infer semantics from extensions or filenames. Additional responsive\nrenditions are accepted only when the immutable renderer manifest declares the\nbounded `build-images.auditable-demo-web-delivery/v1` role and MIME metadata and\nthe selected Buildchain profile supplies the byte ceiling; producer metadata\ncannot raise that ceiling. Unbound outputs,\nduplicate singleton roles, unknown profiles, or unsupported required versions\nfail closed.\n\nInitial byte ceilings are derived from the checked-in\n`auditable-demo-web-delivery-v1` fixture rendered by Build Images\n`v1.3.0-alpha.16` at its exact source SHA and image digest. GIF, MP4, WebM, and\nPNG ceilings are the next power of two above sixteen times the measured member\nbytes. The not-yet-produced WebP poster uses eight times the measured lossless\nPNG as its conservative proxy. The path-scoped qualification workflow\nregenerates the content-addressed evidence and fails on any byte or fact drift.\n\n## Consumer Example\n\nThe build job must expose both the exact artifact name and the digest returned\nby `upload-artifact`:\n\n```yaml\njobs:\n  build:\n    runs-on: ubuntu-24.04\n    outputs:\n      artifact-name: product-linux-${{ github.sha }}\n      artifact-digest: ${{ steps.upload.outputs.artifact-digest }}\n    steps:\n      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09\n      - run: ./scripts/build-product\n      - id: upload\n        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a\n        with:\n          name: product-linux-${{ github.sha }}\n          path: dist\n          if-no-files-found: error\n          retention-days: 14\n          compression-level: 0\n\n  auditable-demo:\n    needs: build\n    permissions:\n      actions: read\n      contents: read\n    uses: kungfu-systems/buildchain/.github/workflows/.auditable-demo.yml@BUILDCHAIN_EXACT_SHA\n    with:\n      source-ref: ${{ github.sha }}\n      source-artifact-name: ${{ needs.build.outputs.artifact-name }}\n      source-artifact-digest: ${{ needs.build.outputs.artifact-digest }}\n      adapter-path: scripts/auditable-demo-adapter\n      renderer-image: ghcr.io/kungfu-systems/build-images/demo-renderer@sha256:RENDERER_DIGEST\n      render-media: false\n      media-profile: archive-v1\n```\n\nReplace both placeholders with reviewed immutable SHAs or digests. An eligible\nbuild should always call the reusable workflow. Selection policy changes only\n`render-media`; it must never condition away the Gate job.\n\nUse `web-delivery-v1` only when the rendered bundle is intended to become a\nqualified web-delivery source. Use `site-hero-v1` when an optimized browser\nposter is also required. Profile qualification does not prove browser playback,\nresponsive layout, reduced-motion behavior, accessibility, or production\ndeployment; those remain site responsibilities.\n\n## Failure Evidence\n\nGate and render jobs use bounded timeouts and non-cancelling concurrency.\nDiagnostics artifacts are attempted with `always()` so adapter stdout/stderr\nand the resolved source coordinate remain available when qualification fails.\nNo production deployment, publication authority, token, or provider mutation\nis part of this workflow."
+      "markdown": "---\nstatus: draft\nperiod: 2026-07\ntheme: auditable-demo-pipeline\ndoc_type: technical-contract\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-31\n  invisible_context_boundary: No hidden model build, parameter count, or private corpus is asserted.\n---\n\n# Auditable Demo Pipeline\n\nBuildchain's auditable demo workflow turns an exact GitHub build artifact into\ntwo distinct evidence products:\n\n1. a required qualified Gate bundle; and\n2. an optional rendered media bundle that can exist only after that exact Gate\n   bundle passes.\n\nThe public reusable workflow is\n`.github/workflows/.auditable-demo.yml`. It is consumer-neutral: Buildchain\ndoes not know how a Kungfu, library, service, or application artifact should be\ninterpreted. The consumer owns a small checked-in executable adapter.\n\n## Authority Boundary\n\nThe retained build output is authoritative. The adapter reads that exact\nartifact and projects three files:\n\n```text\ncomplete-transcript.txt\npublic-projection.json\nscene.json\n```\n\nIt may additionally emit one declared `terminal-capture.json` using\n`kungfu.terminal-capture/v1`. The optional capture is bounded to 60 seconds,\nfixed 80-200 by 24-80 terminal cells, 10,000 events, and 4 MiB of canonical\nbase64 bytes. It must contain a passed completion sentinel and an explicitly\nempty authority-grant list. Existing three-file adapters remain valid.\n\nTerminal bytes are volatile observations, not Work, Warrant, capability, or\npublication authority. First-party or System identity, KFD compliance, Product\nSystem metadata, package metadata, scan output, registry history, and\nstandalone generation remain non-authoritative unless an exact higher-level\ncontract independently admits them.\n\nThe adapter must not rebuild or rerun the product. It receives:\n\n```text\n--artifact-root PATH\n--output PATH\n--source-coordinate PATH\n```\n\nConsumers with one shared adapter for several deterministic demos may also set\n`adapter-arguments-json` to a bounded JSON array. Buildchain parses the array,\nrejects malformed values, newlines, NUL bytes, more than 32 arguments, values\nlonger than 256 bytes, and attempts to override the three coordinate flags\nabove, then appends the accepted strings directly to the adapter argv. It never\nevaluates a shell command. The exact argument vector and its content root are\nretained in `adapter.json`; the Gate receipt binds that root. Adapter arguments\nselect consumer-owned capture behavior only and grant no authority.\n\n`--source-coordinate` identifies the caller repository, run, artifact id,\nartifact name, upload digest, expiry, and exact source SHA. The workflow finds\nexactly one live artifact with the requested name in the current caller run and\nrejects a digest mismatch before invoking the adapter. Callers must pass the\ndigest emitted by their own `upload-artifact` step; a name resolved later from\nthe Actions API is discovery evidence, not a substitute for that producer\noutput.\n\nBuildchain's reusable build workflow exposes `artifact-coordinates-json` after\nall resolved platform uploads complete. That producer-owned output binds every\nplatform id to its same-run artifact id, name, upload digest, URL, and expiry,\nso a consumer that delegates its build to Buildchain can pass an exact\ncoordinate without rediscovering authority in a downstream job. The build\naggregate fails closed if any declared platform lacks one live, digest-bearing\nartifact coordinate. The compact coordinate set is sorted by platform id so\ndownstream machine consumers do not depend on matrix completion order.\n\nThe adapter runs with a disposable Home/XDG/npm prefix, a minimal environment,\nand no GitHub, npm, or cloud credential injection. It must be a regular,\nnon-symlink, executable file inside the exact checked-out consumer source.\n\n## Required Gate\n\nThe Gate:\n\n- checks out the exact consumer source and exact called-workflow SHA;\n- resolves and downloads one exact same-run GitHub Artifact;\n- invokes the checked-in adapter by argv, never as an evaluated shell string;\n- rejects undeclared adapter outputs, symlinks, invalid UTF-8, invalid scene or\n  projection or terminal-capture schemas, implicit capture grants,\n  out-of-range transcript references, and oversized input;\n- derives a one-second compatibility scene from the consumer projection;\n- anonymously pulls an immutable `image@sha256:digest` renderer;\n- runs it as non-root with `--network none`, a read-only root filesystem, and a\n  bounded tmpfs;\n- verifies the renderer manifest, media probe, exact input roots, exact output\n  member set, and complete checksums;\n- uploads a content-addressed qualified bundle plus an independent GitHub\n  Artifact id, URL, archive digest, and expiry-bearing source coordinate.\n\nThe Gate bundle contains the complete consumer transcript/projection/scene,\nsource artifact coordinate, adapter identity, bounded renderer evidence, a\npassed gate receipt, and checksums covering every member exactly once.\n\n## Selective Render\n\n`render-media: true` enables the second job. It downloads the just-uploaded Gate\nbundle by its content-addressed name, recomputes the Gate member root, verifies\nthe exact source SHA and renderer digest, and only then renders the complete\nqualified scene.\n\nThe media bundle contains MP4, WebM, GIF, poster, probe, renderer manifest,\nrenderer checksums, passed Gate receipt, a versioned media receipt, and\ndistribution checksums. A web-delivery profile also retains\n`media-inspection.json`, whose content root is bound into the receipt.\n`render-media: false` does not weaken or skip the Gate.\n\nWhen the Gate bundle contains a qualified terminal capture, the render job\npasses it read-only to the immutable renderer. The renderer manifest binds the\ncapture root and terminal-state-machine version, but raw capture bytes remain\nin the Gate bundle rather than being copied into the public media bundle.\n\n## Media Qualification Profiles\n\nThe single machine-readable source is\n`contracts/auditable-demo-media-profiles-v1.json`. Callers select one reviewed\nprofile through `media-profile`; they cannot pass ffmpeg commands, codec flags,\nshell fragments, arbitrary profile paths, or transcoding instructions.\n\n| Profile | Meaning |\n| --- | --- |\n| `archive-v1` | Default compatibility contract. Retains the exact renderer outputs and classifies GIF as README compatibility evidence without making a browser-delivery claim. |\n| `web-delivery-v1` | Independently qualifies H.264 MP4 and VP9 WebM playback sources, forbids audio, requires exact scene dimensions and bounded duration/frame-rate drift, checks per-rendition byte ceilings, and proves MP4 `moov` precedes `mdat`. PNG remains the lossless evidence poster. |\n| `responsive-web-delivery-v1` | Extends `web-delivery-v1` with exact 1280x720 H.264 MP4 and VP9 WebM responsive sources plus a 1280x720 README GIF while keeping the primary MP4/WebM and evidence poster at the source scene dimensions. Every declared downscale must preserve the scene aspect ratio and may never upscale. |\n| `site-hero-v1` | Extends `web-delivery-v1` and additionally requires a qualified WebP browser poster. The current Build Images v1 renderer does not emit that member, so selecting this profile fails closed until the producer adds it. |\n\nFor web-delivery profiles, Buildchain runs its own fixed `ffprobe` invocation\ninside the same immutable, network-disabled renderer image. That command is\nBuildchain-controlled; the producer cannot inject flags. The resulting witness\nrecords exact roots and byte counts plus container, codec, pixel format,\ndimensions, duration, frame rate, audio stream count, and progressive-download\nevidence. Finalization re-hashes the retained bytes, rechecks the witness root,\nand parses MP4 top-level boxes itself. The producer's `media-probe.json.passed`\nfield remains supporting evidence, never sufficient authority.\n\nThe default `archive-v1` path preserves the existing v1 media receipt exactly.\nAn explicitly selected web-delivery profile emits a v2 media receipt with a\ncontent-addressed rendition list and explicit roles, MIME types, dimensions,\nand dimension policy. Agents and site builds select `primary-video`,\n`alternate-video`, `responsive-primary-video`,\n`responsive-alternate-video`, `browser-poster`, or evidence-only roles from\nthat receipt; they do not infer semantics from extensions or filenames.\nProfile-declared responsive renditions must match their exact dimensions,\nremain within the source scene, and preserve its aspect ratio. Additional\nproducer-declared renditions remain bounded by the selected profile and cannot\nraise their own byte ceiling. Unbound outputs, implicit upscales, aspect-ratio\ndrift, duplicate singleton roles, unknown profiles, or unsupported required\nversions fail closed.\n\nThe required Gate binds the exact selected media profile and the smoke media\nqualification root before optional full rendering starts. Gate-only validation\nand full rendering therefore exercise the same profile contract; a later media\njob cannot silently switch rendition authority.\n\nInitial byte ceilings are derived from the checked-in\n`auditable-demo-web-delivery-v1` fixture rendered by Build Images\n`v1.3.0-alpha.16` at its exact source SHA and image digest. GIF, MP4, WebM, and\nPNG ceilings are the next power of two above sixteen times the measured member\nbytes. The not-yet-produced WebP poster uses eight times the measured lossless\nPNG as its conservative proxy. The path-scoped qualification workflow\nregenerates the content-addressed evidence and fails on any byte or fact drift.\nIts matrix retains the original 1280x720 web-delivery baseline on the renderer\nthat produced it and separately measures the responsive profile against a\n1920x1080 fixture and the first exact renderer release that emits both\nsource-resolution and 720p renditions. This keeps historical budget evidence\nreproducible while giving the responsive contract its own immutable\nqualification root.\n\n## Consumer Example\n\nThe build job must expose both the exact artifact name and the digest returned\nby `upload-artifact`:\n\n```yaml\njobs:\n  build:\n    runs-on: ubuntu-24.04\n    outputs:\n      artifact-name: product-linux-${{ github.sha }}\n      artifact-digest: ${{ steps.upload.outputs.artifact-digest }}\n    steps:\n      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09\n      - run: ./scripts/build-product\n      - id: upload\n        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a\n        with:\n          name: product-linux-${{ github.sha }}\n          path: dist\n          if-no-files-found: error\n          retention-days: 14\n          compression-level: 0\n\n  auditable-demo:\n    needs: build\n    permissions:\n      actions: read\n      contents: read\n    uses: kungfu-systems/buildchain/.github/workflows/.auditable-demo.yml@BUILDCHAIN_EXACT_SHA\n    with:\n      source-ref: ${{ github.sha }}\n      source-artifact-name: ${{ needs.build.outputs.artifact-name }}\n      source-artifact-digest: ${{ needs.build.outputs.artifact-digest }}\n      adapter-path: scripts/auditable-demo-adapter\n      adapter-arguments-json: '[\"--demo-id\",\"agent-work-lab\"]'\n      renderer-image: ghcr.io/kungfu-systems/build-images/demo-renderer@sha256:RENDERER_DIGEST\n      render-media: false\n      media-profile: archive-v1\n```\n\nReplace both placeholders with reviewed immutable SHAs or digests. An eligible\nbuild should always call the reusable workflow. Selection policy changes only\n`render-media`; it must never condition away the Gate job.\n\nUse `web-delivery-v1` only when the rendered bundle is intended to become a\nqualified web-delivery source. Use `site-hero-v1` when an optimized browser\nposter is also required. Profile qualification does not prove browser playback,\nresponsive layout, reduced-motion behavior, accessibility, or production\ndeployment; those remain site responsibilities.\n\n## Failure Evidence\n\nGate and render jobs use bounded timeouts and non-cancelling concurrency.\nDiagnostics artifacts are attempted with `always()` so adapter stdout/stderr\nand the resolved source coordinate remain available when qualification fails.\nNo production deployment, publication authority, token, or provider mutation\nis part of this workflow."
+    },
+    {
+      "id": "manual:aws-us-elastic-runner-burst-plane",
+      "title": "AWS US elastic runner burst plane",
+      "route": "/docs/aws-us-elastic-runner-burst-plane",
+      "category": "manual",
+      "capabilityGroup": "getting-started",
+      "audience": [
+        "agent"
+      ],
+      "maturity": "stable",
+      "sourcePath": "docs/aws-us-elastic-runner-burst-plane.md",
+      "digest": "sha256:13e8e212499e7af51884cff37d644998d2e0795f8c1bc28ac6566c4ddd2885e8",
+      "headings": [
+        {
+          "level": 1,
+          "title": "AWS US elastic runner burst plane",
+          "anchor": "aws-us-elastic-runner-burst-plane"
+        },
+        {
+          "level": 2,
+          "title": "Phase 1 contract",
+          "anchor": "phase-1-contract"
+        },
+        {
+          "level": 2,
+          "title": "Cost and kill-switch envelope",
+          "anchor": "cost-and-kill-switch-envelope"
+        },
+        {
+          "level": 2,
+          "title": "Qualification evidence",
+          "anchor": "qualification-evidence"
+        },
+        {
+          "level": 3,
+          "title": "Phase 1 recorded outcome",
+          "anchor": "phase-1-recorded-outcome"
+        },
+        {
+          "level": 2,
+          "title": "Phase 2 contract",
+          "anchor": "phase-2-contract"
+        },
+        {
+          "level": 2,
+          "title": "Phase 3 contract",
+          "anchor": "phase-3-contract"
+        },
+        {
+          "level": 2,
+          "title": "Provider lifecycle",
+          "anchor": "provider-lifecycle"
+        },
+        {
+          "level": 2,
+          "title": "Source boundaries",
+          "anchor": "source-boundaries"
+        }
+      ],
+      "markdown": "---\nstatus: draft\nperiod: 2026-07-28\ntheme: aws-us-elastic-runner-burst-plane\ndoc_type: design\nsource_level: local-files-and-provider-docs\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-30\n---\n\n# AWS US elastic runner burst plane\n\nThe local runner fleet remains the normal Kungfu build plane. This AWS US plane\nis an explicit, temporary overflow mechanism with sequential qualification:\n\n1. Linux CodeBuild proof of concept under USD 50.\n2. Windows EC2 one-job JIT runners.\n3. One bounded 24-hour EC2 Mac campaign.\n\nNo later phase can start from design intent alone. The preceding phase must\nproduce a qualifying source-bound receipt, actual cost, and zero-resource\ncleanup proof.\n\n## Phase 1 contract\n\n`aws-us-codebuild-linux` is a Linux-only runner preset. It requires the exact\nCodeBuild project name and resolves the runner label at workflow evaluation\ntime:\n\n```text\ncodebuild-<project>-<github.run_id>-<github.run_attempt>\n```\n\nThe GitHub-hosted `trust-gate` remains ahead of the matrix job. A fork pull\nrequest therefore fails or skips before the CodeBuild `runs-on` label exists as\na queued job. The dedicated consumer workflow is manual-only and does not add\nthe preset to dev, alpha, release, signing, notarization, deployment, or\npublication workflows.\n\nThe CodeBuild project is:\n\n- repository-scoped through an AWS CodeConnections GitHub App;\n- one ephemeral runner and one GitHub job per CodeBuild build;\n- outside a VPC, with no idle VM, NAT gateway, public ingress, SSH, or persistent\n  workspace;\n- limited to two concurrent builds, 15 queued minutes, and 40 execution\n  minutes;\n- allowed to write only its dedicated CloudWatch log group and request a token\n  from its dedicated GitHub App connection;\n- forbidden from receiving signing, notarization, package publication, release,\n  deploy, static AWS, long-lived GitHub, or SSH credentials.\n\nThe AWS-managed Ubuntu 24.04 standard image is the immutable base. Before a\nnative lifecycle starts, Buildchain installs the distribution's `gcc-14` and\n`g++-14` packages, exposes only per-job `gcc`/`g++` aliases, and downloads the\npinned Kitware CMake 3.31.6 archive after verifying its reviewed SHA256. The\nresolved package manager, versions, and CMake source digest are retained as\n`aws-native-toolchain.json`; no toolchain state survives the ephemeral\nCodeBuild execution. The toolchain adapter also retains the reviewed Amazon\nLinux 2023 `gcc14` path for compatible projects.\n\n## Cost and kill-switch envelope\n\nThe 2026-07-28 AWS Price List entry for\n`BUILD_GENERAL1_XLARGE` Linux in `us-east-1` is USD 0.0798 per build minute.\nThe contract rounds that rate up to USD 0.08. Twelve fully timed-out accepted\nbuilds reserve at most USD 38.40. At project concurrency two, the fail-closed\ncontroller can see at most two over-cap builds. The envelope conservatively\ncharges both race builds for their complete 40-minute timeout rather than\nassuming fast EventBridge delivery. The bounded CodeBuild maximum is therefore\nUSD 44.80, below the dedicated USD 49 budget and leaving USD 4.20 for the small\ncontroller, state, notification, and log charges.\n\nThe controller stores an idempotent build-id ledger, an atomic accepted-build\ncounter, and worst-case reservation in DynamoDB. Duplicate EventBridge delivery\ndoes not consume the bounded build allowance. It deletes the CodeBuild webhook\nand stops the triggering build when:\n\n- the accepted-build or reserved-cost cap is reached;\n- actual-cost telemetry is missing or more than six hours old;\n- actual CodeBuild spend reaches the budget;\n- AWS Budgets sends the 80% or 95% actual-spend notification;\n- the kill switch was already set.\n\nThe stack starts fail closed: it has no cost telemetry item and CloudFormation\ndoes not create the webhook. Before arming the webhook, the operator must write\na current Cost Explorer observation to the `COST` item, clear only the dedicated\ncontroller's killed state, and create the exact workflow-filtered webhook.\nRe-arming after any kill is a separate provider mutation and requires a new\nexplicit approval.\n\n## Qualification evidence\n\nEach successful job uploads `aws-runner-burst.json`, binding:\n\n- consumer repository, exact source SHA and ref;\n- GitHub run id, attempt and job;\n- CodeBuild project, build id, build ARN and initiator;\n- observation timestamp and canonical digest.\n\nLinux qualification requires:\n\n- at least 10 trusted exact-source successful jobs;\n- observed concurrency of at least two;\n- p95 queue-to-start of at most five minutes;\n- actual incremental AWS spend below USD 49;\n- no idle build and no active cloud residue.\n\n`node scripts/aws-runner-burst.mjs verify-linux --input <snapshot.json>` fails\nclosed when cost telemetry is missing/stale or any acceptance predicate is\nfalse.\n\n### Phase 1 recorded outcome\n\nThe Linux phase passed on 2026-07-29. Ten trusted exact-source Kungfu jobs\ncompleted successfully, including four overlapping two-job waves. The observed\nCodeBuild queue-to-start p95 was 0.696 seconds. All 16 paid executions,\nincluding six diagnostic runs, produced a conservative incremental compute\nupper bound of USD 25.798 by rounding every execution up to a whole minute at\nthe live AWS Price List rate.\n\nThe global webhook kill switch was exercised after the tenth qualifying job.\nThe project then reported no webhook or in-progress build, and the card-owned\nEC2 inventory was empty. AWS Billing and Cost Explorer still reported an\nestimated zero during their provider ingestion delay; the retained\nexecution-derived upper bound is therefore the immediate cost proof and must be\nreconciled with the eventual AWS line item in the final campaign report.\n\nThe source-bound evidence and deterministic phase receipt are:\n\n- `evidence/aws-us-elastic-runner-burst-plane/linux-codebuild-qualification-input.json`\n- `evidence/aws-us-elastic-runner-burst-plane/linux-codebuild-qualification-receipt.json`\n\n## Phase 2 contract\n\nThe Windows phase uses the explicit `aws-us-ec2-windows-jit` runner preset.\nIts caller supplies one bounded label under\n`aws-us-ec2-windows-jit-<qualification-id>`, and Buildchain resolves exactly\none Windows x64 native lane. The reusable trust gate still runs on a\nGitHub-hosted runner before the JIT label can select EC2.\n\nThe provider creates repository-level GitHub JIT configuration for\n`kungfu-systems/kungfu`. Its `labels` request must contain all four scheduling\nlabels: `self-hosted`, `Windows`, `X64`, and the card-scoped\n`aws-us-ec2-windows-jit-<qualification-id>` label. GitHub's JIT endpoint does\nnot infer the default OS and architecture labels when they are omitted. The\nencoded configuration is never placed in EC2 user data, a tag, a command log,\nor an artifact. The operator writes it to a card-scoped SSM SecureString under\n`/kungfu/burst/windows/`; the instance role can read and delete only that\nprefix. Bootstrap reads the value once, deletes the parameter immediately, and\npasses it only to the pinned runner process.\n\nEach runner uses:\n\n- Amazon's current Windows Server 2025 Full Base AMI, resolved through the\n  public SSM AMI parameter and retained by exact AMI id and name;\n- `c7i.4xlarge`, one instance and one JIT runner per job;\n- GitHub Actions Runner 2.336.0 with the official Windows x64 SHA256;\n- PowerShell 7.6.4 with the official Windows x64 MSI SHA256 and Microsoft\n  Authenticode verification;\n- pinned PortableGit 2.55.0.3 with its GitHub release SHA256, exposing only its\n  `cmd` directory so POSIX compatibility tools cannot shadow Windows tools;\n- a Microsoft Authenticode-verified Visual Studio 2022 Build Tools bootstrap;\n- IMDSv2, an encrypted root volume with delete-on-termination, no inbound\n  security-group rule, no key pair, and no warm Auto Scaling capacity.\n\nRunner diagnostics and a redacted lifecycle record are uploaded to the\nprovider's encrypted, private evidence bucket. The runner process exits after\none job, Windows shuts down, and EC2's instance-initiated shutdown behavior is\nset to `terminate`. A five-minute reaper terminates card-owned stopped or\nthree-hour-old instances and deletes only their dedicated JIT parameter.\n\nAt the 2026-07-29 AWS Price List rate of USD 1.45 per Windows\n`c7i.4xlarge` hour, six accepted three-hour instances reserve USD 26.10. The\ntwo-instance race envelope reserves another USD 8.70, producing a USD 34.80\nworst case below the dedicated USD 40 budget. Budget notifications at 80% and\n95% invoke the same card-scoped global kill switch.\n\nQualification requires one runner-profile smoke, three trusted exact-source\nfull Windows jobs, independent cancellation and timeout cleanup exercises, and\nzero repository runner, EC2 instance, disposable volume, min capacity, and\ndesired capacity within 15 minutes of the final job.\n\n## Phase 3 contract\n\nThe macOS phase uses the explicit `aws-us-ec2-macos-jit` runner preset. Its\ncaller supplies one unique label under\n`aws-us-ec2-macos-jit-<qualification-id>`, and Buildchain resolves exactly one\nnative macOS ARM64 lane with `self-hosted`, `macOS`, `ARM64`, and the unique\ncampaign label. The reusable trust gate remains ahead of the JIT runner.\n\nUnlike Windows, the Mac campaign deliberately reuses one instance on one\n`mac2.metal` Dedicated Host. The operator allocates exactly one tagged host,\nlaunches exactly one tagged instance, and sends three sequential SSM bootstrap\ncommands. Each command consumes and immediately deletes a distinct repository\nJIT SecureString under `/kungfu/burst/macos/`, then runs GitHub Actions Runner\n2.336.0 for exactly one job. The runner archive is pinned to the official\nmacOS ARM64 SHA256. No GitHub, signing, notarization, publication, SSH, or\nstatic AWS credential is admitted to the instance.\n\nThe instance uses the exact retained Amazon EC2 macOS AMI, IMDSv2, an encrypted\ndelete-on-termination root volume, no inbound security-group rule, and the\nAMI's preinstalled SSM Agent and AWS CLI v2. The three accepted jobs must bind\nto the same host id, instance id, AMI id, source SHA, and campaign. At least one\njob must exercise the full native lifecycle.\n\nAWS imposes a 24-hour minimum Dedicated Host allocation. The contract therefore\nkeeps the one host for at least 24 hours even if all three jobs finish earlier.\nAt the recorded USD 0.6498 hourly rate, the minimum commitment rounds to USD\n15.60. A 30-hour fail-closed ceiling rounds to USD 19.49, below the dedicated\nUSD 25 budget. A ten-minute reaper terminates an expired campaign instance and\nretries host release after the minimum allocation and Apple scrub constraints\nallow it. Budget notifications at 80% and 95% invoke the same card-scoped kill\nswitch.\n\nQualification requires three trusted exact-source one-job JIT runs on the one\nhost, including at least one full run, plus proof that:\n\n- the instance terminated and the encrypted disposable volume disappeared;\n- Apple host scrub completed;\n- the Dedicated Host was released between 24 and 30 hours after allocation;\n- the repository has no registered campaign runner;\n- AWS has no active campaign instance or allocated campaign host;\n- actual incremental spend remained below USD 25.\n\n## Provider lifecycle\n\nThe three infrastructure templates live under\n`infra/aws-us-elastic-runner-burst-plane/`. Creating a change set is the review\nboundary. Executing it, completing the GitHub App connection, creating or\nre-arming a webhook, allocating or releasing a Dedicated Host, writing cost\ntelemetry, dispatching paid jobs, operating a kill switch, and deleting a stack\nare all explicit provider mutations.\n\nThe reviewed Phase 1 provider sequence is below. It deliberately separates\nconnection creation, change-set inspection, stack execution, cost observation,\nand webhook arming:\n\n```bash\nburst_profile=us\nburst_region=us-east-1\nburst_stack=kungfu-buildchain-linux-burst-poc\nburst_project=kungfu-buildchain-linux-burst-poc\nburst_connection_name=kungfu-linux-burst-poc\nburst_change_set=phase1-linux-codebuild-poc\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n  codeconnections create-connection \\\n  --provider-type GitHub \\\n  --connection-name \"$burst_connection_name\" \\\n  --tags Key=kungfu:owner,Value=buildchain \\\n    Key=kungfu:plane,Value=aws-us-elastic-runner-burst\n```\n\nThe returned connection is `PENDING` until an operator completes the GitHub App\nhandshake in AWS. Read back `ConnectionStatus=AVAILABLE` before creating the\nchange set. Do not put an OAuth token or GitHub token in the shell:\n\nAWS CodeConnections connection names are limited to 32 characters, so keep the\nshorter connection name even when the stack and project use the longer\nBuildchain-specific name.\n\n```bash\nburst_connection_arn=REPLACE_WITH_AVAILABLE_CONNECTION_ARN\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n  codeconnections get-connection \\\n  --connection-arn \"$burst_connection_arn\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n  cloudformation create-change-set \\\n  --stack-name \"$burst_stack\" \\\n  --change-set-name \"$burst_change_set\" \\\n  --change-set-type CREATE \\\n  --template-body \\\n    file://infra/aws-us-elastic-runner-burst-plane/codebuild-poc.template.yml \\\n  --capabilities CAPABILITY_IAM \\\n  --parameters \\\n    ParameterKey=GitHubConnectionArn,ParameterValue=\"$burst_connection_arn\" \\\n    ParameterKey=ProjectName,ParameterValue=\"$burst_project\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n  cloudformation wait change-set-create-complete \\\n  --stack-name \"$burst_stack\" \\\n  --change-set-name \"$burst_change_set\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n  cloudformation describe-change-set \\\n  --stack-name \"$burst_stack\" \\\n  --change-set-name \"$burst_change_set\"\n```\n\nOnly after the change-set resource list and IAM diff are accepted:\n\n```bash\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n  cloudformation execute-change-set \\\n  --stack-name \"$burst_stack\" \\\n  --change-set-name \"$burst_change_set\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n  cloudformation wait stack-create-complete \\\n  --stack-name \"$burst_stack\"\n```\n\nArming requires a fresh, operator-observed CodeBuild cost value. `COST` is the\nonly mutable telemetry item and `CONTROL` is the only state cleared:\n\n```bash\nburst_table=$(\n  aws --profile \"$burst_profile\" --region \"$burst_region\" \\\n    cloudformation describe-stacks \\\n    --stack-name \"$burst_stack\" \\\n    --query \"Stacks[0].Outputs[?OutputKey=='StateTable'].OutputValue\" \\\n    --output text\n)\nburst_observed_at=$(date -u +%s)\nburst_actual_usd=REPLACE_WITH_CURRENT_CODEBUILD_ACTUAL_USD\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n  dynamodb put-item \\\n  --table-name \"$burst_table\" \\\n  --item \"{\\\"pk\\\":{\\\"S\\\":\\\"COST\\\"},\\\"actual_usd\\\":{\\\"N\\\":\\\"$burst_actual_usd\\\"},\\\"observed_at\\\":{\\\"N\\\":\\\"$burst_observed_at\\\"}}\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n  dynamodb delete-item \\\n  --table-name \"$burst_table\" \\\n  --key '{\"pk\":{\"S\":\"CONTROL\"}}'\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n  codebuild create-webhook \\\n  --project-name \"$burst_project\" \\\n  --filter-groups \\\n    '[[{\"type\":\"EVENT\",\"pattern\":\"WORKFLOW_JOB_QUEUED\"},{\"type\":\"WORKFLOW_NAME\",\"pattern\":\"^AWS US Linux Burst Qualification$\"}]]'\n```\n\nThe immediate global kill is idempotent and targets only the dedicated project:\n\n```bash\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n  codebuild delete-webhook \\\n  --project-name \"$burst_project\"\n```\n\nAfter preserving the qualification evidence and proving no build is in\nprogress, rollback removes only the card-owned stack and connection:\n\n```bash\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n  cloudformation delete-stack \\\n  --stack-name \"$burst_stack\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n  cloudformation wait stack-delete-complete \\\n  --stack-name \"$burst_stack\"\n\naws --profile \"$burst_profile\" --region \"$burst_region\" \\\n  codeconnections delete-connection \\\n  --connection-arn \"$burst_connection_arn\"\n```\n\nPhase cleanup evidence must include:\n\n- CodeBuild batch/list results showing no in-progress build;\n- controller state and accepted-build ledger;\n- CodeBuild actual cost observation and its timestamp;\n- no EC2 instance, volume, launch template, Auto Scaling group, or dedicated\n  host created by this phase;\n- the CodeBuild webhook deleted or the whole stack deleted.\n\n## Source boundaries\n\nThe design follows the current AWS CodeBuild GitHub Actions runner contract:\n`WORKFLOW_JOB_QUEUED` starts an ephemeral runner, the run id maps cancellation,\nand the build terminates after one job. It uses the current GitHub guidance to\nprefer ephemeral autoscaled self-hosted runners and to retain runner logs\nexternally. Provider documentation and the live AWS Price List query are the\nauthoritative external sources; this document is an auditable cache."
     },
     {
       "id": "manual:binary-distribution",
@@ -536,7 +597,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/cli.md",
-      "digest": "sha256:49da688f9f8b726a9169a3e4b246cb6ef07c6c626ea15c22f0b26ba1a37a58b4",
+      "digest": "sha256:60c6b00e0dbf60f0b7ba8c3c549027925d94a6bdf8a2af3f8e35d24ef1dd50ba",
       "headings": [
         {
           "level": 1,
@@ -558,13 +619,18 @@
           "title": "Commands",
           "anchor": "commands"
         },
+        {
+          "level": 3,
+          "title": "Governed paper lifecycle",
+          "anchor": "governed-paper-lifecycle"
+        },
         {
           "level": 2,
           "title": "npm Publish Gate",
           "anchor": "npm-publish-gate"
         }
       ],
-      "markdown": "# Buildchain CLI, npm Package, and Toolkit API\n\nBuildchain is published as the public npm package\n`@kungfu-tech/buildchain`. The package contains the `buildchain` command,\nthe importable ESM toolkit APIs, and the local scripts needed to initialize and\nvalidate repositories before they use the reusable GitHub workflow surface.\n\nThe npm package is not the release authority. Release authority still comes\nfrom the protected Buildchain branch and tag state machine. npm publishing is a\nside effect of an exact release tag that has already been produced by that\nstate machine.\n\n## Install and Run\n\nUse the published package directly:\n\n```bash\nnpx @kungfu-tech/buildchain --help\nnpx @kungfu-tech/buildchain init --type package\nnpx @kungfu-tech/buildchain validate --require-version-state\n```\n\nOr install it in a repository:\n\n```bash\npnpm add -D @kungfu-tech/buildchain\npnpm exec buildchain validate\n```\n\nConsumers should pin the exact Buildchain version that was validated in their\nrepository. When dogfooding a fresh Buildchain release immediately after it is\npublished, pnpm may block the install through a minimum release-age policy. In\nthat case, add a temporary package/version-specific `minimumReleaseAgeExclude`\nentry, such as `@kungfu-tech/buildchain@3.0.0`, and remove it once the package\nhas aged past the normal policy window. Do not replace that with a broad\nregistry or scope-wide exclude.\n\nUse the package API directly inside JavaScript build scripts:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"build\" });\nawait logger.span(\"build.native\", { phase: \"build\" }, async () => {\n  await buildNativeArtifacts();\n});\n```\n\nThe standalone binary and CLI are for workflow steps, shell scripts, and\nnon-JavaScript environments. JavaScript code that already depends on\n`@kungfu-tech/buildchain` should import the toolkit API instead of spawning\n`npx buildchain` or a downloaded binary.\n\n## Node API and Package Exports\n\nBuildchain's public Node API is the package `exports` surface, not arbitrary\ninternal file paths. The npm package also ships\n`dist/site/node-api-registry.json` and exports it as\n`@kungfu-tech/buildchain/site/node-api-registry.json` so agents can enumerate\nthe supported imports from the installed package.\nFor navigation, start with `dist/site/capability-registry.json`: it groups\nmanuals, CLI commands, workflow/action inputs, Node exports, site pages, and KFD\nclaim facts by product capability before an agent chooses a concrete command or\nmanual.\n\nCurrent public import families include:\n\n```js\nimport * as buildchain from \"@kungfu-tech/buildchain\";\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\nimport { collectModuleBuildFacts } from \"@kungfu-tech/buildchain/build-facts\";\nimport { checkHomebrewTap } from \"@kungfu-tech/buildchain/homebrew\";\nimport { verifyKfd1ReleaseGate } from \"@kungfu-tech/buildchain/kfd-gate\";\nimport { collectBadgeBundleFacts } from \"@kungfu-tech/buildchain/badges\";\nimport { collectReadmeBadgeFacts } from \"@kungfu-tech/buildchain/readme-badges\";\nimport { verifyReleasePassport } from \"@kungfu-tech/buildchain/release-passport\";\nimport { verifyGitHubArtifactAttestationEvidence } from \"@kungfu-tech/buildchain/github-artifact-attestation\";\nimport { createReleasePropagationPlan } from \"@kungfu-tech/buildchain/release-propagation\";\nimport { planReleaseLineBootstrap } from \"@kungfu-tech/buildchain/release-line-bootstrap\";\nimport { collectPublicSurfaceReverseAudit } from \"@kungfu-tech/buildchain/public-surface-audit\";\nimport { createBuildchainLayoutDiscovery } from \"@kungfu-tech/buildchain/buildchain-layout\";\nimport { createPortableDevCachePlan } from \"@kungfu-tech/buildchain/portable-dev-cache\";\nimport contractWorld from \"@kungfu-tech/buildchain/site/buildchain-contract.json\" with { type: \"json\" };\nimport capabilityRegistry from \"@kungfu-tech/buildchain/site/capability-registry.json\" with { type: \"json\" };\nimport manualRegistry from \"@kungfu-tech/buildchain/site/manual-registry.json\" with { type: \"json\" };\nimport nodeApiRegistry from \"@kungfu-tech/buildchain/site/node-api-registry.json\" with { type: \"json\" };\nimport publicSurfaceAudit from \"@kungfu-tech/buildchain/site/public-surface-audit.json\" with { type: \"json\" };\n```\n\nUse `dist/site/manual-registry.json` to find the packaged operating manuals and\ntheir SHA-256 digests. Use `dist/site/buildchain-contract.json` to verify the\nfloating-ref contract world for a runtime such as `@v3`.\n\n## Commands\n\n`buildchain create github-artifact-attestation-policy` seals the expected\nartifact, caller source, original Linux build, immutable Buildchain signer, and\nGitHub permission set before the Release Passport is collected.\n`buildchain verify github-artifact-attestation` invokes `gh attestation verify`\nwith the exact signer/source policy and then verifies the retained bundle,\npredicate, platform manifest, Passport, and Buildchain evidence locally. See\n[`github-artifact-attestation.md`](github-artifact-attestation.md).\n\n`buildchain layout` is the stable machine question for repository layout. Tools\nsuch as Shifu should call it instead of copying `.buildchain/` path constants:\n\n```bash\nbuildchain layout --cwd /path/to/repository --json\n```\n\nThe result identifies the Buildchain version pin, repository root and config,\nthe canonical and currently resolved KFD-3 registry paths, and the KFD field\nused to declare Shifu jurisdiction. A repository is in Shifu's distribution\njurisdiction only when a KFD-3 surface explicitly declares\n`distribution.registrar=\"shifu\"`; the presence of Buildchain configuration is\nnot sufficient. The same contract is available through\n`createBuildchainLayoutDiscovery()` from\n`@kungfu-tech/buildchain/buildchain-layout`.\n\n`buildchain init` writes a starter `.buildchain/buildchain.toml` and a reusable workflow\ncaller at `.github/workflows/build.yml`.\n\n`buildchain portable-cache plan` turns a consumer-owned, secret-free manifest\ninto GitHub Actions cache inputs without letting each consumer invent key or\nrestore-prefix semantics. The exact key binds source SHA and the consumer plan\ndigest; the compatible restore prefix still requires the same provider schema,\nlayer, roots, runner image, platform/architecture, toolchain, dependency lock,\nand build profile.\n\n```bash\nbuildchain portable-cache plan \\\n  --manifest .buildchain/portable-cache.json \\\n  --output .buildchain/portable-cache-plan.json \\\n  --github-output \"$GITHUB_OUTPUT\"\n```\n\nThe emitted `cache-key`, `restore-keys`, and `cache-paths` values are intended\nfor pinned `actions/cache/restore` and `actions/cache/save` actions. After\nrestore and a consumer validation probe, seal the provider result:\n\n```bash\nbuildchain portable-cache receipt \\\n  --plan .buildchain/portable-cache-plan.json \\\n  --matched-key \"$CACHE_MATCHED_KEY\" \\\n  --cache-hit \"$CACHE_HIT\" \\\n  --validation-status pass \\\n  --cold-fallback-status passed \\\n  --output .buildchain/portable-cache-receipt.json\n```\n\nThe receipt distinguishes `exact`, `compatible`, `miss`, and `corrupt`.\nUnknown or contradictory provider evidence fails closed. A miss or corruption\nrequires the consumer's audited cold path; a cache never substitutes for the\nconsumer's current build or tests. Roots must be workspace-relative or under\n`~/`, and manifests cannot carry credentials, absolute host paths, or escape\nsegments. `cold-fallback-status=passed` qualifies a miss only after the current\nsource has completed its normal build and test path.\n\nSupported presets:\n\n- `--type package` for Node package repositories with pnpm, npm, or yarn.\n- `--type native` for CMake-style native projects.\n- `--type web-surface` for preview/staging/production site or app deployments.\n- `--type infra-contract` for provider-agnostic infrastructure contract\n  validation, observation, contract publication, and downstream propagation\n  planning without default mutation. Provider adapters expose built-in command\n  plans by default, and only configured `[infra.commands]` hooks can execute.\n- `--type publication-artifact` for papers, reports, specifications, and other\n  publication repositories that produce PDFs, metadata, source bundles, and\n  site-consumable manifests without becoming web-surface repositories. The\n  scaffold uses Buildchain's pinned\n  `ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0` toolchain for\n  LaTeX PDF builds.\n- `--type distribution-index` for Homebrew taps and other index repositories\n  whose files are projections of upstream release passport evidence.\n- `--type anchored-package` for packages whose version is anchored to an\n  explicit upstream release manifest.\n\nThe native preset includes an opt-in `[diagnostics.native]` profile with common\ntool/cache/artifact probes. Consumers can keep it enabled, adjust the tool and\ndirectory lists, or disable it if a repository does not need native diagnostics.\n\n`buildchain validate` parses `.buildchain/buildchain.toml`, checks configured version-state\nfiles, and can require named lifecycle stages:\n\n```bash\nbuildchain validate \\\n  --require-version-state \\\n  --require-lifecycle-stages install,build,verify\n```\n\n`buildchain lifecycle run <stage>` executes a lifecycle stage and writes the\nsame deterministic artifact manifest contract used by the reusable workflow:\n\n```bash\nbuildchain lifecycle run build \\\n  --artifact-path dist \\\n  --artifact-name \"{repo}-{version}-{platform}\"\n```\n\n`buildchain dev merge-queue` plans a GitHub merge-queue policy for a protected\nBuildchain dev channel. Declare every workflow that emits a required check; the\ncommand fails closed unless each file handles both `pull_request` and\n`merge_group` without reading `github.event.pull_request` directly:\n\n```bash\nbuildchain dev merge-queue \\\n  --repository kungfu-systems/example \\\n  --branch dev/v4/v4.0 \\\n  --workflow .github/workflows/source-acceptance.yml \\\n  --workflow .github/workflows/affected-native-pr.yml\n```\n\nThe default output is a read-only plan. Add `--apply` only after reviewing it.\nApply creates the exact-branch merge-queue ruleset before changing classic\nrequired status checks from strict to loose, preserves the required check\nidentities, and is safe to repeat. `gh` must be authenticated with repository\nAdministration write permission for apply mode.\n\nRepositories can make that policy declarative in `buildchain.toml`:\n\n```toml\n[governance.dev.merge_queue]\nmode = \"enabled\" # enabled, inherit, or disabled\nrequired_workflows = [\".github/workflows/verify.yml\"]\ncheck_response_timeout_minutes = 120\nmax_entries_to_build = 1\nbypass_users = [\"release-owner\"]\n```\n\nUse `buildchain dev merge-queue --from-config` to resolve and reconcile the\ndeclaration. `enabled` requires an exact queue on the target dev branch;\n`disabled` suppresses automatic queue creation; `inherit` copies the active\ndefault dev branch's queue parameters and bypass actors. When the table is\nabsent, release-line bootstrap uses the backward-compatible `inherit` mode.\nEvery inherited or explicitly enabled queue still validates each declared\nrequired workflow before any mutation. For a legacy repository with no table,\nan already-active exact queue on the current default dev branch is accepted as\nthe inheritance evidence; new declarations should list the workflows so future\nchanges are revalidated from source.\nThe `Dev Merge Queue Governance` workflow runs this reconciliation after\ngovernance-relevant changes land on a dev branch; its manual dispatch remains\ndry-run by default.\n\n`buildchain release line open` plans or writes the first version-state commit\nfor a new semver minor line. It does not publish anything. The dry-run mode is\nthe default and returns the dev/alpha/release refs, protection contract, default\nbranch action, and initial version before any GitHub mutation happens:\n\n```bash\nbuildchain release line open \\\n  --major 2 \\\n  --minor 10 \\\n  --source-ref release/v2/v2.9 \\\n  --json\n```\n\nThe write mode only updates local version-state files. The repository workflow\n`Release Line Bootstrap` wraps this command and, when `apply=true`, commits the\ninitial version state, creates `dev/vX/vX.Y`, `alpha/vX/vX.Y`, and\n`release/vX/vX.Y`, applies one-review branch protection, reconciles declared or\ninherited merge-queue governance, switches the default branch only after that\nreconciliation succeeds, and opens the first dev-to-alpha channel PR:\n\n```bash\nbuildchain release line open \\\n  --major 2 \\\n  --minor 10 \\\n  --source-ref release/v2/v2.9 \\\n  --write \\\n  --json\n```\n\n`buildchain` also publishes a public surface reverse audit as\n`dist/site/public-surface-audit.json`. The audit enumerates CLI commands from\n`bin/buildchain.mjs`, workflow inputs, action inputs, site pages, and docs\ncommand references, then compares them with the generated registries. Buildchain\nself-checks fail closed when an enumerable public surface is missing from the\nregistry:\n\n```js\nimport {\n  collectPublicSurfaceReverseAudit,\n  assertPublicSurfaceReverseAudit,\n} from \"@kungfu-tech/buildchain/public-surface-audit\";\n\nassertPublicSurfaceReverseAudit(collectPublicSurfaceReverseAudit({ root: process.cwd() }));\n```\n\n`buildchain kfd` is the product-facing KFD namespace. Schema commands expose the\nmachine-readable KFD standards shipped by `@kungfu-tech/kfd`, while versioned\nsubcommands host concrete product workflows. KFD-1, KFD-2, and KFD-3 are\nfirst-class Buildchain surfaces. KFD-4, KFD-5, and KFD-7 expose fail-closed\nproduct-evidence gate and verification protocols; passing those protocols does\nnot itself qualify, certify, activate, or ship support.\n\n`status` reports implemented support and the active repo-owned file layout.\n`migrate-layout` moves legacy root files into `.buildchain/`:\n\n```bash\nbuildchain kfd status --json\nbuildchain kfd migrate-layout --write\nbuildchain kfd 4 gate --input-json kfd-4-gate-input.json --output kfd-4-gate.json\nbuildchain kfd 5 gate --input-json kfd-5-gate-input.json --output kfd-5-gate.json\nbuildchain kfd 7 gate --input-json kfd-7-gate-input.json --output kfd-7-gate.json\nbuildchain kfd support project --matrix-json support-matrix.json \\\n  --gate-json kfd-4-gate.json --gate-json kfd-5-gate.json \\\n  --gate-json kfd-7-gate.json --output kfd-support.json\n```\n\nKFD-1 commands generate and validate contract-world release evidence:\n\n```bash\nbuildchain kfd 1 schema --json\nbuildchain kfd 1 witness --json\nbuildchain kfd 1 gate --witness-json kfd-1-witness.json --json\nbuildchain kfd 1 verify --gate-json kfd-1-gate.json --json\n```\n\nKFD-2 commands validate trust taxonomy entries and generate Buildchain's public\nclaim evidence. Product repositories use the `product-claims` subcommand to\nvalidate and render their own declared KFD-2 release claims under the canonical\nBuildchain KFD layout:\n\n```bash\nbuildchain kfd 2 schema --json\nbuildchain kfd 2 taxonomy --entry-json residual-risk.json --kind residualRisk --json\nbuildchain kfd 2 claims --json\nbuildchain kfd 2 product-claims check --json\nbuildchain kfd 2 product-claims write --json\nbuildchain kfd 2 product-claims render --json\n```\n\nThe default source is `.buildchain/kfd/kfd-2/registry.json`; outputs are\n`.buildchain/kfd/kfd-2/release-claims.json`, per-claim release-passport inputs\nunder `claims/`, and `buildchain-claim-args.txt`. Use `--registry` or\n`--output-dir` only for an explicit product packaging projection. `check` never\nwrites and exits non-zero when outputs drift.\n\nKFD-3 commands are separate from Buildchain's self reverse audit: products can\ndetect standard public surfaces, register the accepted boundary, audit the\ncurrent source or artifact tree, generate a release-passport-compatible witness,\nand expose a capability map for agents:\n\n```bash\nbuildchain kfd schema list --json\nbuildchain kfd schema show kfd-3 --json\nbuildchain kfd 3 detect --kind node-api --kind cli --json\nbuildchain kfd 3 register node-api --product Buildchain\nbuildchain kfd 3 audit --json\nbuildchain kfd 3 witness --kind prebuild --output .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json\nbuildchain kfd 3 query buildchain --json\nbuildchain kfd 4 schema --json\n```\n\nThe public Node API is exported from `@kungfu-tech/buildchain/kfd`. See\n[`kfd-support.md`](kfd-support.md) for the detected / declared / enforced model\nand the agent query flow.\n\nLifecycle runs also write a Buildchain observability JSONL log at\n`.buildchain/logs/events.jsonl` by default. Framework events use\n`source=buildchain`; consumer lifecycle commands use `source=user`. This lets a\nmaintainer tell apart time spent inside Buildchain's artifact/manifest\nframework from time spent in the repository's own build, test, packaging, or\npublish commands. The artifact manifest and summary embed the observability\nsummary for that lifecycle run id, so uploaded artifacts preserve the timing\nfacts without mixing in older JSONL events.\n\n`buildchain log`, `buildchain mark`, and `buildchain span` expose the same event\nprotocol to repository scripts:\n\n```bash\nbuildchain mark --event configure.ready --phase configure --attribute target=release\nbuildchain span --event native.build --phase build -- cmake --build build\nbuildchain log warn --event cache.miss --component conan --attribute token=hidden\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4 --require-phase build\nbuildchain diagnostics summary .buildchain/artifacts/*/diagnostics.json --json\nbuildchain sample process-tree --label native-build --interval-ms 15000 -- make -j20\n```\n\nDuring `buildchain lifecycle run`, child processes receive\n`BUILDCHAIN_LOG_PATH` and `BUILDCHAIN_LOG_RUN_ID`. A shell, Python, CMake, Conan,\nor JavaScript helper can call `buildchain mark` or `buildchain span` mid-build\nand have those events grouped into the same lifecycle summary.\n`buildchain verify observability-log` is a release gate: it fails when the log\nis missing, has too few events, contains error events, or does not include\nrequired phases, components, or event names.\n\nThe JSON summary also includes an additive `controlPlane` block. It counts\nworkflow-friction incident outcomes and production release-intent outcomes,\nincluding incident reuse rate, release-intent suppression rate, and suppression\nreasons. Buildchain writes those outcome events locally; it does not send\ntelemetry outside the runner.\n\nThe event protocol is JSONL and is also available from the SDK:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"native-build\" });\nlogger.mark(\"configure.ready\", { phase: \"configure\" });\n```\n\nSecret-looking attribute keys such as `token`, `password`, `secret`,\n`authorization`, `cookie`, and `private-key` are redacted before they are written.\nFull command strings are not recorded by `span`; scripts should provide stable\nevent names and safe attributes instead.\n\n`buildchain diagnostics summary` reads one or more small diagnostics artifacts\nand emits the same cross-platform summary as the diagnostics SDK:\n\n```bash\nbuildchain diagnostics summary \\\n  .buildchain/artifacts/linux-x64/diagnostics.json \\\n  .buildchain/artifacts/macos-arm64/diagnostics.json \\\n  --output .buildchain/artifacts/diagnostics-summary.json \\\n  --json\n```\n\nThe JSON summary keeps per-platform lifecycle stage tables, adds lifecycle\ntotal durations, carries top slow spans, aggregates warning/error counts, and\nsorts the slowest platforms. Each platform row carries compact runner facts,\nchecked tool versions/missing tools, package manager/cache directory details,\ncompiler-cache availability, and a compact process sampler summary: requested\nparallelism, observed max active processes, the ratio between them, sample\ncount, process categories, and the top sampled command basenames. This lets\nmaintainers inspect matrix timing, runner, tool, cache, and concurrency context\nwithout downloading large platform binaries or process sidecars first.\nWhen a sibling `diagnostics-manifest.json` is available, the summary also records\nits file list and verifies the listed `diagnostics.json` byte count and sha256.\nMissing, unreadable, or mismatched sidecar manifests are reported through\n`diagnosticsManifestWarningCount` and the per-platform `diagnosticsManifest`\nfield without failing the timing rollup.\nThe summary also compares each `diagnostics.json` contract to\n`BUILDCHAIN_DIAGNOSTICS_CONTRACT`; mismatches are reported through\n`diagnosticsContractWarningCount` and the per-platform `diagnosticsContract`\nfield so reviewers can separate diagnostics schema drift from lifecycle\nwarnings or build failures.\n\nWithout `--json`, the command prints a compact lifecycle timing table with\ninstall/build/verify/publish, artifact scan/upload, total, warning, and error\ncolumns for each platform, plus `jobs` and `active` columns for requested and\nobserved process concurrency when sampler data is present.\n\n`buildchain facts` collects and verifies source/version/output facts for\nmodules and products:\n\n```bash\nbuildchain facts module \\\n  --module native-core \\\n  --output .buildchain/facts/native-core.json \\\n  --legacy-kungfu-buildinfo framework/core/src/kungfu/yijinjing/kungfubuildinfo.json\n\nbuildchain facts aggregate \\\n  --product kungfu \\\n  --module-fact .buildchain/facts/native-core.json \\\n  --artifact dist/kungfu.zip \\\n  --output .buildchain/facts/kungfu.json\n\nbuildchain facts verify --fact .buildchain/facts/kungfu.json\n```\n\nThe same implementation is available from\n`@kungfu-tech/buildchain/build-facts`. Release passports can include these\nfacts with repeated `--build-facts-json` arguments to\n`buildchain collect github-release`. See\n[`build-facts.md`](build-facts.md) for the config schema and Node API.\n\n`buildchain sample process-tree` wraps a long-running command and periodically\nwrites process-tree snapshots:\n\n```bash\nbuildchain sample process-tree \\\n  --label native-build \\\n  --interval-ms 15000 \\\n  --output .buildchain/diagnostics/process-samples.jsonl \\\n  --summary-output .buildchain/diagnostics/process-summary.json \\\n  -- \\\n  make -j20\n```\n\nThe command returns the wrapped command's exit status. The JSONL file contains\nsmall timestamped samples; the summary JSON records requested parallelism,\nobserved concurrency, sampled CPU, command categories, and top command\nbasenames. Use it when a native build requests high parallelism but appears to\nspend long stretches in low-concurrency compile, archive, link, or cache steps.\n\n`buildchain doctor` checks repository readiness before remote side effects:\n\n```bash\nbuildchain doctor --json\n```\n\nIt validates `.buildchain/buildchain.toml`, package-manager detection, Git repository state,\nand the reusable workflow caller. For `version.strategy = \"anchored\"` with\n`version.next = \"manual\"`, it also embeds the anchored package release contract\ncheck: anchor manifest readability, configured version files, trusted\npublishing, package publish order, and required lifecycle stages. Add\n`--require-publish-source-lock` inside a publish job when the doctor report\nshould also fail unless the job is running from a resolved `publish-gate/*`\nsource lock.\n\nAnchored/manual package publish jobs can run the narrower source-lock gate\ndirectly:\n\n```bash\nbuildchain publish-source validate-anchored-release --json\n```\n\nThe command requires `BUILDCHAIN_PUBLISH_SOURCE_REF`,\n`BUILDCHAIN_PUBLISH_SOURCE_SHA`, and `BUILDCHAIN_PUBLISH_SOURCE_LOCKED` from the\nreusable build workflow outputs. It fails closed for direct `alpha/*` or\n`release/*` channel-branch publication, and checks the publish-gate consumer\nversion against configured version files and the anchor manifest. The JSON\nresult is shaped for future `buildchain.libkungfu.dev` fact ingestion.\n\n`buildchain release`, `buildchain web-surface`, `buildchain infra-contract`,\n`buildchain publication-artifact`, `buildchain publish-source`,\n`buildchain badges`, `buildchain homebrew`, and `buildchain build-contract`\nroute to the same implementation used by\nBuildchain's package APIs or GitHub Actions workflows. This keeps local\ninspection and CI behavior on the same implementation path.\n\nGenerate publication artifact metadata after building a paper or report:\n\n```bash\nbuildchain publication-artifact manifest \\\n  --source-sha \"$(git rev-parse HEAD)\" \\\n  --json\n```\n\nGenerate the Buildchain-owned npm paper package contents from declared\npublication facts:\n\n```bash\nbuildchain publication-artifact npm-package --json\n```\n\nThis command reads `project.type = \"publication-artifact\"`,\n`publication.version`, and `[publish] kind = \"npm-paper-package\"` plus\n`publish.package`; it writes `.buildchain/publication/npm-package` by default.\nThe `paper-release.yml@v3` reusable workflow uses the same command before\nrunning the standard npm publish transaction.\n\nThe command writes `.buildchain/publication/publication-artifact.json`,\n`.buildchain/publication/publication-artifact-passport.json`, a source bundle,\nand, when `[publication.archive]` is configured,\n`.buildchain/publication/publication-registry.json` by default. See\n[`publication-artifacts.md`](publication-artifacts.md) for the repository\ncontract, pinned LaTeX builder, and reusable workflow.\n\nGenerate, check, or update the managed README badge block:\n\n```bash\nbuildchain badges readme --json\nbuildchain badges readme --check\nbuildchain badges readme --write\nbuildchain badges bundle --json\nbuildchain badges bundle --check\nbuildchain badges bundle --write\nbuildchain badges bundle --claims kfd-1,release-passport --write\n```\n\nThe `--json` form emits the `kungfu-buildchain-readme-badge-facts` object.\n`--check` fails closed when the README marker block is missing or stale.\n`--write` inserts or replaces only the marked block. KFD passed badges come\nfrom the repository's own verified release passport; unreleased repositories\ndowngrade to explicit local declarations such as `declared`, `aligned`, or\n`planned`. `buildchain badges bundle` is the focused trust-badge entrypoint: it\nemits `kungfu-buildchain-badge-bundle-facts` and defaults to KFD-1, KFD-2,\nKFD-3, and Release Passport. See [`readme-badges.md`](readme-badges.md) for the\nmarker contract and `[badges]` / `[badges.bundle]` configuration.\n\nGenerate or check Homebrew tap projections from upstream release passports:\n\n```bash\nbuildchain homebrew update-formula \\\n  --package buildchain \\\n  --release-passport https://github.com/kungfu-systems/buildchain/releases/download/v3.0.0/buildchain.release.json \\\n  --write\n\nbuildchain homebrew check --json\n```\n\n`update-formula` writes `Formula/buildchain.rb` and `tap-manifest.json` from\nupstream release passport evidence. `check` fails closed when the Formula,\nmanifest, artifact digests, or KFD status drift from the upstream passport. See\n[`homebrew.md`](homebrew.md) for the distribution-index project contract.\n\n`buildchain collect github-release` creates a release passport bundle from\nGitHub Release assets or a local asset directory:\n\n```bash\nbuildchain collect github-release \\\n  --tag v3.0.0 \\\n  --repository kungfu-systems/buildchain \\\n  --assets-dir dist \\\n  --output-dir .buildchain/release-passport\n```\n\nThe bundle includes `buildchain.release.json`, `artifact-evidence.json`,\n`impact.json`, `agent-index.json`, `product-mechanism.json`, `check-report.json`,\nand `llms.txt`. Production binary distribution defaults to GitHub-hosted\nrunners so other projects can reproduce the release lane; self-hosted runners\nremain compatibility fixtures and are recorded as runner facts when used.\n\nFor publish-transaction releases, pass the additional evidence inputs so\n`buildchain.release.json` becomes the unified passport instead of a binary-only\nasset summary:\n\n```bash\nbuildchain collect github-release \\\n  --tag v3.0.0 \\\n  --repository kungfu-systems/buildchain \\\n  --assets-dir dist \\\n  --publish-evidence-json .buildchain/release-evidence/v3.0.0/evidence.json \\\n  --transaction-json .buildchain/release-state/v3.0.0/state.json \\\n  --package-set-json package-set.json \\\n  --impact-json impact.json \\\n  --trusted-publishing-json trusted-publishing.json \\\n  --anchor-manifest-json libnode.release.json \\\n  --build-summary-json .buildchain/artifacts/build-summary.json \\\n  --platform-manifest-json .buildchain/artifacts/linux-x64/manifest.json \\\n  --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \\\n  --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \\\n  --dist-tag-evidence-json .buildchain/release-evidence/v3.0.0/dist-tag-evidence.json \\\n  --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \\\n  --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \\\n  --kfd-3-prebuild-witness-json .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json \\\n  --kfd-3-artifact-verify-cmd \"kungfu agent verify --json\" \\\n  --release-extra-json '{\"channel\":\"release\",\"targetRef\":\"release/v2/v2.3\"}' \\\n  --output-dir .buildchain/release-passport\n```\n\nThe generated passport records the main and platform packages, npm dist-tags,\npublished versions, release source/ref state, anchor manifest digest, registry\nartifact digests, trusted publishing evidence, and Buildchain transaction\nresult. It also records `buildSummary`, `platformArtifactManifests`, and\n`distTagPromotion` when those JSON inputs are supplied. `packageSet` keeps the\nordered package set; `publish.packages[]` is the agent-readable npm publication\nsummary for each main/platform package. For Buildchain releases, verification\nexpects the supplied package set to include the main package plus the three\nplatform packages with version, dist-tag, and digest evidence. Verification\nfails closed if supplied sections are internally incomplete or point to\nartifacts without matching evidence.\n\n`--kfd-1-witness-json` attaches a KFD-1 contract-world release gate. The witness\nis structured JSON: consumers declare the contract world, canonical JSON policy,\nartifact paths, and expected SHA-256 digests. Buildchain imports KFD-owned\nmetadata from `@kungfu-tech/kfd`, freezes the witness before build publication,\nthen verifies the resulting artifact bytes itself and writes the evidence under\nthe KFD-provided top-level key currently named `kfd-1`. Consumers should not\nduplicate this by running repository-specific scripts or invoking the Kungfu\nSDK from their release workflow.\n\nFor the KFD repository, KFD-1 witnesses may be self-hosted standard-contract\nwitnesses: docs, schemas, standards metadata, package exports, and\nsite-consumption entrypoints are checked from source hashes to packaged artifact\nhashes, and the passport records schema IDs, self-hosting boundary, result, and\nresponsibility state.\n\n`--kfd-2-claim-json` attaches explicit public release claims to the KFD-2\nrelease trust passport audit. Buildchain also derives KFD-2 claims from KFD-1\nand KFD-3 gate evidence. Public claims must bind declared sources,\nmachine-readable evidence, hashes, artifact coordinates, verification results,\naudit boundary, responsibility state, and residual risk. Unbound claims fail\npassport verification; prose-only claims downgrade the KFD-2 audit and emit a\nwarning.\n\n`--kfd-3-prebuild-witness-json` attaches a KFD-3 collaboration-interface\nrelease gate. The product remains the source of truth: it emits a pre-build\nwitness that contains or points to its KFD-3 collaboration interface, declared\nparticipant-facing public surfaces, and registry digest. Buildchain freezes\nthat declaration before publication. The artifact side is supplied either by\n`--kfd-3-artifact-witness-json` or by a product-owned command such as\n`--kfd-3-artifact-verify-cmd \"kungfu agent verify --json\"`. Buildchain then\nchecks closure: every declared shipped public surface must be present in the\nartifact witness, and every artifact-exposed participant-facing public surface\nmust have been declared. The generated passport writes this evidence under the\nKFD-provided top-level key currently named `kfd-3`.\n\nThis gate is useful for agent-facing products because it turns KFD-3 from prose\ninto release evidence. A package cannot claim KFD-3 collaboration-interface\nsupport merely because the docs mention it; the release passport must show the\nfrozen declaration, the artifact-side witness digest, and a passing closure\ncomparison.\n\n`--invariant-passport-json` attaches a product-owned invariant Passport to the\nrelease gate and may be repeated. `--invariant-passport-cmd` runs a product\ncommand that emits one Passport JSON document. Buildchain verifies the\nPassport root, exact clean source identity, `verified` verdict, complete\nplatform coverage, and residual-risk shape; it does not redefine the product's\ninvariant semantics. Declared invariant Passport input is fail-closed.\nFor the KFD repository itself, the witness can declare docs, schemas, standards\nmetadata, package exports, and site-consumption contracts as grouped public\nsurfaces; the artifact witness must expose the same enumerable package/site\nsurfaces or verification fails closed.\n\n`--impact-json` supplies the surface-aware impact ledger. Production release\npassports (`release/*`) and major publish-gate passports require\n`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep it\noptional. When `surfaceImpacts[]` is required or supplied, the verifier requires\neach entry to include an id, impact, and rationale, and requires\n`versionImpact.final` to match the highest declared surface impact. The\ncollector copies `versionImpact` plus `surfaceImpacts` into\n`buildchain.release.json`. This lets\n`buildchain explain release --for agent --json` state why a release is patch,\nminor, or major instead of relying on file-path memory.\n\nFor a promote-only stable transaction, Buildchain can derive a patch-level\nrelease-governance ledger when the PR-stage release-candidate passport proves\nthe stable source tree is exactly the previously qualified candidate tree.\nThis fallback is unavailable when candidate evidence is absent, stale, or not\ntree-equivalent.\n\nBuildchain dogfoods its observability toolkit in this lane. The standalone\nbuilder writes API-generated events, while the workflow uses `buildchain mark`,\n`buildchain span`, `buildchain verify observability-log`, and `buildchain log\nsummary`; the event logs and summaries are published as release passport assets.\n\nVerify and explain release passports:\n\n```bash\nbuildchain verify release-passport .buildchain/release-passport/buildchain.release.json\nbuildchain explain release --passport .buildchain/release-passport/buildchain.release.json --for agent --json\nbuildchain inspect release --passport .buildchain/release-passport/buildchain.release.json\n```\n\nThe verifier fails closed when required protocol files are absent, artifacts are\nnot covered by evidence, or digests disagree. The explanation output is shaped\nfor agents: trust, completeness, impact, recovery route, and next action.\n\nVerify a published artifact by subject:\n\n```bash\nbuildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe\nbuildchain inspect artifact ./Kungfu-2.8.0-windows-x64.exe --json\nbuildchain explain artifact ./Kungfu-2.8.0-windows-x64.exe --for agent --json\nbuildchain verify artifact npm:@kungfu-tech/libnode@22.22.3-kf.3-alpha.18 \\\n  --repository kungfu-systems/libnode \\\n  --tag v22.22.3-kf.3-alpha.18 \\\n  --json\n```\n\n`verify artifact` computes or obtains the subject digest, discovers the\ndetached release passport, verifies the passport, then requires that the\nsubject digest appears in the passport's release assets, package set, publish\nevidence, or artifact evidence. Outcomes are explicit: `pass`, `fail`, or\n`unverifiable`. A filename is only a hint; trust comes from digest equality.\nFor `npm:<name>@<version>` subjects, Buildchain resolves `dist.integrity` from\nthe npm registry before matching passport evidence. Use `--npm-registry <url>`\nto verify packages from a custom registry; otherwise Buildchain uses\n`npm_config_registry` or `https://registry.npmjs.org/`.\n\nDiscovery is fail-closed and ordered:\n\n1. `--passport <file-or-url>`.\n2. Sidecar pointer, such as `<artifact>.buildchain-passport.json`.\n3. Embedded/package pointer, such as `package.json` `buildchain.releasePassport`.\n4. Local config or org index, such as `.buildchain/artifact-passport-locators.json`.\n5. GitHub Release default discovery from `github-release:` subjects, GitHub\n   Release asset URLs, or `--repository <owner/repo> --tag <tag>`.\n6. Custom `--locator-config <json-or-url>`.\n7. `unverifiable` with retry guidance.\n\nLocator files are policy, not protocol. They map subject fields such as\n`name`, `kind`, `version`, `digest`, `repository`, or `tag` to a detached\npassport location:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"contract\": \"kungfu-buildchain-artifact-passport-locator\",\n  \"locators\": [\n    {\n      \"match\": {\n        \"name\": \"Kungfu-2.8.0-windows-x64.exe\",\n        \"digest\": \"sha256:...\"\n      },\n      \"passport\": \"../release-passport/buildchain.release.json\"\n    }\n  ]\n}\n```\n\nSupported subject shapes include local files and directories, URLs,\n`npm:<name>@<version>`, `oci:...`, `s3:...`,\n`github-release:<owner/repo>@<tag>/<asset>`, and deployment endpoints. Local\nfiles, directories, and URLs are digestable directly; remote package, OCI,\nobject storage, and deployment subjects should provide a digest or resolve to a\nlocator that records one.\n\nSeal an exact artifact verification with the Node API, then verify or project\nthe resulting KFX admission envelope without reconstructing its roots:\n\n```bash\nbuildchain verify artifact-envelope envelope.json \\\n  --assessment-time 150 \\\n  --expected-root sha256:... \\\n  --expected-issuer buildchain.libkungfu.dev \\\n  --expected-publisher kungfu-systems \\\n  --expected-contract buildchain.release/v1 \\\n  --json\n\nbuildchain project kfx-admission envelope.json \\\n  --assessment-time 150 \\\n  --json\n```\n\nBoth commands call the public artifact-verification-envelope verifier. The\nprojected `attestation`, `trustInputs`, and `kfdAssessment` are direct copies of\nthe sealed envelope, and `envelopeRoot` stays identical across Node and CLI.\nSee [`artifact-verification-envelope.md`](artifact-verification-envelope.md).\n\nVerify infra-contract lifecycle evidence bundles:\n\n```bash\nbuildchain infra-contract --mode ci --source-sha \"$GITHUB_SHA\"\nbuildchain verify infra-contract-evidence-bundle .buildchain/infra-contract-evidence-bundle.json\n```\n\nThe infra-contract `ci` mode is mutation-free. It writes validate, plan,\ncontract, propagation dry-run, evidence bundle, and verification JSON artifacts\nunder `.buildchain/`, giving reusable workflows one standard responsibility\nchain instead of hand-written command sequences.\n\nThe infra-contract verifier is read-only. It recomputes the bundle hash and\nchecks that desired, plan, approval, apply, observe, contract, and propagate\nevidence remain bound to the same contract artifact. It also recomputes the\nbundle validation summary, so stale or misleading summary booleans fail closed\neven when the bundle hash has been refreshed.\n\n`buildchain release --dry-run` explains the release-line state machine before a\nmaintainer opens or merges a channel PR:\n\n```bash\nbuildchain release --dry-run --target-ref alpha/v3/v3.0\nbuildchain release --dry-run --target-ref release/v3/v3.0 --sha <verified-sha>\nbuildchain release dry-run --target-ref publish-gate/major --source-ref release/v3/v3.0\nbuildchain release explain --target-ref alpha/v3/v3.0 --json\n```\n\nThis is a Buildchain-level dry-run, not an npm dry-run. It explains the legal\nsource branch, exact release or alpha tags, floating tags, channel branches,\nversion-state files, governance checks, and publish transaction behavior that\nwould apply if the corresponding PR merge were promoted. It does not move\nbranches, move tags, edit files, publish npm packages, or run lifecycle publish\ncommands. `release explain` is the same explanation surface with a clearer name.\nPass `--json` for a machine-readable plan.\n\n`buildchain transaction inspect` is the top-level recovery inspection command\nfor the publish transaction state:\n\n```bash\nbuildchain transaction inspect --version v3.0.1-alpha.2\n```\n\nIt reads or locally initializes the durable transaction record and validates\navailable publish evidence. Remote durable refs and public Git ref finalization\nremain owned by `actions/promote-buildchain-ref`; the CLI inspection surface is\nfor preflight and recovery reasoning before a maintainer reruns or resumes a\npromotion.\n\n`buildchain npm dry-run` verifies the package shape before a release tag exists:\n\n```bash\nbuildchain npm dry-run --json\n```\n\nThe command validates `package.json`, infers the exact release tag\n`v${package.json.version}`, chooses npm dist-tag `alpha` for prereleases and\n`latest` for stable releases, runs `npm pack --dry-run --json`, and then runs\n`npm publish --dry-run --access public --tag <alpha|latest>` unless\n`--skip-npm-publish-dry-run` is passed. It never performs a real publish.\n\n## npm Publish Gate\n\nBuildchain's own npm package is published from\n`.github/workflows/buildchain-ref-promotion.yml`, inside the same publish\ntransaction that promotes release refs:\n\n- `v2.0.13-alpha.0` publishes to npm with dist-tag `alpha`.\n- `v2.0.13` publishes to npm with dist-tag `latest`.\n- moving refs such as `v2`, `v2.0`, and `v2.0-alpha` do not match the publish\n  workflow and do not publish.\n\nThe promotion workflow uses npm Trusted Publishing through GitHub Actions OIDC.\nIt runs on a GitHub-hosted runner with `id-token: write`, but it does not\nmanually run the release-candidate resolver or promote action. Buildchain's own\ndogfood path calls the declarative `release-candidate-promote.yml` wrapper with\nchannel, target ref/SHA, PR-stage workflow, artifact, status-check, and passport\ninputs. The wrapper generates the version-state commit, runs\n`lifecycle.verify`, runs `lifecycle.publish`, writes Buildchain publish\nevidence, validates that evidence, and only then moves exact tags and floating\nrefs.\n\n```bash\nnode scripts/npm-publish-transaction.mjs\n```\n\nBefore the first real release, configure npm Trusted Publishing for:\n\n- package: `@kungfu-tech/buildchain`\n- repository: `kungfu-systems/buildchain`\n- workflow: `.github/workflows/buildchain-ref-promotion.yml`\n\nNo npm package is published by manual dispatch or ordinary branch builds.\nManual dispatch on `.github/workflows/npm-publish.yml` remains dry-run only, so\nmaintainers can verify package contents and npm publish shape before opening or\nmerging the release PR."
+      "markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-cli\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-31\n  invisible_context: not asserted\n---\n\n# Buildchain CLI, npm Package, and Toolkit API\n\nBuildchain is published as the public npm package\n`@kungfu-tech/buildchain`. The package contains the `buildchain` command,\nthe importable ESM toolkit APIs, and the local scripts needed to initialize and\nvalidate repositories before they use the reusable GitHub workflow surface.\n\nThe npm package is not the release authority. Release authority still comes\nfrom the protected Buildchain branch and tag state machine. npm publishing is a\nside effect of an exact release tag that has already been produced by that\nstate machine.\n\n## Install and Run\n\nUse the published package directly:\n\n```bash\nnpx @kungfu-tech/buildchain --help\nnpx @kungfu-tech/buildchain init --type package\nnpx @kungfu-tech/buildchain validate --require-version-state\n```\n\nOr install it in a repository:\n\n```bash\npnpm add -D @kungfu-tech/buildchain\npnpm exec buildchain validate\n```\n\nConsumers should pin the exact Buildchain version that was validated in their\nrepository. When dogfooding a fresh Buildchain release immediately after it is\npublished, pnpm may block the install through a minimum release-age policy. In\nthat case, add a temporary package/version-specific `minimumReleaseAgeExclude`\nentry, such as `@kungfu-tech/buildchain@3.0.0`, and remove it once the package\nhas aged past the normal policy window. Do not replace that with a broad\nregistry or scope-wide exclude.\n\nUse the package API directly inside JavaScript build scripts:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({ source: \"user\", component: \"build\" });\nawait logger.span(\"build.native\", { phase: \"build\" }, async () => {\n  await buildNativeArtifacts();\n});\n```\n\nThe standalone binary and CLI are for workflow steps, shell scripts, and\nnon-JavaScript environments. JavaScript code that already depends on\n`@kungfu-tech/buildchain` should import the toolkit API instead of spawning\n`npx buildchain` or a downloaded binary.\n\n## Node API and Package Exports\n\nBuildchain's public Node API is the package `exports` surface, not arbitrary\ninternal file paths. The npm package also ships\n`dist/site/node-api-registry.json` and exports it as\n`@kungfu-tech/buildchain/site/node-api-registry.json` so agents can enumerate\nthe supported imports from the installed package.\nFor navigation, start with `dist/site/capability-registry.json`: it groups\nmanuals, CLI commands, workflow/action inputs, Node exports, site pages, and KFD\nclaim facts by product capability before an agent chooses a concrete command or\nmanual.\n\nCurrent public import families include:\n\n```js\nimport * as buildchain from \"@kungfu-tech/buildchain\";\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\nimport { collectModuleBuildFacts } from \"@kungfu-tech/buildchain/build-facts\";\nimport { checkHomebrewTap } from \"@kungfu-tech/buildchain/homebrew\";\nimport { verifyKfd1ReleaseGate } from \"@kungfu-tech/buildchain/kfd-gate\";\nimport { collectBadgeBundleFacts } from \"@kungfu-tech/buildchain/badges\";\nimport { collectReadmeBadgeFacts } from \"@kungfu-tech/buildchain/readme-badges\";\nimport { verifyReleasePassport } from \"@kungfu-tech/buildchain/release-passport\";\nimport { verifyGitHubArtifactAttestationEvidence } from \"@kungfu-tech/buildchain/github-artifact-attestation\";\nimport { createReleasePropagationPlan } from \"@kungfu-tech/buildchain/release-propagation\";\nimport { verifyPublicationReproducibility } from \"@kungfu-tech/buildchain/publication-reproducibility\";\nimport { collectPaperStatus } from \"@kungfu-tech/buildchain/paper\";\nimport { planReleaseLineBootstrap } from \"@kungfu-tech/buildchain/release-line-bootstrap\";\nimport { collectPublicSurfaceReverseAudit } from \"@kungfu-tech/buildchain/public-surface-audit\";\nimport { createBuildchainLayoutDiscovery } from \"@kungfu-tech/buildchain/buildchain-layout\";\nimport { createPortableDevCachePlan } from \"@kungfu-tech/buildchain/portable-dev-cache\";\nimport contractWorld from \"@kungfu-tech/buildchain/site/buildchain-contract.json\" with { type: \"json\" };\nimport capabilityRegistry from \"@kungfu-tech/buildchain/site/capability-registry.json\" with { type: \"json\" };\nimport manualRegistry from \"@kungfu-tech/buildchain/site/manual-registry.json\" with { type: \"json\" };\nimport nodeApiRegistry from \"@kungfu-tech/buildchain/site/node-api-registry.json\" with { type: \"json\" };\nimport publicSurfaceAudit from \"@kungfu-tech/buildchain/site/public-surface-audit.json\" with { type: \"json\" };\n```\n\nUse `dist/site/manual-registry.json` to find the packaged operating manuals and\ntheir SHA-256 digests. Use `dist/site/buildchain-contract.json` to verify the\nfloating-ref contract world for a runtime such as `@v3`.\n\n## Commands\n\n`buildchain create github-artifact-attestation-policy` seals the expected\nartifact, caller source, original Linux build, immutable Buildchain signer, and\nGitHub permission set before the Release Passport is collected.\n`buildchain verify github-artifact-attestation` invokes `gh attestation verify`\nwith the exact signer/source policy and then verifies the retained bundle,\npredicate, platform manifest, Passport, and Buildchain evidence locally. See\n[`github-artifact-attestation.md`](github-artifact-attestation.md).\n\n### Governed paper lifecycle\n\n`buildchain paper` is the unified operator surface for a paper repository. Its\neight subcommands return versioned JSON contracts with `--json`:\n\n```bash\nbuildchain paper scaffold --package @kungfu-tech/paper-example \\\n  --repository kungfu-systems/paper-example\nbuildchain paper migrate --json\nbuildchain paper preflight --offline --json\nbuildchain paper bootstrap npm --json\nbuildchain paper build --json\nbuildchain paper alpha --json\nbuildchain paper status --json\nbuildchain paper resume --json\n```\n\nThe safety and authority boundary is explicit:\n\n- `scaffold` plans a 14-file, no-overwrite repository shape by default; add\n  `--write` to create only missing files.\n- `migrate` plans the five Buildchain-owned control-file changes needed by an\n  existing paper repository. Add `--write` only after reviewing exact old and\n  new digests; paper content and publication configuration are never rewritten.\n- The scaffolded `.buildchain/paper/provisioning-authority.json` binds both\n  caller workflow byte digests, their exact reusable-workflow SHA, the runtime\n  SHA, contract-lock bytes, npm registry and trusted-publisher coordinates, and\n  the repository Actions/generated-write policy under one digest. A floating\n  Buildchain ref cannot change release policy after that authority is accepted.\n- `preflight` separates local readiness from readiness for external mutation.\n  `--offline` skips live GitHub and npm observations without treating them as\n  local failures. Live readiness requires default workflow permissions `read`,\n  Actions pull-request approval disabled, and GitHub App or equivalent narrow\n  generated-write credential metadata.\n- `bootstrap npm` always performs npm pack and publish dry-runs first. A real\n  public bootstrap requires both `--execute` and\n  `--confirm-public-package <exact-name>`, uses only the official npm registry,\n  fixes the bootstrap version at `0.0.0-bootstrap.0`, and returns only npm URLs\n  observed from command output. Success requires public package readback and\n  the exact repository/workflow/environment trusted-publisher binding. For\n  GitHub, the npm coordinate is the workflow filename (`paper-release.yml`),\n  not its `.github/workflows/` repository path.\n- `build` plans the two-clean-build reproducibility proof. Add `--execute` to\n  create and verify the sealed publication bundle.\n- `alpha` plans or opens the protected Alpha pull request; it never merges,\n  publishes, or advances a floating ref.\n- `status` reports only evidence found in the repository or external\n  observations. It never infers a later lifecycle state from an earlier one.\n- `resume` plans or dispatches the repository's thin release workflow; the\n  protected workflow remains the release authority.\n\nThe ordered evidence states are `scaffolded`, `governed`, `admitted`,\n`bootstrapped`, `trust-bound`, `content-ready`, `artifact-sealed`,\n`package-published`, `alpha-complete`, `staging-visible`, and\n`production-visible`. A state can be `satisfied`, `not-reached`, `blocked`, or\n`unknown`; consumers must not collapse those distinctions.\n\nThe corresponding Node surface is\n`@kungfu-tech/buildchain/paper`. Planning and status functions are read-only;\n`writePaperScaffold()` and `writePaperMigration()` are the bounded local\nwriters, and\n`executePaperNpmBootstrap()` preserves the same confirmation boundary used by\nthe CLI.\n\n`buildchain layout` is the stable machine question for repository layout. Tools\nsuch as Shifu should call it instead of copying `.buildchain/` path constants:\n\n```bash\nbuildchain layout --cwd /path/to/repository --json\n```\n\nThe result identifies the Buildchain version pin, repository root and config,\nthe canonical and currently resolved KFD-3 registry paths, and the KFD field\nused to declare Shifu jurisdiction. A repository is in Shifu's distribution\njurisdiction only when a KFD-3 surface explicitly declares\n`distribution.registrar=\"shifu\"`; the presence of Buildchain configuration is\nnot sufficient. The same contract is available through\n`createBuildchainLayoutDiscovery()` from\n`@kungfu-tech/buildchain/buildchain-layout`.\n\n`buildchain init` writes a starter `.buildchain/buildchain.toml` and a reusable workflow\ncaller at `.github/workflows/build.yml`.\n\n`buildchain portable-cache plan` turns a consumer-owned, secret-free manifest\ninto GitHub Actions cache inputs without letting each consumer invent key or\nrestore-prefix semantics. The exact key binds source SHA and the consumer plan\ndigest; the compatible restore prefix still requires the same provider schema,\nlayer, roots, runner image, platform/architecture, toolchain, dependency lock,\nand build profile.\n\n```bash\nbuildchain portable-cache plan \\\n  --manifest .buildchain/portable-cache.json \\\n  --output .buildchain/portable-cache-plan.json \\\n  --github-output \"$GITHUB_OUTPUT\"\n```\n\nThe emitted `cache-key`, `restore-keys`, and `cache-paths` values are intended\nfor pinned `actions/cache/restore` and `actions/cache/save` actions. After\nrestore and a consumer validation probe, seal the provider result:\n\n```bash\nbuildchain portable-cache receipt \\\n  --plan .buildchain/portable-cache-plan.json \\\n  --matched-key \"$CACHE_MATCHED_KEY\" \\\n  --cache-hit \"$CACHE_HIT\" \\\n  --validation-status pass \\\n  --cold-fallback-status passed \\\n  --output .buildchain/portable-cache-receipt.json\n```\n\nThe receipt distinguishes `exact`, `compatible`, `miss`, and `corrupt`.\nUnknown or contradictory provider evidence fails closed. A miss or corruption\nrequires the consumer's audited cold path; a cache never substitutes for the\nconsumer's current build or tests. Roots must be workspace-relative or under\n`~/`, and manifests cannot carry credentials, absolute host paths, or escape\nsegments. `cold-fallback-status=passed` qualifies a miss only after the current\nsource has completed its normal build and test path.\n\nSupported presets:\n\n- `--type package` for Node package repositories with pnpm, npm, or yarn.\n- `--type native` for CMake-style native projects.\n- `--type web-surface` for preview/staging/production site or app deployments.\n- `--type infra-contract` for provider-agnostic infrastructure contract\n  validation, observation, contract publication, and downstream propagation\n  planning without default mutation. Provider adapters expose built-in command\n  plans by default, and only configured `[infra.commands]` hooks can execute.\n- `--type publication-artifact` for papers, reports, specifications, and other\n  publication repositories that produce PDFs, metadata, source bundles, and\n  site-consumable manifests without becoming web-surface repositories. The\n  scaffold uses Buildchain's pinned\n  `ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0` toolchain for\n  LaTeX PDF builds.\n- `--type distribution-index` for Homebrew taps and other index repositories\n  whose files are projections of upstream release passport evidence.\n- `--type anchored-package` for packages whose version is anchored to an\n  explicit upstream release manifest.\n\nThe native preset includes an opt-in `[diagnostics.native]` profile with common\ntool/cache/artifact probes. Consumers can keep it enabled, adjust the tool and\ndirectory lists, or disable it if a repository does not need native diagnostics.\n\n`buildchain validate` parses `.buildchain/buildchain.toml`, checks configured version-state\nfiles, and can require named lifecycle stages:\n\n```bash\nbuildchain validate \\\n  --require-version-state \\\n  --require-lifecycle-stages install,build,verify\n```\n\n`buildchain lifecycle run <stage>` executes a lifecycle stage and writes the\nsame deterministic artifact manifest contract used by the reusable workflow:\n\n```bash\nbuildchain lifecycle run build \\\n  --artifact-path dist \\\n  --artifact-name \"{repo}-{version}-{platform}\"\n```\n\n`buildchain dev merge-queue` plans a GitHub merge-queue policy for a protected\nBuildchain dev channel. Declare every workflow that emits a required check; the\ncommand fails closed unless each file handles both `pull_request` and\n`merge_group` without reading `github.event.pull_request` directly:\n\n```bash\nbuildchain dev merge-queue \\\n  --repository kungfu-systems/example \\\n  --branch dev/v4/v4.0 \\\n  --workflow .github/workflows/source-acceptance.yml \\\n  --workflow .github/workflows/affected-native-pr.yml\n```\n\nThe default output is a read-only plan. Add `--apply` only after reviewing it.\nApply creates the exact-branch merge-queue ruleset before changing classic\nrequired status checks from strict to loose, preserves the required check\nidentities, and is safe to repeat. `gh` must be authenticated with repository\nAdministration write permission for apply mode.\n\nRepositories can make that policy declarative in `buildchain.toml`:\n\n```toml\n[governance.dev.merge_queue]\nmode = \"enabled\" # enabled, inherit, or disabled\nrequired_workflows = [\".github/workflows/verify.yml\"]\ncheck_response_timeout_minutes = 120\nmax_entries_to_build = 1\nbypass_users = [\"release-owner\"]\n```\n\nUse `buildchain dev merge-queue --from-config` to resolve and reconcile the\ndeclaration. `enabled` requires an exact queue on the target dev branch;\n`disabled` suppresses automatic queue creation; `inherit` copies the active\ndefault dev branch's queue parameters and bypass actors. When the table is\nabsent, release-line bootstrap uses the backward-compatible `inherit` mode.\nEvery inherited or explicitly enabled queue still validates each declared\nrequired workflow before any mutation. For a legacy repository with no table,\nan already-active exact queue on the current default dev branch is accepted as\nthe inheritance evidence; new declarations should list the workflows so future\nchanges are revalidated from source.\nThe `Dev Merge Queue Governance` workflow runs this reconciliation after\ngovernance-relevant changes land on a dev branch; its manual dispatch remains\ndry-run by default.\n\n`buildchain release line open` plans or writes the first version-state commit\nfor a new semver minor line. It does not publish anything. The dry-run mode is\nthe default and returns the dev/alpha/release refs, protection contract, default\nbranch action, and initial version before any GitHub mutation happens:\n\n```bash\nbuildchain release line open \\\n  --major 3 \\\n  --minor 1 \\\n  --source-ref release/v3/v3.0 \\\n  --json\n```\n\nThe write mode only updates local version-state files. The repository workflow\n`Release Line Bootstrap` wraps this command and, when `apply=true`, commits the\ninitial version state, creates `dev/vX/vX.Y`, `alpha/vX/vX.Y`, and\n`release/vX/vX.Y`, applies one-review branch protection, reconciles declared or\ninherited merge-queue governance, switches the default branch only after that\nreconciliation succeeds, and opens the first dev-to-alpha channel PR:\n\n```bash\nbuildchain release line open \\\n  --major 3 \\\n  --minor 1 \\\n  --source-ref release/v3/v3.0 \\\n  --write \\\n  --json\n```\n\n`buildchain` also publishes a public surface reverse audit as\n`dist/site/public-surface-audit.json`. The audit enumerates CLI commands from\n`bin/buildchain.mjs`, workflow inputs, action inputs, site pages, and docs\ncommand references, then compares them with the generated registries. Buildchain\nself-checks fail closed when an enumerable public surface is missing from the\nregistry:\n\n```js\nimport {\n  collectPublicSurfaceReverseAudit,\n  assertPublicSurfaceReverseAudit,\n} from \"@kungfu-tech/buildchain/public-surface-audit\";\n\nassertPublicSurfaceReverseAudit(\n  collectPublicSurfaceReverseAudit({ root: process.cwd() }),\n);\n```\n\n`buildchain kfd` is the product-facing KFD namespace. Schema commands expose the\nmachine-readable KFD standards shipped by `@kungfu-tech/kfd`, while versioned\nsubcommands host concrete product workflows. KFD-1, KFD-2, and KFD-3 are\nfirst-class Buildchain surfaces. KFD-4, KFD-5, and KFD-7 expose fail-closed\nproduct-evidence gate and verification protocols; passing those protocols does\nnot itself qualify, certify, activate, or ship support.\n\n`status` reports implemented support and the active repo-owned file layout.\n`migrate-layout` moves legacy root files into `.buildchain/`:\n\n```bash\nbuildchain kfd status --json\nbuildchain kfd migrate-layout --write\nbuildchain kfd 4 gate --input-json kfd-4-gate-input.json --output kfd-4-gate.json\nbuildchain kfd 5 gate --input-json kfd-5-gate-input.json --output kfd-5-gate.json\nbuildchain kfd 7 gate --input-json kfd-7-gate-input.json --output kfd-7-gate.json\nbuildchain kfd support project --matrix-json support-matrix.json \\\n  --gate-json kfd-4-gate.json --gate-json kfd-5-gate.json \\\n  --gate-json kfd-7-gate.json --output kfd-support.json\n```\n\nKFD-1 commands generate and validate contract-world release evidence:\n\n```bash\nbuildchain kfd 1 schema --json\nbuildchain kfd 1 witness --json\nbuildchain kfd 1 gate --witness-json kfd-1-witness.json --json\nbuildchain kfd 1 verify --gate-json kfd-1-gate.json --json\n```\n\nKFD-2 commands validate trust taxonomy entries and generate Buildchain's public\nclaim evidence. Product repositories use the `product-claims` subcommand to\nvalidate and render their own declared KFD-2 release claims under the canonical\nBuildchain KFD layout:\n\n```bash\nbuildchain kfd 2 schema --json\nbuildchain kfd 2 taxonomy --entry-json residual-risk.json --kind residualRisk --json\nbuildchain kfd 2 claims --json\nbuildchain kfd 2 product-claims check --json\nbuildchain kfd 2 product-claims write --json\nbuildchain kfd 2 product-claims render --json\n```\n\nThe default source is `.buildchain/kfd/kfd-2/registry.json`; outputs are\n`.buildchain/kfd/kfd-2/release-claims.json`, per-claim release-passport inputs\nunder `claims/`, and `buildchain-claim-args.txt`. Use `--registry` or\n`--output-dir` only for an explicit product packaging projection. `check` never\nwrites and exits non-zero when outputs drift.\n\nKFD-3 commands are separate from Buildchain's self reverse audit: products can\ndetect standard public surfaces, register the accepted boundary, audit the\ncurrent source or artifact tree, generate a release-passport-compatible witness,\nand expose a capability map for agents:\n\n```bash\nbuildchain kfd schema list --json\nbuildchain kfd schema show kfd-3 --json\nbuildchain kfd 3 detect --kind node-api --kind cli --json\nbuildchain kfd 3 register node-api --product Buildchain\nbuildchain kfd 3 audit --json\nbuildchain kfd 3 witness --kind prebuild --output .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json\nbuildchain kfd 3 query buildchain --json\nbuildchain kfd 4 schema --json\n```\n\nThe public Node API is exported from `@kungfu-tech/buildchain/kfd`. See\n[`kfd-support.md`](kfd-support.md) for the detected / declared / enforced model\nand the agent query flow.\n\nLifecycle runs also write a Buildchain observability JSONL log at\n`.buildchain/logs/events.jsonl` by default. Framework events use\n`source=buildchain`; consumer lifecycle commands use `source=user`. This lets a\nmaintainer tell apart time spent inside Buildchain's artifact/manifest\nframework from time spent in the repository's own build, test, packaging, or\npublish commands. The artifact manifest and summary embed the observability\nsummary for that lifecycle run id, so uploaded artifacts preserve the timing\nfacts without mixing in older JSONL events.\n\n`buildchain log`, `buildchain mark`, and `buildchain span` expose the same event\nprotocol to repository scripts:\n\n```bash\nbuildchain mark --event configure.ready --phase configure --attribute target=release\nbuildchain span --event native.build --phase build -- cmake --build build\nbuildchain log warn --event cache.miss --component conan --attribute token=hidden\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4 --require-phase build\nbuildchain diagnostics summary .buildchain/artifacts/*/diagnostics.json --json\nbuildchain sample process-tree --label native-build --interval-ms 15000 -- make -j20\n```\n\nDuring `buildchain lifecycle run`, child processes receive\n`BUILDCHAIN_LOG_PATH` and `BUILDCHAIN_LOG_RUN_ID`. A shell, Python, CMake, Conan,\nor JavaScript helper can call `buildchain mark` or `buildchain span` mid-build\nand have those events grouped into the same lifecycle summary.\n`buildchain verify observability-log` is a release gate: it fails when the log\nis missing, has too few events, contains error events, or does not include\nrequired phases, components, or event names.\n\nThe JSON summary also includes an additive `controlPlane` block. It counts\nworkflow-friction incident outcomes and production release-intent outcomes,\nincluding incident reuse rate, release-intent suppression rate, and suppression\nreasons. Buildchain writes those outcome events locally; it does not send\ntelemetry outside the runner.\n\nThe event protocol is JSONL and is also available from the SDK:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n  source: \"user\",\n  component: \"native-build\",\n});\nlogger.mark(\"configure.ready\", { phase: \"configure\" });\n```\n\nSecret-looking attribute keys such as `token`, `password`, `secret`,\n`authorization`, `cookie`, and `private-key` are redacted before they are written.\nFull command strings are not recorded by `span`; scripts should provide stable\nevent names and safe attributes instead.\n\n`buildchain diagnostics summary` reads one or more small diagnostics artifacts\nand emits the same cross-platform summary as the diagnostics SDK:\n\n```bash\nbuildchain diagnostics summary \\\n  .buildchain/artifacts/linux-x64/diagnostics.json \\\n  .buildchain/artifacts/macos-arm64/diagnostics.json \\\n  --output .buildchain/artifacts/diagnostics-summary.json \\\n  --json\n```\n\nThe JSON summary keeps per-platform lifecycle stage tables, adds lifecycle\ntotal durations, carries top slow spans, aggregates warning/error counts, and\nsorts the slowest platforms. Each platform row carries compact runner facts,\nchecked tool versions/missing tools, package manager/cache directory details,\ncompiler-cache availability, and a compact process sampler summary: requested\nparallelism, observed max active processes, the ratio between them, sample\ncount, process categories, and the top sampled command basenames. This lets\nmaintainers inspect matrix timing, runner, tool, cache, and concurrency context\nwithout downloading large platform binaries or process sidecars first.\nWhen a sibling `diagnostics-manifest.json` is available, the summary also records\nits file list and verifies the listed `diagnostics.json` byte count and sha256.\nMissing, unreadable, or mismatched sidecar manifests are reported through\n`diagnosticsManifestWarningCount` and the per-platform `diagnosticsManifest`\nfield without failing the timing rollup.\nThe summary also compares each `diagnostics.json` contract to\n`BUILDCHAIN_DIAGNOSTICS_CONTRACT`; mismatches are reported through\n`diagnosticsContractWarningCount` and the per-platform `diagnosticsContract`\nfield so reviewers can separate diagnostics schema drift from lifecycle\nwarnings or build failures.\n\nWithout `--json`, the command prints a compact lifecycle timing table with\ninstall/build/verify/publish, artifact scan/upload, total, warning, and error\ncolumns for each platform, plus `jobs` and `active` columns for requested and\nobserved process concurrency when sampler data is present.\n\n`buildchain facts` collects and verifies source/version/output facts for\nmodules and products:\n\n```bash\nbuildchain facts module \\\n  --module native-core \\\n  --output .buildchain/facts/native-core.json \\\n  --legacy-kungfu-buildinfo framework/core/src/kungfu/yijinjing/kungfubuildinfo.json\n\nbuildchain facts aggregate \\\n  --product kungfu \\\n  --module-fact .buildchain/facts/native-core.json \\\n  --artifact dist/kungfu.zip \\\n  --output .buildchain/facts/kungfu.json\n\nbuildchain facts verify --fact .buildchain/facts/kungfu.json\n```\n\nThe same implementation is available from\n`@kungfu-tech/buildchain/build-facts`. Release passports can include these\nfacts with repeated `--build-facts-json` arguments to\n`buildchain collect github-release`. See\n[`build-facts.md`](build-facts.md) for the config schema and Node API.\n\n`buildchain sample process-tree` wraps a long-running command and periodically\nwrites process-tree snapshots:\n\n```bash\nbuildchain sample process-tree \\\n  --label native-build \\\n  --interval-ms 15000 \\\n  --output .buildchain/diagnostics/process-samples.jsonl \\\n  --summary-output .buildchain/diagnostics/process-summary.json \\\n  -- \\\n  make -j20\n```\n\nThe command returns the wrapped command's exit status. The JSONL file contains\nsmall timestamped samples; the summary JSON records requested parallelism,\nobserved concurrency, sampled CPU, command categories, and top command\nbasenames. Use it when a native build requests high parallelism but appears to\nspend long stretches in low-concurrency compile, archive, link, or cache steps.\n\n`buildchain doctor` checks repository readiness before remote side effects:\n\n```bash\nbuildchain doctor --json\n```\n\nIt validates `.buildchain/buildchain.toml`, package-manager detection, Git repository state,\nand the reusable workflow caller. For `version.strategy = \"anchored\"` with\n`version.next = \"manual\"`, it also embeds the anchored package release contract\ncheck: anchor manifest readability, configured version files, trusted\npublishing, package publish order, and required lifecycle stages. Add\n`--require-publish-source-lock` inside a publish job when the doctor report\nshould also fail unless the job is running from a resolved `publish-gate/*`\nsource lock.\n\nAnchored/manual package publish jobs can run the narrower source-lock gate\ndirectly:\n\n```bash\nbuildchain publish-source validate-anchored-release --json\n```\n\nThe command requires `BUILDCHAIN_PUBLISH_SOURCE_REF`,\n`BUILDCHAIN_PUBLISH_SOURCE_SHA`, and `BUILDCHAIN_PUBLISH_SOURCE_LOCKED` from the\nreusable build workflow outputs. It fails closed for direct `alpha/*` or\n`release/*` channel-branch publication, and checks the publish-gate consumer\nversion against configured version files and the anchor manifest. The JSON\nresult is shaped for future `buildchain.libkungfu.dev` fact ingestion.\n\n`buildchain release`, `buildchain web-surface`, `buildchain infra-contract`,\n`buildchain publication-artifact`, `buildchain publish-source`,\n`buildchain badges`, `buildchain homebrew`, and `buildchain build-contract`\nroute to the same implementation used by\nBuildchain's package APIs or GitHub Actions workflows. This keeps local\ninspection and CI behavior on the same implementation path.\n\nGenerate publication artifact metadata after building a paper or report:\n\n```bash\nbuildchain publication-artifact manifest \\\n  --source-sha \"$(git rev-parse HEAD)\" \\\n  --json\n```\n\nRun the fail-closed clean-room gate before Alpha or release admission:\n\n```bash\nbuildchain publication-artifact reproducibility \\\n  --source-sha \"$(git rev-parse HEAD)\" \\\n  --promote \\\n  --json\n```\n\nThe command checks two independent clones of the exact commit, isolates caches,\nderives `SOURCE_DATE_EPOCH` from Git, and compares every declared artifact,\nsource bundle, publication evidence file, npm package file, and actual npm\ntarball. It writes\n`.buildchain/publication/reproducibility-receipt.json`. Only a byte-identical\nbuild using the digest-pinned `latex-docker` toolchain is qualifying.\n`--allow-unpinned-toolchain` exists for local diagnostics and never changes the\nreceipt's `qualifying` field.\n\nGenerate the Buildchain-owned npm paper package contents from declared\npublication facts:\n\n```bash\nbuildchain publication-artifact npm-package --json\n```\n\nThis command reads `project.type = \"publication-artifact\"`,\n`publication.version`, and `[publish] kind = \"npm-paper-package\"` plus\n`publish.package`; it writes `.buildchain/publication/npm-package` by default.\nThe `paper-release.yml@v3` reusable workflow uses the same command before\nrunning the standard npm publish transaction.\n\nThe command writes `.buildchain/publication/publication-artifact.json`,\n`.buildchain/publication/publication-artifact-passport.json`, a source bundle,\nand, when `[publication.archive]` is configured,\n`.buildchain/publication/publication-registry.json` by default. See\n[`publication-artifacts.md`](publication-artifacts.md) for the repository\ncontract, pinned LaTeX builder, and reusable workflow.\n\nGenerate, check, or update the managed README badge block:\n\n```bash\nbuildchain badges readme --json\nbuildchain badges readme --check\nbuildchain badges readme --write\nbuildchain badges bundle --json\nbuildchain badges bundle --check\nbuildchain badges bundle --write\nbuildchain badges bundle --claims kfd-1,release-passport --write\n```\n\nThe `--json` form emits the `kungfu-buildchain-readme-badge-facts` object.\n`--check` fails closed when the README marker block is missing or stale.\n`--write` inserts or replaces only the marked block. KFD passed badges come\nfrom the repository's own verified release passport; unreleased repositories\ndowngrade to explicit local declarations such as `declared`, `aligned`, or\n`planned`. `buildchain badges bundle` is the focused trust-badge entrypoint: it\nemits `kungfu-buildchain-badge-bundle-facts` and defaults to KFD-1, KFD-2,\nKFD-3, and Release Passport. See [`readme-badges.md`](readme-badges.md) for the\nmarker contract and `[badges]` / `[badges.bundle]` configuration.\n\nGenerate or check Homebrew tap projections from upstream release passports:\n\n```bash\nbuildchain homebrew update-formula \\\n  --package buildchain \\\n  --release-passport https://github.com/kungfu-systems/buildchain/releases/download/v3.0.0/buildchain.release.json \\\n  --write\n\nbuildchain homebrew check --json\n```\n\n`update-formula` writes `Formula/buildchain.rb` and `tap-manifest.json` from\nupstream release passport evidence. `check` fails closed when the Formula,\nmanifest, artifact digests, or KFD status drift from the upstream passport. See\n[`homebrew.md`](homebrew.md) for the distribution-index project contract.\n\n`buildchain collect github-release` creates a release passport bundle from\nGitHub Release assets or a local asset directory:\n\n```bash\nbuildchain collect github-release \\\n  --tag v3.0.0 \\\n  --repository kungfu-systems/buildchain \\\n  --assets-dir dist \\\n  --output-dir .buildchain/release-passport\n```\n\nThe bundle includes `buildchain.release.json`, `artifact-evidence.json`,\n`impact.json`, `agent-index.json`, `product-mechanism.json`, `check-report.json`,\nand `llms.txt`. Production binary distribution defaults to GitHub-hosted\nrunners so other projects can reproduce the release lane; self-hosted runners\nremain compatibility fixtures and are recorded as runner facts when used.\n\nFor publish-transaction releases, pass the additional evidence inputs so\n`buildchain.release.json` becomes the unified passport instead of a binary-only\nasset summary:\n\n```bash\nbuildchain collect github-release \\\n  --tag v3.0.0 \\\n  --repository kungfu-systems/buildchain \\\n  --assets-dir dist \\\n  --publish-evidence-json .buildchain/release-evidence/v3.0.0/evidence.json \\\n  --transaction-json .buildchain/release-state/v3.0.0/state.json \\\n  --package-set-json package-set.json \\\n  --impact-json impact.json \\\n  --trusted-publishing-json trusted-publishing.json \\\n  --anchor-manifest-json libnode.release.json \\\n  --build-summary-json .buildchain/artifacts/build-summary.json \\\n  --platform-manifest-json .buildchain/artifacts/linux-x64/manifest.json \\\n  --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \\\n  --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \\\n  --dist-tag-evidence-json .buildchain/release-evidence/v3.0.0/dist-tag-evidence.json \\\n  --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \\\n  --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \\\n  --kfd-3-prebuild-witness-json .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json \\\n  --kfd-3-artifact-verify-cmd \"kungfu agent verify --json\" \\\n  --release-extra-json '{\"channel\":\"release\",\"targetRef\":\"release/v3/v3.0\"}' \\\n  --output-dir .buildchain/release-passport\n```\n\nThe generated passport records the main and platform packages, npm dist-tags,\npublished versions, release source/ref state, anchor manifest digest, registry\nartifact digests, trusted publishing evidence, and Buildchain transaction\nresult. It also records `buildSummary`, `platformArtifactManifests`, and\n`distTagPromotion` when those JSON inputs are supplied. `packageSet` keeps the\nordered package set; `publish.packages[]` is the agent-readable npm publication\nsummary for each main/platform package. For Buildchain releases, verification\nexpects the supplied package set to include the main package plus the three\nplatform packages with version, dist-tag, and digest evidence. Verification\nfails closed if supplied sections are internally incomplete or point to\nartifacts without matching evidence.\n\n`--kfd-1-witness-json` attaches a KFD-1 contract-world release gate. The witness\nis structured JSON: consumers declare the contract world, canonical JSON policy,\nartifact paths, and expected SHA-256 digests. Buildchain imports KFD-owned\nmetadata from `@kungfu-tech/kfd`, freezes the witness before build publication,\nthen verifies the resulting artifact bytes itself and writes the evidence under\nthe KFD-provided top-level key currently named `kfd-1`. Consumers should not\nduplicate this by running repository-specific scripts or invoking the Kungfu\nSDK from their release workflow.\n\nFor the KFD repository, KFD-1 witnesses may be self-hosted standard-contract\nwitnesses: docs, schemas, standards metadata, package exports, and\nsite-consumption entrypoints are checked from source hashes to packaged artifact\nhashes, and the passport records schema IDs, self-hosting boundary, result, and\nresponsibility state.\n\n`--kfd-2-claim-json` attaches explicit public release claims to the KFD-2\nrelease trust passport audit. Buildchain also derives KFD-2 claims from KFD-1\nand KFD-3 gate evidence. Public claims must bind declared sources,\nmachine-readable evidence, hashes, artifact coordinates, verification results,\naudit boundary, responsibility state, and residual risk. Unbound claims fail\npassport verification; prose-only claims downgrade the KFD-2 audit and emit a\nwarning.\n\n`--kfd-3-prebuild-witness-json` attaches a KFD-3 collaboration-interface\nrelease gate. The product remains the source of truth: it emits a pre-build\nwitness that contains or points to its KFD-3 collaboration interface, declared\nparticipant-facing public surfaces, and registry digest. Buildchain freezes\nthat declaration before publication. The artifact side is supplied either by\n`--kfd-3-artifact-witness-json` or by a product-owned command such as\n`--kfd-3-artifact-verify-cmd \"kungfu agent verify --json\"`. Buildchain then\nchecks closure: every declared shipped public surface must be present in the\nartifact witness, and every artifact-exposed participant-facing public surface\nmust have been declared. The generated passport writes this evidence under the\nKFD-provided top-level key currently named `kfd-3`.\n\nThis gate is useful for agent-facing products because it turns KFD-3 from prose\ninto release evidence. A package cannot claim KFD-3 collaboration-interface\nsupport merely because the docs mention it; the release passport must show the\nfrozen declaration, the artifact-side witness digest, and a passing closure\ncomparison.\n\n`--invariant-passport-json` attaches a product-owned invariant Passport to the\nrelease gate and may be repeated. `--invariant-passport-cmd` runs a product\ncommand that emits one Passport JSON document. Buildchain verifies the\nPassport root, exact clean source identity, `verified` verdict, complete\nplatform coverage, and residual-risk shape; it does not redefine the product's\ninvariant semantics. Declared invariant Passport input is fail-closed.\nFor the KFD repository itself, the witness can declare docs, schemas, standards\nmetadata, package exports, and site-consumption contracts as grouped public\nsurfaces; the artifact witness must expose the same enumerable package/site\nsurfaces or verification fails closed.\n\n`--impact-json` supplies the surface-aware impact ledger. Production release\npassports (`release/*`) and major publish-gate passports require\n`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep it\noptional. When `surfaceImpacts[]` is required or supplied, the verifier requires\neach entry to include an id, impact, and rationale, and requires\n`versionImpact.final` to match the highest declared surface impact. The\ncollector copies `versionImpact` plus `surfaceImpacts` into\n`buildchain.release.json`. This lets\n`buildchain explain release --for agent --json` state why a release is patch,\nminor, or major instead of relying on file-path memory.\n\nFor a promote-only stable transaction, Buildchain can derive a patch-level\nrelease-governance ledger when the PR-stage release-candidate passport proves\nthe stable source tree is exactly the previously qualified candidate tree.\nThis fallback is unavailable when candidate evidence is absent, stale, or not\ntree-equivalent.\n\nBuildchain dogfoods its observability toolkit in this lane. The standalone\nbuilder writes API-generated events, while the workflow uses `buildchain mark`,\n`buildchain span`, `buildchain verify observability-log`, and `buildchain log\nsummary`; the event logs and summaries are published as release passport assets.\n\nVerify and explain release passports:\n\n```bash\nbuildchain verify release-passport .buildchain/release-passport/buildchain.release.json\nbuildchain explain release --passport .buildchain/release-passport/buildchain.release.json --for agent --json\nbuildchain inspect release --passport .buildchain/release-passport/buildchain.release.json\n```\n\nThe verifier fails closed when required protocol files are absent, artifacts are\nnot covered by evidence, or digests disagree. The explanation output is shaped\nfor agents: trust, completeness, impact, recovery route, and next action.\n\nVerify a published artifact by subject:\n\n```bash\nbuildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe\nbuildchain inspect artifact ./Kungfu-2.8.0-windows-x64.exe --json\nbuildchain explain artifact ./Kungfu-2.8.0-windows-x64.exe --for agent --json\nbuildchain verify artifact npm:@kungfu-tech/libnode@22.22.3-kf.3-alpha.18 \\\n  --repository kungfu-systems/libnode \\\n  --tag v22.22.3-kf.3-alpha.18 \\\n  --json\n```\n\n`verify artifact` computes or obtains the subject digest, discovers the\ndetached release passport, verifies the passport, then requires that the\nsubject digest appears in the passport's release assets, package set, publish\nevidence, or artifact evidence. Outcomes are explicit: `pass`, `fail`, or\n`unverifiable`. A filename is only a hint; trust comes from digest equality.\nFor `npm:<name>@<version>` subjects, Buildchain resolves `dist.integrity` from\nthe npm registry before matching passport evidence. Use `--npm-registry <url>`\nto verify packages from a custom registry; otherwise Buildchain uses\n`npm_config_registry` or `https://registry.npmjs.org/`.\n\nDiscovery is fail-closed and ordered:\n\n1. `--passport <file-or-url>`.\n2. Sidecar pointer, such as `<artifact>.buildchain-passport.json`.\n3. Embedded/package pointer, such as `package.json` `buildchain.releasePassport`.\n4. Local config or org index, such as `.buildchain/artifact-passport-locators.json`.\n5. GitHub Release default discovery from `github-release:` subjects, GitHub\n   Release asset URLs, or `--repository <owner/repo> --tag <tag>`.\n6. Custom `--locator-config <json-or-url>`.\n7. `unverifiable` with retry guidance.\n\nLocator files are policy, not protocol. They map subject fields such as\n`name`, `kind`, `version`, `digest`, `repository`, or `tag` to a detached\npassport location:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"contract\": \"kungfu-buildchain-artifact-passport-locator\",\n  \"locators\": [\n    {\n      \"match\": {\n        \"name\": \"Kungfu-2.8.0-windows-x64.exe\",\n        \"digest\": \"sha256:...\"\n      },\n      \"passport\": \"../release-passport/buildchain.release.json\"\n    }\n  ]\n}\n```\n\nSupported subject shapes include local files and directories, URLs,\n`npm:<name>@<version>`, `oci:...`, `s3:...`,\n`github-release:<owner/repo>@<tag>/<asset>`, and deployment endpoints. Local\nfiles, directories, and URLs are digestable directly; remote package, OCI,\nobject storage, and deployment subjects should provide a digest or resolve to a\nlocator that records one.\n\nSeal an exact artifact verification with the Node API, then verify or project\nthe resulting KFX admission envelope without reconstructing its roots:\n\n```bash\nbuildchain verify artifact-envelope envelope.json \\\n  --assessment-time 150 \\\n  --expected-root sha256:... \\\n  --expected-issuer buildchain.libkungfu.dev \\\n  --expected-publisher kungfu-systems \\\n  --expected-contract buildchain.release/v1 \\\n  --json\n\nbuildchain project kfx-admission envelope.json \\\n  --assessment-time 150 \\\n  --json\n```\n\nBoth commands call the public artifact-verification-envelope verifier. The\nprojected `attestation`, `trustInputs`, and `kfdAssessment` are direct copies of\nthe sealed envelope, and `envelopeRoot` stays identical across Node and CLI.\nSee [`artifact-verification-envelope.md`](artifact-verification-envelope.md).\n\nVerify infra-contract lifecycle evidence bundles:\n\n```bash\nbuildchain infra-contract --mode ci --source-sha \"$GITHUB_SHA\"\nbuildchain verify infra-contract-evidence-bundle .buildchain/infra-contract-evidence-bundle.json\n```\n\nThe infra-contract `ci` mode is mutation-free. It writes validate, plan,\ncontract, propagation dry-run, evidence bundle, and verification JSON artifacts\nunder `.buildchain/`, giving reusable workflows one standard responsibility\nchain instead of hand-written command sequences.\n\nThe infra-contract verifier is read-only. It recomputes the bundle hash and\nchecks that desired, plan, approval, apply, observe, contract, and propagate\nevidence remain bound to the same contract artifact. It also recomputes the\nbundle validation summary, so stale or misleading summary booleans fail closed\neven when the bundle hash has been refreshed.\n\n`buildchain release --dry-run` explains the release-line state machine before a\nmaintainer opens or merges a channel PR:\n\n```bash\nbuildchain release --dry-run --target-ref alpha/v3/v3.0\nbuildchain release --dry-run --target-ref release/v3/v3.0 --sha <verified-sha>\nbuildchain release dry-run --target-ref publish-gate/major --source-ref release/v3/v3.0\nbuildchain release explain --target-ref alpha/v3/v3.0 --json\n```\n\nThis is a Buildchain-level dry-run, not an npm dry-run. It explains the legal\nsource branch, exact release or alpha tags, floating tags, channel branches,\nversion-state files, governance checks, and publish transaction behavior that\nwould apply if the corresponding PR merge were promoted. It does not move\nbranches, move tags, edit files, publish npm packages, or run lifecycle publish\ncommands. `release explain` is the same explanation surface with a clearer name.\nPass `--json` for a machine-readable plan.\n\n`buildchain transaction inspect` is the top-level recovery inspection command\nfor the publish transaction state:\n\n```bash\nbuildchain transaction inspect --version v3.0.1-alpha.2\n```\n\nIt reads or locally initializes the durable transaction record and validates\navailable publish evidence. Remote durable refs and public Git ref finalization\nremain owned by `actions/promote-buildchain-ref`; the CLI inspection surface is\nfor preflight and recovery reasoning before a maintainer reruns or resumes a\npromotion.\n\n`buildchain npm dry-run` verifies the package shape before a release tag exists:\n\n```bash\nbuildchain npm dry-run --json\n```\n\nThe command validates `package.json`, infers the exact release tag\n`v${package.json.version}`, chooses npm dist-tag `alpha` for prereleases and\n`latest` for stable releases, runs `npm pack --dry-run --json`, and then runs\n`npm publish --dry-run --access public --tag <alpha|latest>` unless\n`--skip-npm-publish-dry-run` is passed. It never performs a real publish.\n\n## npm Publish Gate\n\nBuildchain's own npm package is published from\n`.github/workflows/buildchain-ref-promotion.yml`, inside the same publish\ntransaction that promotes release refs:\n\n- `v3.0.3-alpha.0` publishes to npm with dist-tag `alpha`.\n- `v3.0.2` publishes to npm with dist-tag `latest`.\n- moving refs such as `v3`, `v3.0`, and `v3.0-alpha` do not match the publish\n  workflow and do not publish.\n\nThe promotion workflow uses npm Trusted Publishing through GitHub Actions OIDC.\nIt runs on a GitHub-hosted runner with `id-token: write`, but it does not\nmanually run the release-candidate resolver or promote action. Buildchain's own\ndogfood path calls the declarative `release-candidate-promote.yml` wrapper with\nchannel, target ref/SHA, PR-stage workflow, artifact, status-check, and passport\ninputs. The wrapper generates the version-state commit, runs\n`lifecycle.verify`, runs `lifecycle.publish`, writes Buildchain publish\nevidence, validates that evidence, and only then moves exact tags and floating\nrefs.\n\n```bash\nnode scripts/npm-publish-transaction.mjs\n```\n\nBefore the first real release, configure npm Trusted Publishing for:\n\n- package: `@kungfu-tech/buildchain`\n- repository: `kungfu-systems/buildchain`\n- workflow: `.github/workflows/buildchain-ref-promotion.yml`\n\nNo npm package is published by manual dispatch or ordinary branch builds.\nManual dispatch on `.github/workflows/npm-publish.yml` remains dry-run only, so\nmaintainers can verify package contents and npm publish shape before opening or\nmerging the release PR."
     },
     {
       "id": "manual:consumer-issue-reporting",
@@ -578,7 +644,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/consumer-issue-reporting.md",
-      "digest": "sha256:96804310360c02f408fee9d540385d875a40d09bef046c3df369228d311a1cdd",
+      "digest": "sha256:324342b10e69ca5ce6d04a267fb5fc2a6b52e674f6252eec2121557c5542f729",
       "headings": [
         {
           "level": 1,
@@ -601,7 +667,7 @@
           "anchor": "javascript-api"
         }
       ],
-      "markdown": "# Consumer Issue Reporting\n\nBuildchain ships a first-class issue reporting surface for consumer workflows.\nIt lets a repository open or update a Buildchain-owned GitHub issue when a\nBuildchain reusable workflow, action, or toolkit API produces a failure that\nneeds Buildchain maintainers.\n\n## Trust model\n\nThe consumer workflow must provide a token with issue-write access to the\ntarget repository. A repository's default `GITHUB_TOKEN` only writes to its own\nrepository, so cross-repository reports should use a GitHub App installation\ntoken scoped to:\n\n- the `kungfu-systems/buildchain` repository;\n- Issues: read and write;\n- no content write permission unless another workflow step needs it.\n\nThe recommended pattern is:\n\n```yaml\n- uses: actions/create-github-app-token@v2\n  id: buildchain-issue-token\n  with:\n    app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}\n    private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}\n    owner: kungfu-systems\n    repositories: buildchain\n\n- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v3\n  if: failure()\n  with:\n    token: ${{ steps.buildchain-issue-token.outputs.token }}\n    summary: \"Buildchain reusable build failed before artifact finalization\"\n    failure-code: reusable-build-failed\n    diagnostics-path: .buildchain/artifacts/diagnostics.json\n    buildchain-ref: ${{ inputs.buildchain-ref || 'v2' }}\n```\n\n## Behavior\n\n`report-buildchain-issue` builds an issue body with consumer repository,\nworkflow, ref, SHA, Buildchain ref/version, diagnostics links, and optional\ndetails. It computes a stable fingerprint and embeds a hidden marker:\n\n```text\nbuildchain-consumer-issue:fingerprint=<sha256-prefix>\n```\n\nWhen an open issue with the same marker exists, the action comments on it with\nthe new run evidence. Otherwise it creates a new issue. Consumers may pass an\nexplicit `fingerprint` when they need a different dedupe boundary.\n\nThe action is fail-soft by default. It retries GitHub API 429/5xx responses and\nconnection failures, redacts common secret/token/private-key patterns, truncates\nlarge bodies, and retries issue creation without labels if the target\nrepository does not have the configured labels yet.\n\nSet `fail-on-error: \"true\"` only when the reporting step is part of a release\ngate and missing Buildchain feedback should stop the workflow.\n\n## JavaScript API\n\nConsumer scripts can import the same implementation:\n\n```js\nimport {\n  buildConsumerIssueReport,\n  reportBuildchainIssue,\n} from \"@kungfu-tech/buildchain/issue-reporting\";\n\nconst result = await reportBuildchainIssue({\n  token: process.env.BUILDCHAIN_ISSUE_TOKEN,\n  summary: \"Native artifact manifest is incomplete\",\n  failureCode: \"native-manifest-incomplete\",\n  buildchainRef: \"v2\",\n  diagnosticsPath: \".buildchain/artifacts/diagnostics.json\",\n});\n```\n\nUse `buildConsumerIssueReport` for dry-run validation, previewing redaction, or\nunit tests without calling GitHub."
+      "markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-consumer-issue-reporting\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-31\n  invisible_context: not asserted\n---\n\n# Consumer Issue Reporting\n\nBuildchain ships a first-class issue reporting surface for consumer workflows.\nIt lets a repository open or update a Buildchain-owned GitHub issue when a\nBuildchain reusable workflow, action, or toolkit API produces a failure that\nneeds Buildchain maintainers.\n\n## Trust model\n\nThe consumer workflow must provide a token with issue-write access to the\ntarget repository. A repository's default `GITHUB_TOKEN` only writes to its own\nrepository, so cross-repository reports should use a GitHub App installation\ntoken scoped to:\n\n- the `kungfu-systems/buildchain` repository;\n- Issues: read and write;\n- no content write permission unless another workflow step needs it.\n\nThe recommended pattern is:\n\n```yaml\n- uses: actions/create-github-app-token@v2\n  id: buildchain-issue-token\n  with:\n    app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}\n    private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}\n    owner: kungfu-systems\n    repositories: buildchain\n\n- uses: kungfu-systems/buildchain/actions/report-buildchain-issue@v3\n  if: failure()\n  with:\n    token: ${{ steps.buildchain-issue-token.outputs.token }}\n    summary: \"Buildchain reusable build failed before artifact finalization\"\n    failure-code: reusable-build-failed\n    diagnostics-path: .buildchain/artifacts/diagnostics.json\n    buildchain-ref: ${{ inputs.buildchain-ref || 'v3' }}\n```\n\n## Behavior\n\n`report-buildchain-issue` builds an issue body with consumer repository,\nworkflow, ref, SHA, Buildchain ref/version, diagnostics links, and optional\ndetails. It computes a stable fingerprint and embeds a hidden marker:\n\n```text\nbuildchain-consumer-issue:fingerprint=<sha256-prefix>\n```\n\nWhen an open issue with the same marker exists, the action comments on it with\nthe new run evidence. Otherwise it creates a new issue. Consumers may pass an\nexplicit `fingerprint` when they need a different dedupe boundary.\n\nThe action is fail-soft by default. It retries GitHub API 429/5xx responses and\nconnection failures, redacts common secret/token/private-key patterns, truncates\nlarge bodies, and retries issue creation without labels if the target\nrepository does not have the configured labels yet.\n\nSet `fail-on-error: \"true\"` only when the reporting step is part of a release\ngate and missing Buildchain feedback should stop the workflow.\n\n## JavaScript API\n\nConsumer scripts can import the same implementation:\n\n```js\nimport {\n  buildConsumerIssueReport,\n  reportBuildchainIssue,\n} from \"@kungfu-tech/buildchain/issue-reporting\";\n\nconst result = await reportBuildchainIssue({\n  token: process.env.BUILDCHAIN_ISSUE_TOKEN,\n  summary: \"Native artifact manifest is incomplete\",\n  failureCode: \"native-manifest-incomplete\",\n  buildchainRef: \"v3\",\n  diagnosticsPath: \".buildchain/artifacts/diagnostics.json\",\n});\n```\n\nUse `buildConsumerIssueReport` for dry-run validation, previewing redaction, or\nunit tests without calling GitHub."
     },
     {
       "id": "manual:controller-evidence",
@@ -667,7 +733,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/dev-alpha-candidate-patrol.md",
-      "digest": "sha256:d275b4dbcb5eca8d927e00aae1635acc2bd6337e88e052d76df2e52f7ebf6809",
+      "digest": "sha256:9f8fa0c89f833fe654cae47c19fcb49ac28c892a16e14e1582e0342c82954e61",
       "headings": [
         {
           "level": 1,
@@ -680,7 +746,7 @@
           "anchor": "reusable-workflow"
         }
       ],
-      "markdown": "---\nstatus: preview\nperiod: ongoing\ntheme: dev-alpha-candidate-patrol\ndoc_type: architecture-and-usage\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-07-27\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-27\n  visible_context: Existing Buildchain stable-candidate source locks, Kungfu exact-source Alpha preflight, Dev Patrol, and repository release governance.\n  invisible_context_boundary: No credentials, private logs, or private configuration were used.\n---\n\n# Dev to Alpha Candidate Patrol\n\nBuildchain provides a reusable observation and single-flight PR controller for\nrepositories that promote a development branch into a protected Alpha branch.\nIt does not publish Alpha. The read-only observer reads the exact heads of both\nbranches, walks the\nbounded development history from newest to oldest (stopping early at the Alpha\nhead), and selects the newest commit that satisfies all of these conditions:\n\n- the source is strictly ahead of the recorded target head;\n- the latest completed Dev Patrol for that exact commit SHA succeeded;\n- the latest completed Alpha preflight for the same commit SHA succeeded; and\n- both runs are within the caller's evidence age limit.\n\nThe selected commit can be behind the observed development head when newer\ncommits have not completed both workflows yet. The decision binds the observed\nhead, selected SHA, and count of skipped newer commits. This makes a slow native\nverification lane live under continuous development without silently treating\nan unqualified head as releasable.\n\nHistory discovery is bounded to the newest 1000 development commits. The\ncontroller then compares the selected SHA to the exact Alpha head before it can\nbe eligible, so a bounded scan cannot turn a commit outside the promotion\nancestry into a candidate.\n\nThe decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records the\nsource and target branches and SHAs, comparison distance, workflow paths, run\nidentities and attempts, completion times, URLs, policy, and a canonical decision\nroot. Missing, stale, failed, duplicate, or source-mismatched evidence fails\nclosed as an auditable `blocked` or `stale` observation and cannot enter\nsettlement.\n\nThe companion state is\n`kungfu-buildchain-dev-alpha-candidate-state/v1`. Its current state is one of:\n\n- `observed`: no exact candidate is currently settleable;\n- `eligible-for-settlement`: a qualified candidate exists and no managed Alpha\n  candidate PR is active;\n- `active`: exactly one managed candidate PR is open;\n- `retained-next`: an active PR remains authoritative and the newest different\n  qualified SHA is retained as `nextCandidate`;\n- `stale`: the available exact-SHA evidence pair is outside policy age; or\n- `blocked`: qualification or reconciliation failed closed.\n\nWhen a newer qualified SHA replaces an earlier `nextCandidate`, the state also\nrecords that earlier SHA as `supersededCandidate`. Every state carries exact\nrepository, source/target refs and SHAs, workflow-run evidence through the\ncandidate decision, and canonical decision/state roots.\n\n## Reusable workflow\n\nCall `.github/workflows/dev-alpha-candidate-patrol.yml` from a thin repository\nworkflow. Start with `dry-run: true`. The reusable workflow always runs an\n`observe` job with only Actions/content/pull-request read permissions. Once the\nrepository has proven that its two workflow names and branch topology produce\nexact same-SHA evidence, it may set `settlement-authorized: true` and\n`dry-run: false`. The older `create-pull-request` input remains a compatibility\nalias for settlement authorization.\n\nRepositories whose promotion policy requires a machine-readable PR declaration\ncan pass it through `pull-request-body-prefix`. Buildchain prepends that trusted,\nrepository-owned text only when it creates the candidate PR and preserves it\nwhen later controller observations update the managed state marker. Keep the\ndeclaration source-controlled in the caller workflow and update it whenever the\nqualified development delta changes its release or architecture settlement.\nBuildchain rejects a prefix that attempts to inject its managed controller\nmarker.\n\nThe separately permissioned `settle` job re-runs the exact observation before\nany write. With no active managed candidate, it creates one branch named from\nthe target branch and the first 12 characters of the full source SHA. An\nexisting branch must point to the same full SHA or the run fails. With one\nactive managed candidate, it only updates the machine-readable state marker in\nthat PR body so repeated events and rapid dev progress cannot create another\ncandidate PR or another heavy candidate build. Foreign human-authored Alpha PRs\nare ignored. More than one open Buildchain-managed candidate fails closed.\n\nThe PR body is the bounded durable controller state: it preserves the active\ncandidate and newest retained `nextCandidate` without introducing an always-on\nservice. Once the active PR settles or is abandoned, the next execution\nrecomputes current exact-SHA qualification and creates only the newest still\nfresh candidate. It never trusts a `workflow_run` trigger SHA as evidence.\n\nConsumers should invoke this workflow after relevant qualification workflow\ncompletion and from an offset periodic fallback. GitHub may delay scheduled\nruns, so the event path supplies low latency while the fallback supplies\nrecovery. Workflow concurrency plus the server-side open-PR reconciliation\nmakes duplicate or delayed events idempotent.\n\nThe workflow never moves the Alpha ref directly, merges or auto-merges the pull\nrequest, publishes npm, creates a Git tag or GitHub Release, or changes branch\nprotection. Those remain repository-owned protected settlement actions."
+      "markdown": "---\nstatus: preview\nperiod: ongoing\ntheme: dev-alpha-candidate-patrol\ndoc_type: architecture-and-usage\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-07-29\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-29\n  visible_context: Existing Buildchain source locks, Kungfu exact-source Alpha preflight, Dev Patrol, repository release governance, and the consumer-owned settlement renderer threat model.\n  invisible_context_boundary: No credentials, private logs, or private configuration were used.\n---\n\n# Dev to Alpha Candidate Patrol\n\nBuildchain provides a reusable observation and single-flight PR controller for\nrepositories that promote a development branch into a protected Alpha branch.\nIt does not publish Alpha. The read-only observer reads the exact heads of both\nbranches, walks the\nbounded development history from newest to oldest (stopping early at the Alpha\nhead), and selects the newest commit that satisfies all of these conditions:\n\n- the source is strictly ahead of the recorded target head;\n- the latest completed Dev Patrol for that exact commit SHA succeeded;\n- the latest completed Alpha preflight for the same commit SHA succeeded; and\n- both runs are within the caller's evidence age limit.\n\nThe selected commit can be behind the observed development head when newer\ncommits have not completed both workflows yet. The decision binds the observed\nhead, selected SHA, and count of skipped newer commits. This makes a slow native\nverification lane live under continuous development without silently treating\nan unqualified head as releasable.\n\nHistory discovery is bounded to the newest 1000 development commits. The\ncontroller then compares the selected SHA to the exact Alpha head before it can\nbe eligible, so a bounded scan cannot turn a commit outside the promotion\nancestry into a candidate.\n\nThe decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records the\nsource and target branches and SHAs, comparison distance, workflow paths, run\nidentities and attempts, completion times, URLs, policy, and a canonical decision\nroot. Missing, stale, failed, duplicate, or source-mismatched evidence fails\nclosed as an auditable `blocked` or `stale` observation and cannot enter\nsettlement.\n\nThe companion state is\n`kungfu-buildchain-dev-alpha-candidate-state/v1`. Its current state is one of:\n\n- `observed`: no exact candidate is currently settleable;\n- `eligible-for-settlement`: a qualified candidate exists and no managed Alpha\n  candidate PR is active;\n- `active`: exactly one managed candidate PR is open;\n- `retained-next`: an active PR remains authoritative and the newest different\n  qualified SHA is retained as `nextCandidate`;\n- `stale`: the available exact-SHA evidence pair is outside policy age; or\n- `blocked`: qualification or reconciliation failed closed.\n\nWhen a newer qualified SHA replaces an earlier `nextCandidate`, the state also\nrecords that earlier SHA as `supersededCandidate`. Every state carries exact\nrepository, source/target refs and SHAs, workflow-run evidence through the\ncandidate decision, and canonical decision/state roots.\n\n## Reusable workflow\n\nCall `.github/workflows/dev-alpha-candidate-patrol.yml` from a thin repository\nworkflow. Start with `dry-run: true`. The reusable workflow always runs an\n`observe` job with only Actions/content/pull-request read permissions. Once the\nrepository has proven that its two workflow names and branch topology produce\nexact same-SHA evidence, it may set `settlement-authorized: true` and\n`dry-run: false`. The older `create-pull-request` input remains a compatibility\nalias for settlement authorization.\n\nRepositories whose promotion policy requires a machine-readable PR declaration\ncan pass static text through `pull-request-body-prefix`. When the declaration\ndepends on the exact qualified delta, use `pull-request-body-prefix-renderer`\ninstead. It names a repository-relative Node.js file in the consumer checkout.\nThe read-only `observe` job checks out the selected SHA with credentials disabled,\nruns the renderer with a reduced environment, and requires it to write UTF-8 text\nto `BUILDCHAIN_CHANNEL_PATROL_PR_BODY_PREFIX_OUTPUT`. The renderer also receives\nthe selected SHA plus source and target branch names. It may derive a declaration\nfrom the exact checkout and `origin/<target-branch>` without receiving the\npromotion token.\n\nStatic and rendered prefixes are mutually exclusive. A renderer failure, path\nescape, source-SHA mismatch, empty or oversized result, invalid UTF-8, or managed\ncontroller-marker injection fails before the write-permission job can run. The\nrendered bytes are retained with the read-only observation artifact and passed\nto `settle` as a job output, so the candidate PR is created with the correct\ndeclaration on its first write. Buildchain preserves that repository-owned text\nwhen later observations update only the managed state marker. Before any write,\n`settle` also requires its fresh observation to select the same SHA that produced\nthe rendered bytes. Concurrent qualification progress therefore fails closed\nand is recomputed by the next patrol instead of attaching a declaration to the\nwrong candidate.\n\nThe separately permissioned `settle` job re-runs the exact observation before\nany write. With no active managed candidate, it creates one branch named from\nthe target branch and the first 12 characters of the full source SHA. An\nexisting branch must point to the same full SHA or the run fails. With one\nactive managed candidate, it only updates the machine-readable state marker in\nthat PR body so repeated events and rapid dev progress cannot create another\ncandidate PR or another heavy candidate build. Foreign human-authored Alpha PRs\nare ignored. More than one open Buildchain-managed candidate fails closed.\n\nThe PR body is the bounded durable controller state: it preserves the active\ncandidate and newest retained `nextCandidate` without introducing an always-on\nservice. Once the active PR settles or is abandoned, the next execution\nrecomputes current exact-SHA qualification and creates only the newest still\nfresh candidate. It never trusts a `workflow_run` trigger SHA as evidence.\n\nConsumers should invoke this workflow after relevant qualification workflow\ncompletion and from an offset periodic fallback. GitHub may delay scheduled\nruns, so the event path supplies low latency while the fallback supplies\nrecovery. Workflow concurrency plus the server-side open-PR reconciliation\nmakes duplicate or delayed events idempotent.\n\nThe workflow never moves the Alpha ref directly, merges or auto-merges the pull\nrequest, publishes npm, creates a Git tag or GitHub Release, or changes branch\nprotection. Those remain repository-owned protected settlement actions."
     },
     {
       "id": "manual:github-artifact-attestation",
@@ -747,7 +813,7 @@
       ],
       "maturity": "preview",
       "sourcePath": "docs/github-governance-authority.md",
-      "digest": "sha256:b8c3d9ad53c2509bbd95804ccc31f6aa89989c3aadf3a2b75d9c73aef168b7e8",
+      "digest": "sha256:197ae7a949817f60f46b67b060731df14d0343d9daecd7d6eacfae9a526b6a12",
       "headings": [
         {
           "level": 1,
@@ -780,7 +846,7 @@
           "anchor": "mutation-and-rollback-boundary"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: github-governance-authority\ndoc_type: protocol\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-07-24\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-24\n  limits: Live GitHub state and account recovery remain provider-controlled and must be re-audited.\n---\n\n# GitHub Governance Authority\n\nBuildchain treats GitHub governance as an independently verified, fail-closed\nauthority boundary. A green CI run, a CODEOWNERS file, an API success response,\nor an administrator's assertion is not sufficient by itself. The verifier\ncombines the exact CODEOWNERS bytes from the target base branch, classic branch\nprotection, every applicable repository or organization ruleset, account role\nclasses, plan capability, required checks, and provider-read completeness into\none short-lived immutable receipt.\n\nThe machine contract is\n`@kungfu-tech/buildchain/github-governance-authority`. Its policy root covers\nthe managed-zone repository and target-ref admission rules, the exact\nrequired-check context/App bindings and strict-update semantics for every\npublic authoritative target, the dual-account authority split, protected\nverifier paths, native review requirements, break-glass constraints, and the\nexplicit trust boundary.\n\n## Trust boundary and non-claims\n\nThe trusted computing base contains GitHub service integrity, retained\norganization-owner recovery custody, the `kungfu-origin` review/governance\nidentity, the exact Buildchain verifier, and official publication identities.\nThe protocol does not claim resistance to compromise of GitHub itself,\ncompromise of all retained owner and recovery anchors, or malicious control of\nall independent trust anchors. A governance receipt grants no GitHub\npermission and is not a bearer credential.\n\n`dongkeren` is the development and pull-request author identity.\n`kungfu-origin` is the independent Code Owner and governance identity. A\nqualifying receipt requires the development identity to be active without an\nadministrator or maintainer role and requires the review identity to retain the\nadmitted governance role. Account recovery and retained root custody remain\noutside normal contributor and workflow paths.\n\n## Effective policy\n\nThe verifier evaluates native provider layers together. Every authoritative\ntarget must require:\n\n- a pull request, at least one independent Code Owner approval, and a fresh\n  approval after the latest reviewable push;\n- administrator enforcement, resolved review conversations, and a non-empty\n  required-check set whose exact contexts, GitHub App producer identities, and\n  strict-update setting match the versioned target policy;\n- no unapproved bypass actor, force push, or protected-ref deletion. Managed\n  dev/alpha/release ref bookkeeping may admit only the exact GitHub Actions App\n  identity versioned for that target; user and team bypass actors remain\n  non-qualifying;\n- exact last-match ownership of CODEOWNERS and the governance descriptor,\n  collector, rollout planner, and scheduled audit workflow;\n- complete readable GitHub API evidence. Missing, forbidden, ambiguous, or\n  malformed provider state is non-qualifying.\n\nRepository and organization rulesets are additive to classic branch\nprotection. Inspecting only one layer is insufficient because an applicable\nbypass or weaker update path in another layer can invalidate the effective\npolicy.\n\n## Repository and plan admission\n\nThe 2026-07-24 baseline contains 16 managed repositories: 13 public and three\nprivate. Public repository names are versioned in the descriptor. Private\nrepository names are never emitted in public evidence; their identities are\nrepresented by stable roots derived from the GitHub provider repository ID,\nindependent of the governance policy root. This prevents a policy revision from\nchanging repository identity or creating a circular admission dependency. A\nnewly discovered repository or target ref is non-authoritative until explicitly\nadmitted.\n\nThe descriptor also versions every active public merge target. The full audit\nevaluates one receipt per authoritative target rather than assuming the default\nbranch represents dev, alpha, release, or major publish-gate branches. The live\ndefault branch is always included even if it drifts outside the registry, in\nwhich case it is non-qualifying. Retained historical channels and generated\nper-release publish-gate refs are not silently deleted or promoted to current\nauthority; they require an explicit registry revision before they can qualify.\n\nFor an admitted private repository, the active target set is the current\ndefault branch plus existing alpha/release siblings on the same version line.\nIts required-check bindings remain non-qualifying until their sanitized binding\nroots are sealed into the private identity entry after supported native\nprotection exists.\n\nPublic repositories can qualify on supported Free, Team, or Enterprise\nenforcement. Private repositories and organization-wide rules require Team or\nEnterprise capability. On an unsupported plan they remain explicitly\n`non-authoritative-plan-capability-required` and publication-ineligible. The\nverifier does not replace missing native enforcement with CI or documentation,\nand the implementation never makes a private repository public as a\nworkaround.\n\n## Read-only audit\n\nRun the organization audit without mutation:\n\n```bash\nbuildchain audit github-governance \\\n  --organization kungfu-systems \\\n  --output github-governance.json \\\n  --json\n```\n\nLimit a canary to one repository:\n\n```bash\nbuildchain audit github-governance \\\n  --repository kungfu-systems/buildchain \\\n  --target-ref dev/v3/v3.0 \\\n  --require-qualifying \\\n  --json\n```\n\nProtected merge and publication consumers verify the receipt against the exact\nrepository, target base ref, policy root, freshness window, and exact\nBuildchain verifier source revision. Non-dry-run publication does not trust a\ncaller-supplied JSON hash: it mints a bounded token for the dedicated read-only\ngovernance auditor GitHub App, recollects live provider state with the exact\nBuildchain runtime, requires the resulting single-repository/single-target\naudit to qualify, and consumes that independently generated receipt. Missing\nApp configuration or unreadable provider state denies publication before\nprovider mutation. The publication authority workflow is itself an explicit\nCode Owner path.\n\nThe publication authority job and every reusable-workflow caller grant the\nbuilt-in `GITHUB_TOKEN` only `actions: read`, `checks: read`, `contents: read`,\nand `pull-requests: read`. The dedicated auditor App independently recollects\nthe organization-wide governance receipt, while these job-scoped permissions\nallow the exact publication transaction audit to resolve required check runs\nand merged pull-request review lineage. Omitting either read permission makes\nthe transaction evidence incomplete and therefore non-qualifying.\n\nThe output is sanitized. Public repositories retain their public identity.\nPrivate repositories expose only an identity root, visibility class, target\nref, sanitized required-check bindings and fact roots, and a qualifying or\nnon-qualifying decision. Tokens, cookies, recovery material, private\nCODEOWNERS bytes, raw permission payloads, and credential-bearing URLs are\nnever included.\n\n## Mutation and rollback boundary\n\nLive role, ruleset, branch-protection, Actions, Environment, or repository\nchanges are separate from audit. Every mutation starts from a read-only\ninventory and a frozen rollback snapshot. A rollout plan binds both roots and\nlists the exact API operation, impact, expected observation, and inverse\noperation. Apply must stop on the first unexplained drift and must perform a\npost-change read-back before continuing to the next bounded canary.\n\nPlan one exact branch without mutation:\n\n```bash\nbuildchain github-governance plan \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v3/v3.0 \\\n  --required-check check \\\n  --required-check-app-id check=15368 \\\n  --required-approvals 1 \\\n  --snapshot-output rollback.json \\\n  --plan-output rollout.json\n```\n\nAn already protected check preserves its observed GitHub App binding. Every new\nrequired check must declare `--required-check-app-id <context>=<app-id>`;\ncontext-only replacement is rejected because it would broaden which producer\ncan satisfy the gate.\n\nClassic branch-protection bypass allowances and ruleset bypass actors are both\npart of the effective policy. Reconciliation writes explicit empty user, team,\nand App bypass lists and verifies those lists after apply; omitting the provider\nfield is not treated as removal because GitHub may preserve the prior value.\n\nThe plan prints a `planRoot`. Apply requires that exact root and stops if live\nprotection no longer matches the frozen inventory:\n\n```bash\nbuildchain github-governance apply \\\n  --plan-json rollout.json \\\n  --confirm-plan-root sha256:...\n```\n\nRollback is separately explicit and root-bound:\n\n```bash\nbuildchain github-governance rollback \\\n  --plan-json rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nFor an admitted exact target, classic branch protection can also be compiled\ndirectly from the authority descriptor. This mode preserves both App-bound\nchecks and intentionally unbound check contexts such as Kungfu alpha's\n`build`, rather than guessing a provider App identity.\n\n```bash\nbuildchain github-governance protection-policy-plan \\\n  --repository kungfu-systems/kungfu \\\n  --branch alpha/v4/v4.0 \\\n  --snapshot-output protection-rollback.json \\\n  --plan-output protection-rollout.json\n\nbuildchain github-governance protection-policy-apply \\\n  --plan-json protection-rollout.json \\\n  --confirm-plan-root sha256:...\n\nbuildchain github-governance protection-policy-rollback \\\n  --plan-json protection-rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nFor an admitted exact target, repository ruleset reconciliation compiles the\ntarget descriptor into the provider body. It replaces bypass actors with the\nexact provider-admitted desired set, requires fresh Code Owner approval and\nresolved review threads, and binds required checks plus strict-update semantics\nto the target policy. Newly synthesized managed rules include GitHub's explicit\ncanonical defaults so the frozen expected root matches provider read-back.\nRepository rulesets default to no bypass actors. The\ndescriptor's target-bound GitHub Actions allowance is an upper bound on\neffective provider state, not a requirement to add that actor to every\nprotection layer; when needed, the built-in App allowance is expressed by\nclassic branch protection. The target condition must contain exactly one\nbranch; unrelated rules and conditions are preserved in place.\n\n```bash\nbuildchain github-governance ruleset-policy-plan \\\n  --repository kungfu-systems/buildchain \\\n  --branch alpha/v2/v2.14 \\\n  --ruleset-id 19518955 \\\n  --snapshot-output ruleset-rollback.json \\\n  --plan-output ruleset-rollout.json\n\nbuildchain github-governance ruleset-policy-apply \\\n  --plan-json ruleset-rollout.json \\\n  --confirm-plan-root sha256:...\n\nbuildchain github-governance ruleset-policy-rollback \\\n  --plan-json ruleset-rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nThe narrower `ruleset-plan` mode changes only `bypass_actors`; it remains\navailable for a bypass-only canary, but it cannot prove that an effective\nruleset matches the target descriptor. Both modes require the frozen ruleset\nsnapshot root for rollback.\n\nPaid-plan purchase, billing, legal/account-owner decisions, and any operation\nthat could remove the last recoverable owner remain external human gates.\nBreak-glass is disabled by default and, if ever admitted, must be separately\nauthenticated, reason-bound, time-bounded, independently receipted, and\nfollowed by mandatory restoration and root comparison."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: github-governance-authority\ndoc_type: protocol\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-30\n  limits: Live GitHub state and account recovery remain provider-controlled and must be re-audited.\n---\n\n# GitHub Governance Authority\n\nBuildchain treats GitHub governance as an independently verified, fail-closed\nauthority boundary. A green CI run, a CODEOWNERS file, an API success response,\nor an administrator's assertion is not sufficient by itself. The verifier\ncombines the exact CODEOWNERS bytes from the target base branch, classic branch\nprotection, every applicable repository or organization ruleset, account role\nclasses, plan capability, required checks, and provider-read completeness into\none short-lived immutable receipt.\n\nThe machine contract is\n`@kungfu-tech/buildchain/github-governance-authority`. Its policy root covers\nthe managed-zone repository and target-ref admission rules, the exact\nrequired-check context/App bindings and strict-update semantics for every\npublic authoritative target, the dual-account authority split, protected\nverifier paths, native review requirements, break-glass constraints, and the\nexplicit trust boundary.\n\n## Trust boundary and non-claims\n\nThe trusted computing base contains GitHub service integrity, retained\norganization-owner recovery custody, the `kungfu-origin` review/governance\nidentity, the exact Buildchain verifier, and official publication identities.\nThe protocol does not claim resistance to compromise of GitHub itself,\ncompromise of all retained owner and recovery anchors, or malicious control of\nall independent trust anchors. A governance receipt grants no GitHub\npermission and is not a bearer credential.\n\n`dongkeren` is the development and pull-request author identity.\n`kungfu-origin` is the independent Code Owner and governance identity. A\nqualifying receipt requires the development identity to be active without an\nadministrator or maintainer role and requires the review identity to retain the\nadmitted governance role. Account recovery and retained root custody remain\noutside normal contributor and workflow paths.\n\n## Effective policy\n\nThe verifier evaluates native provider layers together. Every authoritative\ntarget must require:\n\n- a pull request, at least one independent Code Owner approval, and a fresh\n  approval after the latest reviewable push;\n- administrator enforcement, resolved review conversations, and a non-empty\n  required-check set whose exact contexts, GitHub App producer identities, and\n  strict-update setting match the versioned target policy;\n- no unapproved bypass actor, force push, or protected-ref deletion. Managed\n  dev/alpha/release ref bookkeeping may admit only the exact GitHub Actions App\n  identity versioned for that target; user and team bypass actors remain\n  non-qualifying;\n- exact last-match ownership of CODEOWNERS and the governance descriptor,\n  collector, rollout planner, and scheduled audit workflow;\n- complete readable GitHub API evidence. Missing, forbidden, ambiguous, or\n  malformed provider state is non-qualifying.\n\nRepository and organization rulesets are additive to classic branch\nprotection. Inspecting only one layer is insufficient because an applicable\nbypass or weaker update path in another layer can invalidate the effective\npolicy.\n\nWhen an admitted default development branch uses GitHub merge queue, its\ncandidate-source, queue-lease, and final build checks are one exact authority\nset. The queue lease may remain intentionally unbound while workflow-produced\nchecks retain their GitHub Actions App binding; strictness must match the live\nqueue ruleset.\n\n## Repository and plan admission\n\nThe 2026-07-30 baseline contains 16 managed public repositories. The descriptor\nsets `managedVisibilities` to `public`; private repositories are outside the\nmanaged-zone inventory and do not produce governance receipts. Public\nrepository names are versioned in the descriptor. A newly discovered public\nrepository or target ref is non-authoritative until explicitly admitted.\n\nThe descriptor also versions every active public merge target. The full audit\nevaluates one receipt per authoritative target rather than assuming the default\nbranch represents dev, alpha, release, or major publish-gate branches. The live\ndefault branch is always included even if it drifts outside the registry, in\nwhich case it is non-qualifying. Retained historical channels and generated\nper-release publish-gate refs are not silently deleted or promoted to current\nauthority; they require an explicit registry revision before they can qualify.\n\nPublic repositories can qualify on supported Free, Team, or Enterprise\nenforcement. Organization-wide rules require Team or Enterprise capability.\nThe verifier does not reinterpret an excluded private repository as qualifying,\nreplace missing native enforcement with CI or documentation, or make a private\nrepository public as a workaround.\n\n## Read-only audit\n\nRun the organization audit without mutation:\n\n```bash\nbuildchain audit github-governance \\\n  --organization kungfu-systems \\\n  --output github-governance.json \\\n  --json\n```\n\nLimit a canary to one repository:\n\n```bash\nbuildchain audit github-governance \\\n  --repository kungfu-systems/buildchain \\\n  --target-ref dev/v3/v3.0 \\\n  --require-qualifying \\\n  --json\n```\n\nProtected merge and publication consumers verify the receipt against the exact\nrepository, target base ref, policy root, freshness window, and exact\nBuildchain verifier source revision. Non-dry-run publication does not trust a\ncaller-supplied JSON hash: it mints a bounded token for the dedicated read-only\ngovernance auditor GitHub App, recollects live provider state with the exact\nBuildchain runtime, requires the resulting single-repository/single-target\naudit to qualify, and consumes that independently generated receipt. Missing\nApp configuration or unreadable provider state denies publication before\nprovider mutation. The publication authority workflow is itself an explicit\nCode Owner path.\n\nThe publication authority job and every reusable-workflow caller grant the\nbuilt-in `GITHUB_TOKEN` only `actions: read`, `checks: read`, `contents: read`,\nand `pull-requests: read`. The dedicated auditor App independently recollects\nthe organization-wide governance receipt, while these job-scoped permissions\nallow the exact publication transaction audit to resolve required check runs\nand merged pull-request review lineage. Omitting either read permission makes\nthe transaction evidence incomplete and therefore non-qualifying.\n\nThe output is sanitized. Managed public repositories retain their public\nidentity. Excluded private repositories produce no receipt or diagnostic.\nTokens, cookies, recovery material, private CODEOWNERS bytes, raw permission\npayloads, and credential-bearing URLs are never included.\n\n## Mutation and rollback boundary\n\nLive role, ruleset, branch-protection, Actions, Environment, or repository\nchanges are separate from audit. Every mutation starts from a read-only\ninventory and a frozen rollback snapshot. A rollout plan binds both roots and\nlists the exact API operation, impact, expected observation, and inverse\noperation. Apply must stop on the first unexplained drift and must perform a\npost-change read-back before continuing to the next bounded canary.\n\nPlan one exact branch without mutation:\n\n```bash\nbuildchain github-governance plan \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v3/v3.0 \\\n  --required-check check \\\n  --required-check-app-id check=15368 \\\n  --required-approvals 1 \\\n  --snapshot-output rollback.json \\\n  --plan-output rollout.json\n```\n\nAn already protected check preserves its observed GitHub App binding. Every new\nrequired check must declare `--required-check-app-id <context>=<app-id>`;\ncontext-only replacement is rejected because it would broaden which producer\ncan satisfy the gate.\n\nClassic branch-protection bypass allowances and ruleset bypass actors are both\npart of the effective policy. Reconciliation writes explicit empty user, team,\nand App bypass lists and verifies those lists after apply; omitting the provider\nfield is not treated as removal because GitHub may preserve the prior value.\n\nThe plan prints a `planRoot`. Apply requires that exact root and stops if live\nprotection no longer matches the frozen inventory:\n\n```bash\nbuildchain github-governance apply \\\n  --plan-json rollout.json \\\n  --confirm-plan-root sha256:...\n```\n\nRollback is separately explicit and root-bound:\n\n```bash\nbuildchain github-governance rollback \\\n  --plan-json rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nFor an admitted exact target, classic branch protection can also be compiled\ndirectly from the authority descriptor. This mode preserves both App-bound\nchecks and intentionally unbound check contexts such as Kungfu release's\nlegacy `build`, rather than guessing a provider App identity.\n\n```bash\nbuildchain github-governance protection-policy-plan \\\n  --repository kungfu-systems/kungfu \\\n  --branch alpha/v4/v4.0 \\\n  --snapshot-output protection-rollback.json \\\n  --plan-output protection-rollout.json\n\nbuildchain github-governance protection-policy-apply \\\n  --plan-json protection-rollout.json \\\n  --confirm-plan-root sha256:...\n\nbuildchain github-governance protection-policy-rollback \\\n  --plan-json protection-rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nFor an admitted exact target, repository ruleset reconciliation compiles the\ntarget descriptor into the provider body. It replaces bypass actors with the\nexact provider-admitted desired set, requires fresh Code Owner approval and\nresolved review threads, and binds required checks plus strict-update semantics\nto the target policy. Newly synthesized managed rules include GitHub's explicit\ncanonical defaults so the frozen expected root matches provider read-back.\nRepository rulesets default to no bypass actors. The\ndescriptor's target-bound GitHub Actions allowance is an upper bound on\neffective provider state, not a requirement to add that actor to every\nprotection layer; when needed, the built-in App allowance is expressed by\nclassic branch protection. The target condition must contain exactly one\nbranch; unrelated rules and conditions are preserved in place.\n\n```bash\nbuildchain github-governance ruleset-policy-plan \\\n  --repository kungfu-systems/buildchain \\\n  --branch alpha/v3/v3.0 \\\n  --ruleset-id 19518955 \\\n  --snapshot-output ruleset-rollback.json \\\n  --plan-output ruleset-rollout.json\n\nbuildchain github-governance ruleset-policy-apply \\\n  --plan-json ruleset-rollout.json \\\n  --confirm-plan-root sha256:...\n\nbuildchain github-governance ruleset-policy-rollback \\\n  --plan-json ruleset-rollout.json \\\n  --confirm-rollback-root sha256:...\n```\n\nThe narrower `ruleset-plan` mode changes only `bypass_actors`; it remains\navailable for a bypass-only canary, but it cannot prove that an effective\nruleset matches the target descriptor. Both modes require the frozen ruleset\nsnapshot root for rollback.\n\nPaid-plan purchase, billing, legal/account-owner decisions, and any operation\nthat could remove the last recoverable owner remain external human gates.\nBreak-glass is disabled by default and, if ever admitted, must be separately\nauthenticated, reason-bound, time-bounded, independently receipted, and\nfollowed by mandatory restoration and root comparison."
     },
     {
       "id": "manual:homebrew",
@@ -1049,7 +1115,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/lifecycle-protocol.md",
-      "digest": "sha256:55425241363da6105a6b36a46bf8c9d7edd5b0e0f9dbcebe1452327642eb2af9",
+      "digest": "sha256:4b7a8efe1d22751ded069f46a23490db70cda9e9e14641acab600ab781245b19",
       "headings": [
         {
           "level": 1,
@@ -1132,7 +1198,7 @@
           "anchor": "design-boundaries"
         }
       ],
-      "markdown": "# Lifecycle Protocol\n\nBuildchain uses `.buildchain/buildchain.toml` as the v2 repository configuration format.\nThe file is optional for simple JavaScript repositories, but it is the preferred\nway to describe release version state and lifecycle commands when a project is\nnot a plain pnpm, npm, or yarn workspace.\n\nFor compatibility, Buildchain still reads a legacy root `buildchain.toml` when\n`.buildchain/buildchain.toml` is absent. New repositories should use the\n`.buildchain/` layout so all Buildchain-owned local state lives under one\ndirectory.\n\nOnly TOML is supported in v2. YAML, JSON, and JavaScript config files are not\nloaded.\n\n## Minimal File\n\n```toml\nschema = 1\n\n[version]\nrequired = true\n\n[[version.files]]\ntype = \"json\"\npath = \"package.json\"\nkey = \"version\"\n\n[lifecycle.verify]\ncommands = [\n  \"pnpm run check\",\n]\n```\n\n`schema = 1` is required. Buildchain fails closed when the schema is missing or\nunknown.\n\n## Version State\n\nVersion state is the source file evidence that matches a release tag. During\npromotion, Buildchain writes the selected release or prerelease version into the\nconfigured files, verifies the resulting tree, creates a source version commit,\nthen moves exact and floating refs.\n\nSupported version file types:\n\n| Type | Use case | Required fields |\n| --- | --- | --- |\n| `json` | `package.json`, JSON manifests | `path`, `key` |\n| `toml` | `pyproject.toml`, other TOML manifests | `path`, `key` |\n| `regex` | `CMakeLists.txt`, `conanfile.py`, plain version files | `path`, `pattern`, `replacement` |\n\n`key` is a dotted key path:\n\n```toml\n[[version.files]]\ntype = \"toml\"\npath = \"pyproject.toml\"\nkey = \"project.version\"\n```\n\nConfigured JSON and TOML version files are semantic no-ops when the declared\nkey already equals the requested version. Buildchain preserves the repository's\noriginal TOML bytes in that case instead of serializing the whole document and\ncreating formatter-only release state. When a TOML version really changes,\nBuildchain applies a parser-verified lossless edit to that key and fails closed\nif it cannot prove a unique edit; unrelated arrays, comments, and formatting\nremain repository-owned.\n\nRegex files must expose the current version through a named capture group called\n`version`:\n\n```toml\n[[version.files]]\ntype = \"regex\"\npath = \"CMakeLists.txt\"\npattern = 'project\\([^)]* VERSION (?<version>[^ )]+)'\nreplacement = '${version}'\n```\n\nIf `version.required = true`, promotion fails when no configured version files\nare available.\n\n### Anchored Manual Versions\n\nSome repositories do not derive their package version from the Buildchain\nrelease tag. `libnode` is the canonical example: the package version is anchored\nto an explicitly selected upstream Node.js release such as `22.22.3-kf.0`, while\nthe channel line may be `release/v22/v22.22`.\n\nThose repositories can opt into anchored manual semantics:\n\n```toml\n[version]\nrequired = true\nstrategy = \"anchored\"\nnext = \"manual\"\nmanifest = \"libnode.release.json\"\nderived_files = [\n  \"dist/version-witness.json\",\n]\n\n[[version.files]]\ntype = \"json\"\npath = \"package.json\"\nkey = \"version\"\n```\n\nWith `strategy = \"anchored\"` and `next = \"manual\"`:\n\n- Buildchain validates the configured version files and anchor manifest, but it\n  does not rewrite those files to the Buildchain release tag.\n- `lifecycle.verify` is the project-owned truth gate. It should compare the\n  package version, anchor manifest, and upstream source/submodule state.\n- `version.derived_files` can declare committed witnesses or generated metadata\n  whose bytes are derived by `lifecycle.version-state`. The field is valid only\n  for anchored/manual projects that declare both `lifecycle.version-state` and\n  `lifecycle.verify`.\n- release-candidate builds rerun derivation and verification before heavy\n  platform builds, require the committed tree to remain unchanged, and bind the\n  alpha/release tree identities plus declared file digests into controller and\n  release-passport evidence.\n- release promotion permits differences from the tested alpha tree only in\n  `version.files`, the anchor manifest, and declared `version.derived_files`;\n  any other changed path fails closed before publication.\n- release promotion still creates the exact/floating production refs for the\n  current line;\n- release promotion does not auto-create the next alpha branch or tag;\n- the action output `next-anchor-required` is `true`, signaling that the next\n  upstream anchor line must be created explicitly by the repository.\n\nThe configured anchor manifest must be JSON or TOML. Buildchain does not\ninterpret project-specific field names; it only loads the manifest and exposes\nits top-level fields to validation summaries and lifecycle environment:\n\n```text\nBUILDCHAIN_VERSION_STRATEGY=anchored\nBUILDCHAIN_VERSION_NEXT=manual\nBUILDCHAIN_ANCHOR_MANIFEST=libnode.release.json\nBUILDCHAIN_ANCHOR_MANIFEST_JSON={\"nodeTag\":\"v22.22.3\",...}\n```\n\nThe upstream anchor decision remains outside Buildchain. A future line such as\n`dev/v24/v24.xx` should be created by an explicit repository workflow or human\ndecision after the upstream version has been selected and checked in.\n\n## Lifecycle Stages\n\nLifecycle stages are declarative shell commands. A stage can use exactly one of:\n\n- `command`: one shell command;\n- `commands`: multiple shell commands run in order;\n- `script`: a multiline shell script.\n\nAny command failure fails the stage. `timeout_minutes`, `retries`, `shell`, and\n`env` can be attached to a stage.\n\nDuring version-state verification, Buildchain also sets `BUILDCHAIN_VERSION` to\nthe release or prerelease version being verified.\n\n```toml\n[lifecycle.install]\ntimeout_minutes = 10\nretries = 3\ncommands = [\n  \"pnpm install --frozen-lockfile\",\n]\n\n[lifecycle.build]\ncommands = [\n  \"pnpm run build\",\n  \"pnpm run package\",\n]\n\n[lifecycle.check]\ncommand = \"pnpm run check:source\"\n\n[lifecycle.verify]\nshell = \"bash\"\nscript = \"\"\"\nset -euo pipefail\npnpm run check\ngit diff --check\n\"\"\"\n```\n\n`lifecycle.check` is the repository-owned source-acceptance gate. It should\nvalidate the checked-out source revision without entering the build, artifact,\nor release lifecycle. Consumers can run it on GitHub-hosted Linux through\n`.github/workflows/check.yml@v3` with `mode: source`; the reusable workflow runs\nonly `lifecycle.install` and `lifecycle.check`. The default `mode: verify`\ncontinues to run `lifecycle.install` and `lifecycle.verify` for existing callers.\nBoth executed stages receive `BUILDCHAIN_CHECK_MODE=source` or\n`BUILDCHAIN_CHECK_MODE=verify`, so a repository whose normal install path can\ncompile native tooling can select a provisioning-only install path for source\nacceptance without weakening promotion installs.\nThe reusable job name remains `check`, and `upload-artifacts: false` disables\nevidence upload without changing the job conclusion used by branch protection.\n\nShared environment variables can be declared once:\n\n```toml\n[lifecycle.env]\nPYTHONUNBUFFERED = \"1\"\n```\n\nStage-specific environment variables override shared lifecycle environment:\n\n```toml\n[lifecycle.test]\ncommand = \"pytest\"\n\n[lifecycle.test.env]\nPYTHONPATH = \"src\"\n```\n\n### Publish Stage\n\n`lifecycle.publish` is the project-owned side-effect stage. It may call npm,\nPyPI, Conan, CMake packaging scripts, Docker/OCI registries, S3 uploaders, or\nany other publisher. Buildchain does not assume the tool; it assumes the\nevidence contract.\n\n```toml\n[lifecycle.publish]\nscript = \"\"\"\nset -euo pipefail\npython scripts/publish_wheels.py\nnode scripts/publish-images.mjs\nnode scripts/write-publish-evidence.mjs\n\"\"\"\n```\n\nWhen `actions/promote-buildchain-ref` runs with `publish-transaction: \"true\"`,\nthe publish stage receives the transaction identity plus the resolved publish\ncontract:\n\n```text\nBUILDCHAIN_VERSION\nBUILDCHAIN_CHANNEL\nBUILDCHAIN_SOURCE_SHA\nBUILDCHAIN_TARGET_REF\nBUILDCHAIN_RELEASE_STATE\nBUILDCHAIN_EVIDENCE_DIR\nBUILDCHAIN_RELEASE_SHA\nBUILDCHAIN_RELEASE_MATERIAL_SHA\nBUILDCHAIN_PUBLISH_TOOLING_SHA\nBUILDCHAIN_PUBLISH_EVIDENCE\nBUILDCHAIN_PUBLISH_MODE\nBUILDCHAIN_PUBLISH_AUTH\nBUILDCHAIN_NPM_DIST_TAG\nBUILDCHAIN_PACKAGE_SET_ORDER\nBUILDCHAIN_PACKAGE_SET_MAIN_PACKAGE\n```\n\nThe stage must write publish evidence JSON. Buildchain validates that evidence\nbefore exact tags and floating refs move. In GitHub Actions, the promotion\naction also persists `state.json` and `evidence.json` to\n`refs/heads/buildchain/release-state/<version>` so fresh runners can recover\nwithout local workspace residue. See\n[`docs/publish-transaction.md`](publish-transaction.md) for the state machine,\nevidence schema, and recovery commands.\n\nFor npm packages, prefer:\n\n```toml\n[publish]\nmode = \"publish-final-version\"\nauth = \"trusted-publishing\"\ndist_tag = \"latest\"\n```\n\nUse `mode = \"promote-existing-version\"` only for explicit same-version\ndist-tag recovery, and pair it with `auth = \"npm-token\"`. Trusted Publishing\ndoes not authorize `npm dist-tag add`; Buildchain fails that combination before\nany publish transaction side effect.\n\n## Promotion Semantics\n\n`actions/promote-buildchain-ref` consumes `version.files`, `lifecycle.verify`,\nand optionally `lifecycle.publish`.\n\nThe verify stage runs after Buildchain has applied the generated version-state\nchanges to the local checkout, and before it creates release commits or moves\nrefs. After the command finishes, Buildchain checks that only declared\nversion-state files changed. This prevents verification from quietly adding\nextra source changes to the release commit.\n\nBuildchain-owned untracked runtime evidence is excluded only through an exact\ninternal allowlist. This includes contract-drift issue material under\n`.buildchain/contract-drift/` and the paper workflow's\n`.buildchain/publication-result.json`, alongside release-candidate, passport,\nrelease-state, KFD, and runtime evidence directories. Tracked changes, ordinary\nsource files, and undeclared `.buildchain/*` paths still fail version\nverification.\n\nOn protected alpha and release branches, the generated version-state commit is\napplied by the promotion automation after the reviewed channel PR has merged.\nBuildchain keeps review requirements, conversation resolution, strict status\nchecks, and admin enforcement for human channel changes, but admits only the\nexact GitHub Actions App to the target-bound bypass allowlist for generated\nrelease bookkeeping. Buildchain also creates the configured required\ncheck on the exact generated version-state commit before patching the protected\nref, then applies the protected ref update with the declared generated ref\nupdate token. The reusable wrapper uses the run-scoped `github.token` for that\nprotected bookkeeping update. If finalization bookkeeping is still rejected,\nBuildchain creates or reuses a same-repository `buildchain/version-state/*` PR\nand reports `finalization-needed=true` so a later idempotent promotion run can\nresume. This fallback also applies to strict alpha target and dev\nreconciliation. The generated PR must pass the repository's normal protected\nchecks, review, and merge-queue policy; Buildchain never weakens that policy or\ntreats PR creation as completed finalization.\n\nFor `version.strategy = \"anchored\"` with `version.next = \"manual\"`, release\npromotion does not generate a Buildchain-owned version-state commit. In that\nmode, a protected `alpha -> release` PR may carry the declared `version.files`\nfrom the tested alpha package version to the final package version, and may\ncarry the configured `version.manifest` with it. Buildchain only accepts that\nrelease tree difference when the PR is the valid channel-promotion PR, the\nchanged paths are limited to those declared version files plus the anchor\nmanifest, and `lifecycle.verify` or `verification-command` has validated the\nchecked-out release material. Any code or undeclared file change still fails the\nrelease tree gate.\n\nThe action input `verification-command` remains supported. When it is provided,\nit overrides `lifecycle.verify` for that invocation. The override inherits\n`[lifecycle.env]` and `lifecycle.verify.env`; when the configured stage declares\n`shell`, it also inherits that shell. If the stage has no explicit shell,\nBuildchain preserves the platform-default shell for compatibility.\n\n## Migration Preflight\n\nHeavy repositories can validate their Buildchain declaration before they are\nready to run the real build. `actions/validate-config` checks that\n`.buildchain/buildchain.toml` parses, configured version-state files exist, configured\nversion keys are strings, and required lifecycle stage names are declared.\nFor web-surface repositories it also validates `project`, `channels`, `deploy`,\n`retention`, and `security` declarations.\n\nIt does not run lifecycle commands. This is useful for repositories such as\n`libnode`, where `lifecycle.build` represents an expensive multi-platform native\nbuild and the first migration milestone is to prove the release metadata and\nlifecycle protocol without consuming build runners.\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/validate-config@v3\n  with:\n    require-version-state: \"true\"\n    require-lifecycle-stages: \"install,build,verify\"\n```\n\nWeb-surface repositories can use the same action without requiring version\nstate:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/validate-config@v3\n  with:\n    require-lifecycle-stages: \"build,verify\"\n```\n\nThe action exposes project and deploy metadata through outputs such as\n`project-type`, `project-site`, `channels`, and `deploy-adapters-json`.\n\n## Web-Surface Projects\n\n`project.type = \"web-surface\"` is for sites, docs, browser apps, and operator\nconsoles whose release object is a deployed surface, not a package version.\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-libkungfu-dev\"\nsite = \"libkungfu-dev\"\n\n[channels.preview]\nurl_pattern = \"https://{alias}.preview.libkungfu.dev\"\nvisibility = \"ephemeral\"\nnoindex = true\n\n[channels.staging]\nurl = \"https://staging.libkungfu.dev\"\nvisibility = \"protected\"\naccess_control = \"managed-network\"\nedge_auth = \"none\"\nnoindex = true\npromotable = true\n\n[channels.production]\nurl = \"https://libkungfu.dev\"\nvisibility = \"public\"\ncanonical = true\nnoindex = false\n\n[surfaces.hub]\npath = \"/\"\nproduction_url = \"https://libkungfu.dev\"\nstaging_url = \"https://staging.libkungfu.dev\"\npreview_url_pattern = \"https://{alias}.preview.libkungfu.dev\"\n\n[surfaces.core]\npath = \"/core/\"\nproduction_url = \"https://core.libkungfu.dev\"\nstaging_url = \"https://core.staging.libkungfu.dev\"\npreview_url_pattern = \"https://core-{alias}.preview.libkungfu.dev\"\n\n[deploy.production]\nadapter = \"aws-s3-cloudfront\"\nbucket = \"libkungfu-dev-production\"\nartifact_path = \"dist\"\nsecret_refs = [\"AWS_ROLE_ARN\"]\n```\n\nSee [Web-surface deployments](web-surface-deployments.md) for named surface host\nmappings, the manifest, preview alias, retention, cleanup, and dry-run deploy\ncontract.\n\n## Infra-Contract Projects\n\n`project.type = \"infra-contract\"` is for infrastructure contract repositories\nthat need provider-neutral desired, plan, approval, apply, observe, contract,\nand propagation evidence. `buildchain init --type infra-contract` wires\n`lifecycle.verify` to `buildchain infra-contract --mode ci`, which writes\nmutation-free plan, contract, propagation dry-run, evidence bundle, and\nverification artifacts under `.buildchain/`. The surface supports\nmanual-observed, observe-only, and mocked adapter fixtures without reading\ncloud state files or executing live infrastructure mutation. See\n[Infra Contract](infra-contract.md).\n\n## Examples\n\n### Node Workspace\n\n```toml\nschema = 1\n\n[version]\nrequired = true\n\n[[version.files]]\ntype = \"json\"\npath = \"package.json\"\nkey = \"version\"\n\n[lifecycle.verify]\ncommands = [\n  \"pnpm run check\",\n]\n```\n\n### Python Package\n\n```toml\nschema = 1\n\n[version]\nrequired = true\n\n[[version.files]]\ntype = \"toml\"\npath = \"pyproject.toml\"\nkey = \"project.version\"\n\n[lifecycle.install]\ncommand = \"python -m pip install -e .[test]\"\n\n[lifecycle.build]\ncommand = \"python -m build\"\n\n[lifecycle.verify]\ncommands = [\n  \"python -m build\",\n  \"pytest\",\n]\n```\n\n### CMake and Conan\n\n```toml\nschema = 1\n\n[[version.files]]\ntype = \"regex\"\npath = \"CMakeLists.txt\"\npattern = 'project\\([^)]* VERSION (?<version>[^ )]+)'\nreplacement = '${version}'\n\n[lifecycle.configure]\ncommands = [\n  \"conan install . --build=missing\",\n  \"cmake -S . -B build -DCMAKE_BUILD_TYPE=Release\",\n]\n\n[lifecycle.build]\ncommand = \"cmake --build build --config Release\"\n\n[lifecycle.verify]\ncommands = [\n  \"cmake --build build --config Release\",\n  \"ctest --test-dir build --output-on-failure\",\n]\n```\n\n### Docker Image\n\n```toml\nschema = 1\n\n[[version.files]]\ntype = \"json\"\npath = \"package.json\"\nkey = \"version\"\n\n[lifecycle.build]\ncommand = \"docker build -f Dockerfile -t kungfutrader/example:${BUILDCHAIN_VERSION} .\"\n\n[lifecycle.verify]\ncommand = \"docker build -f Dockerfile -t kungfutrader/example:verify .\"\n```\n\nDocker publishing is an external side effect and should be gated by a release\nworkflow after version-state promotion has been verified.\n\n## Design Boundaries\n\nThe lifecycle protocol is also the command source for the reusable build\nsurface. `.github/workflows/.build.yml` runs `lifecycle.install`,\n`lifecycle.build`, and `lifecycle.verify` by default, while allowing callers to\noverride each stage with explicit workflow inputs. The underlying\n`actions/run-lifecycle` action can be used directly by repositories that need a\ncustom workflow but still want Buildchain's lifecycle and deterministic manifest\ncontract.\n\nBuildchain lifecycle commands are data, not executable configuration files.\nThey make release behavior reviewable in pull requests and keep the release\nfact chain simple:\n\n1. choose the channel branch and release line;\n2. generate a source version commit from declared version files;\n3. verify that exact tree;\n4. move exact tags and floating refs only after verification succeeds;\n5. run publish or deployment side effects in separately gated workflows."
+      "markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-lifecycle-protocol\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-31\n  invisible_context: not asserted\n---\n\n# Lifecycle Protocol\n\nBuildchain uses `.buildchain/buildchain.toml` as the v3 repository configuration format.\nThe file is optional for simple JavaScript repositories, but it is the preferred\nway to describe release version state and lifecycle commands when a project is\nnot a plain pnpm, npm, or yarn workspace.\n\nFor compatibility, Buildchain still reads a legacy root `buildchain.toml` when\n`.buildchain/buildchain.toml` is absent. New repositories should use the\n`.buildchain/` layout so all Buildchain-owned local state lives under one\ndirectory.\n\nOnly TOML is supported in v3. YAML, JSON, and JavaScript config files are not\nloaded.\n\n## Minimal File\n\n```toml\nschema = 1\n\n[version]\nrequired = true\n\n[[version.files]]\ntype = \"json\"\npath = \"package.json\"\nkey = \"version\"\n\n[lifecycle.verify]\ncommands = [\n  \"pnpm run check\",\n]\n```\n\n`schema = 1` is required. Buildchain fails closed when the schema is missing or\nunknown.\n\n## Version State\n\nVersion state is the source file evidence that matches a release tag. During\npromotion, Buildchain writes the selected release or prerelease version into the\nconfigured files, verifies the resulting tree, creates a source version commit,\nthen moves exact and floating refs.\n\nSupported version file types:\n\n| Type | Use case | Required fields |\n| --- | --- | --- |\n| `json` | `package.json`, JSON manifests | `path`, `key` |\n| `toml` | `pyproject.toml`, other TOML manifests | `path`, `key` |\n| `regex` | `CMakeLists.txt`, `conanfile.py`, plain version files | `path`, `pattern`, `replacement` |\n\n`key` is a dotted key path:\n\n```toml\n[[version.files]]\ntype = \"toml\"\npath = \"pyproject.toml\"\nkey = \"project.version\"\n```\n\nConfigured JSON and TOML version files are semantic no-ops when the declared\nkey already equals the requested version. Buildchain preserves the repository's\noriginal TOML bytes in that case instead of serializing the whole document and\ncreating formatter-only release state. When a TOML version really changes,\nBuildchain applies a parser-verified lossless edit to that key and fails closed\nif it cannot prove a unique edit; unrelated arrays, comments, and formatting\nremain repository-owned.\n\nRegex files must expose the current version through a named capture group called\n`version`:\n\n```toml\n[[version.files]]\ntype = \"regex\"\npath = \"CMakeLists.txt\"\npattern = 'project\\([^)]* VERSION (?<version>[^ )]+)'\nreplacement = '${version}'\n```\n\nIf `version.required = true`, promotion fails when no configured version files\nare available.\n\n### Anchored Manual Versions\n\nSome repositories do not derive their package version from the Buildchain\nrelease tag. `libnode` is the canonical example: the package version is anchored\nto an explicitly selected upstream Node.js release such as `22.22.3-kf.0`, while\nthe channel line may be `release/v22/v22.22`.\n\nThose repositories can opt into anchored manual semantics:\n\n```toml\n[version]\nrequired = true\nstrategy = \"anchored\"\nnext = \"manual\"\nmanifest = \"libnode.release.json\"\nderived_files = [\n  \"dist/version-witness.json\",\n]\n\n[[version.files]]\ntype = \"json\"\npath = \"package.json\"\nkey = \"version\"\n```\n\nWith `strategy = \"anchored\"` and `next = \"manual\"`:\n\n- Buildchain validates the configured version files and anchor manifest, but it\n  does not rewrite those files to the Buildchain release tag.\n- `lifecycle.verify` is the project-owned truth gate. It should compare the\n  package version, anchor manifest, and upstream source/submodule state.\n- `version.derived_files` can declare committed witnesses or generated metadata\n  whose bytes are derived by `lifecycle.version-state`. The field is valid only\n  for anchored/manual projects that declare both `lifecycle.version-state` and\n  `lifecycle.verify`.\n- release-candidate builds rerun derivation and verification before heavy\n  platform builds, require the committed tree to remain unchanged, and bind the\n  alpha/release tree identities plus declared file digests into controller and\n  release-passport evidence.\n- release promotion permits differences from the tested alpha tree only in\n  `version.files`, the anchor manifest, and declared `version.derived_files`;\n  any other changed path fails closed before publication.\n- release promotion still creates the exact/floating production refs for the\n  current line;\n- release promotion does not auto-create the next alpha branch or tag;\n- the action output `next-anchor-required` is `true`, signaling that the next\n  upstream anchor line must be created explicitly by the repository.\n\nThe configured anchor manifest must be JSON or TOML. Buildchain does not\ninterpret project-specific field names; it only loads the manifest and exposes\nits top-level fields to validation summaries and lifecycle environment:\n\n```text\nBUILDCHAIN_VERSION_STRATEGY=anchored\nBUILDCHAIN_VERSION_NEXT=manual\nBUILDCHAIN_ANCHOR_MANIFEST=libnode.release.json\nBUILDCHAIN_ANCHOR_MANIFEST_JSON={\"nodeTag\":\"v22.22.3\",...}\n```\n\nThe upstream anchor decision remains outside Buildchain. A future line such as\n`dev/v24/v24.xx` should be created by an explicit repository workflow or human\ndecision after the upstream version has been selected and checked in.\n\n## Lifecycle Stages\n\nLifecycle stages are declarative shell commands. A stage can use exactly one of:\n\n- `command`: one shell command;\n- `commands`: multiple shell commands run in order;\n- `script`: a multiline shell script.\n\nAny command failure fails the stage. `timeout_minutes`, `retries`, `shell`, and\n`env` can be attached to a stage.\n\nDuring version-state verification, Buildchain also sets `BUILDCHAIN_VERSION` to\nthe release or prerelease version being verified.\n\n```toml\n[lifecycle.install]\ntimeout_minutes = 10\nretries = 3\ncommands = [\n  \"pnpm install --frozen-lockfile\",\n]\n\n[lifecycle.build]\ncommands = [\n  \"pnpm run build\",\n  \"pnpm run package\",\n]\n\n[lifecycle.check]\ncommand = \"pnpm run check:source\"\n\n[lifecycle.verify]\nshell = \"bash\"\nscript = \"\"\"\nset -euo pipefail\npnpm run check\ngit diff --check\n\"\"\"\n```\n\n`lifecycle.check` is the repository-owned source-acceptance gate. It should\nvalidate the checked-out source revision without entering the build, artifact,\nor release lifecycle. Consumers can run it on GitHub-hosted Linux through\n`.github/workflows/check.yml@v3` with `mode: source`; the reusable workflow runs\nonly `lifecycle.install` and `lifecycle.check`. The default `mode: verify`\ncontinues to run `lifecycle.install` and `lifecycle.verify` for existing callers.\nBoth executed stages receive `BUILDCHAIN_CHECK_MODE=source` or\n`BUILDCHAIN_CHECK_MODE=verify`, so a repository whose normal install path can\ncompile native tooling can select a provisioning-only install path for source\nacceptance without weakening promotion installs.\nThe reusable job name remains `check`, and `upload-artifacts: false` disables\nevidence upload without changing the job conclusion used by branch protection.\n\nShared environment variables can be declared once:\n\n```toml\n[lifecycle.env]\nPYTHONUNBUFFERED = \"1\"\n```\n\nStage-specific environment variables override shared lifecycle environment:\n\n```toml\n[lifecycle.test]\ncommand = \"pytest\"\n\n[lifecycle.test.env]\nPYTHONPATH = \"src\"\n```\n\n### Publish Stage\n\n`lifecycle.publish` is the project-owned side-effect stage. It may call npm,\nPyPI, Conan, CMake packaging scripts, Docker/OCI registries, S3 uploaders, or\nany other publisher. Buildchain does not assume the tool; it assumes the\nevidence contract.\n\n```toml\n[lifecycle.publish]\nscript = \"\"\"\nset -euo pipefail\npython scripts/publish_wheels.py\nnode scripts/publish-images.mjs\nnode scripts/write-publish-evidence.mjs\n\"\"\"\n```\n\nWhen `actions/promote-buildchain-ref` runs with `publish-transaction: \"true\"`,\nthe publish stage receives the transaction identity plus the resolved publish\ncontract:\n\n```text\nBUILDCHAIN_VERSION\nBUILDCHAIN_CHANNEL\nBUILDCHAIN_SOURCE_SHA\nBUILDCHAIN_TARGET_REF\nBUILDCHAIN_RELEASE_STATE\nBUILDCHAIN_EVIDENCE_DIR\nBUILDCHAIN_RELEASE_SHA\nBUILDCHAIN_RELEASE_MATERIAL_SHA\nBUILDCHAIN_PUBLISH_TOOLING_SHA\nBUILDCHAIN_PUBLISH_EVIDENCE\nBUILDCHAIN_PUBLISH_MODE\nBUILDCHAIN_PUBLISH_AUTH\nBUILDCHAIN_NPM_DIST_TAG\nBUILDCHAIN_PACKAGE_SET_ORDER\nBUILDCHAIN_PACKAGE_SET_MAIN_PACKAGE\n```\n\nThe stage must write publish evidence JSON. Buildchain validates that evidence\nbefore exact tags and floating refs move. In GitHub Actions, the promotion\naction also persists `state.json` and `evidence.json` to\n`refs/heads/buildchain/release-state/<version>` so fresh runners can recover\nwithout local workspace residue. See\n[`docs/publish-transaction.md`](publish-transaction.md) for the state machine,\nevidence schema, and recovery commands.\n\nFor npm packages, prefer:\n\n```toml\n[publish]\nmode = \"publish-final-version\"\nauth = \"trusted-publishing\"\ndist_tag = \"latest\"\n```\n\nUse `mode = \"promote-existing-version\"` only for explicit same-version\ndist-tag recovery, and pair it with `auth = \"npm-token\"`. Trusted Publishing\ndoes not authorize `npm dist-tag add`; Buildchain fails that combination before\nany publish transaction side effect.\n\n## Promotion Semantics\n\n`actions/promote-buildchain-ref` consumes `version.files`, `lifecycle.verify`,\nand optionally `lifecycle.publish`.\n\nThe verify stage runs after Buildchain has applied the generated version-state\nchanges to the local checkout, and before it creates release commits or moves\nrefs. After the command finishes, Buildchain checks that only declared\nversion-state files changed. This prevents verification from quietly adding\nextra source changes to the release commit.\n\nBuildchain-owned untracked runtime evidence is excluded only through an exact\ninternal allowlist. This includes contract-drift issue material under\n`.buildchain/contract-drift/` and the paper workflow's\n`.buildchain/publication-result.json`, alongside release-candidate, passport,\nrelease-state, KFD, and runtime evidence directories. Tracked changes, ordinary\nsource files, and undeclared `.buildchain/*` paths still fail version\nverification.\n\nOn protected alpha and release branches, the generated version-state commit is\napplied by the promotion automation after the reviewed channel PR has merged.\nBuildchain keeps review requirements, conversation resolution, strict status\nchecks, and admin enforcement for human channel changes, but admits only the\nexact GitHub Actions App to the target-bound bypass allowlist for generated\nrelease bookkeeping. Buildchain also creates the configured required\ncheck on the exact generated version-state commit before patching the protected\nref, then applies the protected ref update with the declared generated ref\nupdate token. The reusable wrapper uses the run-scoped `github.token` for that\nprotected bookkeeping update. If finalization bookkeeping is still rejected,\nBuildchain creates or reuses a same-repository `buildchain/version-state/*` PR\nand reports `finalization-needed=true` so a later idempotent promotion run can\nresume. This fallback also applies to strict alpha target and dev\nreconciliation. The generated PR must pass the repository's normal protected\nchecks, review, and merge-queue policy; Buildchain never weakens that policy or\ntreats PR creation as completed finalization.\n\nFor `version.strategy = \"anchored\"` with `version.next = \"manual\"`, release\npromotion does not generate a Buildchain-owned version-state commit. In that\nmode, a protected `alpha -> release` PR may carry the declared `version.files`\nfrom the tested alpha package version to the final package version, and may\ncarry the configured `version.manifest` with it. Buildchain only accepts that\nrelease tree difference when the PR is the valid channel-promotion PR, the\nchanged paths are limited to those declared version files plus the anchor\nmanifest, and `lifecycle.verify` or `verification-command` has validated the\nchecked-out release material. Any code or undeclared file change still fails the\nrelease tree gate.\n\nThe action input `verification-command` remains supported. When it is provided,\nit overrides `lifecycle.verify` for that invocation. The override inherits\n`[lifecycle.env]` and `lifecycle.verify.env`; when the configured stage declares\n`shell`, it also inherits that shell. If the stage has no explicit shell,\nBuildchain preserves the platform-default shell for compatibility.\n\n## Migration Preflight\n\nHeavy repositories can validate their Buildchain declaration before they are\nready to run the real build. `actions/validate-config` checks that\n`.buildchain/buildchain.toml` parses, configured version-state files exist, configured\nversion keys are strings, and required lifecycle stage names are declared.\nFor web-surface repositories it also validates `project`, `channels`, `deploy`,\n`retention`, and `security` declarations.\n\nIt does not run lifecycle commands. This is useful for repositories such as\n`libnode`, where `lifecycle.build` represents an expensive multi-platform native\nbuild and the first migration milestone is to prove the release metadata and\nlifecycle protocol without consuming build runners.\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/validate-config@v3\n  with:\n    require-version-state: \"true\"\n    require-lifecycle-stages: \"install,build,verify\"\n```\n\nWeb-surface repositories can use the same action without requiring version\nstate:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/validate-config@v3\n  with:\n    require-lifecycle-stages: \"build,verify\"\n```\n\nThe action exposes project and deploy metadata through outputs such as\n`project-type`, `project-site`, `channels`, and `deploy-adapters-json`.\n\n## Web-Surface Projects\n\n`project.type = \"web-surface\"` is for sites, docs, browser apps, and operator\nconsoles whose release object is a deployed surface, not a package version.\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-libkungfu-dev\"\nsite = \"libkungfu-dev\"\n\n[channels.preview]\nurl_pattern = \"https://{alias}.preview.libkungfu.dev\"\nvisibility = \"ephemeral\"\nnoindex = true\n\n[channels.staging]\nurl = \"https://staging.libkungfu.dev\"\nvisibility = \"protected\"\naccess_control = \"managed-network\"\nedge_auth = \"none\"\nnoindex = true\npromotable = true\n\n[channels.production]\nurl = \"https://libkungfu.dev\"\nvisibility = \"public\"\ncanonical = true\nnoindex = false\n\n[surfaces.hub]\npath = \"/\"\nproduction_url = \"https://libkungfu.dev\"\nstaging_url = \"https://staging.libkungfu.dev\"\npreview_url_pattern = \"https://{alias}.preview.libkungfu.dev\"\n\n[surfaces.core]\npath = \"/core/\"\nproduction_url = \"https://core.libkungfu.dev\"\nstaging_url = \"https://core.staging.libkungfu.dev\"\npreview_url_pattern = \"https://core-{alias}.preview.libkungfu.dev\"\n\n[deploy.production]\nadapter = \"aws-s3-cloudfront\"\nbucket = \"libkungfu-dev-production\"\nartifact_path = \"dist\"\nsecret_refs = [\"AWS_ROLE_ARN\"]\n```\n\nSee [Web-surface deployments](web-surface-deployments.md) for named surface host\nmappings, the manifest, preview alias, retention, cleanup, and dry-run deploy\ncontract.\n\n## Infra-Contract Projects\n\n`project.type = \"infra-contract\"` is for infrastructure contract repositories\nthat need provider-neutral desired, plan, approval, apply, observe, contract,\nand propagation evidence. `buildchain init --type infra-contract` wires\n`lifecycle.verify` to `buildchain infra-contract --mode ci`, which writes\nmutation-free plan, contract, propagation dry-run, evidence bundle, and\nverification artifacts under `.buildchain/`. The surface supports\nmanual-observed, observe-only, and mocked adapter fixtures without reading\ncloud state files or executing live infrastructure mutation. See\n[Infra Contract](infra-contract.md).\n\n## Examples\n\n### Node Workspace\n\n```toml\nschema = 1\n\n[version]\nrequired = true\n\n[[version.files]]\ntype = \"json\"\npath = \"package.json\"\nkey = \"version\"\n\n[lifecycle.verify]\ncommands = [\n  \"pnpm run check\",\n]\n```\n\n### Python Package\n\n```toml\nschema = 1\n\n[version]\nrequired = true\n\n[[version.files]]\ntype = \"toml\"\npath = \"pyproject.toml\"\nkey = \"project.version\"\n\n[lifecycle.install]\ncommand = \"python -m pip install -e .[test]\"\n\n[lifecycle.build]\ncommand = \"python -m build\"\n\n[lifecycle.verify]\ncommands = [\n  \"python -m build\",\n  \"pytest\",\n]\n```\n\n### CMake and Conan\n\n```toml\nschema = 1\n\n[[version.files]]\ntype = \"regex\"\npath = \"CMakeLists.txt\"\npattern = 'project\\([^)]* VERSION (?<version>[^ )]+)'\nreplacement = '${version}'\n\n[lifecycle.configure]\ncommands = [\n  \"conan install . --build=missing\",\n  \"cmake -S . -B build -DCMAKE_BUILD_TYPE=Release\",\n]\n\n[lifecycle.build]\ncommand = \"cmake --build build --config Release\"\n\n[lifecycle.verify]\ncommands = [\n  \"cmake --build build --config Release\",\n  \"ctest --test-dir build --output-on-failure\",\n]\n```\n\n### Docker Image\n\n```toml\nschema = 1\n\n[[version.files]]\ntype = \"json\"\npath = \"package.json\"\nkey = \"version\"\n\n[lifecycle.build]\ncommand = \"docker build -f Dockerfile -t kungfutrader/example:${BUILDCHAIN_VERSION} .\"\n\n[lifecycle.verify]\ncommand = \"docker build -f Dockerfile -t kungfutrader/example:verify .\"\n```\n\nDocker publishing is an external side effect and should be gated by a release\nworkflow after version-state promotion has been verified.\n\n## Design Boundaries\n\nThe lifecycle protocol is also the command source for the reusable build\nsurface. `.github/workflows/.build.yml` runs `lifecycle.install`,\n`lifecycle.build`, and `lifecycle.verify` by default, while allowing callers to\noverride each stage with explicit workflow inputs. The underlying\n`actions/run-lifecycle` action can be used directly by repositories that need a\ncustom workflow but still want Buildchain's lifecycle and deterministic manifest\ncontract.\n\nBuildchain lifecycle commands are data, not executable configuration files.\nThey make release behavior reviewable in pull requests and keep the release\nfact chain simple:\n\n1. choose the channel branch and release line;\n2. generate a source version commit from declared version files;\n3. verify that exact tree;\n4. move exact tags and floating refs only after verification succeeds;\n5. run publish or deployment side effects in separately gated workflows."
     },
     {
       "id": "manual:map",
@@ -1146,7 +1212,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/MAP.md",
-      "digest": "sha256:cc32692e8d04816e8de94f208e43c2d5c5c7a8425cec8b32edc73ab78591fbbf",
+      "digest": "sha256:430eed733bfcbebd853da9c60a687822dab73689d7fb9ad2e9a760af279415e5",
       "headings": [
         {
           "level": 1,
@@ -1174,7 +1240,7 @@
           "anchor": "how-this-map-is-maintained"
         }
       ],
-      "markdown": "# Documentation Map\n\nStart here. Find the question you have; follow it to the document that answers\nit. This map is meant to be readable by both a person skimming for the right doc\nand an agent grounding a specific claim.\n\nEach row carries a **plane** - *why* (intent / rationale), *verify* (trust the\nrunning artifact), *use* (consume / extend) - and a **status**:\n\n- `stable` - current and holds.\n- `draft` - exists, rough or incomplete.\n- `to write` - planned; the material exists but is not yet a single doc.\n- `retired` - intentionally not part of the active Buildchain v2 surface.\n\n## Capability Coverage\n\nThis package should be usable by an agent from the npm artifact alone. The\nmachine-readable `dist/site/` bundle is the first fact source; the Markdown\nmanuals explain those facts and give operator examples.\n\n`dist/site/capability-registry.json` is the capability navigation entrypoint.\nIt groups the public surface into stable product areas so sites and agents do\nnot have to infer structure from file names. Each page, manual, CLI command,\nworkflow, action, and Node API export also carries a `capabilityGroup`,\n`audience`, and `maturity` field in its own registry.\n\n| Capability group | Primary facts | Primary manuals |\n| --- | --- | --- |\n| Getting Started | `capability-registry.json`, `product-mechanism.json` | [`install.md`](install.md), [`product-mechanism.md`](product-mechanism.md), [`cli.md`](cli.md) |\n| Release Passport and Trust | `release-model.json`, `artifact-schemas.json`, `publication-authority-registry.json`, `kfd-claims.json` | [`release-passport.md`](release-passport.md), [`github-artifact-attestation.md`](github-artifact-attestation.md), [`publication-authority.md`](publication-authority.md), [`release-candidate.md`](release-candidate.md), [`publish-transaction.md`](publish-transaction.md), [`binary-distribution.md`](binary-distribution.md) |\n| Reusable Build and Lifecycle | `workflow-registry.json`, `controller-registry.json`, `release-model.json` | [`reusable-build-surface.md`](reusable-build-surface.md), [`controller-evidence.md`](controller-evidence.md), [`shifu-gate-profiles.md`](shifu-gate-profiles.md), [`lifecycle-protocol.md`](lifecycle-protocol.md) |\n| KFD Trust and Surface Closure | `kfd-claims.json`, `public-surface-audit.json`, `cli-registry.json`, `node-api-registry.json` | [`kfd-support.md`](kfd-support.md), [`release-passport.md`](release-passport.md) |\n| Site Bundle, Web Surfaces, and Propagation | `buildchain-site.json`, `site-manifest.json`, `page-registry.json`, `release-model.json` | [`site-bundle-contract.md`](site-bundle-contract.md), [`web-surface-deployments.md`](web-surface-deployments.md), [`release-propagation.md`](release-propagation.md) |\n| Publication Artifacts | `publication-registry.json`, `workflow-registry.json`, `node-api-registry.json`, `manual-registry.json`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md), [`reusable-build-surface.md`](reusable-build-surface.md) |\n| Distribution Indexes and Badges | `badge-endpoint-registry.json`, `node-api-registry.json`, `manual-registry.json` | [`readme-badges.md`](readme-badges.md), [`homebrew.md`](homebrew.md) |\n| Build Facts, Observability, and Diagnostics | `cli-registry.json`, `node-api-registry.json`, lifecycle artifacts | [`build-facts.md`](build-facts.md), [`toolkit-observability.md`](toolkit-observability.md), [`consumer-issue-reporting.md`](consumer-issue-reporting.md) |\n| Governance, Versioning, and Runtime Drift | `buildchain-contract.json`, `workflow-registry.json`, `release-model.json` | [`github-governance-authority.md`](github-governance-authority.md), [`release-governance.md`](release-governance.md), [`release-flow.md`](release-flow.md), [`versioning.md`](versioning.md), [`runtime-train-validation.md`](runtime-train-validation.md), [`cli.md`](cli.md) |\n| CLI and Node API Reference | `cli-registry.json`, `node-api-registry.json`, `workflow-registry.json`, `manual-registry.json` | [`cli.md`](cli.md), [`../packages/core/README.md`](../packages/core/README.md) |\n\n| Capability | Machine-readable entry | Manual entry |\n| --- | --- | --- |\n| Capability-grouped KFD navigation | `dist/site/capability-registry.json`, `dist/site/page-registry.json`, `dist/site/manual-registry.json`, `dist/site/cli-registry.json`, `dist/site/node-api-registry.json` | this map, [`site-bundle-contract.md`](site-bundle-contract.md), [`kfd-support.md`](kfd-support.md) |\n| KFD-1 / KFD-2 / KFD-3 release-passport gates | `dist/site/kfd-claims.json`, `dist/site/buildchain-contract.json`, `dist/site/artifact-schemas.json` | [`release-passport.md`](release-passport.md) |\n| Product invariant Passport release gate | `buildchain.release.json#invariantPassports`, `dist/site/buildchain-contract.json` | [`release-passport.md`](release-passport.md) |\n| GitHub keyless Linux artifact attestation | `buildchain.release.json#githubArtifactAttestations`, `dist/site/workflow-registry.json`, `dist/site/artifact-schemas.json` | [`github-artifact-attestation.md`](github-artifact-attestation.md) |\n| Declarative cross-platform artifact signing | `kungfu-buildchain-artifact-signing-request/v1`, `kungfu-buildchain-artifact-signing-result/v1` | [`reusable-build-surface.md`](reusable-build-surface.md#artifact-signing-authority) |\n| KFD-3 public surface reverse audit | `dist/site/public-surface-audit.json`, `dist/site/cli-registry.json`, `dist/site/workflow-registry.json`, `dist/site/page-registry.json` | [`cli.md`](cli.md), [`site-bundle-contract.md`](site-bundle-contract.md) |\n| KFD-1 / KFD-2 / KFD-3 first-class CLI and Node API | `.buildchain/kfd/kfd-3/surfaces.json`, `dist/site/kfd-claims.json`, `buildchain.release.json`, KFD schemas from `@kungfu-tech/kfd` | [`kfd-support.md`](kfd-support.md), [`cli.md`](cli.md#commands) |\n| Declarative KFD Agent Hub adapter conformance and Passport evidence | `.buildchain/kfd/agent-hub.json`, `.buildchain/artifacts/kfd-agent-hub/evidence.json`, `buildchain.release.json#kfdAgentHub` | [`kfd-agent-hub.md`](kfd-agent-hub.md) |\n| Floating `@v3` drift detection and compatibility issues | `dist/site/buildchain-contract.json` | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) |\n| npm publish transactions, evidence, dist-tags, and recovery | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`publish-transaction.md`](publish-transaction.md) |\n| Git/source/version/module/product build facts | `dist/site/node-api-registry.json`, `dist/site/cli-registry.json`, `kungfu-buildchain-module-build-facts`, `kungfu-buildchain-product-build-facts` | [`build-facts.md`](build-facts.md) |\n| GitHub Release passport/evidence publication | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`release-governance.md`](release-governance.md), [`release-candidate.md`](release-candidate.md) |\n| GitHub ownership, effective protection, plan capability, and managed-zone governance receipts | `dist/site/node-api-registry.json`, `dist/site/cli-registry.json`, `kungfu-buildchain-github-governance-receipt` | [`github-governance-authority.md`](github-governance-authority.md) |\n| release propagation for package/publication/site chains | `dist/site/release-model.json` | [`release-propagation.md`](release-propagation.md) |\n| publication artifact manifests, immutable archive registries, source bundles, and paper repository workflows | `dist/site/publication-registry.json`, `dist/site/workflow-registry.json`, `dist/site/node-api-registry.json`, `kungfu-buildchain-publication-artifact-manifest`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md) |\n| Generated badge bundles, README badge blocks, and badge facts | `dist/site/node-api-registry.json`, `dist/site/manual-registry.json`, `kungfu-buildchain-badge-bundle-facts`, `kungfu-buildchain-readme-badge-facts` | [`readme-badges.md`](readme-badges.md) |\n| Homebrew tap distribution indexes | `dist/site/node-api-registry.json`, `dist/site/buildchain-contract.json` | [`homebrew.md`](homebrew.md) |\n| Buildchain CLI manual | `dist/site/cli-registry.json`, `dist/site/manual-registry.json` | [`cli.md`](cli.md) |\n| Node API / package exports | `dist/site/node-api-registry.json`, `dist/site/release-provenance.json` | [`cli.md`](cli.md#node-api-and-package-exports) |\n\n`dist/site/kfd-claims.json` is generated from\n`packages/core/buildchain-kfd-claims.js`. Treat that module and JSON file as the\nsource claim registry; this map and the manuals explain those claims but do not\nreplace them.\n\n## Map\n\n| Your question | Document | Plane | Status |\n| --- | --- | --- | --- |\n| What is Buildchain, in one idea? | [`../README.md`](../README.md) | - | stable |\n| Why is Buildchain a Release Passport mechanism rather than a generic workflow collection? | [`product-mechanism.md`](product-mechanism.md) | why | stable |\n| How do agents and contributors enter this repo? | [`../AGENTS.md`](../AGENTS.md) + [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | use | stable |\n| How do I install a standalone binary or npm package? | [`install.md`](install.md) | use | stable |\n| How do I run the `buildchain` CLI? | [`cli.md`](cli.md) | use | stable |\n| How do I import Buildchain toolkit APIs from JavaScript build code? | [`toolkit-observability.md`](toolkit-observability.md) + [`../packages/core/README.md`](../packages/core/README.md) | use | stable |\n| How do I initialize a new repository? | [`cli.md`](cli.md) + [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |\n| Why does Buildchain use branch-driven release governance? | [`release-governance.md`](release-governance.md) | why | stable |\n| How do protected dev branches and scheduled ready-PR merging work? | [`release-governance.md`](release-governance.md#protected-dev-branches) | use | stable |\n| How do slow required checks land reliably on a busy dev channel? | [`release-governance.md`](release-governance.md#protected-dev-branches) + [`cli.md`](cli.md#commands) | use | preview |\n| How do I run daily, weekly, or monthly repository patrols? | [`release-governance.md`](release-governance.md#buildchain-patrol) | use | stable |\n| How does Buildchain decide patch, minor, and major release lines? | [`versioning.md`](versioning.md) | why | stable |\n| What exact branch/tag state machine runs on alpha, release, and major gate? | [`release-flow.md`](release-flow.md) | verify | stable |\n| What did Buildchain migrate or retire from old action repositories? | [`migration-inventory.md`](migration-inventory.md) | verify | stable |\n| What is the active action and workflow source of truth? | [`ownership.md`](ownership.md) | verify | stable |\n| How do I declare version files and custom lifecycle commands? | [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |\n| How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |\n| How do I collect and verify module/product build facts from Git source, version files, and outputs? | [`build-facts.md`](build-facts.md) + [`cli.md`](cli.md) | use/verify | stable |\n| How do I publish or verify release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |\n| How do I keylessly attest Linux release artifacts with GitHub and bind them to a Release Passport? | [`github-artifact-attestation.md`](github-artifact-attestation.md) | verify/use | preview |\n| How do I request detached, Developer ID, or Authenticode signing without consumer credentials? | [`reusable-build-surface.md`](reusable-build-surface.md#artifact-signing-authority) | verify/use | preview |\n| How do I seal exact artifact, identity, lifecycle, and KFD assessment roots for KFX admission? | [`artifact-verification-envelope.md`](artifact-verification-envelope.md) | verify/use | preview |\n| How is product publication authority sealed to an exact workflow, runner, control plane, nonce, and artifact? | [`publication-authority.md`](publication-authority.md) | verify | preview |\n| How are GitHub ownership, independent review, effective protection, and plan capability audited fail-closed? | [`github-governance-authority.md`](github-governance-authority.md) | verify | preview |\n| How do I gate release artifacts with KFD-1 contract-world witnesses? | [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate) | verify/use | stable |\n| How do I declare, render, and audit product KFD-2 release trust claims? | [`kfd-support.md`](kfd-support.md#kfd-2) + [`release-passport.md`](release-passport.md#kfd-2-release-trust-passport-audit) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I gate KFD-3 collaboration-interface releases? | [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I detect, register, audit, witness, or query KFD-3 product surfaces? | [`kfd-support.md`](kfd-support.md) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I adopt the KFD Agent Hub profile with one declaration and one adapter? | [`kfd-agent-hub.md`](kfd-agent-hub.md) | verify/use | preview |\n| How do I keep `@v3` floating refs while detecting Buildchain contract drift? | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) | verify/use | stable |\n| How do reusable workflows bind controller intent, source/runtime identity, outcomes, and receipt evidence? | [`controller-evidence.md`](controller-evidence.md) | verify/use | draft |\n| How do I propagate finalized upstream releases to downstream package/site PRs? | [`release-propagation.md`](release-propagation.md) | use | preview |\n| How do paper or report repositories publish PDFs, metadata, source bundles, site-consumable manifests, npm packages, and GitHub Releases? | [`publication-artifacts.md`](publication-artifacts.md) | use | stable |\n| How do I generate KFD / Release Passport badge bundles without hand-maintaining Markdown? | [`readme-badges.md`](readme-badges.md) + [`cli.md`](cli.md) | use | stable |\n| How do I generate and verify a Homebrew tap from release passport evidence? | [`homebrew.md`](homebrew.md) + [`cli.md`](cli.md) | use/verify | stable |\n| How do I prove a PR-stage reusable build is the artifact source promoted later? | [`release-candidate.md`](release-candidate.md) + [`reusable-build-surface.md`](reusable-build-surface.md) | verify | stable |\n| Why are binary release assets archived by platform, and where is the single bundle? | [`binary-distribution.md`](binary-distribution.md) | verify | stable |\n| How do I add timestamped logs inside build scripts? | [`toolkit-observability.md`](toolkit-observability.md) | use | stable |\n| What package-owned facts should buildchain.libkungfu.dev render? | [`site-bundle-contract.md`](site-bundle-contract.md) | use | stable |\n| How do I call the reusable build workflow? | [`reusable-build-surface.md`](reusable-build-surface.md) | use | stable |\n| How does Buildchain schedule and aggregate a project-owned Shifu Gate profile? | [`shifu-gate-profiles.md`](shifu-gate-profiles.md) | use/verify | draft |\n| How do exact build artifacts become qualified, transcript-traceable demo media? | [`auditable-demo.md`](auditable-demo.md) | use/verify | draft |\n| 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 |\n| 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 |\n| 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 |\n| How do ephemeral GitHub-hosted runners share exact dependency or compiler caches without fixed-runner affinity? | [`cli.md`](cli.md#commands) | use/verify | preview |\n| How do I validate an unreleased Buildchain runtime train while keeping `@v3`? | [`runtime-train-validation.md`](runtime-train-validation.md) | use | stable |\n| How do I automatically qualify alpha candidates and publish the newest non-revoked qualified candidate at a fixed window? | [`stable-candidate-patrol.md`](stable-candidate-patrol.md) | use | preview |\n| How do I deploy a site/app preview, staging, or production surface? | [`web-surface-deployments.md`](web-surface-deployments.md) | use | stable |\n| How do I publish observed infrastructure contracts for downstream consumers? | [`infra-contract.md`](infra-contract.md) | use | preview |\n| How do I use the active actions directly? | [`../actions/validate-config/README.md`](../actions/validate-config/README.md), [`../actions/run-lifecycle/README.md`](../actions/run-lifecycle/README.md), [`../actions/promote-buildchain-ref/README.md`](../actions/promote-buildchain-ref/README.md), [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |\n| How can a consumer workflow report a Buildchain-owned failure back to Buildchain? | [`consumer-issue-reporting.md`](consumer-issue-reporting.md) + [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |\n| What do the fixture repositories demonstrate? | [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md), [`../fixtures/publish-transaction-shaped/README.md`](../fixtures/publish-transaction-shaped/README.md), [`../fixtures/web-surface-shaped/README.md`](../fixtures/web-surface-shaped/README.md), [`../fixtures/publication-artifact-shaped/README.md`](../fixtures/publication-artifact-shaped/README.md) | verify | stable |\n| What license and contribution terms apply? | [`../LICENSE`](../LICENSE) + [`../LICENSE-POLICY.md`](../LICENSE-POLICY.md) | use | stable |\n| What trademark, official-service, and provider-compliance boundaries apply? | [`../TRADEMARK.md`](../TRADEMARK.md) + [`../ACCEPTABLE_USE.md`](../ACCEPTABLE_USE.md) + [`../PROVIDER_COMPLIANCE.md`](../PROVIDER_COMPLIANCE.md) | use | stable |\n| How do I report a vulnerability? | [`../SECURITY.md`](../SECURITY.md) | use | stable |\n\n## Also asking about\n\n- **ABV / old workflows / old action repositories** -> [`release-governance.md`](release-governance.md)\n  and [`migration-inventory.md`](migration-inventory.md).\n- **v2 / v3-alpha / v2.0 / v2.0-alpha / exact tags / floating tags** ->\n  [`release-governance.md`](release-governance.md) and\n  [`release-flow.md`](release-flow.md).\n- **Buildchain self-dogfood / released alpha canary / stable compatibility lane** ->\n  [`release-governance.md`](release-governance.md#buildchain-alpha-self-dogfood).\n- **qualified alpha ledger / scheduled stable selection / hold and revoke** ->\n  [`stable-candidate-patrol.md`](stable-candidate-patrol.md).\n- **v2.1 vs v2.2 / when to open a new minor line** ->\n  [`versioning.md`](versioning.md).\n- **dry-run / what would happen if this channel PR merges** -> [`cli.md`](cli.md)\n  and [`release-flow.md`](release-flow.md).\n- **protected dev branches / scheduled ready-PR merge / daily-weekly-monthly patrol** ->\n  [`release-governance.md`](release-governance.md#protected-dev-branches) and\n  [`release-governance.md`](release-governance.md#buildchain-patrol).\n- **pnpm / npm / yarn / package-manager adapters** ->\n  [`lifecycle-protocol.md`](lifecycle-protocol.md).\n- **pip / Conan / CMake / custom commands** -> [`lifecycle-protocol.md`](lifecycle-protocol.md)\n  and [`reusable-build-surface.md`](reusable-build-surface.md).\n- **libnode / native artifacts / self-hosted runner matrix** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md) and\n  [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md).\n- **S3 artifact relay / self-hosted runner artifact transfer** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay).\n- **local Git checkout cache / self-hosted source transport** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache).\n- **runtime train validation / temporary `buildchain-ref` override** ->\n  [`runtime-train-validation.md`](runtime-train-validation.md) and\n  [`reusable-build-surface.md`](reusable-build-surface.md).\n- **consumer workflow feedback / automatic Buildchain GitHub issues** ->\n  [`consumer-issue-reporting.md`](consumer-issue-reporting.md).\n- **PR-stage RC artifacts / promote-only release candidates** ->\n  [`release-candidate.md`](release-candidate.md) and\n  [`reusable-build-surface.md`](reusable-build-surface.md).\n- **infra contract / observed infrastructure outputs / downstream contract propagation** ->\n  [`infra-contract.md`](infra-contract.md).\n- **standalone binary install / platform archives / GitHub Release bundle** ->\n  [`install.md`](install.md), [`binary-distribution.md`](binary-distribution.md),\n  and [`release-passport.md`](release-passport.md).\n- **Trusted Publishing / npm / publish evidence / recovery** ->\n  [`cli.md`](cli.md) and [`publish-transaction.md`](publish-transaction.md).\n- **Git source digest / module build facts / product build facts / legacy\n  Kungfu build info** -> [`build-facts.md`](build-facts.md) and [`cli.md`](cli.md).\n- **release chains / upstream package or publication artifact as source of truth / site synchronization** ->\n  [`release-propagation.md`](release-propagation.md).\n- **paper repositories / PDFs / publication manifests / immutable archive registries / source bundles** ->\n  [`publication-artifacts.md`](publication-artifacts.md).\n- **README status badges / KFD badge bundles / badge facts JSON** ->\n  [`readme-badges.md`](readme-badges.md) and [`cli.md`](cli.md).\n- **Homebrew taps / distribution indexes / Formula drift checks** ->\n  [`homebrew.md`](homebrew.md) and [`cli.md`](cli.md).\n- **KFD-1 contract worlds / byte-for-byte release gates** ->\n  [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate).\n- **KFD-2 public release trust claim audit** ->\n  [`release-passport.md`](release-passport.md#kfd-2-release-trust-passport-audit).\n- **KFD-3 collaboration-interface / agent-facing control surface closure** ->\n  [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate).\n- **floating `@v3` / contract lock / compatible drift issue** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock).\n- **GitHub Release passport / binary assets / artifact evidence / agent release checks** ->\n  [`release-passport.md`](release-passport.md),\n  [`binary-distribution.md`](binary-distribution.md), and [`cli.md`](cli.md).\n- **Buildchain logging / timestamps / consumer build phase timing** ->\n  [`toolkit-observability.md`](toolkit-observability.md) for JavaScript API\n  imports, and [`cli.md`](cli.md) for workflow or shell command usage.\n- **buildchain.libkungfu.dev / package-owned site facts** ->\n  [`site-bundle-contract.md`](site-bundle-contract.md).\n- **sites / web previews / staging / production gates** ->\n  [`web-surface-deployments.md`](web-surface-deployments.md).\n- **trademark / fork / official service / provider compliance / release\n  evidence boundary** -> [`../TRADEMARK.md`](../TRADEMARK.md),\n  [`../ACCEPTABLE_USE.md`](../ACCEPTABLE_USE.md), and\n  [`../PROVIDER_COMPLIANCE.md`](../PROVIDER_COMPLIANCE.md).\n\n## How this map is maintained\n\n- A document becomes a row here when it is a stable entrypoint for a user,\n  contributor, or workflow consumer.\n- A row's status must never claim more than the artifact delivers.\n- `why` documents explain intent and design pressure; `verify` and `use`\n  documents should state what is guaranteed, where to verify it, and the current\n  maturity of that guarantee."
+      "markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-documentation-map\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-31\n  invisible_context: not asserted\n---\n\n# Documentation Map\n\nStart here. Find the question you have; follow it to the document that answers\nit. This map is meant to be readable by both a person skimming for the right doc\nand an agent grounding a specific claim.\n\nEach row carries a **plane** - *why* (intent / rationale), *verify* (trust the\nrunning artifact), *use* (consume / extend) - and a **status**:\n\n- `stable` - current and holds.\n- `draft` - exists, rough or incomplete.\n- `to write` - planned; the material exists but is not yet a single doc.\n- `retired` - intentionally not part of the active Buildchain v3 surface.\n\n## Capability Coverage\n\nThis package should be usable by an agent from the npm artifact alone. The\nmachine-readable `dist/site/` bundle is the first fact source; the Markdown\nmanuals explain those facts and give operator examples.\n\n`dist/site/capability-registry.json` is the capability navigation entrypoint.\nIt groups the public surface into stable product areas so sites and agents do\nnot have to infer structure from file names. Each page, manual, CLI command,\nworkflow, action, and Node API export also carries a `capabilityGroup`,\n`audience`, and `maturity` field in its own registry.\n\n| Capability group | Primary facts | Primary manuals |\n| --- | --- | --- |\n| Getting Started | `capability-registry.json`, `product-mechanism.json` | [`install.md`](install.md), [`product-mechanism.md`](product-mechanism.md), [`cli.md`](cli.md) |\n| Release Passport and Trust | `release-model.json`, `artifact-schemas.json`, `publication-authority-registry.json`, `kfd-claims.json` | [`release-passport.md`](release-passport.md), [`github-artifact-attestation.md`](github-artifact-attestation.md), [`publication-authority.md`](publication-authority.md), [`release-candidate.md`](release-candidate.md), [`publish-transaction.md`](publish-transaction.md), [`binary-distribution.md`](binary-distribution.md) |\n| Reusable Build and Lifecycle | `workflow-registry.json`, `controller-registry.json`, `release-model.json` | [`reusable-build-surface.md`](reusable-build-surface.md), [`controller-evidence.md`](controller-evidence.md), [`shifu-gate-profiles.md`](shifu-gate-profiles.md), [`lifecycle-protocol.md`](lifecycle-protocol.md) |\n| KFD Trust and Surface Closure | `kfd-claims.json`, `public-surface-audit.json`, `cli-registry.json`, `node-api-registry.json` | [`kfd-support.md`](kfd-support.md), [`release-passport.md`](release-passport.md) |\n| Site Bundle, Web Surfaces, and Propagation | `buildchain-site.json`, `site-manifest.json`, `page-registry.json`, `release-model.json` | [`site-bundle-contract.md`](site-bundle-contract.md), [`web-surface-deployments.md`](web-surface-deployments.md), [`release-propagation.md`](release-propagation.md) |\n| Publication Artifacts | `publication-registry.json`, `workflow-registry.json`, `node-api-registry.json`, `manual-registry.json`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md), [`reusable-build-surface.md`](reusable-build-surface.md) |\n| Distribution Indexes and Badges | `badge-endpoint-registry.json`, `node-api-registry.json`, `manual-registry.json` | [`readme-badges.md`](readme-badges.md), [`homebrew.md`](homebrew.md) |\n| Build Facts, Observability, and Diagnostics | `cli-registry.json`, `node-api-registry.json`, lifecycle artifacts | [`build-facts.md`](build-facts.md), [`toolkit-observability.md`](toolkit-observability.md), [`consumer-issue-reporting.md`](consumer-issue-reporting.md) |\n| Governance, Versioning, and Runtime Drift | `buildchain-contract.json`, `workflow-registry.json`, `release-model.json` | [`github-governance-authority.md`](github-governance-authority.md), [`release-governance.md`](release-governance.md), [`release-flow.md`](release-flow.md), [`versioning.md`](versioning.md), [`runtime-train-validation.md`](runtime-train-validation.md), [`cli.md`](cli.md) |\n| CLI and Node API Reference | `cli-registry.json`, `node-api-registry.json`, `workflow-registry.json`, `manual-registry.json` | [`cli.md`](cli.md), [`../packages/core/README.md`](../packages/core/README.md) |\n\n| Capability | Machine-readable entry | Manual entry |\n| --- | --- | --- |\n| Capability-grouped KFD navigation | `dist/site/capability-registry.json`, `dist/site/page-registry.json`, `dist/site/manual-registry.json`, `dist/site/cli-registry.json`, `dist/site/node-api-registry.json` | this map, [`site-bundle-contract.md`](site-bundle-contract.md), [`kfd-support.md`](kfd-support.md) |\n| KFD-1 / KFD-2 / KFD-3 release-passport gates | `dist/site/kfd-claims.json`, `dist/site/buildchain-contract.json`, `dist/site/artifact-schemas.json` | [`release-passport.md`](release-passport.md) |\n| Product invariant Passport release gate | `buildchain.release.json#invariantPassports`, `dist/site/buildchain-contract.json` | [`release-passport.md`](release-passport.md) |\n| GitHub keyless Linux artifact attestation | `buildchain.release.json#githubArtifactAttestations`, `dist/site/workflow-registry.json`, `dist/site/artifact-schemas.json` | [`github-artifact-attestation.md`](github-artifact-attestation.md) |\n| Declarative cross-platform artifact signing | `kungfu-buildchain-artifact-signing-request/v1`, `kungfu-buildchain-artifact-signing-result/v1` | [`reusable-build-surface.md`](reusable-build-surface.md#artifact-signing-authority) |\n| KFD-3 public surface reverse audit | `dist/site/public-surface-audit.json`, `dist/site/cli-registry.json`, `dist/site/workflow-registry.json`, `dist/site/page-registry.json` | [`cli.md`](cli.md), [`site-bundle-contract.md`](site-bundle-contract.md) |\n| KFD-1 / KFD-2 / KFD-3 first-class CLI and Node API | `.buildchain/kfd/kfd-3/surfaces.json`, `dist/site/kfd-claims.json`, `buildchain.release.json`, KFD schemas from `@kungfu-tech/kfd` | [`kfd-support.md`](kfd-support.md), [`cli.md`](cli.md#commands) |\n| Declarative KFD Agent Hub adapter conformance and Passport evidence | `.buildchain/kfd/agent-hub.json`, `.buildchain/artifacts/kfd-agent-hub/evidence.json`, `buildchain.release.json#kfdAgentHub` | [`kfd-agent-hub.md`](kfd-agent-hub.md) |\n| Floating `@v3` drift detection and compatibility issues | `dist/site/buildchain-contract.json` | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) |\n| npm publish transactions, evidence, dist-tags, and recovery | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`publish-transaction.md`](publish-transaction.md) |\n| Git/source/version/module/product build facts | `dist/site/node-api-registry.json`, `dist/site/cli-registry.json`, `kungfu-buildchain-module-build-facts`, `kungfu-buildchain-product-build-facts` | [`build-facts.md`](build-facts.md) |\n| GitHub Release passport/evidence publication | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`release-governance.md`](release-governance.md), [`release-candidate.md`](release-candidate.md) |\n| GitHub ownership, effective protection, plan capability, and managed-zone governance receipts | `dist/site/node-api-registry.json`, `dist/site/cli-registry.json`, `kungfu-buildchain-github-governance-receipt` | [`github-governance-authority.md`](github-governance-authority.md) |\n| release propagation for package/publication/site chains | `dist/site/release-model.json` | [`release-propagation.md`](release-propagation.md) |\n| publication artifact manifests, immutable archive registries, source bundles, and paper repository workflows | `dist/site/publication-registry.json`, `dist/site/workflow-registry.json`, `dist/site/node-api-registry.json`, `kungfu-buildchain-publication-artifact-manifest`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md) |\n| Generated badge bundles, README badge blocks, and badge facts | `dist/site/node-api-registry.json`, `dist/site/manual-registry.json`, `kungfu-buildchain-badge-bundle-facts`, `kungfu-buildchain-readme-badge-facts` | [`readme-badges.md`](readme-badges.md) |\n| Homebrew tap distribution indexes | `dist/site/node-api-registry.json`, `dist/site/buildchain-contract.json` | [`homebrew.md`](homebrew.md) |\n| Buildchain CLI manual | `dist/site/cli-registry.json`, `dist/site/manual-registry.json` | [`cli.md`](cli.md) |\n| Node API / package exports | `dist/site/node-api-registry.json`, `dist/site/release-provenance.json` | [`cli.md`](cli.md#node-api-and-package-exports) |\n\n`dist/site/kfd-claims.json` is generated from\n`packages/core/buildchain-kfd-claims.js`. Treat that module and JSON file as the\nsource claim registry; this map and the manuals explain those claims but do not\nreplace them.\n\n## Map\n\n| Your question | Document | Plane | Status |\n| --- | --- | --- | --- |\n| What is Buildchain, in one idea? | [`../README.md`](../README.md) | - | stable |\n| Why is Buildchain a Release Passport mechanism rather than a generic workflow collection? | [`product-mechanism.md`](product-mechanism.md) | why | stable |\n| How do agents and contributors enter this repo? | [`../AGENTS.md`](../AGENTS.md) + [`../CONTRIBUTING.md`](../CONTRIBUTING.md) | use | stable |\n| How do I install a standalone binary or npm package? | [`install.md`](install.md) | use | stable |\n| How do I run the `buildchain` CLI? | [`cli.md`](cli.md) | use | stable |\n| How do I import Buildchain toolkit APIs from JavaScript build code? | [`toolkit-observability.md`](toolkit-observability.md) + [`../packages/core/README.md`](../packages/core/README.md) | use | stable |\n| How do I initialize a new repository? | [`cli.md`](cli.md) + [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |\n| Why does Buildchain use branch-driven release governance? | [`release-governance.md`](release-governance.md) | why | stable |\n| How do protected dev branches and scheduled ready-PR merging work? | [`release-governance.md`](release-governance.md#protected-dev-branches) | use | stable |\n| How do slow required checks land reliably on a busy dev channel? | [`release-governance.md`](release-governance.md#protected-dev-branches) + [`cli.md`](cli.md#commands) | use | preview |\n| How do I run daily, weekly, or monthly repository patrols? | [`release-governance.md`](release-governance.md#buildchain-patrol) | use | stable |\n| How does Buildchain decide patch, minor, and major release lines? | [`versioning.md`](versioning.md) | why | stable |\n| What exact branch/tag state machine runs on alpha, release, and major gate? | [`release-flow.md`](release-flow.md) | verify | stable |\n| What did Buildchain migrate or retire from old action repositories? | [`migration-inventory.md`](migration-inventory.md) | verify | stable |\n| What is the active action and workflow source of truth? | [`ownership.md`](ownership.md) | verify | stable |\n| How do I declare version files and custom lifecycle commands? | [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |\n| How does publish evidence, recovery, and finalization work? | [`publish-transaction.md`](publish-transaction.md) | verify | stable |\n| How do I collect and verify module/product build facts from Git source, version files, and outputs? | [`build-facts.md`](build-facts.md) + [`cli.md`](cli.md) | use/verify | stable |\n| How do I publish or verify release passport artifacts? | [`release-passport.md`](release-passport.md) | use | stable |\n| How do I keylessly attest Linux release artifacts with GitHub and bind them to a Release Passport? | [`github-artifact-attestation.md`](github-artifact-attestation.md) | verify/use | preview |\n| How do I request detached, Developer ID, or Authenticode signing without consumer credentials? | [`reusable-build-surface.md`](reusable-build-surface.md#artifact-signing-authority) | verify/use | preview |\n| How do I seal exact artifact, identity, lifecycle, and KFD assessment roots for KFX admission? | [`artifact-verification-envelope.md`](artifact-verification-envelope.md) | verify/use | preview |\n| How is product publication authority sealed to an exact workflow, runner, control plane, nonce, and artifact? | [`publication-authority.md`](publication-authority.md) | verify | preview |\n| How are GitHub ownership, independent review, effective protection, and plan capability audited fail-closed? | [`github-governance-authority.md`](github-governance-authority.md) | verify | preview |\n| How do I gate release artifacts with KFD-1 contract-world witnesses? | [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate) | verify/use | stable |\n| How do I declare, render, and audit product KFD-2 release trust claims? | [`kfd-support.md`](kfd-support.md#kfd-2) + [`release-passport.md`](release-passport.md#kfd-2-release-trust-passport-audit) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I gate KFD-3 collaboration-interface releases? | [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I detect, register, audit, witness, or query KFD-3 product surfaces? | [`kfd-support.md`](kfd-support.md) + [`cli.md`](cli.md) | verify/use | stable |\n| How do I adopt the KFD Agent Hub profile with one declaration and one adapter? | [`kfd-agent-hub.md`](kfd-agent-hub.md) | verify/use | preview |\n| How do I keep `@v3` floating refs while detecting Buildchain contract drift? | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) | verify/use | stable |\n| How do reusable workflows bind controller intent, source/runtime identity, outcomes, and receipt evidence? | [`controller-evidence.md`](controller-evidence.md) | verify/use | draft |\n| How do I propagate finalized upstream releases to downstream package/site PRs? | [`release-propagation.md`](release-propagation.md) | use | preview |\n| How do paper or report repositories publish PDFs, metadata, source bundles, site-consumable manifests, npm packages, and GitHub Releases? | [`publication-artifacts.md`](publication-artifacts.md) | use | stable |\n| How do I generate KFD / Release Passport badge bundles without hand-maintaining Markdown? | [`readme-badges.md`](readme-badges.md) + [`cli.md`](cli.md) | use | stable |\n| How do I generate and verify a Homebrew tap from release passport evidence? | [`homebrew.md`](homebrew.md) + [`cli.md`](cli.md) | use/verify | stable |\n| How do I prove a PR-stage reusable build is the artifact source promoted later? | [`release-candidate.md`](release-candidate.md) + [`reusable-build-surface.md`](reusable-build-surface.md) | verify | stable |\n| Why are binary release assets archived by platform, and where is the single bundle? | [`binary-distribution.md`](binary-distribution.md) | verify | stable |\n| How do I add timestamped logs inside build scripts? | [`toolkit-observability.md`](toolkit-observability.md) | use | stable |\n| What package-owned facts should buildchain.libkungfu.dev render? | [`site-bundle-contract.md`](site-bundle-contract.md) | use | stable |\n| How do I call the reusable build workflow? | [`reusable-build-surface.md`](reusable-build-surface.md) | use | stable |\n| How does Buildchain schedule and aggregate a project-owned Shifu Gate profile? | [`shifu-gate-profiles.md`](shifu-gate-profiles.md) | use/verify | draft |\n| How do exact build artifacts become qualified, transcript-traceable demo media? | [`auditable-demo.md`](auditable-demo.md) | use/verify | draft |\n| 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 |\n| 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 |\n| 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 |\n| How do ephemeral GitHub-hosted runners share exact dependency or compiler caches without fixed-runner affinity? | [`cli.md`](cli.md#commands) | use/verify | preview |\n| How do I validate an unreleased Buildchain runtime train while keeping `@v3`? | [`runtime-train-validation.md`](runtime-train-validation.md) | use | stable |\n| How do I automatically qualify alpha candidates and publish the newest non-revoked qualified candidate at a fixed window? | [`stable-candidate-patrol.md`](stable-candidate-patrol.md) | use | preview |\n| How do I deploy a site/app preview, staging, or production surface? | [`web-surface-deployments.md`](web-surface-deployments.md) | use | stable |\n| How do I publish observed infrastructure contracts for downstream consumers? | [`infra-contract.md`](infra-contract.md) | use | preview |\n| How do I use the active actions directly? | [`../actions/validate-config/README.md`](../actions/validate-config/README.md), [`../actions/run-lifecycle/README.md`](../actions/run-lifecycle/README.md), [`../actions/promote-buildchain-ref/README.md`](../actions/promote-buildchain-ref/README.md), [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md), [`../actions/github-artifact-attestation/README.md`](../actions/github-artifact-attestation/README.md), [`../actions/macos-credential-island/README.md`](../actions/macos-credential-island/README.md); `dist/site/workflow-registry.json#actions` is authoritative for the six-entry inventory. | use | stable |\n| How can a consumer workflow report a Buildchain-owned failure back to Buildchain? | [`consumer-issue-reporting.md`](consumer-issue-reporting.md) + [`../actions/report-buildchain-issue/README.md`](../actions/report-buildchain-issue/README.md) | use | stable |\n| What do the fixture repositories demonstrate? | [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md), [`../fixtures/publish-transaction-shaped/README.md`](../fixtures/publish-transaction-shaped/README.md), [`../fixtures/web-surface-shaped/README.md`](../fixtures/web-surface-shaped/README.md), [`../fixtures/publication-artifact-shaped/README.md`](../fixtures/publication-artifact-shaped/README.md) | verify | stable |\n| What license and contribution terms apply? | [`../LICENSE`](../LICENSE) + [`../LICENSE-POLICY.md`](../LICENSE-POLICY.md) | use | stable |\n| What trademark, official-service, and provider-compliance boundaries apply? | [`../TRADEMARK.md`](../TRADEMARK.md) + [`../ACCEPTABLE_USE.md`](../ACCEPTABLE_USE.md) + [`../PROVIDER_COMPLIANCE.md`](../PROVIDER_COMPLIANCE.md) | use | stable |\n| How do I report a vulnerability? | [`../SECURITY.md`](../SECURITY.md) | use | stable |\n\n## Also asking about\n\n- **ABV / old workflows / old action repositories** -> [`release-governance.md`](release-governance.md)\n  and [`migration-inventory.md`](migration-inventory.md).\n- **v3 / v3-alpha / v3.0 / v3.0-alpha / exact tags / floating tags** ->\n  [`release-governance.md`](release-governance.md) and\n  [`release-flow.md`](release-flow.md).\n- **Buildchain self-dogfood / released alpha canary / stable compatibility lane** ->\n  [`release-governance.md`](release-governance.md#buildchain-alpha-self-dogfood).\n- **qualified alpha ledger / scheduled stable selection / hold and revoke** ->\n  [`stable-candidate-patrol.md`](stable-candidate-patrol.md).\n- **v3.1 vs v3.2 / when to open a new minor line** ->\n  [`versioning.md`](versioning.md).\n- **dry-run / what would happen if this channel PR merges** -> [`cli.md`](cli.md)\n  and [`release-flow.md`](release-flow.md).\n- **protected dev branches / scheduled ready-PR merge / daily-weekly-monthly patrol** ->\n  [`release-governance.md`](release-governance.md#protected-dev-branches) and\n  [`release-governance.md`](release-governance.md#buildchain-patrol).\n- **pnpm / npm / yarn / package-manager adapters** ->\n  [`lifecycle-protocol.md`](lifecycle-protocol.md).\n- **pip / Conan / CMake / custom commands** -> [`lifecycle-protocol.md`](lifecycle-protocol.md)\n  and [`reusable-build-surface.md`](reusable-build-surface.md).\n- **libnode / native artifacts / self-hosted runner matrix** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md) and\n  [`../fixtures/libnode-shaped/README.md`](../fixtures/libnode-shaped/README.md).\n- **S3 artifact relay / self-hosted runner artifact transfer** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#artifact-transfer-relay).\n- **local Git checkout cache / self-hosted source transport** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#locked-source-checkout-cache).\n- **runtime train validation / temporary `buildchain-ref` override** ->\n  [`runtime-train-validation.md`](runtime-train-validation.md) and\n  [`reusable-build-surface.md`](reusable-build-surface.md).\n- **consumer workflow feedback / automatic Buildchain GitHub issues** ->\n  [`consumer-issue-reporting.md`](consumer-issue-reporting.md).\n- **PR-stage RC artifacts / promote-only release candidates** ->\n  [`release-candidate.md`](release-candidate.md) and\n  [`reusable-build-surface.md`](reusable-build-surface.md).\n- **infra contract / observed infrastructure outputs / downstream contract propagation** ->\n  [`infra-contract.md`](infra-contract.md).\n- **standalone binary install / platform archives / GitHub Release bundle** ->\n  [`install.md`](install.md), [`binary-distribution.md`](binary-distribution.md),\n  and [`release-passport.md`](release-passport.md).\n- **Trusted Publishing / npm / publish evidence / recovery** ->\n  [`cli.md`](cli.md) and [`publish-transaction.md`](publish-transaction.md).\n- **Git source digest / module build facts / product build facts / legacy\n  Kungfu build info** -> [`build-facts.md`](build-facts.md) and [`cli.md`](cli.md).\n- **release chains / upstream package or publication artifact as source of truth / site synchronization** ->\n  [`release-propagation.md`](release-propagation.md).\n- **paper repositories / PDFs / publication manifests / immutable archive registries / source bundles** ->\n  [`publication-artifacts.md`](publication-artifacts.md).\n- **README status badges / KFD badge bundles / badge facts JSON** ->\n  [`readme-badges.md`](readme-badges.md) and [`cli.md`](cli.md).\n- **Homebrew taps / distribution indexes / Formula drift checks** ->\n  [`homebrew.md`](homebrew.md) and [`cli.md`](cli.md).\n- **KFD-1 contract worlds / byte-for-byte release gates** ->\n  [`release-passport.md`](release-passport.md#kfd-1-contract-world-release-gate).\n- **KFD-2 public release trust claim audit** ->\n  [`release-passport.md`](release-passport.md#kfd-2-release-trust-passport-audit).\n- **KFD-3 collaboration-interface / agent-facing control surface closure** ->\n  [`release-passport.md`](release-passport.md#kfd-3-collaboration-interface-release-gate).\n- **floating `@v3` / contract lock / compatible drift issue** ->\n  [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock).\n- **GitHub Release passport / binary assets / artifact evidence / agent release checks** ->\n  [`release-passport.md`](release-passport.md),\n  [`binary-distribution.md`](binary-distribution.md), and [`cli.md`](cli.md).\n- **Buildchain logging / timestamps / consumer build phase timing** ->\n  [`toolkit-observability.md`](toolkit-observability.md) for JavaScript API\n  imports, and [`cli.md`](cli.md) for workflow or shell command usage.\n- **buildchain.libkungfu.dev / package-owned site facts** ->\n  [`site-bundle-contract.md`](site-bundle-contract.md).\n- **sites / web previews / staging / production gates** ->\n  [`web-surface-deployments.md`](web-surface-deployments.md).\n- **trademark / fork / official service / provider compliance / release\n  evidence boundary** -> [`../TRADEMARK.md`](../TRADEMARK.md),\n  [`../ACCEPTABLE_USE.md`](../ACCEPTABLE_USE.md), and\n  [`../PROVIDER_COMPLIANCE.md`](../PROVIDER_COMPLIANCE.md).\n\n## How this map is maintained\n\n- A document becomes a row here when it is a stable entrypoint for a user,\n  contributor, or workflow consumer.\n- A row's status must never claim more than the artifact delivers.\n- `why` documents explain intent and design pressure; `verify` and `use`\n  documents should state what is guaranteed, where to verify it, and the current\n  maturity of that guarantee."
     },
     {
       "id": "manual:migration-inventory",
@@ -1188,7 +1254,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/migration-inventory.md",
-      "digest": "sha256:bb73731a3b747d02b9453537109754f194c58dba92c260ac84c632b0d58607af",
+      "digest": "sha256:25d896711f4efebffa9a8960b7eb97438d9fd4892aa08bef0339026e83a53bdf",
       "headings": [
         {
           "level": 1,
@@ -1227,8 +1293,8 @@
         },
         {
           "level": 2,
-          "title": "Stable v2 Refs",
-          "anchor": "stable-v2-refs"
+          "title": "Current v3 Refs",
+          "anchor": "current-v3-refs"
         },
         {
           "level": 2,
@@ -1236,7 +1302,7 @@
           "anchor": "verification-gates"
         }
       ],
-      "markdown": "# Buildchain v2 Migration Inventory\n\nThis inventory records the buildchain v2 action surface. Buildchain v2 is the\nmonorepo source of truth for active Kungfu repository workflows, the active\nreusable build workflow, and the three GitHub Actions that are still part of\nBuildchain's reusable contract.\nStandalone `workflows` and `action-*` repositories are historical rollback\nanchors, not active Buildchain migration targets.\n\n## Workflow Sources\n\n| Source repository | Previous branch | Buildchain v2 disposition |\n| --- | --- | --- |\n| `workflows` | `dev/v2/v2.0` | root `.github/workflows` sources migrated; reusable workflows linted by actionlint |\n\n## Reusable Workflow Boundaries\n\nThe active Buildchain-native reusable surface is:\n\n| Workflow | Disposition |\n| --- | --- |\n| `.github/workflows/.build.yml` | active reusable build contract: runner presets, trusted event gate, publish source lock, lifecycle commands, deterministic artifacts, aggregate summary, and release manifest outputs |\n\nHidden reusable workflow files from the old `workflows` repository are retained\nonly when they still have an active compatibility or migration boundary. Retired\nPR orchestration paths are not kept in `.github/workflows`; they remain listed\nin the inventory as excluded legacy surfaces. In particular,\n`.batch-pull-request.yml` is removed with the retired batch PR action family,\nand the legacy `.release-new-version.yml` path is not the modern publish\nsurface. New publish integrations should use `.build.yml`, `buildchain.toml`,\n`lifecycle.publish`, and publish transaction evidence.\n\nRelease templates that previously performed direct publishing or deployment are\nnow fail-closed when retained for compatibility discovery. They do not call\nlegacy publish actions, `npm publish`, or deploy providers directly. Callers must\nmigrate to `release-candidate-promote.yml@v3` or a project-owned\n`lifecycle.publish` command behind a publish-gate source lock, so floating\n`@v3` consumers cannot bypass source-lock drift protection.\n\nThe public promotion workflow is now a generated dual-channel router. Existing\ncallers remain source-compatible, while callers that want alpha workflow-shell\nfixes before stable promotion should add `buildchain-channel: auto` plus\n`buildchain-alpha-contract-lock-path` and\n`buildchain-stable-contract-lock-path`. Keep one common promotion declaration;\ndo not duplicate alpha and stable jobs or call\n`.release-candidate-promote.yml` directly.\n\nBuildchain also keeps the workflow-file layout transition declarative in\n`.buildchain/promotion-shell-routing.json`. Stable `v2.14.13` contains the hidden\nadvanced workflow, so the stable lane is pinned to that implementation's\nimmutable release SHA and forwards the full internal identity surface. This is\nprovider-owned compatibility state; consumers still keep the same single public\npromotion job.\n\n## Migrated Actions\n\nNo standalone `action-*` repository is shipped as a Buildchain action anymore.\nOld product, operations, PR-helper, page-generation, dependency-sync, and\nversion-bump actions have either been retired or absorbed into Buildchain's\nnative lifecycle, reusable workflow, and promotion scripts.\n\n## Retired Actions Excluded From v2\n\nThese legacy action repositories are intentionally not shipped as buildchain v2\nactions because the corresponding workflows now reject the retired mechanism or\nbecause the action is part of that retired path.\n\n| Previous repository | Reason |\n| --- | --- |\n| `action-approve` | retired GitHub issue/PR helper; use repository-native GitHub automation |\n| `action-batch-pull-request` | retired PR orchestration helper; not part of the Buildchain reusable contract |\n| `action-bump-version` | replaced by Buildchain release-line scripts and `actions/promote-buildchain-ref` |\n| `action-check-format` | replaced by project-owned `lifecycle.verify` commands |\n| `action-find-dependencies` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |\n| `action-generate-download-page` | retired product page generator; model as project-owned lifecycle/deploy work if needed |\n| `action-generate-release-page` | retired product page generator; model as project-owned lifecycle/deploy work if needed |\n| `action-merge-close-issue` | retired GitHub issue/PR helper; use repository-native GitHub automation |\n| `action-package-dependency` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |\n| `action-publish-prebuilt` | retired S3 prebuilt publisher; use lifecycle publish plus publish transaction evidence |\n| `action-purge-artifacts` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |\n| `action-qa-automated` | retired external QA trigger; model as project-owned lifecycle or workflow logic |\n| `action-release-note` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |\n| `action-rollback-release` | replaced by Buildchain publish transaction recover/finalize/repair semantics |\n| `action-set-collaborators` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |\n| `action-sync-airtable` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |\n| `action-sync-extensions-version` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |\n| `action-sync-pr` | retired PR synchronization helper; not part of the Buildchain reusable contract |\n| `action-update-dependencies-version` | retired dependency-version helper; use package-manager adapters and lifecycle commands |\n\n## Retired Workflows Excluded From v2\n\nThese legacy workflow entrypoints are intentionally not shipped from the root\n`.github/workflows` directory.\n\n| Previous workflow | Reason |\n| --- | --- |\n| `.batch-pull-request.yml` | retired PR orchestration helper; v2.5 dev integration governance will use a new protected-dev PR protocol instead |\n| `.release-new-version.yml` | retained as a fail-closed compatibility stub; direct publish model replaced by source-locked release-candidate promotion |\n| `.release-elastic-beanstalk.yml` | retained as a fail-closed compatibility stub; deploy side effects must move behind project lifecycle publish and publish-gate source locks |\n| `.sam-release.yml` | retained as a fail-closed compatibility stub; deploy side effects must move behind project lifecycle publish and publish-gate source locks |\n| `.wheel-release.yml` | retained as a fail-closed compatibility stub; package publish side effects must move behind project lifecycle publish and publish-gate source locks |\n\n## Buildchain-Native Actions\n\nThese actions are new Buildchain v2 surfaces rather than migrations from an\nolder standalone action repository.\n\n| Buildchain path | Purpose |\n| --- | --- |\n| `actions/promote-buildchain-ref` | governance-closed Buildchain release ref promotion |\n| `actions/run-lifecycle` | lifecycle command execution and deterministic artifact manifest generation |\n| `actions/validate-config` | `buildchain.toml` version-state and lifecycle preflight without executing lifecycle commands |\n\n## Stable v2 Refs\n\n- Actions: `kungfu-systems/buildchain/actions/<name>@v3`\n- Reusable workflows: `kungfu-systems/buildchain/.github/workflows/<workflow>.yml@v3`\n\n## Verification Gates\n\n- `pnpm install --frozen-lockfile`\n- `pnpm run check`\n- GitHub-hosted `Verify` workflow\n- Manual `Self-hosted Runner Smoke` workflow for trusted self-hosted runner validation"
+      "markdown": "---\nstatus: historical\nperiod: 2026-07\ntheme: buildchain-v2-migration-inventory\ndoc_type: migration-inventory\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-31\n  invisible_context: not asserted\n---\n\n# Buildchain v2 Migration Inventory\n\nThis historical inventory records the Buildchain v2 consolidation boundary.\nBuildchain v3 is now the active monorepo source of truth for Kungfu repository\nworkflows, reusable build workflows, and Buildchain-native actions. The v2\nnames below preserve the migration decisions that v3 inherited; they are not a\ncurrent runtime baseline.\nStandalone `workflows` and `action-*` repositories are historical rollback\nanchors, not active Buildchain migration targets.\n\n## Workflow Sources\n\n| Source repository | Previous branch | Buildchain v2 disposition |\n| --- | --- | --- |\n| `workflows` | `dev/v2/v2.0` | root `.github/workflows` sources migrated; reusable workflows linted by actionlint |\n\n## Reusable Workflow Boundaries\n\nThe active Buildchain-native reusable surface is:\n\n| Workflow | Disposition |\n| --- | --- |\n| `.github/workflows/.build.yml` | active reusable build contract: runner presets, trusted event gate, publish source lock, lifecycle commands, deterministic artifacts, aggregate summary, and release manifest outputs |\n\nHidden reusable workflow files from the old `workflows` repository are retained\nonly when they still have an active compatibility or migration boundary. Retired\nPR orchestration paths are not kept in `.github/workflows`; they remain listed\nin the inventory as excluded legacy surfaces. In particular,\n`.batch-pull-request.yml` is removed with the retired batch PR action family,\nand the legacy `.release-new-version.yml` path is not the modern publish\nsurface. New publish integrations should use `.build.yml`, `buildchain.toml`,\n`lifecycle.publish`, and publish transaction evidence.\n\nRelease templates that previously performed direct publishing or deployment are\nnow fail-closed when retained for compatibility discovery. They do not call\nlegacy publish actions, `npm publish`, or deploy providers directly. Callers must\nmigrate to `release-candidate-promote.yml@v3` or a project-owned\n`lifecycle.publish` command behind a publish-gate source lock, so floating\n`@v3` consumers cannot bypass source-lock drift protection.\n\nThe public promotion workflow is now a generated dual-channel router. Existing\ncallers remain source-compatible, while callers that want alpha workflow-shell\nfixes before stable promotion should add `buildchain-channel: auto` plus\n`buildchain-alpha-contract-lock-path` and\n`buildchain-stable-contract-lock-path`. Keep one common promotion declaration;\ndo not duplicate alpha and stable jobs or call\n`.release-candidate-promote.yml` directly.\n\nBuildchain also keeps the workflow-file layout transition declarative in\n`.buildchain/promotion-shell-routing.json`. Stable `v2.14.13` contains the hidden\nadvanced workflow, so the stable lane is pinned to that implementation's\nimmutable release SHA and forwards the full internal identity surface. This is\nprovider-owned compatibility state; consumers still keep the same single public\npromotion job.\n\n## Migrated Actions\n\nNo standalone `action-*` repository is shipped as a Buildchain action anymore.\nOld product, operations, PR-helper, page-generation, dependency-sync, and\nversion-bump actions have either been retired or absorbed into Buildchain's\nnative lifecycle, reusable workflow, and promotion scripts.\n\n## Retired Actions Excluded From v2\n\nThese legacy action repositories are intentionally not shipped as buildchain v2\nactions because the corresponding workflows now reject the retired mechanism or\nbecause the action is part of that retired path.\n\n| Previous repository | Reason |\n| --- | --- |\n| `action-approve` | retired GitHub issue/PR helper; use repository-native GitHub automation |\n| `action-batch-pull-request` | retired PR orchestration helper; not part of the Buildchain reusable contract |\n| `action-bump-version` | replaced by Buildchain release-line scripts and `actions/promote-buildchain-ref` |\n| `action-check-format` | replaced by project-owned `lifecycle.verify` commands |\n| `action-find-dependencies` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |\n| `action-generate-download-page` | retired product page generator; model as project-owned lifecycle/deploy work if needed |\n| `action-generate-release-page` | retired product page generator; model as project-owned lifecycle/deploy work if needed |\n| `action-merge-close-issue` | retired GitHub issue/PR helper; use repository-native GitHub automation |\n| `action-package-dependency` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |\n| `action-publish-prebuilt` | retired S3 prebuilt publisher; use lifecycle publish plus publish transaction evidence |\n| `action-purge-artifacts` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |\n| `action-qa-automated` | retired external QA trigger; model as project-owned lifecycle or workflow logic |\n| `action-release-note` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |\n| `action-rollback-release` | replaced by Buildchain publish transaction recover/finalize/repair semantics |\n| `action-set-collaborators` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |\n| `action-sync-airtable` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |\n| `action-sync-extensions-version` | retired in workflows v2 or backed by retired Airtable/dependency/collaborator/purge mechanism |\n| `action-sync-pr` | retired PR synchronization helper; not part of the Buildchain reusable contract |\n| `action-update-dependencies-version` | retired dependency-version helper; use package-manager adapters and lifecycle commands |\n\n## Retired Workflows Excluded From v2\n\nThese legacy workflow entrypoints are intentionally not shipped from the root\n`.github/workflows` directory.\n\n| Previous workflow | Reason |\n| --- | --- |\n| `.batch-pull-request.yml` | retired PR orchestration helper; v2.5 dev integration governance will use a new protected-dev PR protocol instead |\n| `.release-new-version.yml` | retained as a fail-closed compatibility stub; direct publish model replaced by source-locked release-candidate promotion |\n| `.release-elastic-beanstalk.yml` | retained as a fail-closed compatibility stub; deploy side effects must move behind project lifecycle publish and publish-gate source locks |\n| `.sam-release.yml` | retained as a fail-closed compatibility stub; deploy side effects must move behind project lifecycle publish and publish-gate source locks |\n| `.wheel-release.yml` | retained as a fail-closed compatibility stub; package publish side effects must move behind project lifecycle publish and publish-gate source locks |\n\n## Buildchain-Native Actions\n\nThese actions are new Buildchain v2 surfaces rather than migrations from an\nolder standalone action repository.\n\n| Buildchain path | Purpose |\n| --- | --- |\n| `actions/promote-buildchain-ref` | governance-closed Buildchain release ref promotion |\n| `actions/run-lifecycle` | lifecycle command execution and deterministic artifact manifest generation |\n| `actions/validate-config` | `buildchain.toml` version-state and lifecycle preflight without executing lifecycle commands |\n\n## Current v3 Refs\n\n- Actions: `kungfu-systems/buildchain/actions/<name>@v3`\n- Reusable workflows: `kungfu-systems/buildchain/.github/workflows/<workflow>.yml@v3`\n\n## Verification Gates\n\n- `pnpm install --frozen-lockfile`\n- `pnpm run check`\n- GitHub-hosted `Verify` workflow\n- Manual `Self-hosted Runner Smoke` workflow for trusted self-hosted runner validation"
     },
     {
       "id": "manual:observed-evidence-patrol",
@@ -1249,7 +1315,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/observed-evidence-patrol.md",
-      "digest": "sha256:dec743faa883f3a3356beb35f97e62098bda09577445e402a5db72159e525167",
+      "digest": "sha256:9e806efee048dd4fbaa68349ed4200c61d6408b0470ff81a4616a454cc32248c",
       "headings": [
         {
           "level": 1,
@@ -1272,7 +1338,7 @@
           "anchor": "rollback-and-recovery"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: observed-evidence-patrol\ndoc_type: contract\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-21\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-21\n  invisible_context_boundary: No credentials, private logs, or unpublished evidence values are included.\n---\n\n# Observed Evidence Patrol\n\nObserved Evidence Patrol publishes a reproducible public observation without\ncreating a content PR for every refresh. It is for derived evidence whose\nmeaning is fully checked by the caller and whose publication safety can be\ndecided mechanically.\n\nThe caller generates a `kungfu-buildchain-observed-evidence-bundle`. The bundle\nbinds one `snapshot.id` to two byte-identical JSON files:\n\n- a versioned immutable object such as\n  `dogfood-evidence/snapshots/<snapshotId>.json`;\n- a mutable last-known-good alias such as `dogfood-evidence.json`.\n\nBuildchain verifies both file digests and snapshot identities before receiving\nproduction authority. Apply then performs this order:\n\n1. conditionally create the immutable key with `If-None-Match: *`;\n2. read the immutable key back and verify its declared SHA-256 metadata;\n3. record the previous latest metadata as the rollback pointer;\n4. atomically replace the latest object;\n5. read latest back and verify the same snapshot and digest;\n6. invalidate only the declared viewer paths.\n\nAny generator, schema, digest, immutable-key, provider, or read-after-write\nfailure leaves the previous latest object in place. A colliding immutable key\nis reusable only when both snapshot identity and SHA-256 match; otherwise the\nrun fails without overwriting it.\n\n## Trust boundary\n\nThe reusable workflow admits only `schedule` or `workflow_dispatch` events on\nthe caller repository's default branch. It checks out that branch explicitly,\ndoes not persist Git credentials, and never runs pull-request or fork code. The\nconsumer owns its evidence semantics through the build and verify commands;\nBuildchain owns publication ordering and provider safety.\n\nProduction OIDC authority should be a dedicated role and Environment with no\nreview gate for steady-state refreshes. Its policy should allow only:\n\n- `s3:GetObject` and `s3:PutObject` on the exact latest key;\n- the same actions on the exact immutable snapshot prefix;\n- `cloudfront:CreateInvalidation` on the one distribution.\n\nIt must not receive bucket-wide delete, list, repository write, GitHub PR, or\ngeneral deployment authority. One-time workflow, IAM, schema, and page changes\nstill use normal review and release governance.\n\n## Ordinary site releases\n\nA site artifact that contains\n`.buildchain/observed-evidence-ownership.json` declares the paths owned by the\nPatrol channel. Web-surface deploy adds those paths to the S3 sync exclusion\nset, so a later full-site release cannot delete the snapshot archive or replace\nlatest with an older build fixture. The HTML page should project the latest\nJSON at runtime, retaining its committed copy only as an explicitly labelled\nfallback.\n\n## Rollback and recovery\n\nEvery receipt records the previous latest snapshot id, digest, ETag, and S3\nversion id when available. Rollback regenerates a bundle whose latest file is\nthe selected immutable snapshot and republishes it through the same validator;\noperators do not edit or delete immutable history. If CDN invalidation fails\nafter latest advances, rerunning the same bundle is idempotent and repairs edge\nconvergence."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: observed-evidence-patrol\ndoc_type: contract\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-30\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-30\n  invisible_context_boundary: No credentials, private logs, or unpublished evidence values are included.\n---\n\n# Observed Evidence Patrol\n\nObserved Evidence Patrol publishes a reproducible public observation without\ncreating a content PR for every refresh. It is for derived evidence whose\nmeaning is fully checked by the caller and whose publication safety can be\ndecided mechanically.\n\nThe caller generates a `kungfu-buildchain-observed-evidence-bundle`. The bundle\nbinds one `snapshot.id` to two byte-identical JSON files:\n\n- a versioned immutable object such as\n  `dogfood-evidence/snapshots/<snapshotId>.json`;\n- a mutable last-known-good alias such as `dogfood-evidence.json`.\n\nThe bundle may also declare up to 16 derived mutable projections under\n`publication.projections`. Each projection declares its artifact-relative\n`source`, bounded destination `key`, exact `sha256`, `contentType`, and\n`cacheControl`. This supports static HTML such as `dogfood/index.html` without\nchanging the existing immutable/latest JSON contract.\n\nBuildchain verifies both file digests and snapshot identities before receiving\nproduction authority. Apply then performs this order:\n\n1. conditionally create the immutable key with `If-None-Match: *`;\n2. read the immutable key back and verify its declared SHA-256 metadata;\n3. record preceding version metadata for every declared mutable key;\n4. write and read back each derived projection in manifest order;\n5. atomically replace the latest object;\n6. read latest back and verify the same snapshot and digest;\n7. invalidate only the declared viewer paths.\n\nProjection-enabled publication requires bucket versioning before replacing an\nexisting mutable key. If a later projection, latest update, or invalidation\nfails, Buildchain restores preceding object versions in reverse order and\nremoves newly introduced declared projection keys. Rollback never lists the\nbucket and never touches keys outside the manifest.\n\nAny generator, schema, digest, immutable-key, provider, or read-after-write\nfailure leaves the previous latest object in place. A colliding immutable key\nis reusable only when both snapshot identity and SHA-256 match; otherwise the\nrun fails without overwriting it.\n\n## Trust boundary\n\nThe reusable workflow admits only `schedule` or `workflow_dispatch` events on\nthe caller repository's default branch. It checks out that branch explicitly,\ndoes not persist Git credentials, and never runs pull-request or fork code. The\nconsumer owns its evidence semantics through the build and verify commands;\nBuildchain owns publication ordering and provider safety.\n\nProduction OIDC authority should be a dedicated role and Environment with no\nreview gate for steady-state refreshes. Its policy should allow only:\n\n- `s3:GetObject` and `s3:PutObject` on the exact latest key;\n- the same actions on the exact immutable snapshot prefix;\n- for projection-enabled bundles, `s3:GetObjectVersion` and bounded\n  `s3:DeleteObject` on the exact declared mutable keys;\n- `cloudfront:CreateInvalidation` on the one distribution.\n\nIt must not receive bucket-wide delete, list, repository write, GitHub PR, or\ngeneral deployment authority. One-time workflow, IAM, schema, and page changes\nstill use normal review and release governance.\n\n## Ordinary site releases\n\nA site artifact that contains\n`.buildchain/observed-evidence-ownership.json` declares the paths owned by the\nPatrol channel. Web-surface deploy adds those paths to the S3 sync exclusion\nset, so a later full-site release cannot delete the snapshot archive or replace\nlatest with an older build fixture. The HTML page should project the latest\nJSON at runtime, retaining its committed copy only as an explicitly labelled\nfallback.\n\n## Rollback and recovery\n\nEvery receipt records the previous latest and projection snapshot ids, digests,\nETags, and S3 version ids when available. A projection transaction rolls back\nautomatically when a later mutable step or CDN invalidation fails. Operators\ncan also regenerate a bundle whose latest file is the selected immutable\nsnapshot and republish it through the same validator; immutable history is\nnever overwritten or deleted. Legacy bundles without projections retain their\nexisting idempotent rerun behavior when CDN invalidation alone fails."
     },
     {
       "id": "manual:ownership",
@@ -1285,7 +1351,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/ownership.md",
-      "digest": "sha256:a9f54f211b55da6464d890b0ebfe046dbf564aabdfee3aadf457723f9aae398a",
+      "digest": "sha256:91a1b59f0f71067c58ffd685a23b29e14a4d6fe33c1a44f8708b7d0512e4baa5",
       "headings": [
         {
           "level": 1,
@@ -1318,7 +1384,7 @@
           "anchor": "source-locked-publish-rule"
         }
       ],
-      "markdown": "# Ownership And Migration Rules\n\n## Source Of Truth\n\nBuildchain v2 workflow and action design lands in this repository. Standalone\n`workflows` and `action-*` repositories are historical rollback anchors.\nBuildchain only ships the native action surface required for config validation,\nlifecycle execution, and release ref promotion.\n\n## Compatibility Rule\n\nDo not break existing stable reusable workflow refs during migration:\n\n- `kungfu-systems/workflows@v2`\n\nAny consumer migration must record:\n\n- old `uses:` refs;\n- new `uses:` refs;\n- workflow run ids;\n- rollback command or revert path.\n\nNew stable references should use:\n\n- `kungfu-systems/buildchain/actions/validate-config@v3`\n- `kungfu-systems/buildchain/actions/run-lifecycle@v3`\n- `kungfu-systems/buildchain/actions/promote-buildchain-ref@v3`\n- `kungfu-systems/buildchain/.github/workflows/<workflow>.yml@v3`\n\n## Publishing Rule\n\nPublishing paths stay disabled in buildchain's own verification workflows unless\nexplicitly enabled by a production release workflow. Any consumer cutover that\npublishes packages, S3 artifacts, release pages, or preview links must include\nrollback notes. Reusable workflow consumers should gate publish jobs with\n`needs.<build-job>.outputs.publish-allowed == 'true'` and record the requested\n`publish-channel`, rather than duplicating channel branch logic in every\nconsumer workflow.\n\n## Candidate Ref Rule\n\nCandidate refs are expected to resolve under `kungfu-systems/*`. Broader\nsources require an explicit trust decision before they can reach self-hosted\nrunners or secrets.\n\n## Source-Locked Publish Rule\n\nWhen a consumer uses `publish-gate/*` branches, publish jobs must use the\nresolved `publish-source-sha` and `release-manifest-json` emitted by the reusable\nbuild workflow. Before touching a package registry, S3 bucket, release page, or\nfloating alias, the publish job must verify that the gate branch still points at\nthe recorded SHA. A moved gate branch is a stale release decision, not a retry."
+      "markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-ownership-and-migration\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-31\n  invisible_context: not asserted\n---\n\n# Ownership And Migration Rules\n\n## Source Of Truth\n\nBuildchain v3 workflow and action design lands in this repository. Standalone\n`workflows` and `action-*` repositories are historical rollback anchors.\nBuildchain only ships the native action surface required for config validation,\nlifecycle execution, and release ref promotion.\n\n## Compatibility Rule\n\nDo not break existing stable reusable workflow refs during migration:\n\n- `kungfu-systems/workflows@v2`\n\nAny consumer migration must record:\n\n- old `uses:` refs;\n- new `uses:` refs;\n- workflow run ids;\n- rollback command or revert path.\n\nNew stable references should use:\n\n- `kungfu-systems/buildchain/actions/validate-config@v3`\n- `kungfu-systems/buildchain/actions/run-lifecycle@v3`\n- `kungfu-systems/buildchain/actions/promote-buildchain-ref@v3`\n- `kungfu-systems/buildchain/.github/workflows/<workflow>.yml@v3`\n\n## Publishing Rule\n\nPublishing paths stay disabled in buildchain's own verification workflows unless\nexplicitly enabled by a production release workflow. Any consumer cutover that\npublishes packages, S3 artifacts, release pages, or preview links must include\nrollback notes. Reusable workflow consumers should gate publish jobs with\n`needs.<build-job>.outputs.publish-allowed == 'true'` and record the requested\n`publish-channel`, rather than duplicating channel branch logic in every\nconsumer workflow.\n\n## Candidate Ref Rule\n\nCandidate refs are expected to resolve under `kungfu-systems/*`. Broader\nsources require an explicit trust decision before they can reach self-hosted\nrunners or secrets.\n\n## Source-Locked Publish Rule\n\nWhen a consumer uses `publish-gate/*` branches, publish jobs must use the\nresolved `publish-source-sha` and `release-manifest-json` emitted by the reusable\nbuild workflow. Before touching a package registry, S3 bucket, release page, or\nfloating alias, the publish job must verify that the gate branch still points at\nthe recorded SHA. A moved gate branch is a stale release decision, not a retry."
     },
     {
       "id": "manual:product-mechanism",
@@ -1373,7 +1439,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/publication-artifacts.md",
-      "digest": "sha256:56f706554ec5fb34e1cc57f77b5237a13e5c616b4e3926a31b07dce3ef8a94db",
+      "digest": "sha256:bd97fb3233cddff59036f555922d7f26c66a68167a26c336618d327bc60adf78",
       "headings": [
         {
           "level": 1,
@@ -1385,6 +1451,11 @@
           "title": "Configuration",
           "anchor": "configuration"
         },
+        {
+          "level": 2,
+          "title": "Reproducibility Gate",
+          "anchor": "reproducibility-gate"
+        },
         {
           "level": 2,
           "title": "Reusable Workflow",
@@ -1400,13 +1471,18 @@
           "title": "CLI And Node API",
           "anchor": "cli-and-node-api"
         },
+        {
+          "level": 3,
+          "title": "Unified paper operator surface",
+          "anchor": "unified-paper-operator-surface"
+        },
         {
           "level": 2,
           "title": "Site Consumption",
           "anchor": "site-consumption"
         }
       ],
-      "markdown": "# Publication Artifact Workflow\n\nBuildchain supports `project.type = \"publication-artifact\"` for repositories\nthat produce auditable papers, reports, specifications, or similar publication\npackages. These repositories are artifact producers. They should not be forced\nto become `web-surface` repositories just because a downstream site later\nrenders the paper.\n\nThe split is:\n\n```text\npaper repo = source, PDF, metadata, source bundle, publication manifest\npapers site = layout, navigation, public web surface, downstream rendering\n```\n\n## Configuration\n\nThe paper repository owns `.buildchain/buildchain.toml`:\n\n```toml\nschema = 1\n\n[project]\ntype = \"publication-artifact\"\nname = \"paper-observer-declared-timelines\"\n\n[publication]\nkind = \"paper\"\ntitle = \"Observer-Declared Timelines for Real-World Agent Work\"\nversion = \"0.1.0\"\nprimary_artifact = \"_build/main.pdf\"\nartifact_paths = [\"_build/main.pdf\"]\nmetadata_paths = [\"README.md\", \"docs/MAP.md\"]\nsource_paths = [\"paper\", \"README.md\", \"LICENSE\", \"Makefile\"]\nsite_consumers = [\"papers.libkungfu.dev\"]\nmanifest_path = \".buildchain/publication/publication-artifact.json\"\nsource_bundle_path = \".buildchain/publication/source.tar.gz\"\n\n[publication.archive]\nid = \"observer-declared-timelines\"\ncanonical_url = \"https://papers.libkungfu.dev/observer-declared-timelines/\"\nlatest_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/\"\nlatest_evidence_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json\"\nimmutable_base_url = \"https://papers.libkungfu.dev/archive\"\nregistry_path = \".buildchain/publication/publication-registry.json\"\n\n[publication.toolchain]\ntype = \"latex-docker\"\nimage = \"ghcr.io/kungfu-systems/build-images/latex-pdf-builder\"\ndigest = \"sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8\"\ncommand = \"latexmk -pdf -outdir=_build paper/main.tex\"\n\n[publish]\nkind = \"npm-paper-package\"\npackage = \"@kungfu-tech/paper-observer-declared-timelines\"\nauth = \"trusted-publishing\"\n\n[lifecycle.build]\ncommand = \"make pdf\"\n\n[lifecycle.verify]\ncommand = \"make check\"\n```\n\n`primary_artifact` is the human-facing publication output, usually a PDF.\n`source_paths` are archived into a source bundle. `metadata_paths` are hashed\nand recorded so a site can consume the paper facts without scraping prose.\n\n`publication.archive` turns the publication into an append-only public archive\ncontract:\n\n- `canonical_url` is the stable human reader page.\n- `latest_url` and `latest_evidence_url` are movable aliases for the latest\n  reader page and latest evidence.\n- `immutable_base_url` plus `id` and `publication.version` produce a versioned\n  prefix such as\n  `https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0/`.\n- `immutable_url_prefix` can be used instead when the repository already owns\n  the full version prefix.\n- `registry_path` records every published version and its manifest, passport,\n  source bundle, primary artifact, URLs, and SHA-256 digests.\n\nImmutable archive prefixes are append-only. Do not run site deployment commands\nwith `sync --delete` or equivalent deletion semantics over those prefixes. A\nsame-version republish is allowed only when the immutable digest is unchanged;\nif PDF, source bundle, route, metadata, or toolchain evidence changes for an\nexisting version, Buildchain fails before the registry is rewritten.\n\nThe Buildchain web-surface adapter consumes this boundary from a surface-local\n`manifest.json` whose `archivePolicy.contract` is\n`kungfu-buildchain-publication-archive-policy`. It excludes the derived archive\nroot from every owning or parent `sync --delete`, verifies existing object\ndigests, uploads only missing immutable files with `--no-overwrite`, and verifies\nthem again before mutable site content is synchronized. A current package set\ndoes not need to rebuild or enumerate every historical version: the protected\narchive root remains outside deletion even when older versions disappear from\nthe current artifact.\n\n`publication.toolchain` makes the source-to-PDF transformation part of the\nmachine-readable contract. `latex-docker` is the preferred LaTeX profile. The\nBuildchain paper scaffold and reusable workflow default to\n`ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0`, pinned by the\ndigest above. The workflow pulls the declared image by digest and runs the\ndeclared command in that pinned container. `custom-command` remains available\nfor compatibility, but the passport records it as lower trust because\nBuildchain can record the command boundary without proving the compiler or\nLaTeX distribution digest.\n\n`publish.kind = \"npm-paper-package\"` declares that Buildchain, not the consumer\nrepository, owns the standard paper npm package shape and release transaction\nmechanics. `publish.package` is the public npm package that contains the PDF,\npublication manifest, publication passport, optional archive registry, source\nbundle, and declared metadata files.\n\n## Reusable Workflow\n\nConsumer repositories that only need to build and upload paper evidence can\ncall the build-only wrapper directly:\n\n```yaml\njobs:\n  publication:\n    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v3\n    with:\n      toolchain-type: config\n      verify-command: make check\n      artifact-name: observer-declared-timelines\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe build-only workflow:\n\n- resolves the Buildchain runtime and checks the floating contract lock before\n  any paper build runs;\n- resolves the declared publication toolchain from `[publication.toolchain]` or\n  workflow inputs;\n- for `latex-docker`, pulls the pinned build-images LaTeX builder digest and\n  runs the declared command in the container;\n- for `custom-command`, runs the declared command and records the lower-trust\n  boundary in the passport;\n- runs the verify command;\n- creates a source bundle from `publication.source_paths`;\n- writes `.buildchain/publication/publication-artifact.json`;\n- writes `.buildchain/publication/publication-artifact-passport.json`;\n- when `[publication.archive]` is configured, writes\n  `.buildchain/publication/publication-registry.json` and verifies same-version\n  immutability;\n- uploads one GitHub artifact containing the PDF, manifest, passport, optional\n  registry, and source bundle.\n\nIt does not publish npm packages, deploy web pages, or create GitHub Releases.\n\nThe paper release preset additionally hydrates every prior published package\nregistry from the npm registry before generating the current manifest. npm\npackage integrity authenticates each downloaded source; Buildchain verifies the\nregistry self-digest, merges immutable records, and fails if a cumulative\nregistry drops an accepted version or changes immutable route/artifact facts.\nThe synthesized package therefore carries complete history even on a clean\nrunner. Its cumulative registry and file SHA-256 values are bound into the paper\nrelease build summary and release passport evidence.\n\n## Paper Release Preset\n\nPaper repositories that publish a versioned npm package should use the\nBuildchain-managed release preset instead of copying npm transaction scripts or\npromotion YAML:\n\n```yaml\nname: Paper Release\n\non:\n  push:\n    branches:\n      - alpha/v1/v1.0\n      - release/v1/v1.0\n  workflow_dispatch:\n    inputs:\n      buildchain-ref:\n        description: \"Temporary Buildchain runtime ref\"\n        required: false\n        default: \"\"\n\njobs:\n  paper-release:\n    uses: kungfu-systems/buildchain/.github/workflows/paper-release-sealed.yml@v3\n    permissions:\n      actions: read\n      checks: write\n      contents: write\n      id-token: write\n      issues: write\n    with:\n      buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n      publisher-workflow-path: .github/workflows/paper-release.yml\n      toolchain-type: config\n      verify-command: make check\n      artifact-paths: _build/paper-name.pdf\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n    secrets:\n      BUILDCHAIN_PROMOTION_TOKEN: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n```\n\nThe sealed preset does not use a long-lived token for npm publication. It may\naccept an optional `BUILDCHAIN_PROMOTION_TOKEN` only for machine-generated\nversion-state updates on protected channel branches; npm publication remains\nbound to GitHub OIDC trusted publishing. The preset builds and packages the\npaper in a read-only job, then a credential-free authority job downloads that\nexact candidate, audits the external control plane, and seals a capability over\nthe source tree, Buildchain runtime, controller receipt, PDF, and npm package\nbytes. Only the final job receives write and OIDC permissions; it downloads the\nadmitted candidate, recomputes the capability binding, and publishes without\nexecuting consumer build commands. npm binds the OIDC identity to the consumer\nworkflow named by `publisher-workflow-path`.\n\nThe preset:\n\n- resolves the floating Buildchain runtime once and binds the exact SHA into the\n  publication candidate and authority capability;\n- builds the PDF through the declared pinned LaTeX Docker toolchain or custom\n  command in a read-only job;\n- verifies the paper repository;\n- writes the publication manifest, publication passport, optional archive\n  registry, and source bundle;\n- synthesizes an npm package from `[publication]` and `[publish]` declarations\n  under `.buildchain/publication/npm-package`;\n- computes npm-style `sha512` integrity from `npm pack --dry-run` and passes\n  it as `publish-required-artifacts-json`;\n- creates a `publish-gate/<alpha|release>/.../<version>` source lock for the\n  channel commit and requires `promote-buildchain-ref` to verify that lock\n  before any publish side effect;\n- verifies the complete candidate again after authority and publishes the\n  package through npm Trusted Publishing without rebuilding it;\n- writes Buildchain release/passport evidence; and\n- creates or updates the exact-version GitHub Release by default, uploading\n  every file declared by `publication.primary_artifact` and\n  `publication.artifact_paths` alongside the release evidence.\n\nConsumers can opt out of the GitHub Release with `github-release: false`, but\nthe default is on so downstream release propagation can observe\n`release.published` without hand-written `gh release` steps.\n\nDeclared publication artifacts are resolved from the generated publication\nmanifest rather than repeated in consumer workflow YAML. Publication fails\nbefore upload if a declared artifact is missing or if its basename would\ncollide with another GitHub Release asset.\n\nFor npm Trusted Publishing, register the consumer workflow file that calls this\npreset, for example `.github/workflows/paper-release.yml`, against the declared\npackage in npm. The trusted publisher is the consumer repository and workflow\nfile; the implementation still runs inside Buildchain's reusable workflow.\n\nStandard paper repositories should not carry local copies of\n`scripts/npm-publish-transaction.mjs`, package-generation scripts, or\npromotion/ref-lock YAML. If the default package shape is insufficient, extend\nBuildchain rather than forking the mechanics into each paper repository.\n\n## CLI And Node API\n\nGenerate the publication manifest locally or in CI:\n\n```sh\nbuildchain publication-artifact manifest --source-sha \"$(git rev-parse HEAD)\" --json\n```\n\nGenerate the npm package contents after the manifest exists:\n\n```sh\nbuildchain publication-artifact npm-package --json\n```\n\nNode API:\n\n```js\nimport {\n  collectPublicationArtifact,\n  writePublicationArtifact,\n} from \"@kungfu-tech/buildchain/publication-artifact\";\n\nimport {\n  collectPublicationPackageFacts,\n  preparePublicationNpmPackage,\n} from \"@kungfu-tech/buildchain/publication-package\";\n```\n\n`writePublicationArtifact()` is the single implementation used by the CLI and\nthe reusable workflow. The generated manifest records:\n\n- publication title, kind, authors, and primary artifact;\n- artifact paths, byte sizes, and SHA-256 digests;\n- metadata paths and SHA-256 digests;\n- source SHA, tree SHA, source files, and source bundle digest;\n- publication toolchain type, image, digest, command, invocation mode, and trust\n  classification;\n- timestamp and reproducibility policy;\n- downstream site-consumption hints;\n- optional archive routes for canonical, latest, latest evidence, immutable\n  version prefix, and public artifact URLs.\n\nThe companion publication artifact passport records the same source and\nartifact evidence plus an explicit responsibility split. Buildchain proves\ndeclared files and hashes; it does not peer-review paper claims.\n\nWhen archive config is present, the registry uses the\n`kungfu-buildchain-publication-artifact-registry` contract. A site repository\ncan render latest pages and historical version indexes from that registry\nwithout rebuilding old PDFs from the latest npm package or paper source.\n\n## Site Consumption\n\nA downstream papers site should treat the publication manifest as the single\nfact source for the artifact. The site owns rendering and navigation; it should\nnot reinterpret the paper repository as a web deployment source.\nFor registry-level routing, sites should first consume the package-owned\nBuildchain fact source:\n\n```text\nnode_modules/@kungfu-tech/buildchain/dist/site/publication-registry.json\n```\n\nor the equivalent package export:\n\n```js\nimport registry from \"@kungfu-tech/buildchain/site/publication-registry.json\" with { type: \"json\" };\n```\n\nThat registry uses the `kungfu-buildchain-publication-release-registry`\ncontract. It separates mutable canonical/latest reader routes from immutable\nversion prefixes, publication artifacts, source bundles, and passport evidence\nso site repositories can render `/papers/**` without maintaining a parallel\nfixture truth source.\n\nFor `paper-observer-declared-timelines`, the expected adoption path is:\n\n```text\npaper repo builds PDF + manifest + source bundle\npaper repo updates publication-registry.json\npapers site consumes publication-artifact.json\npapers site consumes publication-registry.json for history\nsite renders paper page and links the PDF/source bundle\n```\n\nThis mirrors web-surface governance without mixing producer and renderer\nresponsibilities."
+      "markdown": "# Publication Artifact Workflow\n\nBuildchain supports `project.type = \"publication-artifact\"` for repositories\nthat produce auditable papers, reports, specifications, or similar publication\npackages. These repositories are artifact producers. They should not be forced\nto become `web-surface` repositories just because a downstream site later\nrenders the paper.\n\nThe split is:\n\n```text\npaper repo = source, PDF, metadata, source bundle, publication manifest\npapers site = layout, navigation, public web surface, downstream rendering\n```\n\n## Configuration\n\nThe paper repository owns `.buildchain/buildchain.toml`:\n\n```toml\nschema = 1\n\n[project]\ntype = \"publication-artifact\"\nname = \"paper-observer-declared-timelines\"\n\n[publication]\nkind = \"paper\"\ntitle = \"Observer-Declared Timelines for Real-World Agent Work\"\nversion = \"0.1.0\"\nprimary_artifact = \"_build/main.pdf\"\nartifact_paths = [\"_build/main.pdf\"]\nmetadata_paths = [\"README.md\", \"docs/MAP.md\"]\nsource_paths = [\"paper\", \"README.md\", \"LICENSE\", \"Makefile\"]\nsite_consumers = [\"papers.libkungfu.dev\"]\nmanifest_path = \".buildchain/publication/publication-artifact.json\"\nsource_bundle_path = \".buildchain/publication/source.tar.gz\"\n\n[publication.archive]\nid = \"observer-declared-timelines\"\ncanonical_url = \"https://papers.libkungfu.dev/observer-declared-timelines/\"\nlatest_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/\"\nlatest_evidence_url = \"https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json\"\nimmutable_base_url = \"https://papers.libkungfu.dev/archive\"\nregistry_path = \".buildchain/publication/publication-registry.json\"\n\n[publication.toolchain]\ntype = \"latex-docker\"\nimage = \"ghcr.io/kungfu-systems/build-images/latex-pdf-builder\"\ndigest = \"sha256:c20f3809e96836c1c78e97c76939d12f1de3fed0ea9b7c40c43332ec2ea480f8\"\ncommand = \"latexmk -pdf -outdir=_build paper/main.tex\"\n\n[publish]\nkind = \"npm-paper-package\"\npackage = \"@kungfu-tech/paper-observer-declared-timelines\"\nauth = \"trusted-publishing\"\n\n[lifecycle.build]\ncommand = \"make pdf\"\n\n[lifecycle.verify]\ncommand = \"make check\"\n```\n\n`primary_artifact` is the human-facing publication output, usually a PDF.\n`source_paths` are archived into a source bundle. `metadata_paths` are hashed\nand recorded so a site can consume the paper facts without scraping prose.\n\n`publication.archive` turns the publication into an append-only public archive\ncontract:\n\n- `canonical_url` is the stable human reader page.\n- `latest_url` and `latest_evidence_url` are movable aliases for the latest\n  reader page and latest evidence.\n- `immutable_base_url` plus `id` and `publication.version` produce a versioned\n  prefix such as\n  `https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0/`.\n- `immutable_url_prefix` can be used instead when the repository already owns\n  the full version prefix.\n- `registry_path` records every published version and its manifest, passport,\n  source bundle, primary artifact, URLs, and SHA-256 digests.\n\nImmutable archive prefixes are append-only. Do not run site deployment commands\nwith `sync --delete` or equivalent deletion semantics over those prefixes. A\nsame-version republish is allowed only when the immutable digest is unchanged;\nif PDF, source bundle, route, metadata, or toolchain evidence changes for an\nexisting version, Buildchain fails before the registry is rewritten.\n\nThe Buildchain web-surface adapter consumes this boundary from a surface-local\n`manifest.json` whose `archivePolicy.contract` is\n`kungfu-buildchain-publication-archive-policy`. It excludes the derived archive\nroot from every owning or parent `sync --delete`, verifies existing object\ndigests, uploads only missing immutable files with `--no-overwrite`, and verifies\nthem again before mutable site content is synchronized. A current package set\ndoes not need to rebuild or enumerate every historical version: the protected\narchive root remains outside deletion even when older versions disappear from\nthe current artifact.\n\n`publication.toolchain` makes the source-to-PDF transformation part of the\nmachine-readable contract. `latex-docker` is the preferred LaTeX profile. The\nBuildchain paper scaffold and reusable workflow default to\n`ghcr.io/kungfu-systems/build-images/latex-pdf-builder:v1.2.0`, pinned by the\ndigest above. The workflow pulls the declared image by digest and runs the\ndeclared command in that pinned container. `custom-command` remains available\nfor compatibility, but the passport records it as lower trust because\nBuildchain can record the command boundary without proving the compiler or\nLaTeX distribution digest.\n\n## Reproducibility Gate\n\nAlpha and release admission require\n`.buildchain/publication/reproducibility-receipt.json`. Buildchain creates the\nreceipt by cloning the exact checked-out Git commit into two independent local\nrepositories, assigning each build a separate home and npm cache, and deriving\n`SOURCE_DATE_EPOCH` from the source commit. A pinned `latex-docker` build runs\nwith UTC, `C.UTF-8`, no build-time network, and the exact image digest declared\nin `[publication.toolchain]`.\n\nEach clean build independently creates the PDF set, source bundle, publication\nmanifest and passport, append-only registry, synthesized npm package directory,\nand an actual npm tarball. After qualification, Buildchain copies the first\nqualifying tarball into the promoted publication candidate instead of deleting\nit with the temporary clean build. The receipt compares exact bytes and records:\n\n- source repository, commit, tree, and `SOURCE_DATE_EPOCH`;\n- toolchain image, digest, command, and toolchain identity root;\n- every artifact and evidence path with byte size and SHA-256;\n- npm tarball SHA-256, SHA-1 shasum, and `sha512` integrity;\n- per-build output-set roots and the first differing field or artifact.\n\nThe gate is fail-closed. A build-only `custom-command` run can diagnose byte\ndrift and promote its byte-identical local output with\n`--allow-unpinned-toolchain`, but it is never a qualifying publication receipt.\nAny workflow that prepares a publishable paper package accepts only a\ndigest-pinned toolchain and promotes the first clean build into the publication\ncandidate only after both builds are byte-identical. The receipt remains\noutside the npm tarball to avoid a circular digest; it binds the tarball bytes\nfrom the surrounding sealed publication evidence.\n\n`publish.kind = \"npm-paper-package\"` declares that Buildchain, not the consumer\nrepository, owns the standard paper npm package shape and release transaction\nmechanics. `publish.package` is the public npm package that contains the PDF,\npublication manifest, publication passport, optional archive registry, source\nbundle, and declared metadata files.\n\n## Reusable Workflow\n\nConsumer repositories that only need to build and upload paper evidence can\ncall the build-only wrapper directly:\n\n```yaml\njobs:\n  publication:\n    uses: kungfu-systems/buildchain/.github/workflows/publication-artifact.yml@v3\n    with:\n      toolchain-type: config\n      verify-command: make check\n      artifact-name: observer-declared-timelines\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe build-only workflow:\n\n- resolves the Buildchain runtime and checks the floating contract lock before\n  any paper build runs;\n- resolves the declared publication toolchain from `[publication.toolchain]` or\n  workflow inputs;\n- hydrates authenticated registry history before building so both clean\n  candidates include the same append-only history;\n- for `latex-docker`, pulls the pinned build-images LaTeX builder digest and\n  runs two independent clean builds with the reproducibility policy above;\n- for `custom-command`, runs the declared command and records the lower-trust\n  boundary in the passport, but refuses publication qualification;\n- runs the verify command;\n- creates a source bundle from `publication.source_paths`;\n- writes `.buildchain/publication/publication-artifact.json`;\n- writes `.buildchain/publication/publication-artifact-passport.json`;\n- writes a qualifying\n  `.buildchain/publication/reproducibility-receipt.json`;\n- when `[publication.archive]` is configured, writes\n  `.buildchain/publication/publication-registry.json` and verifies same-version\n  immutability;\n- uploads one GitHub artifact containing the PDF, manifest, passport, optional\n  registry, and source bundle.\n\nIt does not publish npm packages, deploy web pages, or create GitHub Releases.\n\nThe paper release preset additionally hydrates every prior published package\nregistry from the npm registry before generating the current manifest. npm\npackage integrity authenticates each downloaded source; Buildchain verifies the\nregistry self-digest, merges immutable records, and fails if a cumulative\nregistry drops an accepted version or changes immutable route/artifact facts.\nThe synthesized package therefore carries complete history even on a clean\nrunner. Its cumulative registry and file SHA-256 values are bound into the paper\nrelease build summary and release passport evidence.\n\n## Paper Release Preset\n\nPaper repositories that publish a versioned npm package should use the\nBuildchain-managed release preset instead of copying npm transaction scripts or\npromotion YAML:\n\n```yaml\nname: Paper Release\n\non:\n  push:\n    branches:\n      - alpha/v1/v1.0\n      - release/v1/v1.0\n  workflow_dispatch:\n\njobs:\n  paper-release:\n    uses: kungfu-systems/buildchain/.github/workflows/paper-release-sealed.yml@<exact-buildchain-sha>\n    permissions:\n      actions: read\n      checks: write\n      contents: read\n      id-token: write\n      issues: write\n    with:\n      buildchain-ref: <exact-buildchain-sha>\n      publisher-workflow-path: .github/workflows/paper-release.yml\n      toolchain-type: config\n      verify-command: make check\n      artifact-paths: _build/paper-name.pdf\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n    secrets:\n      BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_CLIENT_ID }}\n      BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_APP_PRIVATE_KEY }}\n      BUILDCHAIN_GENERATED_WRITE_TOKEN: ${{ secrets.BUILDCHAIN_GENERATED_WRITE_TOKEN }}\n```\n\nThe sealed preset does not use a long-lived token for npm publication. It\nprefers a repository-scoped GitHub App installation token for generated\nrepository writes and accepts `BUILDCHAIN_GENERATED_WRITE_TOKEN` as an\nequivalent narrow compatibility authority. The deprecated\n`BUILDCHAIN_PROMOTION_TOKEN` name remains accepted for existing consumers, but\nthere is no `github.token` fallback for generated writes. npm publication\nremains bound to GitHub OIDC trusted publishing. The preset builds and packages the\npaper in a read-only job, then a credential-free authority job downloads that\nexact candidate, audits the external control plane, and seals a capability over\nthe source tree, Buildchain runtime, controller receipt, PDF, and npm package\nbytes. Only the final job receives write and OIDC permissions; it downloads the\nadmitted candidate, recomputes the capability binding, and publishes without\nexecuting consumer build commands. npm binds the OIDC identity to the consumer\nworkflow named by `publisher-workflow-path`.\n\nThe preset:\n\n- uses the exact Buildchain SHA admitted by the provisioning authority and\n  binds it into the caller bytes, contract lock, publication candidate, and\n  authority capability;\n- builds the PDF through the declared pinned LaTeX Docker toolchain or custom\n  command in a read-only job;\n- verifies the paper repository;\n- writes the publication manifest, publication passport, optional archive\n  registry, and source bundle;\n- synthesizes an npm package from `[publication]` and `[publish]` declarations\n  under `.buildchain/publication/npm-package`;\n- computes npm-style `sha512` integrity from `npm pack --dry-run` and passes\n  it as `publish-required-artifacts-json`;\n- creates a `publish-gate/<alpha|release>/.../<version>` source lock for the\n  channel commit and requires `promote-buildchain-ref` to verify that lock\n  before any publish side effect;\n- verifies the complete candidate again after authority and publishes the\n  package through npm Trusted Publishing without rebuilding or repacking it;\n- writes a typed sealed-bundle manifest that binds the candidate root, exact\n  npm tarball, every GitHub Release asset, durable storage path, and resume\n  command;\n- persists the complete binary bundle to the transaction's durable release-state\n  ref before npm receives credentials, allowing an empty runner to restore and\n  verify the same bytes after interruption;\n- writes Buildchain release/passport evidence; and\n- creates or updates the exact-version GitHub Release by default, uploading\n  every file declared by `publication.primary_artifact` and\n  `publication.artifact_paths` alongside the release evidence.\n\nConsumers can opt out of the GitHub Release with `github-release: false`, but\nthe default is on so downstream release propagation can observe\n`release.published` without hand-written `gh release` steps.\n\nThe transaction exposes a stable publication progression:\n\n```text\nprepared -> sealed -> package-published -> alpha-complete\n```\n\nStable publication ends at `release-complete`. If a run stops after npm but\nbefore GitHub Release completion, the next run starts from\n`package-published`, restores the sealed PDF and companion assets, and finishes\nthe release without invoking the paper build or `npm pack` again.\n\nDeclared publication artifacts are resolved from the generated publication\nmanifest rather than repeated in consumer workflow YAML. Publication fails\nbefore upload if a declared artifact is missing or if its basename would\ncollide with another GitHub Release asset.\n\nFor npm Trusted Publishing, register the consumer workflow file that calls this\npreset, for example `.github/workflows/paper-release.yml`, against the declared\npackage in npm. The trusted publisher is the consumer repository and workflow\nfile; the implementation still runs inside Buildchain's reusable workflow.\n\nStandard paper repositories should not carry local copies of\n`scripts/npm-publish-transaction.mjs`, package-generation scripts, or\npromotion/ref-lock YAML. If the default package shape is insufficient, extend\nBuildchain rather than forking the mechanics into each paper repository.\n\n## CLI And Node API\n\n### Unified paper operator surface\n\nThe `buildchain paper` command family assembles the existing publication\nprimitives into a resumable operator flow:\n\n```text\nscaffold/new or migrate/existing -> preflight -> bootstrap npm -> build -> alpha -> status -> resume\n```\n\nEach command emits a typed JSON envelope with `--json`. Dry-run is the default\nfor every external mutation. `scaffold --write` is limited to no-overwrite\nlocal file creation. `migrate --write` is limited to the Buildchain-owned\ncontract lock, version pin, thin workflows, and provisioning authority; paper\ncontent and publication configuration are preserved. `bootstrap npm --execute`, `alpha --execute`, and\n`resume --execute` cross external authority boundaries and therefore require\nexplicit execution.\n\nThe evidence model is intentionally non-inferential:\n\n| State                | Required evidence                                        |\n| -------------------- | -------------------------------------------------------- |\n| `scaffolded`         | Complete managed scaffold inventory                      |\n| `governed`           | Compatible Buildchain contract lock                      |\n| `admitted`           | Repository admission receipt                             |\n| `bootstrapped`       | Successful public npm bootstrap receipt or registry fact |\n| `trust-bound`        | Trusted publisher binding receipt                        |\n| `content-ready`      | Declared source paths present                            |\n| `artifact-sealed`    | Verified sealed publication bundle                       |\n| `package-published`  | Exact package version visible in npm                     |\n| `alpha-complete`     | Protected Alpha PR completion evidence                   |\n| `staging-visible`    | Staging route evidence                                   |\n| `production-visible` | Production route evidence                                |\n\n`paper status` reports `satisfied`, `not-reached`, `blocked`, or `unknown` for\neach state. It does not promote a state merely because a prior state is\ncomplete. This makes a later `paper resume` safe: the command dispatches the\nthin repository release workflow, while the workflow re-verifies durable\nevidence and remains the publication authority.\n\nOperationally, responsibility remains split:\n\n- the paper repository owns content, declared metadata, and its thin\n  build/release workflow;\n- Buildchain owns scaffold shape, evidence contracts, reproducibility, sealed\n  bundle mechanics, npm transaction mechanics, and resumption planning;\n- GitHub branch protection and trusted publishing own authority transitions;\n- the papers site consumes publication evidence and owns reader-facing\n  rendering.\n\nRun a local readiness check without network observations:\n\n```sh\nbuildchain paper preflight --offline --json\nbuildchain paper status --json\n```\n\nBefore real npm bootstrap, first inspect the default dry-run result:\n\n```sh\nbuildchain paper bootstrap npm --json\n```\n\nOnly after reviewing the package, repository, workflow, and dry-run evidence:\n\n```sh\nbuildchain paper bootstrap npm \\\n  --execute \\\n  --confirm-public-package @kungfu-tech/paper-example \\\n  --json\n```\n\nGenerate the publication manifest locally or in CI:\n\n```sh\nbuildchain publication-artifact manifest --source-sha \"$(git rev-parse HEAD)\" --json\n```\n\nProve the complete candidate from two clean builds:\n\n```sh\nbuildchain publication-artifact reproducibility \\\n  --source-sha \"$(git rev-parse HEAD)\" \\\n  --promote \\\n  --json\n```\n\nGenerate the npm package contents after the manifest exists:\n\n```sh\nbuildchain publication-artifact npm-package --json\n```\n\nNode API:\n\n```js\nimport {\n  collectPublicationArtifact,\n  writePublicationArtifact,\n} from \"@kungfu-tech/buildchain/publication-artifact\";\n\nimport {\n  collectPublicationPackageFacts,\n  preparePublicationNpmPackage,\n} from \"@kungfu-tech/buildchain/publication-package\";\n\nimport { verifyPublicationReproducibility } from \"@kungfu-tech/buildchain/publication-reproducibility\";\n\nimport {\n  createPublicationSealedBundle,\n  verifyPublicationSealedBundle,\n} from \"@kungfu-tech/buildchain/publication-sealed-bundle\";\n```\n\n`writePublicationArtifact()` is the single implementation used by the CLI and\nthe reusable workflow. The generated manifest records:\n\n- publication title, kind, authors, and primary artifact;\n- artifact paths, byte sizes, and SHA-256 digests;\n- metadata paths and SHA-256 digests;\n- source SHA, tree SHA, source files, and source bundle digest;\n- publication toolchain type, image, digest, command, invocation mode, and trust\n  classification;\n- timestamp and reproducibility policy;\n- downstream site-consumption hints;\n- optional archive routes for canonical, latest, latest evidence, immutable\n  version prefix, and public artifact URLs.\n\nThe companion publication artifact passport records the same source and\nartifact evidence plus an explicit responsibility split. Buildchain proves\ndeclared files and hashes; it does not peer-review paper claims.\n\nWhen archive config is present, the registry uses the\n`kungfu-buildchain-publication-artifact-registry` contract. A site repository\ncan render latest pages and historical version indexes from that registry\nwithout rebuilding old PDFs from the latest npm package or paper source.\n\n## Site Consumption\n\nA downstream papers site should treat the publication manifest as the single\nfact source for the artifact. The site owns rendering and navigation; it should\nnot reinterpret the paper repository as a web deployment source.\nFor registry-level routing, sites should first consume the package-owned\nBuildchain fact source:\n\n```text\nnode_modules/@kungfu-tech/buildchain/dist/site/publication-registry.json\n```\n\nor the equivalent package export:\n\n```js\nimport registry from \"@kungfu-tech/buildchain/site/publication-registry.json\" with { type: \"json\" };\n```\n\nThat registry uses the `kungfu-buildchain-publication-release-registry`\ncontract. It separates mutable canonical/latest reader routes from immutable\nversion prefixes, publication artifacts, source bundles, and passport evidence\nso site repositories can render `/papers/**` without maintaining a parallel\nfixture truth source.\n\nFor `paper-observer-declared-timelines`, the expected adoption path is:\n\n```text\npaper repo builds PDF + manifest + source bundle\npaper repo updates publication-registry.json\npapers site consumes publication-artifact.json\npapers site consumes publication-registry.json for history\nsite renders paper page and links the PDF/source bundle\n```\n\nThis mirrors web-surface governance without mixing producer and renderer\nresponsibilities."
     },
     {
       "id": "manual:publication-authority",
@@ -1420,7 +1496,7 @@
       ],
       "maturity": "preview",
       "sourcePath": "docs/publication-authority.md",
-      "digest": "sha256:118dc751fa3c37b4b20f4b909534458148c0f42c2c9d69f13e2fa5373dbfe244",
+      "digest": "sha256:6c91ee89d1ed5c0c570806684738916876556b2f1bcbf4be4f73f30ff89e98a4",
       "headings": [
         {
           "level": 1,
@@ -1463,7 +1539,7 @@
           "anchor": "publication-lanes"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: sealed-publication-authority\ndoc_type: protocol\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-07-15\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-15\n  limits: Live provider configuration must be re-audited; no credential values are represented.\n---\n\n# Sealed Publication Authority\n\nBuildchain publication authority is a closed-world, fail-closed protocol. It does\nnot mint registry or cloud credentials. It independently verifies whether an\nalready protected publication job is allowed to request a short-lived provider\ncredential for one exact product, target, version, channel, and artifact digest.\n\nThe machine-readable authority inventory is\n`dist/site/publication-authority-registry.json`. Any workflow with a write,\nenvironment, OIDC, cloud credential, registry publish, release, or Git push\nsignal must have an explicit descriptor. A new authority-bearing workflow that\nis absent from the inventory fails site generation. Unknown workflows and every\ndescriptor not marked `product-publication` are denied product publication.\n\n## Evidence chain\n\nA qualifying admission binds exact source and runtime SHAs; contract, consumer\npolicy, qualifying controller receipt, Shifu/Gate aggregate, artifact, runner,\nand control-plane digests; repository, authority workflow, provider publisher\nworkflow, Environment policy,\nproduct, target, version, and channel; plus a unique nonce and a lifetime of no\nmore than 15 minutes. Every expected binding is mandatory at verification time;\nan omitted expected field is not a wildcard.\n\nThe independent verifier recomputes every digest and ignores a producer's own\nallow/deny conclusion. It fetches the exact evidence run, validates the actual\nrelease-candidate passport and referenced qualifying controller receipt,\nrecomputes the Shifu Gate aggregate or explicit consumer-owned no-Gate policy,\nrecomputes the downloaded artifact manifests, and hashes every declared product\npayload file against those manifests. The `.buildchain/` diagnostics envelope is\nbound by the manifest digest but excluded from the product-byte set because it can\nbe finalized after the lifecycle scan. The verifier also compares the PR evidence tree to the\nadmitted post-merge source commit tree. It rejects an unknown\nworkflow, stale or replayed nonce, runner downgrade, control-plane drift,\nsource/runtime mismatch, and artifact substitution. A successful result is a\nscoped capability receipt, not a bearer credential.\n\n## Runner and control-plane evidence\n\nRunner evidence uses exactly four classes: `ephemeral`, `reimaged`,\n`persistent-measured`, and `unqualified`. Ephemeral runners also record their\njob-isolation boundary. Reimaged and persistent runners qualify only when a\nclean baseline is proven and baseline, toolchain, cache-contract, and task-\nisolation digests are all present. Otherwise they still emit diagnostic\nevidence with `qualificationStatus = unqualified`, but cannot receive a product\ncapability.\n\nThe external audit records digests and pass/fail status for repository Actions\ndefaults, classic branch protection or an active matching repository ruleset,\ndeclared protected Environment policy or an explicit no-Environment binding,\njob-scoped credentials,\nabsence of long-lived workflow publication credentials, provider authority,\nand authorized runner class. Provider modes are `npm-trusted-publisher`,\n`github-token`, and `oidc-role`. The OIDC-role mode consumes only a sanitized\nprovider audit containing a role digest and qualifying decision; raw IAM policy,\ntokens, or credentials are rejected. Package-owner, cloud-root, GitHub\nadministrator, and registry-root credentials remain outside Buildchain's trust\nboundary. Missing or unreadable facts fail closed.\n\nAn unauthenticated local npm CLI is not evidence that Trusted Publishing is\nmissing. `npm whoami` reports only the local CLI session and does not report the\nOIDC identity that npm creates during `npm publish`. The default read-only audit\ntherefore binds the exact provider, repository, caller workflow, optional\nEnvironment, job-scoped OIDC permission, and absence of long-lived credentials,\nthen records `provider-at-transaction`: npm makes the final authorization\ndecision when `npm publish` exchanges the job's OIDC token. A missing or drifted\ntrusted-publisher configuration consequently denies the transaction safely; it\nis not preflighted through an unrelated long-lived npm login.\n\nAn authenticated external auditor can add stronger point-in-time evidence by\nsupplying sanitized `npm trust list --json` output with `--npm-trust-json`. This\nchanges the publisher fact to `audited-control-plane`; the workflow never runs\n`npm trust list` itself and never receives that auditor's npm credential.\n\nThe credential-free collector proves effective Actions and runner scope from\nthe publication workflow fetched at `--workflow-ref`: explicit read-only\nworkflow defaults, job-scoped write/OIDC permissions, and an exact GitHub-hosted\nrunner label. It does not call repository Actions-default or self-hosted-runner\nadministration endpoints. Branch/ruleset and OIDC subject facts remain live\nread-only provider queries. When the detailed branch-protection endpoint is not\nreadable with the workflow token, `--source-sha` binds the provider's public\nprotected-branch summary to the exact merged PR, independent approval, required\nsuccessful check, same-repository lineage, and current branch head. This records\nprovider-enforced transaction evidence without treating an unavailable\nadministration endpoint as an unprotected branch. It avoids turning a\nrepository-admin token into a publication prerequisite.\nWhen a legacy caller declares a reusable job id such as `build`, the collector\naccepts it only if the protected branch exposes exactly one required context\nunder `build / ...`; it then verifies that exact context, configured app, and PR\nhead SHA. Exact declarations remain unchanged, and ambiguous prefixes fail\nclosed.\n\nFor non-dry-run workflows, missing admission, runner, control-plane, Gate, or\nexpected-binding evidence is rejected before Buildchain downloads candidate\nartifacts. The denial explicitly records that npm Trusted Publishing and OIDC\nwere not evaluated, so downstream diagnostics cannot misclassify an admission\nassembly failure as an npm authentication failure.\n\nAn explicitly opted-in managed `workflow_run` promotion lane may assemble those\ninputs from evidence owned by its caller repository. It downloads the exact prior RC passport,\nsummary, referenced controller receipt, manifests, and product payloads; proves\nthe admitted channel commit has the same Git tree as the RC; performs the live\nread-only control-plane audit; records the GitHub-hosted job as ephemeral runner\nprovenance; and consumes either a caller-supplied Gate aggregate or an explicit\ncaller no-Gate decision. The\nindependent verifier then recomputes every receipt and payload digest exactly as\nit does for externally supplied admission. Automatic assembly keeps Buildchain\nas the canonical authority repository, requires evidence to belong to the\ncaller, binds a repository-local publisher workflow, and rejects unknown refs,\nnon-exact source SHAs, package/target mismatches, or an undeclared Gate policy.\nManual apply and consumers that do not opt in still require their own explicit\nadmission inputs.\n\nBefore authority verification, the reusable promotion controller runs the same\nrelease transaction selector in read-only mode. That plan supplies one exact\npublication version and tag to the admission verifier, the publish-gate source\nlock, and the real promotion action. The verifier rejects a capability for a\ndifferent version, and the promotion action rechecks the planned version before\nany publish transaction side effect. Release-candidate fixture versions are\nartifact evidence only; they never name Buildchain's own source-lock or\npublication capability.\n\nEvidence publication is a separate authority class and never grants product\npublication.\n\n## Managed web-surface production\n\nThe reusable web-surface controller owns a complete standard producer path for\nits documented production mechanisms. A reviewed matching release-PR merge or a\nmanual dispatch by an actor with current repository write authority creates a\nsigned decision bound to the exact source SHA. After build, verify, and\nproduction planning, the workflow creates a qualifying pre-publication\ncontroller receipt and assembles a ten-minute admission over the source tree,\nimmutable Buildchain runtime, deployment plan, artifact hash, production\nEnvironment, AWS role/deploy target, runner provenance, decision digest, and\nnonce. The independent verifier emits the scoped `web-production` capability.\n\nThe production job rechecks the capability and candidate against the same plan\nbefore downloading product artifacts. AWS authorization is deliberately\nrecorded as `provider-at-transaction`: the capability binds the exact role and\nEnvironment, while `configure-aws-credentials` performs the live OIDC exchange\nand remains the final provider authorization gate before mutation. Buildchain\ndoes not claim that an IAM trust relationship passed before that transaction.\n\nExternally assembled admissions remain an optional compatibility path and must\nprovide the full admission, runner, control-plane, Gate aggregate, expected\nbindings, and nonce set. They are not required for the managed web-surface\nrelease-PR or trusted-manual paths.\n\n## Consumer qualification handoff\n\nConsumers may explicitly opt in to a final, consumer-owned qualification\npredicate. Buildchain then transports the complete Gate aggregate alongside the\nsealed capability instead of reducing it to a summary. The capability binds the\nauthority registry, consumer Gate registry and policy, exact source and runtime,\ncontroller, runner, control-plane, artifact, provider target, channel, version,\nfreshness window, nonce, and exact predicate command digest.\n\nThe predicate runs in a separate job with read-only source access, no inherited\nsecrets, no OIDC permission, and no provider write permission. It receives only\npaths to `capability.json` and `gate-aggregate.json` plus the exact predicate id\nand digest. The consumer writes a\n`kungfu-buildchain-consumer-publication-decision`; Buildchain seals that result\nas a deterministic\n`kungfu-buildchain-publication-qualification-receipt`. Buildchain does not parse\nproduct-specific Gate meanings.\n\nThe provider action revalidates the capability, full aggregate, receipt,\npredicate identity, freshness, nonce, source, version, channel, target, and all\nsealed digests immediately before the publish transaction. Missing, denied,\nstale, replayed, substituted, or drifted receipts fail before provider mutation.\nDirect calls to the provider action cannot bypass the receipt when\n`require-publication-qualification` is enabled. Consumers that do not opt in\nretain the existing publication contract.\n\n## API and CLI\n\nUse `@kungfu-tech/buildchain/publication-authority` or run:\n\n```bash\nbuildchain verify publication-admission admission.json \\\n  --registry-json publication-authority-registry.json \\\n  --runner-json runner.json \\\n  --control-plane-audit-json control-plane.json \\\n  --publication-evidence-json publication-evidence.json \\\n  --expected-json expected.json \\\n  --used-nonce previous-run-nonce \\\n  --json\n```\n\nThe read-only live collector defaults to npm trusted publishing. Other product\nproviders select an explicit adapter:\n\n```bash\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v2/v2.12 \\\n  --source-sha <exact-merged-branch-sha> \\\n  --workflow .github/workflows/release-candidate-promote.yml \\\n  --workflow-ref <exact-buildchain-sha> \\\n  --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \\\n  --job promote \\\n  --environment none\n\n# Optional stronger external evidence; generate the JSON outside the workflow.\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v2/v2.12 \\\n  --workflow .github/workflows/release-candidate-promote.yml \\\n  --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \\\n  --job promote \\\n  --environment none \\\n  --npm-trust-json sanitized-npm-trust.json\n\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch release/v2/v2.12 \\\n  --workflow .github/workflows/.binary-release-assets.yml \\\n  --job publish \\\n  --environment buildchain-release-assets \\\n  --publisher-mode github-token\n\nbuildchain audit publication-control-plane \\\n  --repository OWNER/CONSUMER \\\n  --workflow-repository kungfu-systems/buildchain \\\n  --branch main \\\n  --workflow .github/workflows/.web-surface.yml \\\n  --job production-apply \\\n  --environment production \\\n  --publisher-mode oidc-role \\\n  --provider-audit-json sanitized-oidc-role-audit.json\n```\n\nThe authority workflow identifies the reusable implementation that performs the\npublication job. The publisher workflow identifies the caller filename bound by\nthe provider's trusted-publisher policy; these identities are deliberately\nseparate. `--environment none` is an explicit assertion that the job declares no\nGitHub Environment and the provider policy has no Environment restriction. A\nnamed Environment must exist, be protected, and be declared by the job. The\nBuildchain receipt alone is never sufficient authorization.\n\n## Publication lanes\n\n`Binary Distribution` is evidence-only. It builds platform archives and a\nrelease evidence bundle with read-only repository permissions. GitHub Release\nasset writes live in `Binary Release Assets`, which downloads an exact prior\nevidence run, verifies its bundle digest against the sealed capability, and is\nthe only binary job with `contents: write` in the protected\n`buildchain-release-assets` Environment.\n\nThe npm/promotion, paper, binary-release, and web-production lanes all depend on\nthe independent verifier. Preview, staging, build, source-check, controller,\nand failure-evidence lanes do not inherit product publication capability."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: sealed-publication-authority\ndoc_type: protocol\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-15\n  limits: Live provider configuration must be re-audited; no credential values are represented.\n---\n\n# Sealed Publication Authority\n\nBuildchain publication authority is a closed-world, fail-closed protocol. It does\nnot mint registry or cloud credentials. It independently verifies whether an\nalready protected publication job is allowed to request a short-lived provider\ncredential for one exact product, target, version, channel, and artifact digest.\n\nThe machine-readable authority inventory is\n`dist/site/publication-authority-registry.json`. Any workflow with a write,\nenvironment, OIDC, cloud credential, registry publish, release, or Git push\nsignal must have an explicit descriptor. A new authority-bearing workflow that\nis absent from the inventory fails site generation. Unknown workflows and every\ndescriptor not marked `product-publication` are denied product publication.\n\n## Evidence chain\n\nA qualifying admission binds exact source and runtime SHAs; contract, consumer\npolicy, qualifying controller receipt, Shifu/Gate aggregate, artifact, runner,\nand control-plane digests; repository, authority workflow, provider publisher\nworkflow, Environment policy,\nproduct, target, version, and channel; plus a unique nonce and a lifetime of no\nmore than 15 minutes. Every expected binding is mandatory at verification time;\nan omitted expected field is not a wildcard.\n\nThe independent verifier recomputes every digest and ignores a producer's own\nallow/deny conclusion. It fetches the exact evidence run, validates the actual\nrelease-candidate passport and referenced qualifying controller receipt,\nrecomputes the Shifu Gate aggregate or explicit consumer-owned no-Gate policy,\nrecomputes the downloaded artifact manifests, and hashes every declared product\npayload file against those manifests. The `.buildchain/` diagnostics envelope is\nbound by the manifest digest but excluded from the product-byte set because it can\nbe finalized after the lifecycle scan. The verifier also compares the PR evidence tree to the\nadmitted post-merge source commit tree. It rejects an unknown\nworkflow, stale or replayed nonce, runner downgrade, control-plane drift,\nsource/runtime mismatch, and artifact substitution. A successful result is a\nscoped capability receipt, not a bearer credential.\n\n## Runner and control-plane evidence\n\nRunner evidence uses exactly four classes: `ephemeral`, `reimaged`,\n`persistent-measured`, and `unqualified`. Ephemeral runners also record their\njob-isolation boundary. Reimaged and persistent runners qualify only when a\nclean baseline is proven and baseline, toolchain, cache-contract, and task-\nisolation digests are all present. Otherwise they still emit diagnostic\nevidence with `qualificationStatus = unqualified`, but cannot receive a product\ncapability.\n\nThe external audit records digests and pass/fail status for repository Actions\ndefaults, classic branch protection or an active matching repository ruleset,\ndeclared protected Environment policy or an explicit no-Environment binding,\njob-scoped credentials,\nabsence of long-lived workflow publication credentials, provider authority,\nand authorized runner class. Provider modes are `npm-trusted-publisher`,\n`github-token`, and `oidc-role`. The OIDC-role mode consumes only a sanitized\nprovider audit containing a role digest and qualifying decision; raw IAM policy,\ntokens, or credentials are rejected. Package-owner, cloud-root, GitHub\nadministrator, and registry-root credentials remain outside Buildchain's trust\nboundary. Missing or unreadable facts fail closed.\n\nAn unauthenticated local npm CLI is not evidence that Trusted Publishing is\nmissing. `npm whoami` reports only the local CLI session and does not report the\nOIDC identity that npm creates during `npm publish`. The default read-only audit\ntherefore binds the exact provider, repository, caller workflow, optional\nEnvironment, job-scoped OIDC permission, and absence of long-lived credentials,\nthen records `provider-at-transaction`: npm makes the final authorization\ndecision when `npm publish` exchanges the job's OIDC token. A missing or drifted\ntrusted-publisher configuration consequently denies the transaction safely; it\nis not preflighted through an unrelated long-lived npm login.\n\nAn authenticated external auditor can add stronger point-in-time evidence by\nsupplying sanitized `npm trust list --json` output with `--npm-trust-json`. This\nchanges the publisher fact to `audited-control-plane`; the workflow never runs\n`npm trust list` itself and never receives that auditor's npm credential.\n\nThe credential-free collector proves effective Actions and runner scope from\nthe publication workflow fetched at `--workflow-ref`: explicit read-only\nworkflow defaults, job-scoped write/OIDC permissions, and an exact GitHub-hosted\nrunner label. It does not call repository Actions-default or self-hosted-runner\nadministration endpoints. Branch/ruleset and OIDC subject facts remain live\nread-only provider queries. When the detailed branch-protection endpoint is not\nreadable with the workflow token, `--source-sha` binds the provider's public\nprotected-branch summary to the exact merged PR, independent approval, required\nsuccessful check, same-repository lineage, and current branch head. This records\nprovider-enforced transaction evidence without treating an unavailable\nadministration endpoint as an unprotected branch. It avoids turning a\nrepository-admin token into a publication prerequisite.\nWhen a legacy caller declares a reusable job id such as `build`, the collector\naccepts it only if the protected branch exposes exactly one required context\nunder `build / ...`; it then verifies that exact context, configured app, and PR\nhead SHA. Exact declarations remain unchanged, and ambiguous prefixes fail\nclosed.\n\nFor non-dry-run workflows, missing admission, runner, control-plane, Gate, or\nexpected-binding evidence is rejected before Buildchain downloads candidate\nartifacts. The denial explicitly records that npm Trusted Publishing and OIDC\nwere not evaluated, so downstream diagnostics cannot misclassify an admission\nassembly failure as an npm authentication failure.\n\nAn explicitly opted-in managed `workflow_run` promotion lane may assemble those\ninputs from evidence owned by its caller repository. It downloads the exact prior RC passport,\nsummary, referenced controller receipt, manifests, and product payloads; proves\nthe admitted channel commit has the same Git tree as the RC; performs the live\nread-only control-plane audit; records the GitHub-hosted job as ephemeral runner\nprovenance; and consumes either a caller-supplied Gate aggregate or an explicit\ncaller no-Gate decision. The\nindependent verifier then recomputes every receipt and payload digest exactly as\nit does for externally supplied admission. Automatic assembly keeps Buildchain\nas the canonical authority repository, requires evidence to belong to the\ncaller, binds a repository-local publisher workflow, and rejects unknown refs,\nnon-exact source SHAs, package/target mismatches, or an undeclared Gate policy.\nManual apply and consumers that do not opt in still require their own explicit\nadmission inputs.\n\nBefore authority verification, the reusable promotion controller runs the same\nrelease transaction selector in read-only mode. That plan supplies one exact\npublication version and tag to the admission verifier, the publish-gate source\nlock, and the real promotion action. The verifier rejects a capability for a\ndifferent version, and the promotion action rechecks the planned version before\nany publish transaction side effect. Release-candidate fixture versions are\nartifact evidence only; they never name Buildchain's own source-lock or\npublication capability.\n\nEvidence publication is a separate authority class and never grants product\npublication.\n\n## Managed web-surface production\n\nThe reusable web-surface controller owns a complete standard producer path for\nits documented production mechanisms. A reviewed matching release-PR merge or a\nmanual dispatch by an actor with current repository write authority creates a\nsigned decision bound to the exact source SHA. After build, verify, and\nproduction planning, the workflow creates a qualifying pre-publication\ncontroller receipt and assembles a ten-minute admission over the source tree,\nimmutable Buildchain runtime, deployment plan, artifact hash, production\nEnvironment, AWS role/deploy target, runner provenance, decision digest, and\nnonce. The independent verifier emits the scoped `web-production` capability.\n\nThe production job rechecks the capability and candidate against the same plan\nbefore downloading product artifacts. AWS authorization is deliberately\nrecorded as `provider-at-transaction`: the capability binds the exact role and\nEnvironment, while `configure-aws-credentials` performs the live OIDC exchange\nand remains the final provider authorization gate before mutation. Buildchain\ndoes not claim that an IAM trust relationship passed before that transaction.\n\nExternally assembled admissions remain an optional compatibility path and must\nprovide the full admission, runner, control-plane, Gate aggregate, expected\nbindings, and nonce set. They are not required for the managed web-surface\nrelease-PR or trusted-manual paths.\n\n## Consumer qualification handoff\n\nConsumers may explicitly opt in to a final, consumer-owned qualification\npredicate. Buildchain then transports the complete Gate aggregate alongside the\nsealed capability instead of reducing it to a summary. The capability binds the\nauthority registry, consumer Gate registry and policy, exact source and runtime,\ncontroller, runner, control-plane, artifact, provider target, channel, version,\nfreshness window, nonce, and exact predicate command digest.\n\nThe predicate runs in a separate job with read-only source access, no inherited\nsecrets, no OIDC permission, and no provider write permission. It receives only\npaths to `capability.json` and `gate-aggregate.json` plus the exact predicate id\nand digest. The consumer writes a\n`kungfu-buildchain-consumer-publication-decision`; Buildchain seals that result\nas a deterministic\n`kungfu-buildchain-publication-qualification-receipt`. Buildchain does not parse\nproduct-specific Gate meanings.\n\nThe provider action revalidates the capability, full aggregate, receipt,\npredicate identity, freshness, nonce, source, version, channel, target, and all\nsealed digests immediately before the publish transaction. Missing, denied,\nstale, replayed, substituted, or drifted receipts fail before provider mutation.\nDirect calls to the provider action cannot bypass the receipt when\n`require-publication-qualification` is enabled. Consumers that do not opt in\nretain the existing publication contract.\n\n## API and CLI\n\nUse `@kungfu-tech/buildchain/publication-authority` or run:\n\n```bash\nbuildchain verify publication-admission admission.json \\\n  --registry-json publication-authority-registry.json \\\n  --runner-json runner.json \\\n  --control-plane-audit-json control-plane.json \\\n  --publication-evidence-json publication-evidence.json \\\n  --expected-json expected.json \\\n  --used-nonce previous-run-nonce \\\n  --json\n```\n\nThe read-only live collector defaults to npm trusted publishing. Other product\nproviders select an explicit adapter:\n\n```bash\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v3/v3.0 \\\n  --source-sha <exact-merged-branch-sha> \\\n  --workflow .github/workflows/release-candidate-promote.yml \\\n  --workflow-ref <exact-buildchain-sha> \\\n  --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \\\n  --job promote \\\n  --environment none\n\n# Optional stronger external evidence; generate the JSON outside the workflow.\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch dev/v3/v3.0 \\\n  --workflow .github/workflows/release-candidate-promote.yml \\\n  --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \\\n  --job promote \\\n  --environment none \\\n  --npm-trust-json sanitized-npm-trust.json\n\nbuildchain audit publication-control-plane \\\n  --repository kungfu-systems/buildchain \\\n  --branch release/v3/v3.0 \\\n  --workflow .github/workflows/.binary-release-assets.yml \\\n  --job publish \\\n  --environment buildchain-release-assets \\\n  --publisher-mode github-token\n\nbuildchain audit publication-control-plane \\\n  --repository OWNER/CONSUMER \\\n  --workflow-repository kungfu-systems/buildchain \\\n  --branch main \\\n  --workflow .github/workflows/.web-surface.yml \\\n  --job production-apply \\\n  --environment production \\\n  --publisher-mode oidc-role \\\n  --provider-audit-json sanitized-oidc-role-audit.json\n```\n\nThe authority workflow identifies the reusable implementation that performs the\npublication job. The publisher workflow identifies the caller filename bound by\nthe provider's trusted-publisher policy; these identities are deliberately\nseparate. `--environment none` is an explicit assertion that the job declares no\nGitHub Environment and the provider policy has no Environment restriction. A\nnamed Environment must exist, be protected, and be declared by the job. The\nBuildchain receipt alone is never sufficient authorization.\n\n## Publication lanes\n\n`Binary Distribution` is evidence-only. It builds platform archives and a\nrelease evidence bundle with read-only repository permissions. GitHub Release\nasset writes live in `Binary Release Assets`, which downloads an exact prior\nevidence run, verifies its bundle digest against the sealed capability, and is\nthe only binary job with `contents: write` in the protected\n`buildchain-release-assets` Environment.\n\nThe npm/promotion, paper, binary-release, and web-production lanes all depend on\nthe independent verifier. Preview, staging, build, source-check, controller,\nand failure-evidence lanes do not inherit product publication capability."
     },
     {
       "id": "manual:publish-transaction",
@@ -1476,7 +1552,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/publish-transaction.md",
-      "digest": "sha256:cde5256d5f6443a6d32b47783900a0677e973855266af5a360db8d4d112bb677",
+      "digest": "sha256:9b830727e5b0d2192c937f19106c11ea5064dde77e30d290825f343df47f291b",
       "headings": [
         {
           "level": 1,
@@ -1539,7 +1615,7 @@
           "anchor": "build-images-follow-up"
         }
       ],
-      "markdown": "# Publish Transaction\n\nBuildchain release promotion is not just tag movement. A release can also publish\nexternal artifacts: npm packages, Python wheels, OCI images, binary archives,\nmetadata manifests, or site deployment records. Those side effects are harder\nthan Git refs because most registries are append-only: a failed rerun must know\nwhich artifacts already exist, which are still missing, and whether any existing\nartifact conflicts with the release material.\n\nBuildchain v2 models that work as a release transaction.\n\n## Why This Exists\n\nThe old ABV workflow made Git refs the visible release authority. That was\nenough when \"release\" meant \"create a version commit, move tags, and let\ndownstream jobs react.\" It is not enough when a single publish run must also\nupload packages and images.\n\nThe failure mode to avoid is:\n\n1. publish an external artifact;\n2. fail before moving the exact release tag or floating channel refs;\n3. rerun from a new job id with no memory of the artifact;\n4. either republish something different or move refs without proving the\n   already-published artifact matches the release.\n\nThe transaction gives reruns a stable identity and a machine-readable state so\nBuildchain can resume safely. The identity is:\n\n```text\nrepository + version + source_sha + target_ref\n```\n\nIt is not the GitHub Actions run id.\n\n## Durable State\n\n`actions/promote-buildchain-ref` stores release transaction state in a\nmachine-managed Git branch:\n\n```text\nrefs/heads/buildchain/release-state/<version>\n```\n\nThe branch contains:\n\n```text\nstate.json\nevidence.json   # present after publish evidence exists\n```\n\nThe local `.buildchain/release-state/...` and\n`.buildchain/release-evidence/...` files are working copies. They are useful for\nlocal inspection and lifecycle commands, but they are not the durable truth for\nGitHub-hosted reruns. On action startup, Buildchain reads the durable state ref\nfirst, restores the local working copies, and only then decides whether to\npublish, repair, or finalize.\n\nEvery meaningful state transition is written to the durable ref before public\nrelease refs move. Release-state GitHub API reads and writes use retry/backoff\nfor transient service failures such as HTTP 5xx responses, connection resets,\ntimeouts, and \"other side closed\" socket failures. If the durable write still\ncannot be persisted after retries, the action fails closed.\n\nDurable release-state refs reserve their exact version even when the public exact\ntag was never created. If a later machine run sees a failed or repair-required\nstate for `vX.Y.Z-alpha.N` and cannot resume it with the same transaction\nidentity, alpha version selection must advance to the next prerelease instead\nof reusing or overwriting that failed transaction slot.\n\n## Lifecycle\n\nRepositories declare publish work in `.buildchain/buildchain.toml`:\n\n```toml\n[publish]\nmode = \"publish-final-version\"\nauth = \"trusted-publishing\"\ndist_tag = \"latest\"\npackage_set_order = \"platforms-first-main-last\"\nmain_package = \"@kungfu-tech/libnode\"\n\n[lifecycle.publish]\ncommands = [\n  \"python scripts/publish_wheels.py\",\n  \"node scripts/publish-images.mjs\",\n  \"node scripts/write-publish-evidence.mjs\",\n]\n```\n\n`actions/promote-buildchain-ref` runs `lifecycle.publish` only when\n`publish-transaction: \"true\"` is set or when a `publish-command` input is\nprovided. The action sets:\n\n```text\nBUILDCHAIN_VERSION\nBUILDCHAIN_CHANNEL\nBUILDCHAIN_SOURCE_SHA\nBUILDCHAIN_TARGET_REF\nBUILDCHAIN_RELEASE_STATE\nBUILDCHAIN_EVIDENCE_DIR\nBUILDCHAIN_RELEASE_SHA\nBUILDCHAIN_RELEASE_MATERIAL_SHA\nBUILDCHAIN_PUBLISH_TOOLING_SHA\nBUILDCHAIN_PUBLISH_EVIDENCE\nBUILDCHAIN_REQUIRED_ARTIFACTS\nBUILDCHAIN_PUBLISH_MODE\nBUILDCHAIN_PUBLISH_AUTH\nBUILDCHAIN_NPM_DIST_TAG\nBUILDCHAIN_PACKAGE_SET_ORDER\nBUILDCHAIN_PACKAGE_SET_MAIN_PACKAGE\n```\n\nBuildchain itself uses this contract for npm publishing:\n\n```toml\n[lifecycle.publish]\ncommand = \"node scripts/npm-publish-transaction.mjs\"\n```\n\nThat script validates that `package.json` matches `BUILDCHAIN_VERSION`, runs\n`npm publish --access public --tag <BUILDCHAIN_NPM_DIST_TAG>` through npm Trusted\nPublishing, and writes npm artifact evidence before the promotion action moves\npublic refs.\n\n`BUILDCHAIN_RELEASE_MATERIAL_SHA` is the source material whose artifacts must\nmatch. `BUILDCHAIN_PUBLISH_TOOLING_SHA` identifies the publishing code. A repair\nrun may change tooling, but material drift fails closed.\n\n## Post-Publish Requirements And Artifact Provenance\n\n`publish-required-artifacts-json` is a pre-publish family declaration, not a\nrequest to guess registry digests. A descriptor must include `kind + name`; it\nmay omit `ref` and `digest`. The action resolves a missing `ref` to the exact\n`BUILDCHAIN_VERSION`. Registries whose exact refs add a stable prefix or suffix\nmay instead declare a `ref_template` containing exactly one `{version}`, such\nas `v{version}`. The template is expanded only after exact version selection,\nso a resumed alpha transaction receives the newly selected prerelease rather\nthan the checked-out version. Declaring both `ref` and `ref_template`, using\nanother placeholder, or leaving unmatched braces fails before\n`lifecycle.publish`. The action exports the normalized exact refs as\n`BUILDCHAIN_REQUIRED_ARTIFACTS`, runs `lifecycle.publish`, and then requires the\nfinal evidence to contain every exact member with a non-empty digest. Existing\ncallers may continue supplying exact refs and digests.\n\nOCI publishers can opt into strict per-artifact provenance by adding\n`action: built` or `action: reused`. Those artifacts carry two separate\ncoordinates:\n\n- `content`: the version, ref, source SHA, and material SHA that produced the\n  immutable content;\n- `release`: the exact current version/ref, target ref, source SHA, and release\n  material SHA that bind that content into this release.\n\nThis distinction permits truthful cross-version reuse without claiming that an\nold OCI config was rebuilt from current material. For an OCI artifact with an\naction, final evidence also requires `platform`, positive `contract_major`, and\n`verification` containing a public manifest result, exact ref and digest,\nplatform, contract major, optional parent digest, evidence location, and a\npassed named smoke policy. Buildchain cross-checks those values against the\nartifact and current transaction. Missing family members and ref, digest,\ncontent, release, or verification conflicts enter `repair_required` before\npublic refs move.\n\nExample reused OCI evidence entry (the pre-publish requirement may omit\n`ref`, `digest`, `release`, and the observed verification values):\n\n```json\n{\n  \"group\": \"image\",\n  \"kind\": \"oci\",\n  \"name\": \"ghcr.io/kungfu-systems/base-linux\",\n  \"ref\": \"1.2.0-alpha.3\",\n  \"digest\": \"sha256:...\",\n  \"action\": \"reused\",\n  \"platform\": \"linux/amd64\",\n  \"contract_major\": 1,\n  \"content\": {\n    \"version\": \"1.1.9\",\n    \"ref\": \"1.1.9\",\n    \"source_sha\": \"<source-sha>\",\n    \"material_sha\": \"<material-sha>\"\n  },\n  \"release\": {\n    \"version\": \"1.2.0-alpha.3\",\n    \"ref\": \"1.2.0-alpha.3\",\n    \"target_ref\": \"alpha/v1/v1.2\",\n    \"source_sha\": \"<current-source-sha>\",\n    \"material_sha\": \"<current-material-sha>\"\n  },\n  \"verification\": {\n    \"public_manifest\": true,\n    \"ref\": \"1.2.0-alpha.3\",\n    \"digest\": \"sha256:...\",\n    \"platform\": \"linux/amd64\",\n    \"contract_major\": 1,\n    \"evidence\": \"registry-inspect.json\",\n    \"smoke\": {\n      \"policy\": \"manifest-contract\",\n      \"passed\": true,\n      \"evidence\": \"smoke.json\"\n    }\n  }\n}\n```\n\n## Release Modes And Auth\n\nBuildchain distinguishes two npm release modes:\n\n| Mode | Use | Auth | npm operation |\n| --- | --- | --- | --- |\n| `publish-final-version` | normal alpha or stable publication | `trusted-publishing` | `npm publish --tag <alpha|vX.Y-alpha|latest>` |\n| `promote-existing-version` | same-version alpha-to-latest recovery | `npm-token` | `npm dist-tag add <pkg>@<version> latest` |\n\nThe normal libnode path is `publish-final-version`: publish an alpha package set\nsuch as `22.22.3-kf.3-alpha.0` with the `alpha` dist-tag, then publish a\ndistinct final package set such as `22.22.3-kf.3` with the `latest` dist-tag.\nGitHub-hosted npm Trusted Publishing can authorize those `npm publish` calls\nwhen the workflow grants `id-token: write`.\n\n`promote-existing-version` is deliberately separate. npm Trusted Publishing does\nnot authorize arbitrary registry-management operations such as `npm dist-tag\nadd`; it authorizes publish-time package provenance. Therefore same-version\npromotion must declare `auth = \"npm-token\"`. Buildchain runs an npm token\npreflight with `npm whoami` before it writes any release transaction state or\nmoves a dist-tag. Missing token auth fails early with a contract error instead\nof a late `E401` after publish evidence has started to move.\n\nFor package sets, `package_set_order = \"platforms-first-main-last\"` makes the\nmain package the visibility gate. Platform package side effects are planned or\nretried first, and the main package or main dist-tag move happens last.\n\nWhen the transaction reaches `complete`, `actions/promote-buildchain-ref`\ngenerates `.buildchain/release-passport/buildchain.release.json` and persists\nthe `release-passport/*` files into the durable `buildchain/release-state/...`\nref. The passport is the stable release artifact for agents and people: it\nlinks the package set, npm publish evidence, dist-tag evidence, build summary,\nplatform artifact manifests, trusted publishing metadata, release-state ref,\ndurable release-state SHA, and transaction result in one schema. Consumer\nrepositories can set `release-passport-product-name` so the passport names their\nproduct instead of the Buildchain default.\n\n## Evidence\n\nThe publish lifecycle must write JSON evidence. Buildchain validates common\nfields and required artifact identities before final refs move.\n\n```json\n{\n  \"schema\": 1,\n  \"version\": \"2.0.11\",\n  \"channel\": \"release\",\n  \"source_sha\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\n  \"release_sha\": \"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\n  \"target_ref\": \"release/v2/v2.0\",\n  \"release_material_sha\": \"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\n  \"publish_tooling_sha\": \"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\n  \"artifacts\": [\n    {\n      \"group\": \"node\",\n      \"kind\": \"npm\",\n      \"name\": \"@kungfu-systems/example\",\n      \"ref\": \"2.0.11\",\n      \"digest\": \"sha256:...\"\n    },\n    {\n      \"group\": \"image\",\n      \"kind\": \"oci\",\n      \"name\": \"ghcr.io/kungfu-systems/example\",\n      \"ref\": \"2.0.11\",\n      \"digest\": \"sha256:...\"\n    }\n  ]\n}\n```\n\nThe generic contract is intentionally small:\n\n- `version`, `channel`, `source_sha`, `release_sha`, and `target_ref` must match\n  the promotion run;\n- dist-tag promotion evidence is written beside the publish evidence as\n  `dist-tag-evidence.json` and is referenced from the generated passport;\n- required artifacts must appear in evidence;\n- evidence used by a GitHub-hosted rerun must either be stored in the durable\n  state ref or be reconstructed by a machine-verifiable consumer command;\n- existing artifacts with the same identity and digest are accepted on rerun;\n- missing artifacts can be published by the next run;\n- an existing artifact with a different digest puts the transaction into\n  `repair_required`.\n\nArtifact identity is `group + kind + name + ref`. A required artifact that omits\n`group` matches any group with the same `kind + name + ref`.\n\n## Registry Truth Contract\n\nBuildchain owns transaction orchestration, finalization ordering, durable state,\nand generic evidence validation. It does not embed registry clients for npm,\nPyPI, GHCR/OCI, GitHub Releases, S3, Conan, CMake packaging, or project-specific\ndownload pages.\n\nConsumer `lifecycle.publish` commands own registry truth. A valid consumer stage\nmust be idempotent and machine-verifiable:\n\n- inspect the target registry before publishing;\n- accept an existing exact artifact only when version, identity, digest, and\n  release-source binding match;\n- publish missing required artifacts;\n- reject conflicting existing artifacts and write evidence that lets Buildchain\n  move the transaction to `repair_required`;\n- write `BUILDCHAIN_PUBLISH_EVIDENCE` after every successful inspect/publish\n  cycle;\n- leave floating aliases such as npm dist-tags, PyPI stable markers, OCI\n  floating tags, GitHub Release \"published\" status, or download-page stable\n  links to a finalization step after Buildchain evidence validation.\n\nThe first-class adapter surface is command-based. Projects may wrap npm, PyPI,\nGHCR/OCI, GitHub Release assets, archives, SBOMs, provenance, or checksums\nhowever they need, as long as they emit the common evidence contract.\n\n## States\n\nThe state machine is:\n\n```text\nprepared -> publishing -> published -> finalizing -> complete\n                    |            |            |\n                    v            v            v\n              publish_failed  repair_required failed_permanently\n                    |\n                    v\n                abandoned\n```\n\nSupported states:\n\n| State | Meaning |\n| --- | --- |\n| `prepared` | Transaction identity was created, but publish has not started. |\n| `publishing` | Publish lifecycle is running or may have been interrupted. |\n| `publish_failed` | Publish command failed before valid evidence was produced. |\n| `published` | Evidence is valid; refs have not necessarily finalized. |\n| `finalizing` | Buildchain is moving exact/floating refs or needs a later run to do it. |\n| `complete` | Required evidence is valid and refs have finalized. |\n| `repair_required` | Existing evidence or artifact state conflicts with expected release material. |\n| `abandoned` | A human or controlled process abandoned this transaction, usually because a newer version supersedes it. |\n| `failed_permanently` | Recovery should not continue without explicit override. |\n\n`repair_required`, `abandoned`, and `failed_permanently` fail closed unless the\noperator passes an explicit override. That override is for controlled repair\nruns, not normal retry behavior.\n\n## Ref Ordering\n\nWhen publish transactions are enabled, promotion order is:\n\n1. verify target source and governance;\n2. create or reuse the version-state release commit;\n3. acquire or resume the release transaction;\n4. run `lifecycle.publish` or accept already-valid evidence;\n5. validate evidence and required artifacts;\n6. move exact release/prerelease tag;\n7. move floating tags and channel refs;\n8. mark the transaction `complete`.\n\nWhen a protected channel requires a generated version-state pull request, the\nfirst run can stop at `finalizing` after registry publication. If the reviewed\nmerge commit later contains that exact transaction release material but the\nexact tag is still absent, a retry performs finalization only: it reloads the\nsame durable source, release material, tooling, evidence, version, and target\nbindings; creates the exact and floating tags at the transaction release SHA;\nand completes the passport from the transaction source tree. It does not rerun\nthe provider mutation and does not authorize the newer composite channel tree\nas published material. A different source tree still requires a new version and\na fresh release candidate.\n\nDeferred binary dispatch, controller-evidence bundling, and any consumer\npublication commit are skipped while `finalization-needed=true`. They run only\nafter the exact public tag and complete release passport exist.\n\nConsumer products that expose a signed well-known channel can opt into one\nadditional, deliberately final step with `publication-commit-command`. Before\nthat command runs, Buildchain has already completed the transaction, created\nthe public GitHub Release, and uploaded every release-passport file plus the\nexplicit PR-stage payload files selected by\n`github-release-payload-patterns`. The command is therefore a commit point for\ndiscovery authority, not another artifact publisher.\n\nThe command receives the exact version, source SHA, release SHA, release tag,\nrelease passport path, and downloaded payload directory through\n`BUILDCHAIN_PUBLICATION_COMMIT_*`. Optional consumer-owned dispatch/API\ncredentials and private signing material are exposed separately as\n`BUILDCHAIN_PUBLICATION_COMMIT_TOKEN` and\n`BUILDCHAIN_PUBLICATION_COMMIT_SIGNING_KEY`; Buildchain never logs, persists,\nor interprets either value. The command must write\n`.buildchain/publication-commit/evidence.json` (or another declared path below\n`.buildchain/`) with this contract:\n\n```json\n{\n  \"schema\": \"kungfu-buildchain-publication-commit-evidence/v1\",\n  \"status\": \"passed\",\n  \"identity\": {\n    \"version\": \"4.0.0-alpha.2\",\n    \"sourceSha\": \"<source-sha>\",\n    \"releaseSha\": \"<release-sha>\",\n    \"releaseTag\": \"v4.0.0-alpha.2\"\n  },\n  \"publication\": {\n    \"url\": \"https://example.test/.well-known/product/alpha.json\",\n    \"payloadRoot\": \"sha256:<64-lowercase-hex>\"\n  },\n  \"readback\": {\n    \"status\": \"passed\",\n    \"url\": \"https://example.test/.well-known/product/alpha.json\",\n    \"payloadRoot\": \"sha256:<same-root>\"\n  },\n  \"recovery\": {\n    \"previousAuthority\": \"preserved\",\n    \"rollbackReference\": \"sha256:<previous-root>\"\n  }\n}\n```\n\nBuildchain rejects stale evidence, identity drift, non-public or mutable URLs,\nread-back root drift, and missing recovery evidence. It also rejects\n`standalone-binary-distribution=true` with a final commit command because that\nwould queue product mutations after the authority moved. On any command or\nread-back failure, the consumer must leave the previous well-known document\nauthoritative; Buildchain does not retry the command behind a successful\nreceipt.\n\nIf protected branch finalization is interrupted after publish evidence is\nvalid, the transaction can stop in `finalizing` and output\n`finalization-needed=true`. A later run resumes from the same transaction state\nand completes ref movement without republishing matching artifacts. New\nBuildchain-managed promotions first try to finish generated version-state\nbookkeeping with the promotion token directly. Before patching a protected\ngenerated bookkeeping ref, Buildchain emits every configured required check on\nthe exact generated version-state commit so branch protection can\nvalidate the automation path without a second build, then uses the generated\nref update token for the protected ref PATCH. If release finalization\nbookkeeping is still rejected, Buildchain creates or reuses a same-repository\n`buildchain/version-state/*` PR and leaves the transaction resumable with\n`finalization-needed=true`. Strict alpha uses the same protected PR fallback\nfor both its target channel and subsequent dev reconciliation. A later\nidempotent run continues only after the provider shows that the PR reached the\nprotected branch. The reusable wrapper binds that token to the run-scoped\n`github.token` and rejects user, team, or alternate App bypass actors.\n\nIf finalization fails after an exact Git tag, a channel branch, or dev/alpha\nsync ref has already moved, the next run reads the durable `finalizing` state\nand continues from the recorded transaction. The current workflow SHA may be a\ngenerated version-state commit, or a historical version-state merge commit, that\ncontains or corresponds to the transaction's `release_material_sha`; it does not\nhave to equal the original `source_sha` or the transaction `release_sha`. Exact\ntags are accepted when they already point at the transaction release/material\nSHA or the finalized channel head. Floating\nchannel tags and dev/alpha refs are then retried idempotently, and the\ntransaction is marked `complete` only after those public refs are consistent.\nWriting `complete` clears any stale `failure` value from earlier attempts, so\nthe durable `state.json` represents the successful final state instead of the\nlast transient error seen before a rerun.\nAn exact tag at an unrelated SHA is still a material conflict and blocks\nrecovery.\n\nFor anchored package versions, the package version and internal line tag are\nseparate transaction coordinates. A retry can correct a stale internal tag on\nan unfinished `published` or `finalizing` transaction only when its validated\nevidence and complete artifact set match the same package version, source,\nrelease material, and target. Buildchain additionally requires that the stale\ntag does not already point at the transaction and that the newly selected tag\nis unclaimed or already points at accepted release material. No registry publish\ncommand is rerun during this exact-tag rebind.\n\nGoverned retries distinguish unrelated channel advancement from advancement\nmade by their own durable transaction. An unrelated descendant remains an\nauditable `superseded-promotion` no-op. When the target ref is exactly the\nrecorded `release_sha` for the requested source, target, and expected version,\nBuildchain resumes finalization, restores publish evidence, and emits the\nrelease-passport paths needed by downstream controller receipts.\n\nPublication authority planning applies the same occupied-version rule as the\nlater mutation step. If a current alpha transaction already contains published\nmaterial and regenerating version state would create new release material, the\nplanner advances to the next alpha before sealing authority. It never seals the\nold published version and then lets the publisher discover a different version\ninside the mutation boundary.\n\nIf finalization fails after an exact Git tag is created, the next run reads the\ndurable `finalizing` state, verifies the exact tag points at the recorded\nrelease SHA, and retries the remaining floating refs. An exact tag at a\ndifferent SHA is a material conflict and blocks recovery.\n\n## CLI Recovery\n\nLocal recovery commands operate on the same state/evidence files:\n\n```bash\nnode scripts/release-transaction.mjs inspect --version v2.0.11\nnode scripts/release-transaction.mjs recover --version v2.0.11\nnode scripts/release-transaction.mjs finalize --version v2.0.11\nnode scripts/release-transaction.mjs abort --version v2.0.11 --superseded-by v2.0.12\n```\n\nThe CLI is a diagnostic and local repair surface. It reports the durable\n`state_ref`, but remote durable-ref writes and public Git ref finalization are\nowned by `actions/promote-buildchain-ref`, because that action runs inside the\nsame governed GitHub permissions and branch-protection checks as release\npromotion. In other words, CLI `finalize` can mark the local transaction state\ncomplete after valid evidence; the machine-operated public finalization path is\nto rerun the promotion action.\n\nWhen no state file exists, creation commands also require:\n\n```bash\n--repository kungfu-systems/buildchain \\\n--source-sha <sha> \\\n--release-sha <sha> \\\n--target-ref release/v2/v2.0 \\\n--channel release\n```\n\n## Build-Images Follow-Up\n\n`build-images` should consume this contract rather than inventing a separate\nworkflow rule. The expected integration shape is:\n\n- image build writes OCI digests into publish evidence;\n- required image families are passed through `publish-required-artifacts-json`\n  before their final digests are known;\n- mixed built/reused evidence preserves content provenance separately from the\n  current release binding;\n- reruns check GHCR or the target registry and accept existing images only when\n  tag and digest match;\n- preview or alpha image tags remain non-stable until the transaction evidence\n  validates;\n- production image aliases move only after all required image artifacts are\n  present and the Buildchain exact release tag has finalized."
+      "markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-publish-transaction\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-31\n  invisible_context: not asserted\n---\n\n# Publish Transaction\n\nBuildchain release promotion is not just tag movement. A release can also publish\nexternal artifacts: npm packages, Python wheels, OCI images, binary archives,\nmetadata manifests, or site deployment records. Those side effects are harder\nthan Git refs because most registries are append-only: a failed rerun must know\nwhich artifacts already exist, which are still missing, and whether any existing\nartifact conflicts with the release material.\n\nBuildchain v3 models that work as a release transaction.\n\n## Why This Exists\n\nThe old ABV workflow made Git refs the visible release authority. That was\nenough when \"release\" meant \"create a version commit, move tags, and let\ndownstream jobs react.\" It is not enough when a single publish run must also\nupload packages and images.\n\nThe failure mode to avoid is:\n\n1. publish an external artifact;\n2. fail before moving the exact release tag or floating channel refs;\n3. rerun from a new job id with no memory of the artifact;\n4. either republish something different or move refs without proving the\n   already-published artifact matches the release.\n\nThe transaction gives reruns a stable identity and a machine-readable state so\nBuildchain can resume safely. The identity is:\n\n```text\nrepository + version + source_sha + target_ref\n```\n\nIt is not the GitHub Actions run id.\n\n## Durable State\n\n`actions/promote-buildchain-ref` stores release transaction state in a\nmachine-managed Git branch:\n\n```text\nrefs/heads/buildchain/release-state/<version>\n```\n\nThe branch contains:\n\n```text\nstate.json\nevidence.json   # present after publish evidence exists\nsealed-bundle/<candidate-root>/files/**  # present for build-once publication\n```\n\nThe local `.buildchain/release-state/...` and\n`.buildchain/release-evidence/...` files are working copies. They are useful for\nlocal inspection and lifecycle commands, but they are not the durable truth for\nGitHub-hosted reruns. On action startup, Buildchain reads the durable state ref\nfirst, restores the local working copies, and only then decides whether to\npublish, repair, or finalize.\n\nEvery meaningful state transition is written to the durable ref before public\nrelease refs move. Release-state GitHub API reads and writes use retry/backoff\nfor transient service failures such as HTTP 5xx responses, connection resets,\ntimeouts, and \"other side closed\" socket failures. If the durable write still\ncannot be persisted after retries, the action fails closed.\n\nFor a sealed publication, `state.json` also carries the typed sealed-bundle\nmanifest, its candidate root, publication milestones, stable\n`publication_state`, and an exact resume command. The durable ref stores every\ndeclared bundle file as binary Git blobs before the publish lifecycle starts.\nA fresh runner restores those blobs into\n`.buildchain/recovered-publication/<version>/`, verifies every size and SHA-256\nagainst the manifest, and only then supplies the recovered paths to the publish\nlifecycle. A missing or changed tarball, PDF, source bundle, or manifest fails\nbefore registry publication.\n\nDurable release-state refs reserve their exact version even when the public exact\ntag was never created. If a later machine run sees a failed or repair-required\nstate for `vX.Y.Z-alpha.N` and cannot resume it with the same transaction\nidentity, alpha version selection must advance to the next prerelease instead\nof reusing or overwriting that failed transaction slot.\n\n## Lifecycle\n\nRepositories declare publish work in `.buildchain/buildchain.toml`:\n\n```toml\n[publish]\nmode = \"publish-final-version\"\nauth = \"trusted-publishing\"\ndist_tag = \"latest\"\npackage_set_order = \"platforms-first-main-last\"\nmain_package = \"@kungfu-tech/libnode\"\n\n[lifecycle.publish]\ncommands = [\n  \"python scripts/publish_wheels.py\",\n  \"node scripts/publish-images.mjs\",\n  \"node scripts/write-publish-evidence.mjs\",\n]\n```\n\n`actions/promote-buildchain-ref` runs `lifecycle.publish` only when\n`publish-transaction: \"true\"` is set or when a `publish-command` input is\nprovided. The action sets:\n\n```text\nBUILDCHAIN_VERSION\nBUILDCHAIN_CHANNEL\nBUILDCHAIN_SOURCE_SHA\nBUILDCHAIN_TARGET_REF\nBUILDCHAIN_RELEASE_STATE\nBUILDCHAIN_EVIDENCE_DIR\nBUILDCHAIN_RELEASE_SHA\nBUILDCHAIN_RELEASE_MATERIAL_SHA\nBUILDCHAIN_PUBLISH_TOOLING_SHA\nBUILDCHAIN_PUBLISH_EVIDENCE\nBUILDCHAIN_SEALED_BUNDLE_ROOT\nBUILDCHAIN_SEALED_NPM_TARBALL\nBUILDCHAIN_SEALED_NPM_INTEGRITY\nBUILDCHAIN_SEALED_NPM_SHA256\nBUILDCHAIN_REQUIRED_ARTIFACTS\nBUILDCHAIN_PUBLISH_MODE\nBUILDCHAIN_PUBLISH_AUTH\nBUILDCHAIN_NPM_DIST_TAG\nBUILDCHAIN_PACKAGE_SET_ORDER\nBUILDCHAIN_PACKAGE_SET_MAIN_PACKAGE\n```\n\nBuildchain itself uses this contract for npm publishing:\n\n```toml\n[lifecycle.publish]\ncommand = \"node scripts/npm-publish-transaction.mjs\"\n```\n\nThat script validates that `package.json` matches `BUILDCHAIN_VERSION`, runs\n`npm publish --access public --tag <BUILDCHAIN_NPM_DIST_TAG>` through npm Trusted\nPublishing, and writes npm artifact evidence before the promotion action moves\npublic refs. When the sealed npm variables are present, the script verifies and\npublishes that exact `.tgz` file. It does not run `npm pack` again.\n\n`BUILDCHAIN_RELEASE_MATERIAL_SHA` is the source material whose artifacts must\nmatch. `BUILDCHAIN_PUBLISH_TOOLING_SHA` identifies the publishing code. A repair\nrun may change tooling, but material drift fails closed.\n\n## Post-Publish Requirements And Artifact Provenance\n\n`publish-required-artifacts-json` is a pre-publish family declaration, not a\nrequest to guess registry digests. A descriptor must include `kind + name`; it\nmay omit `ref` and `digest`. The action resolves a missing `ref` to the exact\n`BUILDCHAIN_VERSION`. Registries whose exact refs add a stable prefix or suffix\nmay instead declare a `ref_template` containing exactly one `{version}`, such\nas `v{version}`. The template is expanded only after exact version selection,\nso a resumed alpha transaction receives the newly selected prerelease rather\nthan the checked-out version. Declaring both `ref` and `ref_template`, using\nanother placeholder, or leaving unmatched braces fails before\n`lifecycle.publish`. The action exports the normalized exact refs as\n`BUILDCHAIN_REQUIRED_ARTIFACTS`, runs `lifecycle.publish`, and then requires the\nfinal evidence to contain every exact member with a non-empty digest. Existing\ncallers may continue supplying exact refs and digests.\n\nOCI publishers can opt into strict per-artifact provenance by adding\n`action: built` or `action: reused`. Those artifacts carry two separate\ncoordinates:\n\n- `content`: the version, ref, source SHA, and material SHA that produced the\n  immutable content;\n- `release`: the exact current version/ref, target ref, source SHA, and release\n  material SHA that bind that content into this release.\n\nThis distinction permits truthful cross-version reuse without claiming that an\nold OCI config was rebuilt from current material. For an OCI artifact with an\naction, final evidence also requires `platform`, positive `contract_major`, and\n`verification` containing a public manifest result, exact ref and digest,\nplatform, contract major, optional parent digest, evidence location, and a\npassed named smoke policy. Buildchain cross-checks those values against the\nartifact and current transaction. Missing family members and ref, digest,\ncontent, release, or verification conflicts enter `repair_required` before\npublic refs move.\n\nExample reused OCI evidence entry (the pre-publish requirement may omit\n`ref`, `digest`, `release`, and the observed verification values):\n\n```json\n{\n  \"group\": \"image\",\n  \"kind\": \"oci\",\n  \"name\": \"ghcr.io/kungfu-systems/base-linux\",\n  \"ref\": \"1.2.0-alpha.3\",\n  \"digest\": \"sha256:...\",\n  \"action\": \"reused\",\n  \"platform\": \"linux/amd64\",\n  \"contract_major\": 1,\n  \"content\": {\n    \"version\": \"1.1.9\",\n    \"ref\": \"1.1.9\",\n    \"source_sha\": \"<source-sha>\",\n    \"material_sha\": \"<material-sha>\"\n  },\n  \"release\": {\n    \"version\": \"1.2.0-alpha.3\",\n    \"ref\": \"1.2.0-alpha.3\",\n    \"target_ref\": \"alpha/v1/v1.2\",\n    \"source_sha\": \"<current-source-sha>\",\n    \"material_sha\": \"<current-material-sha>\"\n  },\n  \"verification\": {\n    \"public_manifest\": true,\n    \"ref\": \"1.2.0-alpha.3\",\n    \"digest\": \"sha256:...\",\n    \"platform\": \"linux/amd64\",\n    \"contract_major\": 1,\n    \"evidence\": \"registry-inspect.json\",\n    \"smoke\": {\n      \"policy\": \"manifest-contract\",\n      \"passed\": true,\n      \"evidence\": \"smoke.json\"\n    }\n  }\n}\n```\n\n## Release Modes And Auth\n\nBuildchain distinguishes two npm release modes:\n\n| Mode | Use | Auth | npm operation |\n| --- | --- | --- | --- |\n| `publish-final-version` | normal alpha or stable publication | `trusted-publishing` | `npm publish --tag <alpha|vX.Y-alpha|latest>` |\n| `promote-existing-version` | same-version alpha-to-latest recovery | `npm-token` | `npm dist-tag add <pkg>@<version> latest` |\n\nThe normal libnode path is `publish-final-version`: publish an alpha package set\nsuch as `22.22.3-kf.3-alpha.0` with the `alpha` dist-tag, then publish a\ndistinct final package set such as `22.22.3-kf.3` with the `latest` dist-tag.\nGitHub-hosted npm Trusted Publishing can authorize those `npm publish` calls\nwhen the workflow grants `id-token: write`.\n\n`promote-existing-version` is deliberately separate. npm Trusted Publishing does\nnot authorize arbitrary registry-management operations such as `npm dist-tag\nadd`; it authorizes publish-time package provenance. Therefore same-version\npromotion must declare `auth = \"npm-token\"`. Buildchain runs an npm token\npreflight with `npm whoami` before it writes any release transaction state or\nmoves a dist-tag. Missing token auth fails early with a contract error instead\nof a late `E401` after publish evidence has started to move.\n\nFor package sets, `package_set_order = \"platforms-first-main-last\"` makes the\nmain package the visibility gate. Platform package side effects are planned or\nretried first, and the main package or main dist-tag move happens last.\n\nWhen the transaction reaches `complete`, `actions/promote-buildchain-ref`\ngenerates `.buildchain/release-passport/buildchain.release.json` and persists\nthe `release-passport/*` files into the durable `buildchain/release-state/...`\nref. The passport is the stable release artifact for agents and people: it\nlinks the package set, npm publish evidence, dist-tag evidence, build summary,\nplatform artifact manifests, trusted publishing metadata, release-state ref,\ndurable release-state SHA, and transaction result in one schema. Consumer\nrepositories can set `release-passport-product-name` so the passport names their\nproduct instead of the Buildchain default.\n\n## Evidence\n\nThe publish lifecycle must write JSON evidence. Buildchain validates common\nfields and required artifact identities before final refs move.\n\n```json\n{\n  \"schema\": 1,\n  \"version\": \"2.0.11\",\n  \"channel\": \"release\",\n  \"source_sha\": \"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\n  \"release_sha\": \"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\n  \"target_ref\": \"release/v3/v3.0\",\n  \"release_material_sha\": \"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\n  \"publish_tooling_sha\": \"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\n  \"artifacts\": [\n    {\n      \"group\": \"node\",\n      \"kind\": \"npm\",\n      \"name\": \"@kungfu-systems/example\",\n      \"ref\": \"2.0.11\",\n      \"digest\": \"sha256:...\"\n    },\n    {\n      \"group\": \"image\",\n      \"kind\": \"oci\",\n      \"name\": \"ghcr.io/kungfu-systems/example\",\n      \"ref\": \"2.0.11\",\n      \"digest\": \"sha256:...\"\n    }\n  ]\n}\n```\n\nThe generic contract is intentionally small:\n\n- `version`, `channel`, `source_sha`, `release_sha`, and `target_ref` must match\n  the promotion run;\n- dist-tag promotion evidence is written beside the publish evidence as\n  `dist-tag-evidence.json` and is referenced from the generated passport;\n- required artifacts must appear in evidence;\n- evidence used by a GitHub-hosted rerun must either be stored in the durable\n  state ref or be reconstructed by a machine-verifiable consumer command;\n- existing artifacts with the same identity and digest are accepted on rerun;\n- missing artifacts can be published by the next run;\n- an existing artifact with a different digest puts the transaction into\n  `repair_required`.\n\nArtifact identity is `group + kind + name + ref`. A required artifact that omits\n`group` matches any group with the same `kind + name + ref`.\n\n## Registry Truth Contract\n\nBuildchain owns transaction orchestration, finalization ordering, durable state,\nand generic evidence validation. It does not embed registry clients for npm,\nPyPI, GHCR/OCI, GitHub Releases, S3, Conan, CMake packaging, or project-specific\ndownload pages.\n\nConsumer `lifecycle.publish` commands own registry truth. A valid consumer stage\nmust be idempotent and machine-verifiable:\n\n- inspect the target registry before publishing;\n- accept an existing exact artifact only when version, identity, digest, and\n  release-source binding match;\n- publish missing required artifacts;\n- reject conflicting existing artifacts and write evidence that lets Buildchain\n  move the transaction to `repair_required`;\n- write `BUILDCHAIN_PUBLISH_EVIDENCE` after every successful inspect/publish\n  cycle;\n- leave floating aliases such as npm dist-tags, PyPI stable markers, OCI\n  floating tags, GitHub Release \"published\" status, or download-page stable\n  links to a finalization step after Buildchain evidence validation.\n\nThe first-class adapter surface is command-based. Projects may wrap npm, PyPI,\nGHCR/OCI, GitHub Release assets, archives, SBOMs, provenance, or checksums\nhowever they need, as long as they emit the common evidence contract.\n\n## States\n\nThe state machine is:\n\n```text\nprepared -> sealed -> publishing -> published -> finalizing -> complete\n                          |            |            |\n                          v            v            v\n                    publish_failed  repair_required failed_permanently\n                          |\n                          v\n                      abandoned\n```\n\nSupported states:\n\n| State                | Meaning                                                                                                  |\n| -------------------- | -------------------------------------------------------------------------------------------------------- |\n| `prepared`           | Transaction identity was created, but publish has not started.                                           |\n| `sealed`             | Exact candidate bytes and manifest are verified and durable; registry publication has not started.       |\n| `publishing`         | Publish lifecycle is running or may have been interrupted.                                               |\n| `publish_failed`     | Publish command failed before valid evidence was produced.                                               |\n| `published`          | Evidence is valid; refs have not necessarily finalized.                                                  |\n| `finalizing`         | Buildchain is moving exact/floating refs or needs a later run to do it.                                  |\n| `complete`           | Required evidence is valid and refs have finalized.                                                      |\n| `repair_required`    | Existing evidence or artifact state conflicts with expected release material.                            |\n| `abandoned`          | A human or controlled process abandoned this transaction, usually because a newer version supersedes it. |\n| `failed_permanently` | Recovery should not continue without explicit override.                                                  |\n\n`repair_required`, `abandoned`, and `failed_permanently` fail closed unless the\noperator passes an explicit override. That override is for controlled repair\nruns, not normal retry behavior.\n\n`publication_state` is a stable operator-facing projection over the detailed\ntransaction state. Its successful progression is\n`prepared -> sealed -> package-published -> alpha-complete` for Alpha or\n`release-complete` for stable release. If npm succeeds but GitHub Release work\nis interrupted, the durable record remains `package-published`; the next run\nreuses the exact npm evidence and sealed release assets instead of rebuilding\nor republishing them.\n\n## Ref Ordering\n\nWhen publish transactions are enabled, promotion order is:\n\n1. verify target source and governance;\n2. create or reuse the version-state release commit;\n3. acquire or resume the release transaction;\n4. for build-once publication, verify and persist the complete sealed bundle;\n5. run `lifecycle.publish` from the exact sealed tarball or accept already-valid\n   evidence;\n6. validate evidence and required artifacts;\n7. move exact release/prerelease tag;\n8. move floating tags and channel refs;\n9. mark the transaction `complete`;\n10. create or update the GitHub Release from restored sealed assets and record\n    the `github_release` milestone.\n\nWhen a protected channel requires a generated version-state pull request, the\nfirst run can stop at `finalizing` after registry publication. If the reviewed\nmerge commit later contains that exact transaction release material but the\nexact tag is still absent, a retry performs finalization only: it reloads the\nsame durable source, release material, tooling, evidence, version, and target\nbindings; creates the exact and floating tags at the transaction release SHA;\nand completes the passport from the transaction source tree. It does not rerun\nthe provider mutation and does not authorize the newer composite channel tree\nas published material. A different source tree still requires a new version and\na fresh release candidate.\n\nDeferred binary dispatch, controller-evidence bundling, and any consumer\npublication commit are skipped while `finalization-needed=true`. They run only\nafter the exact public tag and complete release passport exist.\n\nConsumer products that expose a signed well-known channel can opt into one\nadditional, deliberately final step with `publication-commit-command`. Before\nthat command runs, Buildchain has already completed the transaction, created\nthe public GitHub Release, and uploaded every release-passport file plus the\nexplicit PR-stage payload files selected by\n`github-release-payload-patterns`. The command is therefore a commit point for\ndiscovery authority, not another artifact publisher.\n\nThe command receives the exact version, source SHA, release SHA, release tag,\nrelease passport path, and downloaded payload directory through\n`BUILDCHAIN_PUBLICATION_COMMIT_*`. Optional consumer-owned dispatch/API\ncredentials and private signing material are exposed separately as\n`BUILDCHAIN_PUBLICATION_COMMIT_TOKEN` and\n`BUILDCHAIN_PUBLICATION_COMMIT_SIGNING_KEY`; Buildchain never logs, persists,\nor interprets either value. The command must write\n`.buildchain/publication-commit/evidence.json` (or another declared path below\n`.buildchain/`) with this contract:\n\n```json\n{\n  \"schema\": \"kungfu-buildchain-publication-commit-evidence/v1\",\n  \"status\": \"passed\",\n  \"identity\": {\n    \"version\": \"4.0.0-alpha.2\",\n    \"sourceSha\": \"<source-sha>\",\n    \"releaseSha\": \"<release-sha>\",\n    \"releaseTag\": \"v4.0.0-alpha.2\"\n  },\n  \"publication\": {\n    \"url\": \"https://example.test/.well-known/product/alpha.json\",\n    \"payloadRoot\": \"sha256:<64-lowercase-hex>\"\n  },\n  \"readback\": {\n    \"status\": \"passed\",\n    \"url\": \"https://example.test/.well-known/product/alpha.json\",\n    \"payloadRoot\": \"sha256:<same-root>\"\n  },\n  \"recovery\": {\n    \"previousAuthority\": \"preserved\",\n    \"rollbackReference\": \"sha256:<previous-root>\"\n  }\n}\n```\n\nBuildchain rejects stale evidence, identity drift, non-public or mutable URLs,\nread-back root drift, and missing recovery evidence. It also rejects\n`standalone-binary-distribution=true` with a final commit command because that\nwould queue product mutations after the authority moved. On any command or\nread-back failure, the consumer must leave the previous well-known document\nauthoritative; Buildchain does not retry the command behind a successful\nreceipt.\n\nIf protected branch finalization is interrupted after publish evidence is\nvalid, the transaction can stop in `finalizing` and output\n`finalization-needed=true`. A later run resumes from the same transaction state\nand completes ref movement without republishing matching artifacts. New\nBuildchain-managed promotions first try to finish generated version-state\nbookkeeping with the promotion token directly. Before patching a protected\ngenerated bookkeeping ref, Buildchain emits every configured required check on\nthe exact generated version-state commit so branch protection can\nvalidate the automation path without a second build, then uses the generated\nref update token for the protected ref PATCH. If release finalization\nbookkeeping is still rejected, Buildchain creates or reuses a same-repository\n`buildchain/version-state/*` PR and leaves the transaction resumable with\n`finalization-needed=true`. Strict alpha uses the same protected PR fallback\nfor both its target channel and subsequent dev reconciliation. A later\nidempotent run continues only after the provider shows that the PR reached the\nprotected branch. The reusable wrapper binds that token to the run-scoped\n`github.token` and rejects user, team, or alternate App bypass actors.\n\nIf finalization fails after an exact Git tag, a channel branch, or dev/alpha\nsync ref has already moved, the next run reads the durable `finalizing` state\nand continues from the recorded transaction. The current workflow SHA may be a\ngenerated version-state commit, or a historical version-state merge commit, that\ncontains or corresponds to the transaction's `release_material_sha`; it does not\nhave to equal the original `source_sha` or the transaction `release_sha`. Exact\ntags are accepted when they already point at the transaction release/material\nSHA or the finalized channel head. Floating\nchannel tags and dev/alpha refs are then retried idempotently, and the\ntransaction is marked `complete` only after those public refs are consistent.\nWriting `complete` clears any stale `failure` value from earlier attempts, so\nthe durable `state.json` represents the successful final state instead of the\nlast transient error seen before a rerun.\nAn exact tag at an unrelated SHA is still a material conflict and blocks\nrecovery.\n\nFor anchored package versions, the package version and internal line tag are\nseparate transaction coordinates. A retry can correct a stale internal tag on\nan unfinished `published` or `finalizing` transaction only when its validated\nevidence and complete artifact set match the same package version, source,\nrelease material, and target. Buildchain additionally requires that the stale\ntag does not already point at the transaction and that the newly selected tag\nis unclaimed or already points at accepted release material. No registry publish\ncommand is rerun during this exact-tag rebind.\n\nGoverned retries distinguish unrelated channel advancement from advancement\nmade by their own durable transaction. An unrelated descendant remains an\nauditable `superseded-promotion` no-op. When the target ref is exactly the\nrecorded `release_sha` for the requested source, target, and expected version,\nBuildchain resumes finalization, restores publish evidence, and emits the\nrelease-passport paths needed by downstream controller receipts.\n\nPublication authority planning applies the same occupied-version rule as the\nlater mutation step. If a current alpha transaction already contains published\nmaterial and regenerating version state would create new release material, the\nplanner advances to the next alpha before sealing authority. It never seals the\nold published version and then lets the publisher discover a different version\ninside the mutation boundary.\n\nIf finalization fails after an exact Git tag is created, the next run reads the\ndurable `finalizing` state, verifies the exact tag points at the recorded\nrelease SHA, and retries the remaining floating refs. An exact tag at a\ndifferent SHA is a material conflict and blocks recovery.\n\n## CLI Recovery\n\nLocal recovery commands operate on the same state/evidence files:\n\n```bash\nnode scripts/release-transaction.mjs inspect --version v3.0.2\nnode scripts/release-transaction.mjs recover --version v3.0.2\nnode scripts/release-transaction.mjs finalize --version v3.0.2\nnode scripts/release-transaction.mjs abort --version v3.0.2 --superseded-by v3.0.3\n```\n\nThe CLI is a diagnostic and local repair surface. It reports the durable\n`state_ref`, but remote durable-ref writes and public Git ref finalization are\nowned by `actions/promote-buildchain-ref`, because that action runs inside the\nsame governed GitHub permissions and branch-protection checks as release\npromotion. In other words, CLI `finalize` can mark the local transaction state\ncomplete after valid evidence; the machine-operated public finalization path is\nto rerun the promotion action.\n\nWhen no state file exists, creation commands also require:\n\n```bash\n--repository kungfu-systems/buildchain \\\n--source-sha <sha> \\\n--release-sha <sha> \\\n--target-ref release/v3/v3.0 \\\n--channel release\n```\n\n## Build-Images Follow-Up\n\n`build-images` should consume this contract rather than inventing a separate\nworkflow rule. The expected integration shape is:\n\n- image build writes OCI digests into publish evidence;\n- required image families are passed through `publish-required-artifacts-json`\n  before their final digests are known;\n- mixed built/reused evidence preserves content provenance separately from the\n  current release binding;\n- reruns check GHCR or the target registry and accept existing images only when\n  tag and digest match;\n- preview or alpha image tags remain non-stable until the transaction evidence\n  validates;\n- production image aliases move only after all required image artifacts are\n  present and the Buildchain exact release tag has finalized."
     },
     {
       "id": "manual:readme-badges",
@@ -1621,15 +1697,20 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/release-candidate.md",
-      "digest": "sha256:887bc3c041c3231d8e6dd403964d04d28a9eb13081bc4154dc2a6ebd56697ecd",
+      "digest": "sha256:fbcffddf1e2c50502186b7ba557e29f96be59a1da6d438aabd4d1f9ce32b5915",
       "headings": [
         {
           "level": 1,
           "title": "Release Candidate Passport",
           "anchor": "release-candidate-passport"
+        },
+        {
+          "level": 2,
+          "title": "Initiative-family release evidence",
+          "anchor": "initiative-family-release-evidence"
         }
       ],
-      "markdown": "# Release Candidate Passport\n\nThe release-candidate passport is the pre-promotion evidence contract produced\nafter a reusable build matrix succeeds and before any publish-gate side effects\nrun. It is different from the release passport:\n\n- `release-candidate-passport.json` proves which source SHA, channel, runtime,\n  workflow run, and platform artifacts were verified before promotion.\n- `buildchain.release.json` is generated after publish finalization and remains\n  the durable audit entrypoint for the published release.\n\nEnable it on the reusable build workflow:\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    with:\n      artifact-name: libnode\n      release-candidate: true\n      publish-channel: alpha\n      publish-source-ref: publish-gate/alpha/v22/v22.22/22.22.3-kf.3-alpha.7\n```\n\nWhen the platform matrix and aggregate summaries complete, Buildchain uploads:\n\n```text\n<artifact-name>-release-candidate-<publish-source-sha>\n```\n\nThe passport contract is `kungfu-buildchain-release-candidate-passport`. It\ncontains:\n\n- repository and pull request context;\n- target channel, target ref, and product version or a non-publish\n  `source-<shortSha>` candidate label;\n- source head SHA, merge ref SHA, and the Git `HEAD^{tree}` SHA for PR merge\n  equivalence after the channel PR lands;\n- Buildchain runtime ref/SHA and workflow shell ref;\n- workflow run id/attempt/url;\n- normalized platform matrix and artifact summaries;\n- the hash of the aggregate `build-summary.json`.\n\nPromotion workflows that should not rebuild artifacts can enable:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    sha: ${{ needs.build.outputs.publish-source-sha }}\n    target-ref: alpha/v22/v22.22\n    promote-only-release-candidate: \"true\"\n    release-candidate-passport-path: .buildchain/artifacts/release-candidate-passport.json\n    release-candidate-build-summary-path: .buildchain/artifacts/build-summary.json\n```\n\nWith `promote-only-release-candidate: \"true\"`, promotion fails before\nversion-state, publish transaction, tag, or branch side effects when the\npassport does not match the repository, channel, source identity, platform\nmatrix, or build-summary hash. Source identity accepts the exact PR source SHA,\nthe PR merge ref SHA, or an exact Git tree match with the promoted channel HEAD;\nthis keeps post-merge channel commits strict without forcing a rebuild. The\nBuildchain-owned promotion workflow resolves the matching same-repository\nmerged channel PR and downloads its PR-stage RC passport automatically before\npromotion starts. The consumer wrapper defaults to a PR-stage workflow file\nnamed `build.yml` with display name `Build`, and filters the RC passport and\nbuild summary by the configured `artifact-name` before promotion. It also\ndownloads payload artifacts from the same PR-stage run, validates the required\npayload count, passes downloaded platform manifests into the release passport,\nand either forwards an explicit `publish-required-artifacts-json` value or\ngenerates one before calling `promote-buildchain-ref`. Before that call, the\nwrapper creates or updates `publish-gate/{alpha,release,major}` to the\npromotion channel commit and passes that ref, target SHA, and `locked=true` to\nthe promote action with `require-publish-source-lock: \"true\"`. Consumers using\nfloating `@v3` therefore get publish-side source-lock drift protection without\ncopying resolver or promote YAML. The default npm path\ngenerates that requirement list from the downloaded `.tgz` payloads themselves:\nBuildchain reads `package/package.json` inside each tarball for the real scoped\npackage name and version, computes npm-style `sha512-...` integrity over the\ntarball bytes, marks `publish-package-main` as `role: main`, and marks every\nother package as `role: platform`. Consumer workflows therefore stay\ndeclarative and do not need their own artifact download or publish-evidence\ngeneration scripts.\n\nBecause a channel merge can trigger promotion before its PR-stage matrix has\nfinished uploading evidence, the resolver waits up to ten minutes for the exact\nmerged PR's successful workflow run and paired artifacts. Polling remains bound\nto the PR/head identity; timeout or a sibling run still fails closed.\n\nThe public promotion router preserves the requested `vN` or `vN-alpha` ref as\naudit metadata, but binds the router to GitHub's selected reusable-workflow SHA\nand resolves each remaining floating shell/runtime ref exactly once. Every\nlater checkout and delegated promotion receives those immutable SHAs, so a\nchannel tag moving during the run cannot mix two Buildchain revisions.\n\nIf a promote-only run failed after its consumer commit was already merged and\nits PR-stage artifacts were built, rerun the complete failed workflow after the\nfixed Buildchain channel is published:\n\n```bash\ngh run rerun <run-id> --repo <owner>/<consumer>\n```\n\nUse a complete rerun, not `--failed`, so GitHub resolves the reusable workflow\nagain. The release-candidate resolver reuses the existing candidate artifacts,\nand the durable publication transaction makes the recovery idempotent; do not\nopen a replacement consumer PR or rebuild the native matrix solely for this\nrouter failure.\n\nBy default, the wrapper forwards GitHub Release publication to the underlying\n`promote-buildchain-ref` semver model. Once the release transaction is complete,\nthe action creates or updates the public GitHub Release, applies\nprerelease/latest metadata from the authoritative publication channel (falling\nback to semver tag syntax only for ordinary callers without that intent), and\nuploads the publish evidence file together with the generated release passport\nassets. This keeps\nnpm/registry publication, Buildchain release passport persistence, and\n`release.published` propagation in one declarative reusable workflow. Consumers\nthat do not publish GitHub Releases can opt out with `github-release: false`.\nFor anchored/manual package releases, the public GitHub Release tag defaults to\n`v<publishedVersion>` while the internal transaction exact tag remains recorded\nin the release passport.\n\nStandalone binary publication is a separate consumer capability. The promotion\nwrapper does not assume that an npm-only repository provides\n`.github/workflows/binary-distribution.yml`. Repositories that own that workflow\nopt in with `standalone-binary-distribution: true`; Buildchain's self-promotion\ndoes so explicitly. Once enabled, a missing or invalid binary workflow remains a\nhard failure rather than being silently skipped.\n\nProducts that publish KFD release trust evidence can keep that path declarative\ntoo. Pass KFD-1 self contract witnesses, KFD-2 public claim files, and KFD-3\npre-build/artifact evidence into the wrapper:\n\n```yaml\njobs:\n  promote:\n    uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v3\n    with:\n      buildchain-channel: auto\n      buildchain-alpha-contract-lock-path: .buildchain/alpha-contract-lock.json\n      buildchain-stable-contract-lock-path: .buildchain/contract-lock.json\n      channel: alpha\n      artifact-name: libnode\n      release-passport-kfd-1-witness-jsons: .buildchain/kfd/kfd-1/standard-contract.witness.json\n      release-passport-kfd-2-claim-jsons: .buildchain/kfd/kfd-2/release-claims.json\n      release-passport-kfd-3-prebuild-witness-jsons: .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json\n      release-passport-kfd-3-artifact-verify-command: kungfu agent verify --json\n```\n\nBuildchain forwards those declarations into `promote-buildchain-ref`, verifies\nKFD-1 source/artifact contract surfaces, audits KFD-2 public release claims, and\ncompares KFD-3 declared shipped public surfaces with artifact-exposed public\nsurfaces. The release passport records the results under `kfd-1`, `kfd-2`, and\nthe KFD-provided `kfd-3` section.\n\nManaged consumers may also ask the promotion wrapper to assemble sealed\npublication evidence from the exact release candidate instead of producing\nshort-lived admission JSON in repository-specific workflow code:\n\n```yaml\n      publication-auto-admission: true\n      publication-auto-no-gate: true\n      publication-publisher-workflow-path: .github/workflows/buildchain-ref-promotion.yml\n      publication-product: Example Product\n      publication-target: npm:@example/product\n      publication-package-name: \"@example/product\"\n```\n\n`publication-auto-no-gate` is an explicit consumer decision, not a default. A\nconsumer with a Shifu Gate registry supplies `publication-gate-aggregate-json`\ninstead. Buildchain still requires caller-owned RC evidence, an exact authority\nruntime and source SHA, a repository-local publisher workflow, matching npm\ntarget/package identity or exact caller-bound GitHub Release target, and a\nqualifying control-plane audit.\n\nGitHub-Release-only consumers use the same managed admission without inventing\nan npm package identity:\n\n```yaml\n      publication-auto-admission: true\n      publication-auto-no-gate: true\n      publication-publisher-workflow-path: .github/workflows/buildchain-ref-promotion.yml\n      publication-product: Example Binary\n      publication-target: github-release:example/example-binary\n      publication-package-name: \"\"\n```\n\nThe target must exactly match the caller repository. Buildchain audits the\njob-scoped GitHub token, exact release-candidate payloads and manifests,\nprotected channel lineage, and public release transaction before allowing the\nGitHub Release mutation.\n\nA consumer that owns additional product qualification semantics can opt in to\nthe sealed handoff without teaching Buildchain those semantics:\n\n```yaml\n      publication-consumer-predicate-id: kungfu.release-admission/v1\n      publication-consumer-qualification-command: node scripts/qualify-release.mjs\n```\n\nThe command reads `BUILDCHAIN_PUBLICATION_CAPABILITY_PATH` and\n`BUILDCHAIN_PUBLICATION_GATE_AGGREGATE_PATH`, evaluates the complete aggregate,\nand writes a decision JSON document to\n`BUILDCHAIN_PUBLICATION_QUALIFICATION_RESULT_PATH`. It also receives\n`BUILDCHAIN_PUBLICATION_PREDICATE_ID` and\n`BUILDCHAIN_PUBLICATION_PREDICATE_DIGEST`. The separate qualification job has\nno write or OIDC permission and does not inherit publication secrets. A\nsuccessful deterministic receipt is rechecked by the provider action\nimmediately before mutation. Omitting both inputs preserves the existing\nconsumer contract; supplying only one fails closed."
+      "markdown": "# Release Candidate Passport\n\nThe release-candidate passport is the pre-promotion evidence contract produced\nafter a reusable build matrix succeeds and before any publish-gate side effects\nrun. It is different from the release passport:\n\n- `release-candidate-passport.json` proves which source SHA, channel, runtime,\n  workflow run, and platform artifacts were verified before promotion.\n- `buildchain.release.json` is generated after publish finalization and remains\n  the durable audit entrypoint for the published release.\n\nEnable it on the reusable build workflow:\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    with:\n      artifact-name: libnode\n      release-candidate: true\n      publish-channel: alpha\n      publish-source-ref: publish-gate/alpha/v22/v22.22/22.22.3-kf.3-alpha.7\n```\n\nWhen the platform matrix and aggregate summaries complete, Buildchain uploads:\n\n```text\n<artifact-name>-release-candidate-<publish-source-sha>\n```\n\nThe passport contract is `kungfu-buildchain-release-candidate-passport`. It\ncontains:\n\n- repository and pull request context;\n- target channel, target ref, and product version or a non-publish\n  `source-<shortSha>` candidate label;\n- source head SHA, merge ref SHA, and the Git `HEAD^{tree}` SHA for PR merge\n  equivalence after the channel PR lands;\n- Buildchain runtime ref/SHA and workflow shell ref;\n- workflow run id/attempt/url;\n- normalized platform matrix and artifact summaries;\n- the hash of the aggregate `build-summary.json`.\n\n## Initiative-family release evidence\n\nA consumer may pass `release-candidate-family-evidence-json` to the reusable\nbuild. Buildchain normalizes that value as\n`kungfu-buildchain-initiative-family-release-evidence/v1`, binds it into the\ncandidate hash, and carries it unchanged into publication authority. The\nenvelope can identify one Initiative family root plus the exact Initiative and\nAssignment responsible for the release; continuation evidence can also bind\nthe previous family root.\n\nThis is an adapter-edge release contract, not a second Work Control authority.\nThe immutable native Family State v1 projection and the additive Family State\nv2 typed envelope remain owned by Kungfu. Buildchain only proves that the\nrelease candidate consumed the caller-supplied family evidence exactly.\n\nPromotion workflows that should not rebuild artifacts can enable:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3\n  with:\n    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n    sha: ${{ needs.build.outputs.publish-source-sha }}\n    target-ref: alpha/v22/v22.22\n    promote-only-release-candidate: \"true\"\n    release-candidate-passport-path: .buildchain/artifacts/release-candidate-passport.json\n    release-candidate-build-summary-path: .buildchain/artifacts/build-summary.json\n    release-candidate-family-evidence-required: \"true\"\n    release-candidate-family-evidence-root: sha256:<initiative-family-root>\n    release-candidate-family-initiative-id: 2026-07-30-example-initiative\n    release-candidate-family-assignment-id: 2026-07-30-example-release\n```\n\nWith `promote-only-release-candidate: \"true\"`, promotion fails before\nversion-state, publish transaction, tag, or branch side effects when the\npassport does not match the repository, channel, source identity, platform\nmatrix, or build-summary hash. Source identity accepts the exact PR source SHA,\nthe PR merge ref SHA, or an exact Git tree match with the promoted channel HEAD;\nthis keeps post-merge channel commits strict without forcing a rebuild. The\nBuildchain-owned promotion workflow resolves the matching same-repository\nmerged channel PR and downloads its PR-stage RC passport automatically before\npromotion starts. The consumer wrapper defaults to a PR-stage workflow file\nnamed `build.yml` with display name `Build`, and filters the RC passport and\nbuild summary by the configured `artifact-name` before promotion. It also\ndownloads payload artifacts from the same PR-stage run, validates the required\npayload count, passes downloaded platform manifests into the release passport,\nand either forwards an explicit `publish-required-artifacts-json` value or\ngenerates one before calling `promote-buildchain-ref`. Before that call, the\nwrapper creates or updates `publish-gate/{alpha,release,major}` to the\npromotion channel commit and passes that ref, target SHA, and `locked=true` to\nthe promote action with `require-publish-source-lock: \"true\"`. Consumers using\nfloating `@v3` therefore get publish-side source-lock drift protection without\ncopying resolver or promote YAML. The default npm path\ngenerates that requirement list from the downloaded `.tgz` payloads themselves:\nBuildchain reads `package/package.json` inside each tarball for the real scoped\npackage name and version, computes npm-style `sha512-...` integrity over the\ntarball bytes, marks `publish-package-main` as `role: main`, and marks every\nother package as `role: platform`. Consumer workflows therefore stay\ndeclarative and do not need their own artifact download or publish-evidence\ngeneration scripts.\n\nWhen `release-candidate-family-evidence-required` is true, the promotion\nboundary additionally requires the exact family root and may require the\nInitiative and Assignment ids. Missing, mismatched, or source-drifted family\nevidence fails before version-state, release-state, tag, or branch mutation.\n\nBecause a channel merge can trigger promotion before its PR-stage matrix has\nfinished uploading evidence, the resolver waits up to ten minutes for the exact\nmerged PR's successful workflow run and paired artifacts. Polling remains bound\nto the PR/head identity; timeout or a sibling run still fails closed.\n\nThe public promotion router preserves the requested `vN` or `vN-alpha` ref as\naudit metadata, but binds the router to GitHub's selected reusable-workflow SHA\nand resolves each remaining floating shell/runtime ref exactly once. Every\nlater checkout and delegated promotion receives those immutable SHAs, so a\nchannel tag moving during the run cannot mix two Buildchain revisions.\n\nIf a promote-only run failed after its consumer commit was already merged and\nits PR-stage artifacts were built, rerun the complete failed workflow after the\nfixed Buildchain channel is published:\n\n```bash\ngh run rerun <run-id> --repo <owner>/<consumer>\n```\n\nUse a complete rerun, not `--failed`, so GitHub resolves the reusable workflow\nagain. The release-candidate resolver reuses the existing candidate artifacts,\nand the durable publication transaction makes the recovery idempotent; do not\nopen a replacement consumer PR or rebuild the native matrix solely for this\nrouter failure.\n\nBy default, the wrapper forwards GitHub Release publication to the underlying\n`promote-buildchain-ref` semver model. Once the release transaction is complete,\nthe action creates or updates the public GitHub Release, applies\nprerelease/latest metadata from the authoritative publication channel (falling\nback to semver tag syntax only for ordinary callers without that intent), and\nuploads the publish evidence file together with the generated release passport\nassets. This keeps\nnpm/registry publication, Buildchain release passport persistence, and\n`release.published` propagation in one declarative reusable workflow. Consumers\nthat do not publish GitHub Releases can opt out with `github-release: false`.\nFor anchored/manual package releases, the public GitHub Release tag defaults to\n`v<publishedVersion>` while the internal transaction exact tag remains recorded\nin the release passport.\n\nStandalone binary publication is a separate consumer capability. The promotion\nwrapper does not assume that an npm-only repository provides\n`.github/workflows/binary-distribution.yml`. Repositories that own that workflow\nopt in with `standalone-binary-distribution: true`; Buildchain's self-promotion\ndoes so explicitly. Once enabled, a missing or invalid binary workflow remains a\nhard failure rather than being silently skipped.\n\nProducts that publish KFD release trust evidence can keep that path declarative\ntoo. Pass KFD-1 self contract witnesses, KFD-2 public claim files, and KFD-3\npre-build/artifact evidence into the wrapper:\n\n```yaml\njobs:\n  promote:\n    uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v3\n    with:\n      buildchain-channel: auto\n      buildchain-alpha-contract-lock-path: .buildchain/alpha-contract-lock.json\n      buildchain-stable-contract-lock-path: .buildchain/contract-lock.json\n      channel: alpha\n      artifact-name: libnode\n      release-passport-kfd-1-witness-jsons: .buildchain/kfd/kfd-1/standard-contract.witness.json\n      release-passport-kfd-2-claim-jsons: .buildchain/kfd/kfd-2/release-claims.json\n      release-passport-kfd-3-prebuild-witness-jsons: .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json\n      release-passport-kfd-3-artifact-verify-command: kungfu agent verify --json\n```\n\nBuildchain forwards those declarations into `promote-buildchain-ref`, verifies\nKFD-1 source/artifact contract surfaces, audits KFD-2 public release claims, and\ncompares KFD-3 declared shipped public surfaces with artifact-exposed public\nsurfaces. The release passport records the results under `kfd-1`, `kfd-2`, and\nthe KFD-provided `kfd-3` section.\n\nManaged consumers may also ask the promotion wrapper to assemble sealed\npublication evidence from the exact release candidate instead of producing\nshort-lived admission JSON in repository-specific workflow code:\n\n```yaml\n      publication-auto-admission: true\n      publication-auto-no-gate: true\n      publication-publisher-workflow-path: .github/workflows/buildchain-ref-promotion.yml\n      publication-product: Example Product\n      publication-target: npm:@example/product\n      publication-package-name: \"@example/product\"\n```\n\n`publication-auto-no-gate` is an explicit consumer decision, not a default. A\nconsumer with a Shifu Gate registry supplies `publication-gate-aggregate-json`\ninstead. Buildchain still requires caller-owned RC evidence, an exact authority\nruntime and source SHA, a repository-local publisher workflow, matching npm\ntarget/package identity or exact caller-bound GitHub Release target, and a\nqualifying control-plane audit.\n\nGitHub-Release-only consumers use the same managed admission without inventing\nan npm package identity:\n\n```yaml\n      publication-auto-admission: true\n      publication-auto-no-gate: true\n      publication-publisher-workflow-path: .github/workflows/buildchain-ref-promotion.yml\n      publication-product: Example Binary\n      publication-target: github-release:example/example-binary\n      publication-package-name: \"\"\n```\n\nThe target must exactly match the caller repository. Buildchain audits the\njob-scoped GitHub token, exact release-candidate payloads and manifests,\nprotected channel lineage, and public release transaction before allowing the\nGitHub Release mutation.\n\nA consumer that owns additional product qualification semantics can opt in to\nthe sealed handoff without teaching Buildchain those semantics:\n\n```yaml\n      publication-consumer-predicate-id: kungfu.release-admission/v1\n      publication-consumer-qualification-command: node scripts/qualify-release.mjs\n```\n\nThe command reads `BUILDCHAIN_PUBLICATION_CAPABILITY_PATH` and\n`BUILDCHAIN_PUBLICATION_GATE_AGGREGATE_PATH`, evaluates the complete aggregate,\nand writes a decision JSON document to\n`BUILDCHAIN_PUBLICATION_QUALIFICATION_RESULT_PATH`. It also receives\n`BUILDCHAIN_PUBLICATION_PREDICATE_ID` and\n`BUILDCHAIN_PUBLICATION_PREDICATE_DIGEST`. The separate qualification job has\nno write or OIDC permission and does not inherit publication secrets. A\nsuccessful deterministic receipt is rechecked by the provider action\nimmediately before mutation. Omitting both inputs preserves the existing\nconsumer contract; supplying only one fails closed."
     },
     {
       "id": "manual:release-flow",
@@ -1643,7 +1724,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/release-flow.md",
-      "digest": "sha256:fc6495a7b5124c17c880777e16fc98e60ed7766ec9a958abfca3030bdc2c321e",
+      "digest": "sha256:bac959565c36cf39c3cd30dfce00dbbb59b73ed21b852a8f24a6cae281cb5f05",
       "headings": [
         {
           "level": 1,
@@ -1701,7 +1782,7 @@
           "anchor": "failure-boundaries"
         }
       ],
-      "markdown": "# Release Flow Diagrams\n\nThis document describes the Buildchain v2 branch, tag, and version-state flow.\nSee [Release governance](release-governance.md) for the design rationale.\n\n## Architecture\n\n```mermaid\nflowchart TD\n  Maintainer[\"Maintainer opens channel PR\"]\n  Verify[\"Release - Verify\"]\n  Review[\"Protected branch review\"]\n  Merge[\"Merge PR into alpha or release\"]\n  Promotion[\"Buildchain Ref Promotion\"]\n  StableDecision{\"Release channel?\"}\n  StableGate[\"Stable only: exact-alpha canaries + soak + cooldown\"]\n  Action[\"promote-buildchain-ref action\"]\n  VersionState[\"Version-state commit\"]\n  ExactTag[\"Exact tag\"]\n  FloatingRefs[\"Floating tags and channel branches\"]\n  Consumers[\"Consumers pin stable or exact refs\"]\n\n  Maintainer --> Verify\n  Verify --> Review\n  Review --> Merge\n  Merge --> Promotion\n  Promotion --> StableDecision\n  StableDecision -->|yes| StableGate\n  StableDecision -->|no: alpha| Action\n  StableGate --> Action\n  Action --> VersionState\n  Action --> ExactTag\n  Action --> FloatingRefs\n  ExactTag --> Consumers\n  FloatingRefs --> Consumers\n```\n\nBuildchain treats the PR merge as release intent and the promotion action as the\nonly component allowed to turn that intent into release refs.\n\n`StableGate` applies only to Buildchain's release channel. Alpha and train\niteration bypass it. See [Stable Release Throttle And Canary Gate](release-governance.md#stable-release-throttle-and-canary-gate)\nfor the versioned policy and evidence contract.\n\n## Ref State\n\n| Ref kind | Example | Mutability | Purpose |\n| --- | --- | --- | --- |\n| Development branch | `dev/v2/v2.0` | moves | next source state for a minor line |\n| Alpha branch | `alpha/v2/v2.0` | moves | latest test state for a minor line |\n| Release branch | `release/v2/v2.0` | moves | latest production state for a minor line |\n| Major gate branch | `publish-gate/major` | moves | reviewed administrator gate for publishing the next major |\n| Exact alpha tag | `v2.0.3-alpha.0` | immutable | audit ref for one tested prerelease |\n| Exact release tag | `v2.0.2` | immutable | audit ref for one production release |\n| Floating alpha tag | `v2.0-alpha` | moves | latest test channel for a minor line |\n| Floating major alpha tag | `v2-alpha` | moves | latest test channel on the highest published alpha minor for a major line |\n| Floating minor tag | `v2.0` | moves | latest production patch on a minor line |\n| Floating major tag | `v2` | moves | selected stable major entrypoint |\n\n## Ref Protection Contract\n\nRepository rulesets must distinguish immutable evidence refs from mutable\nchannel refs.\n\nProtect exact release and alpha tags as immutable evidence:\n\n```text\nrefs/tags/v*.*.*\n```\n\nDo not apply immutable-tag rulesets to every `refs/tags/v*` ref. Buildchain\nmust be able to update floating channel tags such as `v2`, `v2.0`, `v2.0-alpha`,\nand `v2-alpha` after the exact tag and publish evidence are valid. A ruleset that\nmatches all `v*` tags also matches floating tags, so release finalization can\nfail with GitHub protected-ref errors even though the exact release tag and\npublished artifacts are already durable.\n\nThe intended governance split is:\n\n- exact tags such as `v2.0.14` and `v2.0.15-alpha.0` are immutable audit refs;\n- floating tags such as `v2`, `v2.0`, `v2.0-alpha`, and `v2-alpha` are mutable channel refs\n  owned by the Buildchain promotion token;\n- protected branches still require reviewed channel PRs before Buildchain can\n  move any exact or floating release refs.\n\n## Opening a Minor Line\n\nNew minor lines should be opened through Buildchain instead of hand-created\nbranches. The reusable entrypoint is the `Release Line Bootstrap` workflow. It\ndefaults to dry-run so maintainers can inspect the planned refs, protection\ncontract, initial version, and first alpha PR before any mutation.\n\nThe workflow is backed by the CLI command:\n\n```bash\nbuildchain release line open \\\n  --major 2 \\\n  --minor 10 \\\n  --source-ref release/v2/v2.9 \\\n  --json\n```\n\nWhen the workflow is run with `apply=true`, Buildchain:\n\n- writes the initial version-state commit, such as `2.10.0-alpha.0`;\n- creates `dev/v2/v2.10` from that commit;\n- creates `alpha/v2/v2.10` and `release/v2/v2.10` from the selected source ref;\n- applies branch protection with one approving review and the configured\n  required status check; dev starts strict, while alpha and release also require\n  the pair-specific `verify` aggregate without a source-up-to-date ancestry loop;\n- reconciles the new dev branch's explicitly declared merge queue, or inherits\n  the exact queue parameters and bypass actors from the current default dev\n  branch when the policy is `inherit` or absent;\n- switches the repository default branch to the new dev line when requested;\n- opens the first `dev/v2/v2.10 -> alpha/v2/v2.10` channel PR when requested.\n\nThis makes minor-line creation a single audited operation. The channel PR still\ngoes through the normal verify/review/promotion path before an alpha is\npublished. Queue reconciliation runs after branch protection and before the\ndefault-branch switch, so a failed governance apply leaves the old active line\nin place and the idempotently created new refs can be retried.\n\n## Alpha Promotion\n\n```mermaid\nsequenceDiagram\n  participant Dev as dev/vX/vX.Y\n  participant PR as PR dev -> alpha\n  participant Verify as Release - Verify\n  participant Alpha as alpha/vX/vX.Y\n  participant Promote as Buildchain Ref Promotion\n  participant Tags as Tags\n\n  Dev->>PR: open channel PR\n  PR->>Verify: run verification checks\n  Verify-->>PR: check succeeds\n  PR->>Alpha: reviewed merge\n  Alpha->>Promote: Verify workflow_run completed\n  Promote->>Promote: validate same-repo merged PR\n  Promote->>Promote: compute next vX.Y.Z-alpha.N\n  Promote->>Promote: write and verify version state\n  Promote->>Tags: create or reuse vX.Y.Z-alpha.N\n  Promote->>Tags: move vX.Y-alpha\n  Promote->>Tags: move vX-alpha when X.Y is the highest published alpha minor\n  Promote->>Alpha: move alpha/vX/vX.Y\n  Promote->>Dev: move dev/vX/vX.Y\n```\n\nResult:\n\n```text\nvX.Y.Z-alpha.N\nvX.Y-alpha\nvX-alpha when X.Y is the highest published alpha minor\nalpha/vX/vX.Y\ndev/vX/vX.Y\n```\n\nall point at the generated alpha version-state commit.\n\n## Release Promotion\n\n```mermaid\nsequenceDiagram\n  participant Alpha as alpha/vX/vX.Y\n  participant PR as PR alpha -> release\n  participant Verify as Release - Verify\n  participant Release as release/vX/vX.Y\n  participant Promote as Buildchain Ref Promotion\n  participant Tags as Tags\n  participant Dev as dev/vX/vX.Y\n\n  Alpha->>PR: open channel PR\n  PR->>Verify: run verification checks\n  Verify-->>PR: check succeeds\n  PR->>Release: reviewed merge\n  Release->>Promote: Verify workflow_run completed\n  Promote->>Promote: validate same-repo merged PR\n  Promote->>Promote: find same-patch alpha tag\n  Promote->>Promote: compare release tree with tested alpha tree\n  Promote->>Promote: write final version state or verify anchored material\n  Promote->>Tags: create or reuse vX.Y.Z\n  Promote->>Tags: move vX.Y\n  Promote->>Tags: move vX when eligible\n  Promote->>Release: move release/vX/vX.Y\n  Promote->>Promote: prepare vX.Y.(Z+1)-alpha.0\n  Promote->>Tags: create or reuse vX.Y.(Z+1)-alpha.0\n  Promote->>Tags: move vX.Y-alpha\n  Promote->>Tags: move vX-alpha when X.Y is the highest published alpha minor\n  Promote->>Alpha: move alpha/vX/vX.Y\n  Promote->>Dev: move dev/vX/vX.Y\n```\n\nResult:\n\n```text\nvX.Y.Z\nvX.Y\nvX\nrelease/vX/vX.Y\n```\n\npoint at the production version-state commit, while:\n\n```text\nvX.Y.(Z+1)-alpha.0\nvX.Y-alpha\nvX-alpha when X.Y is the highest published alpha minor\nalpha/vX/vX.Y\ndev/vX/vX.Y\n```\n\npoint at the next alpha version-state commit.\n\n## State Machine\n\n```mermaid\nstateDiagram-v2\n  [*] --> Development: work lands on dev/vX/vX.Y\n  Development --> AlphaCandidate: PR dev -> alpha\n  AlphaCandidate --> AlphaPublished: Verify + review + merge + promotion\n  AlphaPublished --> ReleaseCandidate: PR alpha -> release\n  ReleaseCandidate --> ProductionPublished: Verify + review + merge + promotion\n  ProductionPublished --> NextAlphaPrepared: prepare vX.Y.(Z+1)-alpha.0\n  NextAlphaPrepared --> Development: dev and alpha refs move to next alpha\n```\n\nThe same minor line can loop through this state machine many times.\n\n## Version Examples\n\nAssume `v2.0.2-alpha.1` has been tested and a maintainer merges\n`alpha/v2/v2.0 -> release/v2/v2.0`.\n\nBuildchain should produce:\n\n```text\nv2.0.2                  exact production tag\nv2.0                    floating minor tag\nv2                      floating major tag when v2.0 is the selected major line\nrelease/v2/v2.0         production channel branch\n```\n\nIt should also prepare:\n\n```text\nv2.0.3-alpha.0          exact next alpha tag\nv2.0-alpha              floating alpha tag\nv2-alpha                floating major alpha tag when v2.0 is the highest published alpha minor\nalpha/v2/v2.0           alpha channel branch\ndev/v2/v2.0             development channel branch\n```\n\nThis is expected behavior. A production release closes one patch and opens the\nnext test patch on the same minor line.\n\n## Major Gate Promotion\n\n```mermaid\nsequenceDiagram\n  participant Release as release/vX/vX.Y\n  participant PR as PR release -> publish-gate/major\n  participant Verify as Release - Verify\n  participant Gate as publish-gate/major\n  participant Promote as Buildchain Ref Promotion\n  participant Tags as Tags\n  participant Next as dev/alpha/release v(X+1).0\n\n  Release->>PR: open administrator PR\n  PR->>Verify: run verification checks\n  Verify-->>PR: check succeeds\n  PR->>Gate: reviewed merge\n  Gate->>Promote: Verify workflow_run completed\n  Promote->>Promote: validate same-repo release -> publish-gate/major PR\n  Promote->>Promote: write v(X+1).0.0 version state\n  Promote->>Tags: create v(X+1).0.0\n  Promote->>Tags: move v(X+1).0 and v(X+1)\n  Promote->>Gate: move publish-gate/major to v(X+1).0.0\n  Promote->>Next: move release/v(X+1)/v(X+1).0 to v(X+1).0.0\n  Promote->>Promote: prepare v(X+1).0.1-alpha.0\n  Promote->>Next: move alpha/dev v(X+1).0 to next alpha\n```\n\n`publish-gate/major` is intentionally not an active source branch. It is the PR\ntarget for the administrator's \"publish the next major\" decision. The older\n`major-gate` name is a compatibility alias only.\n\n## Failure Boundaries\n\nPromotion should stop before moving refs when:\n\n- the run is a non-dry-run manual dispatch;\n- the expected same-repository PR cannot be found;\n- the PR was not merged;\n- the branch pair is not a valid channel path;\n- the required status check did not pass;\n- a release tree does not match the same-patch alpha tag tree, except for the\n  declared anchored/manual version files and anchor manifest that\n  `lifecycle.verify` or `verification-command` validates;\n- version-state verification fails;\n- a required exact tag already exists at a commit unrelated to the active\n  transaction or finalized channel head.\n\nThese failures are intentional. They protect consumers from refs that look\nreleased but do not have a complete evidence chain.\n\nDuring transaction finalization recovery, the current channel head may be a\ngenerated version-state merge commit. Buildchain validates that the durable\ntransaction version, exact tag, evidence, and release material match, and that\nthe current target ref contains or corresponds to the recorded\n`release_material_sha`. It must then tolerate exact tags, dev refs, or alpha\nrefs that have already moved and continue filling any missing floating tags\nbefore writing the transaction state as `complete`."
+      "markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-release-flow\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-31\n  invisible_context: not asserted\n---\n\n# Release Flow Diagrams\n\nThis document describes the Buildchain v3 branch, tag, and version-state flow.\nSee [Release governance](release-governance.md) for the design rationale.\n\n## Architecture\n\n```mermaid\nflowchart TD\n  Maintainer[\"Maintainer opens channel PR\"]\n  Verify[\"Release - Verify\"]\n  Review[\"Protected branch review\"]\n  Merge[\"Merge PR into alpha or release\"]\n  Promotion[\"Buildchain Ref Promotion\"]\n  StableDecision{\"Release channel?\"}\n  StableGate[\"Stable only: exact-alpha canaries + soak + cooldown\"]\n  Action[\"promote-buildchain-ref action\"]\n  VersionState[\"Version-state commit\"]\n  ExactTag[\"Exact tag\"]\n  FloatingRefs[\"Floating tags and channel branches\"]\n  Consumers[\"Consumers pin stable or exact refs\"]\n\n  Maintainer --> Verify\n  Verify --> Review\n  Review --> Merge\n  Merge --> Promotion\n  Promotion --> StableDecision\n  StableDecision -->|yes| StableGate\n  StableDecision -->|no: alpha| Action\n  StableGate --> Action\n  Action --> VersionState\n  Action --> ExactTag\n  Action --> FloatingRefs\n  ExactTag --> Consumers\n  FloatingRefs --> Consumers\n```\n\nBuildchain treats the PR merge as release intent and the promotion action as the\nonly component allowed to turn that intent into release refs.\n\n`StableGate` applies only to Buildchain's release channel. Alpha and train\niteration bypass it. See [Stable Release Throttle And Canary Gate](release-governance.md#stable-release-throttle-and-canary-gate)\nfor the versioned policy and evidence contract.\n\n## Ref State\n\n| Ref kind | Example | Mutability | Purpose |\n| --- | --- | --- | --- |\n| Development branch | `dev/v3/v3.0` | moves | next source state for a minor line |\n| Alpha branch | `alpha/v3/v3.0` | moves | latest test state for a minor line |\n| Release branch | `release/v3/v3.0` | moves | latest production state for a minor line |\n| Major gate branch | `publish-gate/major` | moves | reviewed administrator gate for publishing the next major |\n| Exact alpha tag | `v3.0.3-alpha.0` | immutable | audit ref for one tested prerelease |\n| Exact release tag | `v3.0.2` | immutable | audit ref for one production release |\n| Floating alpha tag | `v3.0-alpha` | moves | latest test channel for a minor line |\n| Floating major alpha tag | `v3-alpha` | moves | latest test channel on the highest published alpha minor for a major line |\n| Floating minor tag | `v3.0` | moves | latest production patch on a minor line |\n| Floating major tag | `v3` | moves | selected stable major entrypoint |\n\n## Ref Protection Contract\n\nRepository rulesets must distinguish immutable evidence refs from mutable\nchannel refs.\n\nProtect exact release and alpha tags as immutable evidence:\n\n```text\nrefs/tags/v*.*.*\n```\n\nDo not apply immutable-tag rulesets to every `refs/tags/v*` ref. Buildchain\nmust be able to update floating channel tags such as `v3`, `v3.0`, `v3.0-alpha`,\nand `v3-alpha` after the exact tag and publish evidence are valid. A ruleset that\nmatches all `v*` tags also matches floating tags, so release finalization can\nfail with GitHub protected-ref errors even though the exact release tag and\npublished artifacts are already durable.\n\nThe intended governance split is:\n\n- exact tags such as `v3.0.2` and `v3.0.3-alpha.0` are immutable audit refs;\n- floating tags such as `v3`, `v3.0`, `v3.0-alpha`, and `v3-alpha` are mutable channel refs\n  owned by the Buildchain promotion token;\n- protected branches still require reviewed channel PRs before Buildchain can\n  move any exact or floating release refs.\n\n## Opening a Minor Line\n\nNew minor lines should be opened through Buildchain instead of hand-created\nbranches. The reusable entrypoint is the `Release Line Bootstrap` workflow. It\ndefaults to dry-run so maintainers can inspect the planned refs, protection\ncontract, initial version, and first alpha PR before any mutation.\n\nThe workflow is backed by the CLI command:\n\n```bash\nbuildchain release line open \\\n  --major 3 \\\n  --minor 1 \\\n  --source-ref release/v3/v3.0 \\\n  --json\n```\n\nWhen the workflow is run with `apply=true`, Buildchain:\n\n- writes the initial version-state commit, such as `3.1.0-alpha.0`;\n- creates `dev/v3/v3.1` from that commit;\n- creates `alpha/v3/v3.1` and `release/v3/v3.1` from the selected source ref;\n- applies branch protection with one approving review and the configured\n  required status check; dev starts strict, while alpha and release also require\n  the pair-specific `verify` aggregate without a source-up-to-date ancestry loop;\n- reconciles the new dev branch's explicitly declared merge queue, or inherits\n  the exact queue parameters and bypass actors from the current default dev\n  branch when the policy is `inherit` or absent;\n- switches the repository default branch to the new dev line when requested;\n- opens the first `dev/v3/v3.1 -> alpha/v3/v3.1` channel PR when requested.\n\nThis makes minor-line creation a single audited operation. The channel PR still\ngoes through the normal verify/review/promotion path before an alpha is\npublished. Queue reconciliation runs after branch protection and before the\ndefault-branch switch, so a failed governance apply leaves the old active line\nin place and the idempotently created new refs can be retried.\n\n## Alpha Promotion\n\n```mermaid\nsequenceDiagram\n  participant Dev as dev/vX/vX.Y\n  participant PR as PR dev -> alpha\n  participant Verify as Release - Verify\n  participant Alpha as alpha/vX/vX.Y\n  participant Promote as Buildchain Ref Promotion\n  participant Tags as Tags\n\n  Dev->>PR: open channel PR\n  PR->>Verify: run verification checks\n  Verify-->>PR: check succeeds\n  PR->>Alpha: reviewed merge\n  Alpha->>Promote: Verify workflow_run completed\n  Promote->>Promote: validate same-repo merged PR\n  Promote->>Promote: compute next vX.Y.Z-alpha.N\n  Promote->>Promote: write and verify version state\n  Promote->>Tags: create or reuse vX.Y.Z-alpha.N\n  Promote->>Tags: move vX.Y-alpha\n  Promote->>Tags: move vX-alpha when X.Y is the highest published alpha minor\n  Promote->>Alpha: move alpha/vX/vX.Y\n  Promote->>Dev: move dev/vX/vX.Y\n```\n\nResult:\n\n```text\nvX.Y.Z-alpha.N\nvX.Y-alpha\nvX-alpha when X.Y is the highest published alpha minor\nalpha/vX/vX.Y\ndev/vX/vX.Y\n```\n\nall point at the generated alpha version-state commit.\n\n## Release Promotion\n\n```mermaid\nsequenceDiagram\n  participant Alpha as alpha/vX/vX.Y\n  participant PR as PR alpha -> release\n  participant Verify as Release - Verify\n  participant Release as release/vX/vX.Y\n  participant Promote as Buildchain Ref Promotion\n  participant Tags as Tags\n  participant Dev as dev/vX/vX.Y\n\n  Alpha->>PR: open channel PR\n  PR->>Verify: run verification checks\n  Verify-->>PR: check succeeds\n  PR->>Release: reviewed merge\n  Release->>Promote: Verify workflow_run completed\n  Promote->>Promote: validate same-repo merged PR\n  Promote->>Promote: find same-patch alpha tag\n  Promote->>Promote: compare release tree with tested alpha tree\n  Promote->>Promote: write final version state or verify anchored material\n  Promote->>Tags: create or reuse vX.Y.Z\n  Promote->>Tags: move vX.Y\n  Promote->>Tags: move vX when eligible\n  Promote->>Release: move release/vX/vX.Y\n  Promote->>Promote: prepare vX.Y.(Z+1)-alpha.0\n  Promote->>Tags: create or reuse vX.Y.(Z+1)-alpha.0\n  Promote->>Tags: move vX.Y-alpha\n  Promote->>Tags: move vX-alpha when X.Y is the highest published alpha minor\n  Promote->>Alpha: move alpha/vX/vX.Y\n  Promote->>Dev: move dev/vX/vX.Y\n```\n\nResult:\n\n```text\nvX.Y.Z\nvX.Y\nvX\nrelease/vX/vX.Y\n```\n\npoint at the production version-state commit, while:\n\n```text\nvX.Y.(Z+1)-alpha.0\nvX.Y-alpha\nvX-alpha when X.Y is the highest published alpha minor\nalpha/vX/vX.Y\ndev/vX/vX.Y\n```\n\npoint at the next alpha version-state commit.\n\n## State Machine\n\n```mermaid\nstateDiagram-v2\n  [*] --> Development: work lands on dev/vX/vX.Y\n  Development --> AlphaCandidate: PR dev -> alpha\n  AlphaCandidate --> AlphaPublished: Verify + review + merge + promotion\n  AlphaPublished --> ReleaseCandidate: PR alpha -> release\n  ReleaseCandidate --> ProductionPublished: Verify + review + merge + promotion\n  ProductionPublished --> NextAlphaPrepared: prepare vX.Y.(Z+1)-alpha.0\n  NextAlphaPrepared --> Development: dev and alpha refs move to next alpha\n```\n\nThe same minor line can loop through this state machine many times.\n\n## Version Examples\n\nAssume `v3.0.2-alpha.1` has been tested and a maintainer merges\n`alpha/v3/v3.0 -> release/v3/v3.0`.\n\nBuildchain should produce:\n\n```text\nv3.0.2                  exact production tag\nv3.0                    floating minor tag\nv3                      floating major tag when v3.0 is the selected major line\nrelease/v3/v3.0         production channel branch\n```\n\nIt should also prepare:\n\n```text\nv3.0.3-alpha.0          exact next alpha tag\nv3.0-alpha              floating alpha tag\nv3-alpha                floating major alpha tag when v3.0 is the highest published alpha minor\nalpha/v3/v3.0           alpha channel branch\ndev/v3/v3.0             development channel branch\n```\n\nThis is expected behavior. A production release closes one patch and opens the\nnext test patch on the same minor line.\n\n## Major Gate Promotion\n\n```mermaid\nsequenceDiagram\n  participant Release as release/vX/vX.Y\n  participant PR as PR release -> publish-gate/major\n  participant Verify as Release - Verify\n  participant Gate as publish-gate/major\n  participant Promote as Buildchain Ref Promotion\n  participant Tags as Tags\n  participant Next as dev/alpha/release v(X+1).0\n\n  Release->>PR: open administrator PR\n  PR->>Verify: run verification checks\n  Verify-->>PR: check succeeds\n  PR->>Gate: reviewed merge\n  Gate->>Promote: Verify workflow_run completed\n  Promote->>Promote: validate same-repo release -> publish-gate/major PR\n  Promote->>Promote: write v(X+1).0.0 version state\n  Promote->>Tags: create v(X+1).0.0\n  Promote->>Tags: move v(X+1).0 and v(X+1)\n  Promote->>Gate: move publish-gate/major to v(X+1).0.0\n  Promote->>Next: move release/v(X+1)/v(X+1).0 to v(X+1).0.0\n  Promote->>Promote: prepare v(X+1).0.1-alpha.0\n  Promote->>Next: move alpha/dev v(X+1).0 to next alpha\n```\n\n`publish-gate/major` is intentionally not an active source branch. It is the PR\ntarget for the administrator's \"publish the next major\" decision. The older\n`major-gate` name is a compatibility alias only.\n\n## Failure Boundaries\n\nPromotion should stop before moving refs when:\n\n- the run is a non-dry-run manual dispatch;\n- the expected same-repository PR cannot be found;\n- the PR was not merged;\n- the branch pair is not a valid channel path;\n- the required status check did not pass;\n- a release tree does not match the same-patch alpha tag tree, except for the\n  declared anchored/manual version files and anchor manifest that\n  `lifecycle.verify` or `verification-command` validates;\n- version-state verification fails;\n- a required exact tag already exists at a commit unrelated to the active\n  transaction or finalized channel head.\n\nThese failures are intentional. They protect consumers from refs that look\nreleased but do not have a complete evidence chain.\n\nDuring transaction finalization recovery, the current channel head may be a\ngenerated version-state merge commit. Buildchain validates that the durable\ntransaction version, exact tag, evidence, and release material match, and that\nthe current target ref contains or corresponds to the recorded\n`release_material_sha`. It must then tolerate exact tags, dev refs, or alpha\nrefs that have already moved and continue filling any missing floating tags\nbefore writing the transaction state as `complete`."
     },
     {
       "id": "manual:release-governance",
@@ -1715,7 +1796,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/release-governance.md",
-      "digest": "sha256:42a45f51db7ea11658431718835e1a430959db2a5cc80fc4651681502fe6fb7c",
+      "digest": "sha256:60ec90d3294818d3c53e403312801a8ab47be7c0f34810002676fbfcdbceaa60",
       "headings": [
         {
           "level": 1,
@@ -1808,7 +1889,7 @@
           "anchor": "operational-reading-order"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-release-governance\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-27\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-27\n  invisible_context: not asserted\n---\n\n# Release Governance\n\nBuildchain v2 preserves the release semantics of the older ABV workflow while\nmoving the implementation into one modern repository.\n\nThe central idea is simple: a reviewed merge into a release channel is the\nrelease intent. Automation must then create the version-state commit, exact tag,\nfloating tag, and next alpha state that make that intent true in Git.\n\n## Design Problem\n\nKungfu release automation has to keep four facts aligned:\n\n1. The source tree that was reviewed.\n2. The package version recorded in manifests such as `package.json` or\n   `lerna.json`.\n3. The exact immutable release or prerelease tag.\n4. The floating channel refs that consumers actually use.\n\nIf any one of these facts is updated by hand, the system can split:\n\n- a consumer can fetch `v2.0` and receive a tree whose package version still\n  says the previous release;\n- a maintainer can move `v2` without producing an exact `v2.0.N` audit tag;\n- an alpha can be promoted to production even though the release tree is not the\n  same tree that was tested;\n- a protected branch merge can succeed while the follow-up version commit is\n  missing, or a flow-internal generated `dev`/`alpha`/`release` ref update can\n  fail after publish because the automation identity was not declared in the\n  branch-protection review bypass allowance.\n\nThe older ABV workflow addressed this by letting GitHub PRs drive release\nstate. Buildchain keeps that choice because it makes release intent reviewable,\nobservable, and recoverable from Git history.\n\n## What ABV Contributed\n\nThe old ABV model was not just \"bump a version number.\" It encoded a governance\nloop:\n\n- release branches are named as channels: `dev`, `alpha`, `release`, and the\n  administrative `publish-gate/major`;\n- a PR from one channel to the next is the release request;\n- verify jobs check that the branch pair is valid before merge;\n- a maintainer review is required before the branch moves;\n- after merge, automation writes the version change and moves tags;\n- exact tags and floating refs are aligned with the resulting commit;\n- the next development channel is prepared automatically.\n\nABV also kept the version-state mutation in the repository. For JavaScript\nrepositories that usually meant changing `lerna.json` and/or `package.json`.\nThat commit is important because the tag alone is not enough evidence: the\nsource tree should also declare the version that the tag advertises.\n\nBuildchain v2 treats that as a hard semantic requirement for its own release\nline.\n\n## Buildchain Implementation\n\nBuildchain implements the same governance loop with:\n\n- `.github/workflows/release-verify.yml` for PR verification;\n- `.github/workflows/buildchain-ref-promotion.yml` for post-verify ref\n  promotion; this workflow dogfoods the declarative\n  `release-candidate-promote.yml` wrapper and does not hand-wire resolver,\n  artifact download, publish-gate, or promote action steps;\n- Buildchain self promotion enables `release-passport-buildchain-self-kfd`, so\n  the promote action generates KFD-1 witnesses, KFD-2 public claim JSON, and\n  KFD-3 collaboration-interface witnesses from the final version-state workspace\n  before release passport finalization. The witness hashes therefore bind to the\n  exact published package and site facts from\n  `packages/core/buildchain-kfd-claims.js` instead of relying on prose release\n  notes;\n- `actions/promote-buildchain-ref` for branch, tag, version-state, and\n  governance checks;\n- package-manager adapters that can update version state for pnpm, npm, and\n  yarn style repositories;\n- `buildchain.toml` lifecycle configuration for repositories whose version\n  state or verification commands are not Node package-manager defaults.\n\nThe implementation is intentionally stricter than a local release script:\n\n- manual workflow dispatch can only do dry-run promotion;\n- non-dry-run promotion must be driven by a completed `Verify` workflow;\n- target branch protection details must be readable, and branch protection must\n  apply to administrators as well as regular contributors;\n- `alpha/vX/vX.Y` and `release/vX/vX.Y` branch protection must require both the\n  general `check` context and the Release Verify aggregate `verify` context, so\n  an invalid channel pair cannot merge even when repository checks pass;\n- release targets keep those checks non-strict with respect to source-branch\n  ancestry: generated channel bookkeeping intentionally makes the source and\n  target histories diverge, while the pair-specific `verify` context validates\n  the legal channel transition;\n- alpha promotion must come from a merged same-repository PR from\n  `dev/vX/vX.Y` to `alpha/vX/vX.Y`;\n- release promotion must come from a merged same-repository PR from\n  `alpha/vX/vX.Y` to `release/vX/vX.Y`;\n- major promotion must come from a merged same-repository PR from\n  `release/vX/vX.Y` to `publish-gate/major`;\n- release promotion requires an existing same-patch alpha tag and checks the\n  release source tree against that tested alpha tree;\n- generated version-state commits are verified before refs move.\n\n## Reconciling a protected line without rebuilding\n\nThe public `build.yml` channel router ends with a top-level job named\n`Summarize build contract`. Keeping this aggregate at the public router boundary\nprevents its required check context from changing when the internal reusable\nbuild workflow gains another nesting layer.\n\nFor an already-tested pull request whose protected target still requires an\nolder Buildchain aggregate context, inspect the exact candidate SHA first:\n\n```bash\nGH_TOKEN=\"$(gh auth token)\" npx @kungfu-tech/buildchain@latest \\\n  release-governance reconcile \\\n  --repository kungfu-systems/example \\\n  --branch release/v2/v2.14 \\\n  --candidate-sha <tested-pr-head-sha> \\\n  --json\n```\n\nThe dry run reads the successful checks emitted for that SHA and reports the\nexact expected/actual context pair. It chooses the shallowest successful\n`Summarize build contract` context, so a new top-level router aggregate wins\nover the nested internal build summary. To apply the plan, rerun the same\ncommand with `--apply` using a token that can update branch protection.\n\nReconciliation changes only the required-status-check subresource. It replaces\nstale Buildchain aggregate contexts, preserves unrelated checks and strictness,\nand does not modify review requirements, administrator enforcement,\nconversation resolution, force-push policy, or deletion policy. The candidate\nmust still be the head of a pull request targeting the named managed branch;\nthe command fails closed otherwise. This lets a previously successful candidate\ncontinue from the same SHA without another native build or an administrator\nmerge bypass.\n\nRepositories may also expose a small caller workflow around\n`.github/workflows/release-governance-reconcile.yml@v3`. Pass `branch`,\n`candidate-sha`, and `apply`, and provide `governance-token` through the caller's\nsecrets. The reusable workflow uploads the JSON reconciliation receipt.\n\nExact publication planning installs the checked-out promotion source's declared\ndependencies before version-state verification. This keeps the pre-authority\nversion plan on the same package-manager boundary as the later promotion job,\nincluding repositories whose verification commands import production packages.\nThe planning pass may materialize and verify declared derived files locally,\nbut dry-run never creates Git blobs, trees, commits, refs, or tags.\n\nPromotion intents are serialized globally per caller repository with\n`cancel-in-progress: false`. A queued intent re-reads its protected target ref\nbefore checkout, dependency installation, release-candidate resolution, or any\npublish-gate/ref mutation. If the ref already points at a newer SHA, that older\nintent is no longer release authority: the workflow records the requested and\ncurrent SHAs, proves that the current target is ahead of the requested commit,\nand completes as a `target-ref-advanced` superseded no-op. Diverged or behind\ncomparisons are not superseded transactions and still fail closed.\nMissing refs, unreadable repository state, invalid channels, governance\nfailures, and artifact mismatches still fail closed. The promote action repeats\nthe target check at the mutation boundary, so a ref that advances after the\nworkflow preflight cannot receive a second set of publication side effects.\n\n## Version Lines\n\nKungfu uses Python-like version lines where a minor line can represent a\nlong-lived product train. A line such as `v2.0` can produce many production\npatch releases:\n\n```text\nv2.0.0\nv2.0.1\nv2.0.2\n...\nv2.0.1234\n```\n\nThis is why Buildchain maintains both exact and floating refs:\n\n- `v2.0.2` is immutable release evidence;\n- `v2.0` is the latest production release on the `2.0` line;\n- `v2` is the selected stable major-line entrypoint;\n- `v2.0.3-alpha.0` is immutable alpha evidence;\n- `v2.0-alpha` is the latest test channel for the `2.0` line.\n- `v3-alpha` is the latest test channel on the highest published alpha minor in major `2`.\n\nA release does not mean \"minor is complete.\" It means \"this patch on this minor\nline is now production.\"\n\nGitHub repository rules must preserve that distinction. Exact tags such as\n`v2.0.2` and `v2.0.3-alpha.0` should be immutable. Floating channel tags such as\n`v2`, `v2.0`, `v2.0-alpha`, and `v3-alpha` must remain movable by the Buildchain promotion\ntoken after governance checks and publish evidence pass. A tag ruleset that\nprotects every `refs/tags/v*` ref is too broad because it also locks the\nfloating channel tags that Buildchain is required to update. Prefer exact-tag\npatterns such as `refs/tags/v*.*.*` for immutable release evidence, while\nleaving floating channel tags under Buildchain automation control.\n\n## Alpha Semantics\n\nAn alpha merge is:\n\n```text\ndev/vX/vX.Y -> alpha/vX/vX.Y\n```\n\nBuildchain then:\n\n1. Computes the next prerelease for the minor line.\n2. Writes version state such as `vX.Y.Z-alpha.N`.\n3. Verifies the generated version-state tree.\n4. Creates or reuses the exact alpha tag.\n5. Moves `alpha/vX/vX.Y` to the generated alpha commit.\n6. Moves `dev/vX/vX.Y` to the same generated alpha commit when this is a\n   fast-forward update.\n7. Moves `vX.Y-alpha` to the same generated alpha commit.\n8. Moves `vX-alpha` only when `X.Y` is the highest minor in major `X` with a published alpha; older minor alpha work records a skip and cannot move the major channel backwards.\n\nThe npm channel follows the same ownership rule. The highest alpha minor publishes\nwith dist-tag `alpha`; maintenance alphas on an older minor publish with the\nline-specific dist-tag `vX.Y-alpha` so they cannot roll the global `alpha`\nchannel backward. Exact prerelease versions remain installable directly.\n\nThis keeps the test channel self-describing. If a consumer checks out\n`v2.0-alpha` or `v3-alpha`, the manifests and exact alpha tag agree. The major\nalpha ref removes routine consumer edits when Buildchain opens a newer minor,\nwhile exact tags and SHAs remain the reproducible audit choice.\n\n### Buildchain Alpha Self-Dogfood\n\nBuildchain continuously consumes its own current major alpha through\n`.github/workflows/buildchain-alpha-self-dogfood.yml`. Both lanes call the\nreleased channel router at `build.yml@v3-alpha`. The auto lane must resolve\n`v3-alpha`; the explicit stable lane must resolve `v2`. Both execute the same\ndeclared install, build, and verify fixture, proving that a single consumer\nsurface routes to distinct released runtimes without duplicating lifecycle\nconfiguration in the consumer.\n\nBuildchain's generic artifact-signing contract seals source-, tree-, runtime-,\nplatform-, and digest-bound requests from ordinary credential-free build jobs.\nProvider-specific authority jobs consume only those sealed payloads. Apple\nDeveloper ID, Windows Authenticode, and detached cryptographic signatures share\nthe request/receipt model, while each profile retains its honest platform\nsemantics and fail-closed verification requirements.\n\nThe central `buildchain-artifact-signing` environment reuses the established\nmacOS Credential Island names (`BUILDCHAIN_MACOS_CERTIFICATE_*`,\n`BUILDCHAIN_MACOS_NOTARY_API_*`, and\n`BUILDCHAIN_MACOS_EXPECTED_TEAM_ID`). Those authority-only values are never\ndeclared by or forwarded through a consumer repository. Windows and detached\nproviders follow the same central-environment boundary.\n\nThe reusable build trust gate reads `job.workflow_ref`, which identifies the\ncalled workflow and its selected ref. It does not infer the runtime from\n`github.workflow_ref`, because GitHub defines that context as the caller\nworkflow identity during a reusable call.\n\nThe router selects `.buildchain/alpha-contract-lock.json` for alpha and\n`.buildchain/contract-lock.json` for stable. The alpha lock records the exact\nreviewed alpha SHA and compatibility digest; it does not replace the stable\nconsumer lock. A later alpha with only compatible additive drift continues,\nwhile a changed breaking digest fails until the new alpha contract is reviewed.\n\nThe evidence job resolves `v3-alpha` and `v2` through the GitHub refs API,\ncompares those immutable SHAs with the reusable workflow outputs, verifies the\n`alpha` and `stable` classifications, and uploads a JSON evidence artifact.\nThe canary runs after successful Buildchain ref promotion, on a daily fallback\nschedule, and on manual dispatch. It shares the release-promotion concurrency\ngroup, so another promotion cannot move the floating refs between runtime\nresolution and evidence comparison.\n\nThis is a post-publication consumer canary, not a release bootstrap. Source\nverification still runs the current commit, and\n`buildchain-ref-promotion.yml` still passes the verified exact SHA into the\npromotion workflow. Patrol, dev-merge, repair, and promotion defaults remain on\nstable or exact refs so a broken alpha cannot prevent Buildchain from publishing\nits fix. When Buildchain opens a new major, inventory validation requires this\nworkflow's fixed GitHub `uses` refs to move from `vN`/`vN-alpha` to the new\nmajor; GitHub does not allow expressions in a reusable-workflow `uses` ref.\n\nIf `dev/vX/vX.Y` has already advanced before generated alpha version-state\nbookkeeping can sync back, Buildchain records `skipped-non-fast-forward` for the\ndev sync and still completes the exact and floating alpha tags for the reviewed\nalpha commit. Later dev changes must go through their own dev-to-alpha\npromotion instead of rewinding dev. The normal path is direct: after alpha\nmerges, Buildchain applies the generated version-state commit to alpha and then\nfast-forwards dev to the same commit without a human version-state PR.\n\nIf alpha finalization is resumed after generated version-state bookkeeping was\npartially applied, Buildchain accepts the current alpha head as the generated\ncommit, or as a historical merge commit that contains the recorded release\nmaterial. An already-created exact alpha tag may point at the transaction\nrelease/material SHA or at the finalized alpha head; missing floating alpha\ntags are retried before the transaction becomes `complete`.\n\n## Release Semantics\n\nA release merge is:\n\n```text\nalpha/vX/vX.Y -> release/vX/vX.Y\n```\n\nBuildchain then:\n\n1. Finds the same-patch alpha tag that was tested.\n2. Checks that the release source tree matches that alpha tag tree, excluding\n   only generated version-state differences.\n3. Writes final release version state such as `vX.Y.Z`.\n4. Verifies the generated release tree.\n5. Creates or reuses the exact release tag `vX.Y.Z`.\n6. Moves `release/vX/vX.Y` to the exact release commit.\n7. Moves `vX.Y` to the exact release commit.\n8. Moves `vX` when this minor line should be the stable major entrypoint.\n9. Prepares the next alpha version-state commit, such as\n   `vX.Y.(Z+1)-alpha.0`.\n10. Moves `alpha/vX/vX.Y`, `dev/vX/vX.Y`, and `vX.Y-alpha` to that next alpha\n    commit.\n11. Moves `vX-alpha` to that next alpha only when this remains the highest published alpha minor.\n\nThe historical alpha tree comparison remains the default stable source gate.\nA promote-only stable run may accept a broader reviewed release PR only when\nthe downloaded RC passport proves that the PR's exact target tree is the tree\nthat completed the PR-stage build. Buildchain also requires the target commit\nto belong to a merged same-repository PR into the selected release branch and\nrecords the accepted commit, tree, RC source, alpha source, and PR as promotion\nevidence. A stale passport, a different target tree, a generated final release\ncommit, or an unreviewed target commit still falls through to the normal\nalpha-tree and declared version-state checks.\n\nThe production channel and the test channel therefore intentionally diverge\nafter release: production stays on the release commit, while alpha/dev continue\nat the next prerelease commit.\n\n### Stable Release Throttle And Canary Gate\n\nBuildchain's own stable channel has an additional pre-publication gate. It is\nevaluated after the PR-stage release candidate has been resolved and before the\npublish-gate ref, package registry, exact stable tag, or floating stable refs\nare mutated. Train refs and alpha promotion do not execute this gate.\n\nAll alpha and release promotions first run a metadata-only release-candidate\npreflight after queued-intent revalidation. The preflight uses the same resolver\nand exact target SHA as the publication job, but does not download payloads or\ninstall the candidate repository dependencies. Missing channel PRs, stale\nworkflow runs, expired passport pairs, and insufficient payload artifact sets\ntherefore fail before the full promotion job starts. The publication job still\ndownloads and validates the exact evidence again at the trust boundary; the\npreflight moves failure earlier without weakening the final check.\n\nThe policy is versioned in `.buildchain/stable-release-policy.json`. A stable\ncandidate is allowed only when all of these facts are true:\n\n- the candidate resolves to an immutable exact alpha tag and its GitHub\n  prerelease timestamp;\n- at least 24 hours have passed since the preceding stable patch on the same\n  minor line;\n- the preceding stable-to-alpha comparison contains a product or public\n  contract path, not only version, test, evidence, or retrospective changes;\n- the version-bound impact record has a non-empty summary and at least one\n  surface impact;\n- the `Build Surface Fixture` release-candidate run succeeded;\n- `site-libkungfu-dev` completed its no-apply `Buildchain Stable Canary` and an allowed\n  maintainer attested that successful run on the exact alpha SHA through the\n  `buildchain-canary/site-libkungfu-dev` commit-status context;\n- the canary runtime input is exactly the candidate alpha tag or the 40-character\n  commit SHA resolved from that tag; a successful status pointing at another\n  workflow, repository, tag, floating ref, or SHA is rejected as mismatched;\n- at least one hour has elapsed after the last required canary completed.\n\nThe machine report is written to\n`.buildchain/release-passport/stable-release-gate.json`. A passing report is\nuploaded with the stable release passport. A blocked run writes the same report\nbefore failing, so the missing or stale condition is inspectable without\nopening a publication transaction.\n\nGitHub's Actions run REST object does not expose `workflow_dispatch` inputs.\nBuildchain therefore verifies the run's `workflow_id` against the authoritative\nworkflow metadata, then reads the exact runtime from the workflow-owned\n`<workflow name> / <runtime ref>` run-name when no input field is available.\nAn explicit API input, when present, remains authoritative and cannot be\noverridden by the display name.\n\nThe cooldown is a minimum interval, not an instruction to release every day.\nCompatible work should still be batched until a stable release has a concrete\nconsumer need. Changing the interval, canary set, attestors, product path\nboundary, or soak time is a reviewed policy change.\n\nRepositories that want a predictable scheduled stable window can use\n[`Stable Candidate Patrol`](stable-candidate-patrol.md). It persists each exact\nalpha independently, qualifies it after repository-declared checks and soak,\nand selects the newest qualified non-revoked candidate. A newer soaking alpha\ndoes not invalidate an older qualified candidate. The selected tree enters the\nexisting strict `publish-gate/release/<line>/<version> -> release/<line>` PR\npath, so scheduled selection changes release intent timing without weakening\nsource locks, review, verification, publish transactions, or passports.\n\nIf release finalization is resumed after generated version-state bookkeeping was\npartially applied, Buildchain applies the same recovery rule: the current\nrelease head may be the generated commit, or a historical merge commit that\ncontains the recorded release material, existing exact tags and alpha/dev refs\nare accepted when they match the transaction, and missing floating `vX.Y` or\n`vX` tags are retried idempotently before completion.\n\nOnce the durable release transaction is `complete` and the exact/floating\nstable refs have moved, next-alpha preparation is post-release bookkeeping. A\nfailure there records `deferred-post-release-bookkeeping` and\n`next-anchor-required` instead of retroactively reporting the stable release as\nfailed. Generated next-alpha merges use the current dev tree as their base and\noverlay only declared version-state paths, preserving concurrent dev changes.\n\n## Major Gate Semantics\n\nA major gate merge is:\n\n```text\nrelease/vX/vX.Y -> publish-gate/major\n```\n\n`publish-gate/major` is the explicit replacement for the older ABV `main`\nchannel. The name is intentionally operational: it is a gate for a rare\nadministrator decision, not the active trunk. Keeping this decision in the same\nPR UI as alpha and release promotion keeps the human workflow simple while\navoiding the misleading meaning of `main`. The older `major-gate` branch name is\na compatibility alias only.\n\nBuildchain then:\n\n1. Verifies the source is a merged same-repository PR from a protected release\n   line into `publish-gate/major`.\n2. Writes the next major production version state, such as `v(X+1).0.0`.\n3. Creates or reuses the exact release tag `v(X+1).0.0`.\n4. Moves `publish-gate/major` and `release/v(X+1)/v(X+1).0` to that release commit.\n5. Moves `v(X+1).0` and `v(X+1)` to that release commit.\n6. Prepares the next alpha version-state commit, such as\n   `v(X+1).0.1-alpha.0`.\n7. Moves `alpha/v(X+1)/v(X+1).0`, `dev/v(X+1)/v(X+1).0`, and\n   `v(X+1).0-alpha` to that next alpha commit.\n\nChecking out `publish-gate/major` should therefore look like a frozen release\nstate, not like a branch where day-to-day source work continues. Day-to-day\nsource work continues on `dev/vX/vX.Y`.\n\n## Protected Dev Branches\n\n`dev/vX/vX.Y` is a protected development channel, not a scratch branch. Normal\nsource changes should be made on work branches such as `feature/*`, `fix/*`,\n`chore/*`, `docs/*`, `ci/*`, or `refactor/*`, then reviewed through a pull\nrequest into the target dev line.\n\nThis keeps the earliest development channel audit-friendly:\n\n- the version line being changed is visible in the PR base branch;\n- CI and required checks run before the channel moves;\n- branch protection can prevent direct pushes and stale merges;\n- later `dev -> alpha -> release` promotion inherits a reviewable source\n  lineage instead of trying to reconstruct how the dev branch changed.\n\nWhen required checks take longer than the normal dev-channel commit interval,\nclassic strict up-to-date protection can become a non-converging retry loop:\neach base update invalidates a completed check set and rebasing restarts the\nsame slow checks. Buildchain supports GitHub merge queues for that channel\nshape. The queue validates the projected merged result and serializes the final\nref update, so concurrent channel movement no longer invalidates the candidate.\n\nEvery required workflow must handle both `pull_request` and `merge_group`\nbefore the queue is enabled. Queue runs do not provide\n`github.event.pull_request`; required workflows must use the checked-out\n`github.sha` or event-neutral source facts. The governance command is dry-run by\ndefault and refuses to enable a queue when a declared required workflow lacks\neither trigger or still reads the pull-request-only payload directly:\n\n```bash\nbuildchain dev merge-queue \\\n  --repository owner/repository \\\n  --branch dev/v4/v4.0 \\\n  --workflow .github/workflows/source-acceptance.yml \\\n  --workflow .github/workflows/affected-native-pr.yml \\\n  --bypass-app dedicated-release-app\n```\n\nAfter reviewing the plan, repeat with `--apply`. Buildchain creates or updates\nan exact-branch `merge_queue` ruleset first, then changes only the classic\nrequired-status-check policy from strict to loose. Reviews, administrator\nenforcement, conversation resolution, required check identities, force-push\nprotection, and deletion protection remain owned by the existing branch\nprotection. The ruleset uses the first merge method that the repository itself\nallows, and fails closed when the repository has no enabled merge method.\nRe-running the command is idempotent.\n\nThe repository policy can be declared once instead of repeated as CLI flags:\n\n```toml\n[governance.dev.merge_queue]\nmode = \"inherit\"\nrequired_workflows = [\".github/workflows/verify.yml\"]\n```\n\n`enabled` explicitly requires Buildchain to create or update an exact-branch\nqueue; `inherit` copies queue parameters and bypass actors from the repository's\ncurrent default dev branch; `disabled` prevents automatic queue creation. An\nabsent declaration behaves as `inherit` during release-line bootstrap so a new\nmajor or minor line does not silently lose governance already active on the\nprevious line. Required status-check identities still come from the new\nbranch's own classic protection rather than being copied from the old branch.\n\nMerge-queue rules also reject generated post-publish version-state ref updates.\nWhen the sealed promotion workflow uses a dedicated GitHub App, user, or team\nalready declared by release governance, repeat `--bypass-app`, `--bypass-user`,\nor `--bypass-team` to project that exact actor into the ruleset. Bypass actors\nare never inferred and broad repository or organization roles are not accepted.\nThis keeps ordinary feature PRs on the predecessor-aligned queue path while the\nsealed publication authority can finish its machine-verified bookkeeping. The\ndry-run receipt exposes the exact actor IDs before `--apply` changes GitHub.\n\nBuildchain provides the reusable\n`.github/workflows/dev-pr-auto-merge.yml` workflow for repositories that want a\nscheduled or manual \"merge ready dev PRs\" pass. The consumer repository owns\nthe trigger schedule, but the merge decision is declared through workflow\ninputs: target dev branch, required status/check names, ready and block labels,\nallowed work-branch prefixes, review requirements, maximum merges per run,\nmerge method, and dry-run mode.\n\nThe workflow defaults are conservative. A PR is skipped unless it targets the\nconfigured dev line, is not a draft, has the ready label, has no block label,\ncomes from the same repository, uses an allowed work-branch prefix, has a\ncurrent approval, is mergeable, and has the configured required checks passing.\n`landing-mode: auto` reads the target branch's native merge-queue state. When a\nqueue exists, Buildchain never calls the direct merge endpoint: it admits at\nmost one PR against the observed target-branch SHA and immutable PR head, then\ncalls GraphQL `enqueuePullRequest` with `expectedHeadOid`. GitHub's\n`merge_group` checks remain the final authority for the projected merge.\n\nThe admission receipt records the expected and observed base/head SHAs, policy\nchecks, decision, reason, and active predecessor. Buildchain re-reads the base,\nhead, mergeability, and native queue immediately before enqueueing. Base or\nhead drift fails closed, an active queue entry blocks admission, and a rejected\nready predecessor leaves its PR open while later PRs receive\n`blocked-by-predecessor`. Workflow concurrency serializes Buildchain-owned\nadmission runs; GitHub still owns the atomic queue and protected-ref update.\nRepositories may explicitly select `landing-mode: direct` only when the target\nbranch has no native queue. Queue presence always disables the direct path.\n\nThe canonical consumer required check context is `check / check`, matching the\nreusable workflow call plus its `check` job. Buildchain's own `Verify` workflow\nemits the repository-local context `check`, so Buildchain self-promotion,\nrelease-line bootstrap, and dogfood patrol wrappers pass `check` explicitly.\nRelease governance preserves the exact context emitted by the repository and\nrecords branch-protection policy before/after facts; it does not rewrite one\ncontext shape into the other. Consumer repositories can keep their context\nstable while changing the actual verification command declaratively in\n`buildchain.toml`:\n\n```toml\n[lifecycle.install]\ncommand = \"cargo fetch --locked\"\n\n[lifecycle.verify]\ncommand = \"cargo test --workspace --locked\"\n```\n\nConsumers that want Buildchain to own the check wrapper can call\n`.github/workflows/check.yml@v3`. The wrapper runs the declared\n`lifecycle.install` and `lifecycle.verify` stages and fails the `check` job when\neither declaration is missing or the command exits non-zero.\n\nDevelopment pull requests that need source acceptance without product build or\nartifact verification can opt into `mode: source`. That mode runs only\n`lifecycle.install` and `lifecycle.check` on GitHub-hosted `ubuntu-24.04` while\npreserving the stable `check / check` required-check context. Existing callers\nremain on `mode: verify` by default, and callers may set\n`upload-artifacts: false` without weakening the job conclusion.\n\nTypical consumer wrapper:\n\n```yaml\nname: Merge Ready Dev PRs\n\non:\n  schedule:\n    - cron: \"17 * * * *\"\n  workflow_dispatch:\n    inputs:\n      dry-run:\n        type: boolean\n        default: true\n\njobs:\n  merge-dev:\n    uses: kungfu-systems/buildchain/.github/workflows/dev-pr-auto-merge.yml@v3\n    permissions:\n      contents: write\n      pull-requests: write\n      checks: read\n      statuses: read\n    with:\n      target-branch: dev/v2/v2.6\n      required-status-checks: check / check\n      ready-label: ready\n      block-labels: blocked,do-not-merge\n      max-merges: 1\n      landing-mode: auto\n      dry-run: ${{ inputs.dry-run || false }}\n```\n\n## Buildchain Patrol\n\n`dev-pr-auto-merge.yml` remains the focused merge primitive. For repositories\nthat want a stable day-to-day operations contract, Buildchain also exposes a\npatrol workflow family:\n\n| Workflow | Intended cadence | Default intent |\n| --- | --- | --- |\n| `.github/workflows/patrol-daily.yml` | daily | lightweight inspection plus ready dev PR maintenance |\n| `.github/workflows/patrol-weekly.yml` | weekly | release-state, passport, gate, and stale-state health checks as they are added |\n| `.github/workflows/patrol-monthly.yml` | monthly | governance, permission, branch-protection, and workflow drift checks as they are added |\n| `.github/workflows/patrol-observed-evidence.yml` | caller-selected schedule | validated immutable observation plus atomic last-known-good publication; no per-refresh PR |\n| `.github/workflows/stable-candidate-patrol.yml` | repository-selected release window | qualify immutable alpha candidates and open the exact source-lock stable PR |\n\nThe cadence names describe patrol intensity, not release cadence:\n\n- daily patrol can run every day without implying a daily release;\n- weekly patrol is for medium-cost maintenance and audit checks;\n- monthly patrol is for structural drift checks that should not block ordinary\n  development velocity.\n\nStable Candidate Patrol is separate from those maintenance cadences because its\ncaller-owned cron is a release-intent window. Its candidate ledger and selection\nremain generic; registry-specific side effects still run through the normal\nrepository `lifecycle.publish` transaction. See\n[`stable-candidate-patrol.md`](stable-candidate-patrol.md).\n\nObserved data that is mechanically regenerated and path-scoped uses the\nseparate [`Observed Evidence Patrol`](observed-evidence-patrol.md) contract.\nIts one-time mechanism changes remain reviewed, while steady-state snapshot\nrefreshes publish directly from trusted default-branch schedule/manual callers.\n\nConsumers should schedule thin callers and keep their YAML declarative. For\nexample:\n\n```yaml\nname: Buildchain Daily Patrol\n\non:\n  schedule:\n    - cron: \"17 2 * * *\"\n  workflow_dispatch:\n\njobs:\n  patrol:\n    uses: kungfu-systems/buildchain/.github/workflows/patrol-daily.yml@v3\n    with:\n      dry-run: false\n      max-actions: 1\n```\n\nWeekly and monthly callers use the matching wrapper:\n\n```yaml\njobs:\n  patrol:\n    uses: kungfu-systems/buildchain/.github/workflows/patrol-weekly.yml@v3\n    with:\n      dry-run: true\n```\n\nAll three wrappers default to the `v2` floating Buildchain runtime. When\n`target-branch` is omitted, the caller's current/default branch selects the\nactive semver dev line, so consumers do not pin patrol to a stale minor branch.\nThe separate workflow names keep consumer schedules readable and stable while\nBuildchain adds new checks behind the cadence wrappers.\n\n## Package-Manager Adapters\n\nOld ABV assumed JavaScript repositories with root version state and often\nLerna. Buildchain keeps the version-state contract but does not assume every\nrepository is yarn/Lerna.\n\nThe promotion action discovers and updates:\n\n- root `package.json`;\n- `lerna.json`;\n- package manifests from `package.json` workspaces;\n- package manifests from `lerna.json` packages;\n- package manifests from `pnpm-workspace.yaml`.\n\nIt then runs the repository's detected package manager semantics where needed:\n\n- pnpm repositories use pnpm-oriented workspace discovery;\n- npm repositories use npm/package-lock semantics where present;\n- yarn repositories use yarn-style metadata where present.\n\nFor Buildchain itself, version state is required. For a consumer repository that\nhas no package manifest, the same action can degrade to ref-only behavior only\nwhen that is explicitly allowed by the caller.\n\n## Lifecycle Configuration\n\n`buildchain.toml` is the v2 user configuration format. It lets a repository\ndeclare version-state files and lifecycle commands without pretending every\nproject is a Node workspace. Supported version files include JSON, TOML, and\nregex-based files such as `CMakeLists.txt` or `conanfile.py`.\n\nThe promotion action consumes `version.files`, optional anchored/manual\n`version.derived_files`, and `lifecycle.verify`.\nThe verify stage runs after generated version-state changes are applied locally\nand before any release refs move. If `verification-command` is passed directly\nto the action, that explicit command overrides `lifecycle.verify`.\n\nAnchored/manual repositories may use `version.derived_files` for committed\nversion witnesses that are regenerated by `lifecycle.version-state`. The\nrelease-candidate build verifies those witnesses before heavy builds and records\ntheir digests with the exact alpha and release tree identities. Promotion then\naccepts only declared version files, the anchor manifest, and those derived\nfiles as differences from the tested alpha tree; release passports preserve the\nsame material binding.\n\nProtected release-line branches keep their normal human review gate. Managed\n`dev/vN/vN.M`, `alpha/vN/vN.M`, and `release/vN/vN.M` branches are configured\nwith one required approving review, required GitHub Actions checks, administrator\nenforcement, conversation resolution, no force pushes, and no deletions. Each\ntarget uses the exact check set, GitHub App identity, and strictness declared by\nthe governance authority descriptor. The\nreusable `release-candidate-promote.yml` wrapper defaults\n`branch-protection-bypass-apps` to `github-actions`, which lets the workflow's\nautomation identity apply generated version-state or post-publish channel\nbookkeeping after the reviewed channel PR has merged. Direct\n`promote-buildchain-ref` callers may opt into that one controlled bypass with\n`branch-protection-bypass-apps: github-actions`; every other App slug and all\nuser or team bypass actors are rejected. Before\npatching a protected generated bookkeeping ref, the action creates the\nfull configured required-check set on the exact generated version-state commit, so strict\nstatus checks are satisfied by machine-verifiable Buildchain evidence rather\nthan a human PR. The protected ref PATCH itself uses the generated ref update\ntoken; the reusable wrapper binds it to the run-scoped `github.token`. If direct generated\nrelease finalization bookkeeping is still rejected, Buildchain creates or\nreuses a same-repository `buildchain/version-state/*` PR and records\n`finalization-needed=true` in the durable transaction output. Strict alpha\nfollows the same provider-enforced PR path for its alpha and dev bookkeeping.\nThe PR remains subject to the declared review, required checks, and merge-queue\npolicy; publication resumes idempotently after that protected transaction\nlands.\n\nFor a stable release, the wrapper also checks out the exact current development\nchannel into `.buildchain/reconciliation/dev`. When the prepared next-alpha\ncommit cannot fast-forward dev because reviewed work landed concurrently, the\npromotion action applies the next version to that checkout, regenerates every\ndeclared derived version-state file, reruns the verification lifecycle, and\nonly then creates the two-parent reconciliation commit. A checkout/current-ref\nSHA mismatch blocks reconciliation instead of committing stale projections.\nBuildchain's own promotion workflow accepts only\n`BUILDCHAIN_PROMOTION_BYPASS_APPS=github-actions`, defaulting to that exact App\nwhen the variable is absent. Buildchain's release-line bootstrap uses the\nadministrator-scoped promotion token only to configure protection; branch\ncreation and generated ref updates use the run-scoped token. New channel\nprotection binds required checks to GitHub Actions App id `15368`, enables Code\nOwner, stale-review, and latest-push review gates, and admits no user or team\nbypass actor.\n\n## What This Guarantees\n\nWhen the loop succeeds, maintainers and consumers can rely on these facts:\n\n- every production release has an exact tag such as `v2.0.2`;\n- every production minor line has a floating tag such as `v2.0`;\n- every selected stable major has a floating tag such as `v2`;\n- every next-major release is driven by a reviewed `release -> publish-gate/major` PR,\n  not a hidden manual button;\n- every test channel has an exact alpha tag such as `v2.0.3-alpha.0`;\n- every alpha minor line has a floating tag such as `v2.0-alpha`;\n- every major with a published alpha has a cross-minor floating tag such as `v3-alpha`, owned by its highest published alpha minor;\n- version manifests match the tag visible from the same commit;\n- production releases are derived from the alpha tree that was tested;\n- manual non-dry-run promotion cannot bypass PR review and verification;\n- flow-internal automation bypasses apply only to declared GitHub Apps, users,\n  or teams on Buildchain-managed channel branch protection, while one-review\n  protection remains enforced for humans;\n- admin users cannot make a channel promotion valid by temporarily bypassing\n  branch protection.\n\nThis is the practical meaning of \"governance closed loop\" in Buildchain: the\ndecision, code, version state, and Git refs close over the same evidence chain.\n\n## What This Does Not Do\n\nBuildchain release promotion does not embed registry clients or product-specific\npublish logic. When publish transactions are enabled, `promote-buildchain-ref`\ncan run the consumer's `lifecycle.publish` command and own the transaction,\nevidence validation, durable recovery state, and ref finalization order. The\nconsumer repository still owns registry truth: npm, PyPI, OCI, S3, Conan, CMake\npackaging, download pages, dist-tags, and similar side effects must be\nimplemented by project lifecycle commands that emit Buildchain publish evidence.\n\nDurable transaction recovery is also bound to the exact publication version\nplanned for the current run. An unfinished transaction may be resumed from the\ncurrent source or its history only when its recorded version matches that plan;\nan older failed transaction that happens to be an ancestor cannot reserve its\nold exact tag for a newer package publication.\n\nThe exact tag is also part of the durable transaction identity. If an anchored\npackage publication completed registry side effects under a stale internal tag\nselection, a retry may rebind the unfinished `published` or `finalizing`\ntransaction to the newly planned internal tag only when the package version,\nsource, release material, target, complete artifact set, and evidence all still\nmatch; the stale tag must not point at the transaction, and the requested tag\nmust be absent or already point at accepted release material. This preserves an\nimmutable tag that represents a completed transaction while allowing a tag\ncollision discovered after registry publication to recover without republishing.\n\nEvery Buildchain publish model that can run registry side effects must bind the\npublish entrypoint to an immutable `publish-gate/*` source lock. The reusable\n`release-candidate-promote.yml@v3` wrapper creates or updates that gate ref and\npasses `require-publish-source-lock`, `publish-source-ref`,\n`publish-source-sha`, and `publish-source-locked` to\n`promote-buildchain-ref`. Direct action callers must pass the same four inputs\nfrom the reusable build outputs. Workflows that only collect passports or run\ndry-run package checks do not move publish refs and are not publish-gate\npublication models. A dry-run of `release-candidate-promote.yml` computes and\nreports the exact `publish-gate/*` source lock that a real promotion would use,\nbut does not read, create, or move that ref.\n\nSemver GitHub Release publication is owned by `promote-buildchain-ref`, not by\nconsumer shell glue. Consumers normally use the `release-candidate-promote.yml`\ngenerated channel router, where GitHub Release publication is enabled by default and can be\ndisabled with `github-release: false`; the wrapper passes that declaration to\nthe action. After the publish transaction reaches `complete`, Buildchain creates\nor updates the public GitHub Release and uploads the generated\n`buildchain.release.json`, release-passport assets, and publish evidence. The\nauthoritative publication channel controls GitHub metadata: alpha is marked\n`prerelease=true` and `make_latest=false`; release/stable/major is marked latest.\nSemver tag syntax remains the fallback for ordinary callers without explicit\npublication intent. For anchored/manual package releases, the public\nrelease tag defaults to `v<publishedVersion>` while the internal exact\ntransaction tag remains in the release passport and release-state ref. This is\nthe supported path for downstream\n`release.published` propagation across semver, major, and promote-only release\ncandidate publication models.\n\nPublished GitHub Release assets are immutable evidence. A repeated promotion\npreserves an existing asset when its SHA-256 digest matches the regenerated\nbytes, uploads only missing assets, and fails with an immutable-release\ncollision when a same-name asset has different bytes. It never deletes and\nreplaces an existing asset during retry or duplicate workflow delivery.\n\nProduct payloads are included only through the explicit\n`github-release-payload-patterns` input. Patterns match basenames inside the\ndownloaded PR-stage RC payload bundle; zero matches or duplicate public\nbasenames fail closed. This preserves the exact PR-built bytes instead of\nrebuilding archives during promotion.\n\nConsumers with a signed well-known discovery document can additionally provide\n`publication-commit-command`. The advanced promotion workflow validates its\ntopology before any publish-gate or release mutation, then runs it only after\nthe GitHub Release and its immutable payload/passport assets exist. The command\nmust publicly read back the exact new payload root and emit\n`kungfu-buildchain-publication-commit-evidence/v1`; that evidence is copied\ninto the controller artifact and exposed as workflow outputs. The previous\nauthority must remain valid on every failure. Deferred standalone binary\ndistribution is incompatible with this mode because the discovery authority\nmust be the final product mutation.\n\nBuildchain also does not maintain bare exact tags such as `1.0.0`. The supported\nexact release and alpha refs are v-prefixed:\n\n```text\nv2.0.0\nv2.0.1-alpha.0\n```\n\n## Operational Reading Order\n\nWhen debugging or extending release behavior, read in this order:\n\n1. `docs/release-flow.md`\n2. `.github/workflows/release-verify.yml`\n3. `.github/workflows/buildchain-ref-promotion.yml`\n4. `.github/workflows/release-candidate-promote.yml`\n5. `.github/workflows/.release-candidate-promote.yml`\n6. `actions/promote-buildchain-ref/README.md`\n7. `actions/promote-buildchain-ref/src/`\n8. `docs/migration-inventory.md`\n\nThat path gives the policy first, the workflow trigger second, and the action\nimplementation last."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-release-governance\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-27\n  invisible_context: not asserted\n---\n\n# Release Governance\n\nBuildchain v3 preserves the release semantics of the older ABV workflow while\nmoving the implementation into one modern repository.\n\nThe central idea is simple: a reviewed merge into a release channel is the\nrelease intent. Automation must then create the version-state commit, exact tag,\nfloating tag, and next alpha state that make that intent true in Git.\n\n## Design Problem\n\nKungfu release automation has to keep four facts aligned:\n\n1. The source tree that was reviewed.\n2. The package version recorded in manifests such as `package.json` or\n   `lerna.json`.\n3. The exact immutable release or prerelease tag.\n4. The floating channel refs that consumers actually use.\n\nIf any one of these facts is updated by hand, the system can split:\n\n- a consumer can fetch `v3.0` and receive a tree whose package version still\n  says the previous release;\n- a maintainer can move `v3` without producing an exact `v3.0.N` audit tag;\n- an alpha can be promoted to production even though the release tree is not the\n  same tree that was tested;\n- a protected branch merge can succeed while the follow-up version commit is\n  missing, or a flow-internal generated `dev`/`alpha`/`release` ref update can\n  fail after publish because the automation identity was not declared in the\n  branch-protection review bypass allowance.\n\nThe older ABV workflow addressed this by letting GitHub PRs drive release\nstate. Buildchain keeps that choice because it makes release intent reviewable,\nobservable, and recoverable from Git history.\n\n## What ABV Contributed\n\nThe old ABV model was not just \"bump a version number.\" It encoded a governance\nloop:\n\n- release branches are named as channels: `dev`, `alpha`, `release`, and the\n  administrative `publish-gate/major`;\n- a PR from one channel to the next is the release request;\n- verify jobs check that the branch pair is valid before merge;\n- a maintainer review is required before the branch moves;\n- after merge, automation writes the version change and moves tags;\n- exact tags and floating refs are aligned with the resulting commit;\n- the next development channel is prepared automatically.\n\nABV also kept the version-state mutation in the repository. For JavaScript\nrepositories that usually meant changing `lerna.json` and/or `package.json`.\nThat commit is important because the tag alone is not enough evidence: the\nsource tree should also declare the version that the tag advertises.\n\nBuildchain v3 treats that as a hard semantic requirement for its own release\nline.\n\n## Buildchain Implementation\n\nBuildchain implements the same governance loop with:\n\n- `.github/workflows/release-verify.yml` for PR verification;\n- `.github/workflows/buildchain-ref-promotion.yml` for post-verify ref\n  promotion; this workflow dogfoods the declarative\n  `release-candidate-promote.yml` wrapper and does not hand-wire resolver,\n  artifact download, publish-gate, or promote action steps;\n- Buildchain self promotion enables `release-passport-buildchain-self-kfd`, so\n  the promote action generates KFD-1 witnesses, KFD-2 public claim JSON, and\n  KFD-3 collaboration-interface witnesses from the final version-state workspace\n  before release passport finalization. The witness hashes therefore bind to the\n  exact published package and site facts from\n  `packages/core/buildchain-kfd-claims.js` instead of relying on prose release\n  notes;\n- `actions/promote-buildchain-ref` for branch, tag, version-state, and\n  governance checks;\n- package-manager adapters that can update version state for pnpm, npm, and\n  yarn style repositories;\n- `buildchain.toml` lifecycle configuration for repositories whose version\n  state or verification commands are not Node package-manager defaults.\n\nThe implementation is intentionally stricter than a local release script:\n\n- manual workflow dispatch can only do dry-run promotion;\n- non-dry-run promotion must be driven by a completed `Verify` workflow;\n- target branch protection details must be readable, and branch protection must\n  apply to administrators as well as regular contributors;\n- `alpha/vX/vX.Y` and `release/vX/vX.Y` branch protection must require both the\n  general `check` context and the Release Verify aggregate `verify` context, so\n  an invalid channel pair cannot merge even when repository checks pass;\n- release targets keep those checks non-strict with respect to source-branch\n  ancestry: generated channel bookkeeping intentionally makes the source and\n  target histories diverge, while the pair-specific `verify` context validates\n  the legal channel transition;\n- alpha promotion must come from a merged same-repository PR from\n  `dev/vX/vX.Y` to `alpha/vX/vX.Y`;\n- release promotion must come from a merged same-repository PR from\n  `alpha/vX/vX.Y` to `release/vX/vX.Y`;\n- major promotion must come from a merged same-repository PR from\n  `release/vX/vX.Y` to `publish-gate/major`;\n- release promotion requires an existing same-patch alpha tag and checks the\n  release source tree against that tested alpha tree;\n- generated version-state commits are verified before refs move.\n\n## Reconciling a protected line without rebuilding\n\nThe public `build.yml` channel router ends with a top-level job named\n`Summarize build contract`. Keeping this aggregate at the public router boundary\nprevents its required check context from changing when the internal reusable\nbuild workflow gains another nesting layer.\n\nFor an already-tested pull request whose protected target still requires an\nolder Buildchain aggregate context, inspect the exact candidate SHA first:\n\n```bash\nGH_TOKEN=\"$(gh auth token)\" npx @kungfu-tech/buildchain@latest \\\n  release-governance reconcile \\\n  --repository kungfu-systems/example \\\n  --branch release/v3/v3.0 \\\n  --candidate-sha <tested-pr-head-sha> \\\n  --json\n```\n\nThe dry run reads the successful checks emitted for that SHA and reports the\nexact expected/actual context pair. It chooses the shallowest successful\n`Summarize build contract` context, so a new top-level router aggregate wins\nover the nested internal build summary. To apply the plan, rerun the same\ncommand with `--apply` using a token that can update branch protection.\n\nReconciliation changes only the required-status-check subresource. It replaces\nstale Buildchain aggregate contexts, preserves unrelated checks and strictness,\nand does not modify review requirements, administrator enforcement,\nconversation resolution, force-push policy, or deletion policy. The candidate\nmust still be the head of a pull request targeting the named managed branch;\nthe command fails closed otherwise. This lets a previously successful candidate\ncontinue from the same SHA without another native build or an administrator\nmerge bypass.\n\nRepositories may also expose a small caller workflow around\n`.github/workflows/release-governance-reconcile.yml@v3`. Pass `branch`,\n`candidate-sha`, and `apply`, and provide `governance-token` through the caller's\nsecrets. The reusable workflow uploads the JSON reconciliation receipt.\n\nExact publication planning installs the checked-out promotion source's declared\ndependencies before version-state verification. This keeps the pre-authority\nversion plan on the same package-manager boundary as the later promotion job,\nincluding repositories whose verification commands import production packages.\nThe planning pass may materialize and verify declared derived files locally,\nbut dry-run never creates Git blobs, trees, commits, refs, or tags.\n\nPromotion intents are serialized globally per caller repository with\n`cancel-in-progress: false`. A queued intent re-reads its protected target ref\nbefore checkout, dependency installation, release-candidate resolution, or any\npublish-gate/ref mutation. If the ref already points at a newer SHA, that older\nintent is no longer release authority: the workflow records the requested and\ncurrent SHAs, proves that the current target is ahead of the requested commit,\nand completes as a `target-ref-advanced` superseded no-op. Diverged or behind\ncomparisons are not superseded transactions and still fail closed.\nMissing refs, unreadable repository state, invalid channels, governance\nfailures, and artifact mismatches still fail closed. The promote action repeats\nthe target check at the mutation boundary, so a ref that advances after the\nworkflow preflight cannot receive a second set of publication side effects.\n\n## Version Lines\n\nKungfu uses Python-like version lines where a minor line can represent a\nlong-lived product train. A line such as `v3.0` can produce many production\npatch releases:\n\n```text\nv3.0.0\nv3.0.1\nv3.0.2\n...\nv3.0.1234\n```\n\nThis is why Buildchain maintains both exact and floating refs:\n\n- `v3.0.2` is immutable release evidence;\n- `v3.0` is the latest production release on the `3.0` line;\n- `v3` is the selected stable major-line entrypoint;\n- `v3.0.3-alpha.0` is immutable alpha evidence;\n- `v3.0-alpha` is the latest test channel for the `3.0` line.\n- `v3-alpha` is the latest test channel on the highest published alpha minor in major `3`.\n\nA release does not mean \"minor is complete.\" It means \"this patch on this minor\nline is now production.\"\n\nGitHub repository rules must preserve that distinction. Exact tags such as\n`v3.0.2` and `v3.0.3-alpha.0` should be immutable. Floating channel tags such as\n`v3`, `v3.0`, `v3.0-alpha`, and `v3-alpha` must remain movable by the Buildchain promotion\ntoken after governance checks and publish evidence pass. A tag ruleset that\nprotects every `refs/tags/v*` ref is too broad because it also locks the\nfloating channel tags that Buildchain is required to update. Prefer exact-tag\npatterns such as `refs/tags/v*.*.*` for immutable release evidence, while\nleaving floating channel tags under Buildchain automation control.\n\n## Alpha Semantics\n\nAn alpha merge is:\n\n```text\ndev/vX/vX.Y -> alpha/vX/vX.Y\n```\n\nBuildchain then:\n\n1. Computes the next prerelease for the minor line.\n2. Writes version state such as `vX.Y.Z-alpha.N`.\n3. Verifies the generated version-state tree.\n4. Creates or reuses the exact alpha tag.\n5. Moves `alpha/vX/vX.Y` to the generated alpha commit.\n6. Moves `dev/vX/vX.Y` to the same generated alpha commit when this is a\n   fast-forward update.\n7. Moves `vX.Y-alpha` to the same generated alpha commit.\n8. Moves `vX-alpha` only when `X.Y` is the highest minor in major `X` with a published alpha; older minor alpha work records a skip and cannot move the major channel backwards.\n\nThe npm channel follows the same ownership rule. The highest alpha minor publishes\nwith dist-tag `alpha`; maintenance alphas on an older minor publish with the\nline-specific dist-tag `vX.Y-alpha` so they cannot roll the global `alpha`\nchannel backward. Exact prerelease versions remain installable directly.\n\nThis keeps the test channel self-describing. If a consumer checks out\n`v3.0-alpha` or `v3-alpha`, the manifests and exact alpha tag agree. The major\nalpha ref removes routine consumer edits when Buildchain opens a newer minor,\nwhile exact tags and SHAs remain the reproducible audit choice.\n\n### Buildchain Alpha Self-Dogfood\n\nBuildchain continuously consumes its own current major alpha through\n`.github/workflows/buildchain-alpha-self-dogfood.yml`. Both lanes call the\nreleased channel router at `build.yml@v3-alpha`. The auto lane must resolve\n`v3-alpha`; the explicit stable lane must resolve `v3`. Both execute the same\ndeclared install, build, and verify fixture, proving that a single consumer\nsurface routes to distinct released runtimes without duplicating lifecycle\nconfiguration in the consumer.\n\nBuildchain's generic artifact-signing contract seals source-, tree-, runtime-,\nplatform-, and digest-bound requests from ordinary credential-free build jobs.\nProvider-specific authority jobs consume only those sealed payloads. Apple\nDeveloper ID, Windows Authenticode, and detached cryptographic signatures share\nthe request/receipt model, while each profile retains its honest platform\nsemantics and fail-closed verification requirements.\n\nThe authority verifies the complete result set on GitHub-hosted infrastructure\nbefore delivery. The consumer controller also performs final result verification,\nexact-byte import, manifest recomputation, and deterministic-artifact replacement\non a GitHub-hosted lane. Self-hosted build runners do not download authority\nresult payloads, and aggregate/release evidence fails closed until this\nfinalization succeeds.\n\nThe central `buildchain-artifact-signing` environment reuses the established\nmacOS Credential Island names (`BUILDCHAIN_MACOS_CERTIFICATE_*`,\n`BUILDCHAIN_MACOS_NOTARY_API_*`, and\n`BUILDCHAIN_MACOS_EXPECTED_TEAM_ID`). Those authority-only values are never\ndeclared by or forwarded through a consumer repository. Windows and detached\nproviders follow the same central-environment boundary.\n\nThe reusable build trust gate reads `job.workflow_ref`, which identifies the\ncalled workflow and its selected ref. It does not infer the runtime from\n`github.workflow_ref`, because GitHub defines that context as the caller\nworkflow identity during a reusable call.\n\nThe router selects `.buildchain/alpha-contract-lock.json` for alpha and\n`.buildchain/contract-lock.json` for stable. The alpha lock records the exact\nreviewed alpha SHA and compatibility digest; it does not replace the stable\nconsumer lock. A later alpha with only compatible additive drift continues,\nwhile a changed breaking digest fails until the new alpha contract is reviewed.\n\nThe evidence job resolves `v3-alpha` and `v3` through the GitHub refs API,\ncompares those immutable SHAs with the reusable workflow outputs, verifies the\n`alpha` and `stable` classifications, and uploads a JSON evidence artifact.\nThe canary runs after successful Buildchain ref promotion, on a daily fallback\nschedule, and on manual dispatch. It shares the release-promotion concurrency\ngroup, so another promotion cannot move the floating refs between runtime\nresolution and evidence comparison.\n\nThis is a post-publication consumer canary, not a release bootstrap. Source\nverification still runs the current commit, and\n`buildchain-ref-promotion.yml` still passes the verified exact SHA into the\npromotion workflow. Patrol, dev-merge, repair, and promotion defaults remain on\nstable or exact refs so a broken alpha cannot prevent Buildchain from publishing\nits fix. When Buildchain opens a new major, inventory validation requires this\nworkflow's fixed GitHub `uses` refs to move from `vN`/`vN-alpha` to the new\nmajor; GitHub does not allow expressions in a reusable-workflow `uses` ref.\n\nIf `dev/vX/vX.Y` has already advanced before generated alpha version-state\nbookkeeping can sync back, Buildchain records `skipped-non-fast-forward` for the\ndev sync and still completes the exact and floating alpha tags for the reviewed\nalpha commit. Later dev changes must go through their own dev-to-alpha\npromotion instead of rewinding dev. The normal path is direct: after alpha\nmerges, Buildchain applies the generated version-state commit to alpha and then\nfast-forwards dev to the same commit without a human version-state PR.\n\nIf alpha finalization is resumed after generated version-state bookkeeping was\npartially applied, Buildchain accepts the current alpha head as the generated\ncommit, or as a historical merge commit that contains the recorded release\nmaterial. An already-created exact alpha tag may point at the transaction\nrelease/material SHA or at the finalized alpha head; missing floating alpha\ntags are retried before the transaction becomes `complete`.\n\n## Release Semantics\n\nA release merge is:\n\n```text\nalpha/vX/vX.Y -> release/vX/vX.Y\n```\n\nBuildchain then:\n\n1. Finds the same-patch alpha tag that was tested.\n2. Checks that the release source tree matches that alpha tag tree, excluding\n   only generated version-state differences.\n3. Writes final release version state such as `vX.Y.Z`.\n4. Verifies the generated release tree.\n5. Creates or reuses the exact release tag `vX.Y.Z`.\n6. Moves `release/vX/vX.Y` to the exact release commit.\n7. Moves `vX.Y` to the exact release commit.\n8. Moves `vX` when this minor line should be the stable major entrypoint.\n9. Prepares the next alpha version-state commit, such as\n   `vX.Y.(Z+1)-alpha.0`.\n10. Moves `alpha/vX/vX.Y`, `dev/vX/vX.Y`, and `vX.Y-alpha` to that next alpha\n    commit.\n11. Moves `vX-alpha` to that next alpha only when this remains the highest published alpha minor.\n\nThe historical alpha tree comparison remains the default stable source gate.\nA promote-only stable run may accept a broader reviewed release PR only when\nthe downloaded RC passport proves that the PR's exact target tree is the tree\nthat completed the PR-stage build. Buildchain also requires the target commit\nto belong to a merged same-repository PR into the selected release branch and\nrecords the accepted commit, tree, RC source, alpha source, and PR as promotion\nevidence. A stale passport, a different target tree, a generated final release\ncommit, or an unreviewed target commit still falls through to the normal\nalpha-tree and declared version-state checks.\n\nThe production channel and the test channel therefore intentionally diverge\nafter release: production stays on the release commit, while alpha/dev continue\nat the next prerelease commit.\n\n### Stable Release Throttle And Canary Gate\n\nBuildchain's own stable channel has an additional pre-publication gate. It is\nevaluated after the PR-stage release candidate has been resolved and before the\npublish-gate ref, package registry, exact stable tag, or floating stable refs\nare mutated. Train refs and alpha promotion do not execute this gate.\n\nAll alpha and release promotions first run a metadata-only release-candidate\npreflight after queued-intent revalidation. The preflight uses the same resolver\nand exact target SHA as the publication job, but does not download payloads or\ninstall the candidate repository dependencies. Missing channel PRs, stale\nworkflow runs, expired passport pairs, and insufficient payload artifact sets\ntherefore fail before the full promotion job starts. The publication job still\ndownloads and validates the exact evidence again at the trust boundary; the\npreflight moves failure earlier without weakening the final check.\n\nThe policy is versioned in `.buildchain/stable-release-policy.json`. A stable\ncandidate is allowed only when all of these facts are true:\n\n- the candidate resolves to an immutable exact alpha tag and its GitHub\n  prerelease timestamp;\n- at least 24 hours have passed since the preceding stable patch on the same\n  minor line;\n- the preceding stable-to-alpha comparison contains a product or public\n  contract path, not only version, test, evidence, or retrospective changes;\n- the version-bound impact record has a non-empty summary and at least one\n  surface impact;\n- the `Build Surface Fixture` release-candidate run succeeded;\n- `site-libkungfu-dev` completed its no-apply `Buildchain Stable Canary` and an allowed\n  maintainer attested that successful run on the exact alpha SHA through the\n  `buildchain-canary/site-libkungfu-dev` commit-status context;\n- the canary runtime input is exactly the candidate alpha tag or the 40-character\n  commit SHA resolved from that tag; a successful status pointing at another\n  workflow, repository, tag, floating ref, or SHA is rejected as mismatched;\n- at least one hour has elapsed after the last required canary completed.\n\nThe machine report is written to\n`.buildchain/release-passport/stable-release-gate.json`. A passing report is\nuploaded with the stable release passport. A blocked run writes the same report\nbefore failing, so the missing or stale condition is inspectable without\nopening a publication transaction.\n\nGitHub's Actions run REST object does not expose `workflow_dispatch` inputs.\nBuildchain therefore verifies the run's `workflow_id` against the authoritative\nworkflow metadata, then reads the exact runtime from the workflow-owned\n`<workflow name> / <runtime ref>` run-name when no input field is available.\nAn explicit API input, when present, remains authoritative and cannot be\noverridden by the display name.\n\nThe cooldown is a minimum interval, not an instruction to release every day.\nCompatible work should still be batched until a stable release has a concrete\nconsumer need. Changing the interval, canary set, attestors, product path\nboundary, or soak time is a reviewed policy change.\n\nRepositories that want a predictable scheduled stable window can use\n[`Stable Candidate Patrol`](stable-candidate-patrol.md). It persists each exact\nalpha independently, qualifies it after repository-declared checks and soak,\nand selects the newest qualified non-revoked candidate. A newer soaking alpha\ndoes not invalidate an older qualified candidate. The selected tree enters the\nexisting strict `publish-gate/release/<line>/<version> -> release/<line>` PR\npath, so scheduled selection changes release intent timing without weakening\nsource locks, review, verification, publish transactions, or passports.\n\nIf release finalization is resumed after generated version-state bookkeeping was\npartially applied, Buildchain applies the same recovery rule: the current\nrelease head may be the generated commit, or a historical merge commit that\ncontains the recorded release material, existing exact tags and alpha/dev refs\nare accepted when they match the transaction, and missing floating `vX.Y` or\n`vX` tags are retried idempotently before completion.\n\nOnce the durable release transaction is `complete` and the exact/floating\nstable refs have moved, next-alpha preparation is post-release bookkeeping. A\nfailure there records `deferred-post-release-bookkeeping` and\n`next-anchor-required` instead of retroactively reporting the stable release as\nfailed. Generated next-alpha merges use the current dev tree as their base and\noverlay only declared version-state paths, preserving concurrent dev changes.\n\n## Major Gate Semantics\n\nA major gate merge is:\n\n```text\nrelease/vX/vX.Y -> publish-gate/major\n```\n\n`publish-gate/major` is the explicit replacement for the older ABV `main`\nchannel. The name is intentionally operational: it is a gate for a rare\nadministrator decision, not the active trunk. Keeping this decision in the same\nPR UI as alpha and release promotion keeps the human workflow simple while\navoiding the misleading meaning of `main`. The older `major-gate` branch name is\na compatibility alias only.\n\nBuildchain then:\n\n1. Verifies the source is a merged same-repository PR from a protected release\n   line into `publish-gate/major`.\n2. Writes the next major production version state, such as `v(X+1).0.0`.\n3. Creates or reuses the exact release tag `v(X+1).0.0`.\n4. Moves `publish-gate/major` and `release/v(X+1)/v(X+1).0` to that release commit.\n5. Moves `v(X+1).0` and `v(X+1)` to that release commit.\n6. Prepares the next alpha version-state commit, such as\n   `v(X+1).0.1-alpha.0`.\n7. Moves `alpha/v(X+1)/v(X+1).0`, `dev/v(X+1)/v(X+1).0`, and\n   `v(X+1).0-alpha` to that next alpha commit.\n\nChecking out `publish-gate/major` should therefore look like a frozen release\nstate, not like a branch where day-to-day source work continues. Day-to-day\nsource work continues on `dev/vX/vX.Y`.\n\n## Protected Dev Branches\n\n`dev/vX/vX.Y` is a protected development channel, not a scratch branch. Normal\nsource changes should be made on work branches such as `feature/*`, `fix/*`,\n`chore/*`, `docs/*`, `ci/*`, or `refactor/*`, then reviewed through a pull\nrequest into the target dev line.\n\nThis keeps the earliest development channel audit-friendly:\n\n- the version line being changed is visible in the PR base branch;\n- CI and required checks run before the channel moves;\n- branch protection can prevent direct pushes and stale merges;\n- later `dev -> alpha -> release` promotion inherits a reviewable source\n  lineage instead of trying to reconstruct how the dev branch changed.\n\nWhen required checks take longer than the normal dev-channel commit interval,\nclassic strict up-to-date protection can become a non-converging retry loop:\neach base update invalidates a completed check set and rebasing restarts the\nsame slow checks. Buildchain supports GitHub merge queues for that channel\nshape. The queue validates the projected merged result and serializes the final\nref update, so concurrent channel movement no longer invalidates the candidate.\n\nEvery required workflow must handle both `pull_request` and `merge_group`\nbefore the queue is enabled. Queue runs do not provide\n`github.event.pull_request`; required workflows must use the checked-out\n`github.sha` or event-neutral source facts. The governance command is dry-run by\ndefault and refuses to enable a queue when a declared required workflow lacks\neither trigger or still reads the pull-request-only payload directly:\n\n```bash\nbuildchain dev merge-queue \\\n  --repository owner/repository \\\n  --branch dev/v4/v4.0 \\\n  --workflow .github/workflows/source-acceptance.yml \\\n  --workflow .github/workflows/affected-native-pr.yml \\\n  --bypass-app dedicated-release-app\n```\n\nAfter reviewing the plan, repeat with `--apply`. Buildchain creates or updates\nan exact-branch `merge_queue` ruleset first, then changes only the classic\nrequired-status-check policy from strict to loose. Reviews, administrator\nenforcement, conversation resolution, required check identities, force-push\nprotection, and deletion protection remain owned by the existing branch\nprotection. The ruleset uses the first merge method that the repository itself\nallows, and fails closed when the repository has no enabled merge method.\nRe-running the command is idempotent.\n\nThe repository policy can be declared once instead of repeated as CLI flags:\n\n```toml\n[governance.dev.merge_queue]\nmode = \"inherit\"\nrequired_workflows = [\".github/workflows/verify.yml\"]\n```\n\n`enabled` explicitly requires Buildchain to create or update an exact-branch\nqueue; `inherit` copies queue parameters and bypass actors from the repository's\ncurrent default dev branch; `disabled` prevents automatic queue creation. An\nabsent declaration behaves as `inherit` during release-line bootstrap so a new\nmajor or minor line does not silently lose governance already active on the\nprevious line. Required status-check identities still come from the new\nbranch's own classic protection rather than being copied from the old branch.\n\nMerge-queue rules also reject generated post-publish version-state ref updates.\nWhen the sealed promotion workflow uses a dedicated GitHub App, user, or team\nalready declared by release governance, repeat `--bypass-app`, `--bypass-user`,\nor `--bypass-team` to project that exact actor into the ruleset. Bypass actors\nare never inferred and broad repository or organization roles are not accepted.\nThis keeps ordinary feature PRs on the predecessor-aligned queue path while the\nsealed publication authority can finish its machine-verified bookkeeping. The\ndry-run receipt exposes the exact actor IDs before `--apply` changes GitHub.\n\nBuildchain provides the reusable\n`.github/workflows/dev-pr-auto-merge.yml` workflow for repositories that want a\nscheduled or manual \"merge ready dev PRs\" pass. The consumer repository owns\nthe trigger schedule, but the merge decision is declared through workflow\ninputs: target dev branch, required status/check names, ready and block labels,\nallowed work-branch prefixes, review requirements, maximum merges per run,\nmerge method, and dry-run mode.\n\nThe workflow defaults are conservative. A PR is skipped unless it targets the\nconfigured dev line, is not a draft, has the ready label, has no block label,\ncomes from the same repository, uses an allowed work-branch prefix, has a\ncurrent approval, is mergeable, and has the configured required checks passing.\n`landing-mode: auto` reads the target branch's native merge-queue state. When a\nqueue exists, Buildchain never calls the direct merge endpoint: it admits at\nmost one PR against the observed target-branch SHA and immutable PR head, then\ncalls GraphQL `enqueuePullRequest` with `expectedHeadOid`. GitHub's\n`merge_group` checks remain the final authority for the projected merge.\n\nThe admission receipt records the expected and observed base/head SHAs, policy\nchecks, decision, reason, and active predecessor. Buildchain re-reads the base,\nhead, mergeability, and native queue immediately before enqueueing. Base or\nhead drift fails closed, an active queue entry blocks admission, and a rejected\nready predecessor leaves its PR open while later PRs receive\n`blocked-by-predecessor`. Workflow concurrency serializes Buildchain-owned\nadmission runs; GitHub still owns the atomic queue and protected-ref update.\nRepositories may explicitly select `landing-mode: direct` only when the target\nbranch has no native queue. Queue presence always disables the direct path.\n\nThe canonical consumer required check context is `check / check`, matching the\nreusable workflow call plus its `check` job. Buildchain's own `Verify` workflow\nemits the repository-local context `check`, so Buildchain self-promotion,\nrelease-line bootstrap, and dogfood patrol wrappers pass `check` explicitly.\nRelease governance preserves the exact context emitted by the repository and\nrecords branch-protection policy before/after facts; it does not rewrite one\ncontext shape into the other. Consumer repositories can keep their context\nstable while changing the actual verification command declaratively in\n`buildchain.toml`:\n\n```toml\n[lifecycle.install]\ncommand = \"cargo fetch --locked\"\n\n[lifecycle.verify]\ncommand = \"cargo test --workspace --locked\"\n```\n\nConsumers that want Buildchain to own the check wrapper can call\n`.github/workflows/check.yml@v3`. The wrapper runs the declared\n`lifecycle.install` and `lifecycle.verify` stages and fails the `check` job when\neither declaration is missing or the command exits non-zero.\n\nDevelopment pull requests that need source acceptance without product build or\nartifact verification can opt into `mode: source`. That mode runs only\n`lifecycle.install` and `lifecycle.check` on GitHub-hosted `ubuntu-24.04` while\npreserving the stable `check / check` required-check context. Existing callers\nremain on `mode: verify` by default, and callers may set\n`upload-artifacts: false` without weakening the job conclusion.\n\nTypical consumer wrapper:\n\n```yaml\nname: Merge Ready Dev PRs\n\non:\n  schedule:\n    - cron: \"17 * * * *\"\n  workflow_dispatch:\n    inputs:\n      dry-run:\n        type: boolean\n        default: true\n\njobs:\n  merge-dev:\n    uses: kungfu-systems/buildchain/.github/workflows/dev-pr-auto-merge.yml@v3\n    permissions:\n      contents: write\n      pull-requests: write\n      checks: read\n      statuses: read\n    with:\n      target-branch: dev/v3/v3.0\n      required-status-checks: check / check\n      ready-label: ready\n      block-labels: blocked,do-not-merge\n      max-merges: 1\n      landing-mode: auto\n      dry-run: ${{ inputs.dry-run || false }}\n```\n\n## Buildchain Patrol\n\n`dev-pr-auto-merge.yml` remains the focused merge primitive. For repositories\nthat want a stable day-to-day operations contract, Buildchain also exposes a\npatrol workflow family:\n\n| Workflow | Intended cadence | Default intent |\n| --- | --- | --- |\n| `.github/workflows/patrol-daily.yml` | daily | lightweight inspection plus ready dev PR maintenance |\n| `.github/workflows/patrol-weekly.yml` | weekly | release-state, passport, gate, and stale-state health checks as they are added |\n| `.github/workflows/patrol-monthly.yml` | monthly | governance, permission, branch-protection, and workflow drift checks as they are added |\n| `.github/workflows/patrol-observed-evidence.yml` | caller-selected schedule | validated immutable observation plus atomic last-known-good publication; no per-refresh PR |\n| `.github/workflows/stable-candidate-patrol.yml` | repository-selected release window | qualify immutable alpha candidates and open the exact source-lock stable PR |\n\nThe cadence names describe patrol intensity, not release cadence:\n\n- daily patrol can run every day without implying a daily release;\n- weekly patrol is for medium-cost maintenance and audit checks;\n- monthly patrol is for structural drift checks that should not block ordinary\n  development velocity.\n\nStable Candidate Patrol is separate from those maintenance cadences because its\ncaller-owned cron is a release-intent window. Its candidate ledger and selection\nremain generic; registry-specific side effects still run through the normal\nrepository `lifecycle.publish` transaction. See\n[`stable-candidate-patrol.md`](stable-candidate-patrol.md).\n\nObserved data that is mechanically regenerated and path-scoped uses the\nseparate [`Observed Evidence Patrol`](observed-evidence-patrol.md) contract.\nIts one-time mechanism changes remain reviewed, while steady-state snapshot\nrefreshes publish directly from trusted default-branch schedule/manual callers.\n\nConsumers should schedule thin callers and keep their YAML declarative. For\nexample:\n\n```yaml\nname: Buildchain Daily Patrol\n\non:\n  schedule:\n    - cron: \"17 2 * * *\"\n  workflow_dispatch:\n\njobs:\n  patrol:\n    uses: kungfu-systems/buildchain/.github/workflows/patrol-daily.yml@v3\n    with:\n      dry-run: false\n      max-actions: 1\n```\n\nWeekly and monthly callers use the matching wrapper:\n\n```yaml\njobs:\n  patrol:\n    uses: kungfu-systems/buildchain/.github/workflows/patrol-weekly.yml@v3\n    with:\n      dry-run: true\n```\n\nAll three wrappers default to the `v3` floating Buildchain runtime. When\n`target-branch` is omitted, the caller's current/default branch selects the\nactive semver dev line, so consumers do not pin patrol to a stale minor branch.\nThe separate workflow names keep consumer schedules readable and stable while\nBuildchain adds new checks behind the cadence wrappers.\n\n## Package-Manager Adapters\n\nOld ABV assumed JavaScript repositories with root version state and often\nLerna. Buildchain keeps the version-state contract but does not assume every\nrepository is yarn/Lerna.\n\nThe promotion action discovers and updates:\n\n- root `package.json`;\n- `lerna.json`;\n- package manifests from `package.json` workspaces;\n- package manifests from `lerna.json` packages;\n- package manifests from `pnpm-workspace.yaml`.\n\nIt then runs the repository's detected package manager semantics where needed:\n\n- pnpm repositories use pnpm-oriented workspace discovery;\n- npm repositories use npm/package-lock semantics where present;\n- yarn repositories use yarn-style metadata where present.\n\nFor Buildchain itself, version state is required. For a consumer repository that\nhas no package manifest, the same action can degrade to ref-only behavior only\nwhen that is explicitly allowed by the caller.\n\n## Lifecycle Configuration\n\n`.buildchain/buildchain.toml` is the v3 user configuration format. It lets a repository\ndeclare version-state files and lifecycle commands without pretending every\nproject is a Node workspace. Supported version files include JSON, TOML, and\nregex-based files such as `CMakeLists.txt` or `conanfile.py`.\n\nThe promotion action consumes `version.files`, optional anchored/manual\n`version.derived_files`, and `lifecycle.verify`.\nThe verify stage runs after generated version-state changes are applied locally\nand before any release refs move. If `verification-command` is passed directly\nto the action, that explicit command overrides `lifecycle.verify`.\n\nAnchored/manual repositories may use `version.derived_files` for committed\nversion witnesses that are regenerated by `lifecycle.version-state`. The\nrelease-candidate build verifies those witnesses before heavy builds and records\ntheir digests with the exact alpha and release tree identities. Promotion then\naccepts only declared version files, the anchor manifest, and those derived\nfiles as differences from the tested alpha tree; release passports preserve the\nsame material binding.\n\nProtected release-line branches keep their normal human review gate. Managed\n`dev/vN/vN.M`, `alpha/vN/vN.M`, and `release/vN/vN.M` branches are configured\nwith one required approving review, required GitHub Actions checks, administrator\nenforcement, conversation resolution, no force pushes, and no deletions. Each\ntarget uses the exact check set, GitHub App identity, and strictness declared by\nthe governance authority descriptor. The\nreusable `release-candidate-promote.yml` wrapper defaults\n`branch-protection-bypass-apps` to `github-actions`, which lets the workflow's\nautomation identity apply generated version-state or post-publish channel\nbookkeeping after the reviewed channel PR has merged. Direct\n`promote-buildchain-ref` callers may opt into that one controlled bypass with\n`branch-protection-bypass-apps: github-actions`; every other App slug and all\nuser or team bypass actors are rejected. Before\npatching a protected generated bookkeeping ref, the action creates the\nfull configured required-check set on the exact generated version-state commit, so strict\nstatus checks are satisfied by machine-verifiable Buildchain evidence rather\nthan a human PR. The protected ref PATCH itself uses the generated ref update\ntoken; the reusable wrapper binds it to the run-scoped `github.token`. If direct generated\nrelease finalization bookkeeping is still rejected, Buildchain creates or\nreuses a same-repository `buildchain/version-state/*` PR and records\n`finalization-needed=true` in the durable transaction output. Strict alpha\nfollows the same provider-enforced PR path for its alpha and dev bookkeeping.\nThe PR remains subject to the declared review, required checks, and merge-queue\npolicy; publication resumes idempotently after that protected transaction\nlands.\n\nFor a stable release, the wrapper also checks out the exact current development\nchannel into `.buildchain/reconciliation/dev`. When the prepared next-alpha\ncommit cannot fast-forward dev because reviewed work landed concurrently, the\npromotion action applies the next version to that checkout, regenerates every\ndeclared derived version-state file, reruns the verification lifecycle, and\nonly then creates the two-parent reconciliation commit. A checkout/current-ref\nSHA mismatch blocks reconciliation instead of committing stale projections.\nBuildchain's own promotion workflow accepts only\n`BUILDCHAIN_PROMOTION_BYPASS_APPS=github-actions`, defaulting to that exact App\nwhen the variable is absent. Buildchain's release-line bootstrap uses the\nadministrator-scoped promotion token only to configure protection; branch\ncreation and generated ref updates use the run-scoped token. New channel\nprotection binds required checks to GitHub Actions App id `15368`, enables Code\nOwner, stale-review, and latest-push review gates, and admits no user or team\nbypass actor.\n\n## What This Guarantees\n\nWhen the loop succeeds, maintainers and consumers can rely on these facts:\n\n- every production release has an exact tag such as `v3.0.2`;\n- every production minor line has a floating tag such as `v3.0`;\n- every selected stable major has a floating tag such as `v3`;\n- every next-major release is driven by a reviewed `release -> publish-gate/major` PR,\n  not a hidden manual button;\n- every test channel has an exact alpha tag such as `v3.0.3-alpha.0`;\n- every alpha minor line has a floating tag such as `v3.0-alpha`;\n- every major with a published alpha has a cross-minor floating tag such as `v3-alpha`, owned by its highest published alpha minor;\n- version manifests match the tag visible from the same commit;\n- production releases are derived from the alpha tree that was tested;\n- manual non-dry-run promotion cannot bypass PR review and verification;\n- flow-internal automation bypasses apply only to declared GitHub Apps, users,\n  or teams on Buildchain-managed channel branch protection, while one-review\n  protection remains enforced for humans;\n- admin users cannot make a channel promotion valid by temporarily bypassing\n  branch protection.\n\nThis is the practical meaning of \"governance closed loop\" in Buildchain: the\ndecision, code, version state, and Git refs close over the same evidence chain.\n\n## What This Does Not Do\n\nBuildchain release promotion does not embed registry clients or product-specific\npublish logic. When publish transactions are enabled, `promote-buildchain-ref`\ncan run the consumer's `lifecycle.publish` command and own the transaction,\nevidence validation, durable recovery state, and ref finalization order. The\nconsumer repository still owns registry truth: npm, PyPI, OCI, S3, Conan, CMake\npackaging, download pages, dist-tags, and similar side effects must be\nimplemented by project lifecycle commands that emit Buildchain publish evidence.\n\nDurable transaction recovery is also bound to the exact publication version\nplanned for the current run. An unfinished transaction may be resumed from the\ncurrent source or its history only when its recorded version matches that plan;\nan older failed transaction that happens to be an ancestor cannot reserve its\nold exact tag for a newer package publication.\n\nThe exact tag is also part of the durable transaction identity. If an anchored\npackage publication completed registry side effects under a stale internal tag\nselection, a retry may rebind the unfinished `published` or `finalizing`\ntransaction to the newly planned internal tag only when the package version,\nsource, release material, target, complete artifact set, and evidence all still\nmatch; the stale tag must not point at the transaction, and the requested tag\nmust be absent or already point at accepted release material. This preserves an\nimmutable tag that represents a completed transaction while allowing a tag\ncollision discovered after registry publication to recover without republishing.\n\nEvery Buildchain publish model that can run registry side effects must bind the\npublish entrypoint to an immutable `publish-gate/*` source lock. The reusable\n`release-candidate-promote.yml@v3` wrapper creates or updates that gate ref and\npasses `require-publish-source-lock`, `publish-source-ref`,\n`publish-source-sha`, and `publish-source-locked` to\n`promote-buildchain-ref`. Direct action callers must pass the same four inputs\nfrom the reusable build outputs. Workflows that only collect passports or run\ndry-run package checks do not move publish refs and are not publish-gate\npublication models. A dry-run of `release-candidate-promote.yml` computes and\nreports the exact `publish-gate/*` source lock that a real promotion would use,\nbut does not read, create, or move that ref.\n\nSemver GitHub Release publication is owned by `promote-buildchain-ref`, not by\nconsumer shell glue. Consumers normally use the `release-candidate-promote.yml`\ngenerated channel router, where GitHub Release publication is enabled by default and can be\ndisabled with `github-release: false`; the wrapper passes that declaration to\nthe action. After the publish transaction reaches `complete`, Buildchain creates\nor updates the public GitHub Release and uploads the generated\n`buildchain.release.json`, release-passport assets, and publish evidence. The\nauthoritative publication channel controls GitHub metadata: alpha is marked\n`prerelease=true` and `make_latest=false`; release/stable/major is marked latest.\nSemver tag syntax remains the fallback for ordinary callers without explicit\npublication intent. For anchored/manual package releases, the public\nrelease tag defaults to `v<publishedVersion>` while the internal exact\ntransaction tag remains in the release passport and release-state ref. This is\nthe supported path for downstream\n`release.published` propagation across semver, major, and promote-only release\ncandidate publication models.\n\nPublished GitHub Release assets are immutable evidence. A repeated promotion\npreserves an existing asset when its SHA-256 digest matches the regenerated\nbytes, uploads only missing assets, and fails with an immutable-release\ncollision when a same-name asset has different bytes. It never deletes and\nreplaces an existing asset during retry or duplicate workflow delivery.\n\nProduct payloads are included only through the explicit\n`github-release-payload-patterns` input. Patterns match basenames inside the\ndownloaded PR-stage RC payload bundle; zero matches or duplicate public\nbasenames fail closed. This preserves the exact PR-built bytes instead of\nrebuilding archives during promotion.\n\nConsumers with a signed well-known discovery document can additionally provide\n`publication-commit-command`. The advanced promotion workflow validates its\ntopology before any publish-gate or release mutation, then runs it only after\nthe GitHub Release and its immutable payload/passport assets exist. The command\nmust publicly read back the exact new payload root and emit\n`kungfu-buildchain-publication-commit-evidence/v1`; that evidence is copied\ninto the controller artifact and exposed as workflow outputs. The previous\nauthority must remain valid on every failure. Deferred standalone binary\ndistribution is incompatible with this mode because the discovery authority\nmust be the final product mutation.\n\nBuildchain also does not maintain bare exact tags such as `1.0.0`. The supported\nexact release and alpha refs are v-prefixed:\n\n```text\nv3.0.0\nv3.0.1-alpha.0\n```\n\n## Operational Reading Order\n\nWhen debugging or extending release behavior, read in this order:\n\n1. `docs/release-flow.md`\n2. `.github/workflows/release-verify.yml`\n3. `.github/workflows/buildchain-ref-promotion.yml`\n4. `.github/workflows/release-candidate-promote.yml`\n5. `.github/workflows/.release-candidate-promote.yml`\n6. `actions/promote-buildchain-ref/README.md`\n7. `actions/promote-buildchain-ref/src/`\n8. `docs/migration-inventory.md`\n\nThat path gives the policy first, the workflow trigger second, and the action\nimplementation last."
     },
     {
       "id": "manual:release-passport",
@@ -1822,7 +1903,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/release-passport.md",
-      "digest": "sha256:d698078075700e60bafb9677bc4c35d49970136b98caaecfc51d38344285cdd5",
+      "digest": "sha256:e1ca1d470de4faeb9f7f0a57228aebbc166d0c96d03a5603fc576ad955c497a4",
       "headings": [
         {
           "level": 1,
@@ -1875,7 +1956,7 @@
           "anchor": "binary-distribution"
         }
       ],
-      "markdown": "# Release Passport\n\nBuildchain Release Passport is the core product mechanism: a mature product\nrelease record for artifacts that users or agents depend on.\n\nThe protocol is GitHub-native because it uses protected refs, reviewed\npromotion PRs, exact tags, GitHub Releases, npm Trusted Publishing, and\nmachine-readable evidence. A project can keep its existing build system and use\nBuildchain to make the release record auditable.\n\nLinux release artifacts can additionally carry a GitHub keyless attestation\npolicy in `githubArtifactAttestations[]`. The policy binds the exact subject,\nconsumer source, original Linux build evidence, immutable Buildchain signer\nworkflow, and minimum permissions before the provider attestation exists. The\ncompleted provider bundle and attestation identifier remain separate evidence,\navoiding a Passport hash cycle. See\n[`github-artifact-attestation.md`](github-artifact-attestation.md).\n\nRelease-candidate and final passports may also include compact\n`controllerReceipts[]` references. These bind a real reusable-workflow receipt\nto its plan digest, consumer source SHA, and exact Buildchain runtime SHA; they\ndo not infer execution evidence from a green job. See\n[`controller-evidence.md`](controller-evidence.md).\n\n## Contract\n\nThe release passport surface is a welded contract. Additive fields are allowed;\nbreaking semantic changes require a new major line.\n\nIndependent verifiers can pin two package-owned, standalone files without\nscraping this implementation:\n\n- `dist/site/schemas/release-passport-v1.schema.json` is the self-contained\n  JSON Schema for the Buildchain-owned envelope;\n- `dist/site/release-passport-check-manifest.json` names the normative checker,\n  required and conditional sibling evidence, local-resolution rules,\n  Buildchain aggregation fields, canonical KFD subsection schema authorities,\n  and forward-compatibility policy.\n\nThe same files are exported as\n`@kungfu-tech/buildchain/site/schemas/release-passport-v1.schema.json` and\n`@kungfu-tech/buildchain/site/release-passport-check-manifest.json`. The schema\nchecks the envelope shape. `buildchain verify release-passport` remains the\nnormative semantic checker: it resolves sibling evidence relative to the\npassport and fails closed on missing evidence, digest drift, or inconsistent\nrelease facts. Buildchain owns envelope aggregation; KFD retains schema and\ncompatibility authority for the `kfd-1`, `kfd-2`, and `kfd-3` subsections.\n\nP0 protocol artifacts:\n\n- `product-mechanism.json`\n- `buildchain.release.json`\n- `artifact-evidence.json`\n- `impact.json`\n- `agent-index.json`\n- `check-report.json`\n- `llms.txt`\n- `buildchain-release-bundle.json`\n- `buildchain-release-bundle.tar.gz`\n\n`buildchain.release.json` is the first file an agent should read. It points to\nartifact evidence, impact, recovery, product mechanism, and agent index facts.\nIt is also the unified release responsibility summary: when publish\ntransactions are used, the same passport records the package set, npm dist-tags,\nrelease source refs, release-state ref, anchor manifest, registry artifact\ndigests, trusted publishing evidence, and transaction result.\n\nAdditive passport sections:\n\n- `release`: public release tag, internal transaction tag, line, channel,\n  source SHA, target ref, release SHA, release material SHA, publish tooling\n  SHA, and durable release-state ref. Anchored/manual package releases use the\n  published package version for the public tag while preserving the internal\n  exact transaction tag for Buildchain recovery.\n- `versionImpact`: final patch/minor/major classification, source, and\n  rationale.\n- `surfaceImpacts`: per registered surface classification. The final impact is\n  the highest entry in this list.\n- `packageSet`: main package, platform packages, package-set order, registry,\n  versions, dist-tags, and package digests.\n- `anchorManifest`: anchored/manual version manifest path, digest, and fields.\n- `trustedPublishing`: provider, auth mode, workflow run evidence, and whether\n  trusted publishing was enabled.\n- `transaction`: durable Buildchain release transaction id, state, exact tag,\n  release SHA, state ref, and state SHA.\n- `surfaceTimestampPolicy`: the common Buildchain surface manifest timestamp\n  policy. It records real CI/release generation and publication times,\n  reproducibility inputs, source revision or source-date-epoch, and whether\n  timestamp fields participate in the release artifact digest.\n- `buildFacts`: module/product build facts that bind Git source digests,\n  version sources, lifecycle invocations, platforms, outputs, product\n  artifacts, and verification results to the release.\n- `artifacts`: release assets and registry artifacts in one list, each pointing\n  back to the evidence file that proves its digest. Registry artifacts retain\n  optional built/reused action, content and current-release coordinates,\n  platform/contract/parent metadata, and fail-closed verification evidence.\n- `invariantPassports`: product-owned invariant verification results admitted\n  by Buildchain. Each entry binds the product contract and registry roots,\n  semantic Passport root, exact clean source revision, complete platform\n  coverage, verdict, and residual risk. Buildchain owns release admission, not\n  the meaning of the product invariants.\n- `githubArtifactAttestations`: expected GitHub keyless attestation identities\n  for Linux release artifacts, including subject, caller source, original build\n  evidence, exact Buildchain signer workflow digest, and least-privilege\n  permissions. Dynamic provider evidence is stored beside the Passport.\n\nBuildchain's own binary lane also publishes observability artifacts generated by\nthe Buildchain logging API and CLI:\n\n- `buildchain-log-events-<platform>.jsonl`\n- `buildchain-log-summary-<platform>.json`\n- `buildchain-log-events-passport.jsonl`\n- `buildchain-log-summary-passport.json`\n\n`buildchain-release-bundle.tar.gz` is the single evidence bundle for consumers\nthat want one file for offline inspection, mirroring, or site ingestion.\n`buildchain-release-bundle.json` records its digest and the digest of every\nincluded file.\n\n## Runner Policy\n\nProduction binary distribution should use GitHub-hosted runners by default:\n\n- `ubuntu-24.04`\n- `macos-latest`\n- `windows-2022`\n\nThis keeps the public release path easy for other projects to reproduce.\nSelf-hosted runners remain compatibility fixtures: they prove that the protocol\ndoes not depend on GitHub-hosted images, but they are not the default public\ndistribution lane.\n\nThe protocol records runner facts in `artifact-evidence.json`; it does not\nrequire a specific runner class.\n\n## CLI\n\nGenerate a local release passport bundle from release assets:\n\n```bash\nbuildchain collect github-release \\\n  --tag v3.0.0 \\\n  --repository kungfu-systems/buildchain \\\n  --assets-dir dist \\\n  --publish-evidence-json .buildchain/release-evidence/v3.0.0/evidence.json \\\n  --transaction-json .buildchain/release-state/v3.0.0/state.json \\\n  --package-set-json package-set.json \\\n  --anchor-manifest-json libnode.release.json \\\n  --build-summary-json .buildchain/artifacts/build-summary.json \\\n  --build-facts-json .buildchain/facts/native-core.json \\\n  --build-facts-json .buildchain/facts/product.json \\\n  --platform-manifest-json .buildchain/artifacts/linux-x64/manifest.json \\\n  --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \\\n  --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \\\n  --dist-tag-evidence-json .buildchain/release-evidence/v3.0.0/dist-tag-evidence.json \\\n  --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \\\n  --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \\\n  --invariant-passport-json product/release/qualification/invariant-passport.json \\\n  --github-artifact-attestation-policy-json .buildchain/github-artifact-attestation/policy.json \\\n  --output-dir .buildchain/release-passport\n```\n\nFor a promotion workflow, consumers can instead use\n`release-passport-invariant-passport-command`. The command must emit exactly one\ncanonical JSON object on stdout; for example:\n\n```yaml\nrelease-passport-invariant-passport-command: >-\n  node scripts/kungfu-invariant.mjs --collect-evidence .\n  --passport product/release/qualification/invariant-passport.json --json\n```\n\nSupplying the input makes the invariant gate mandatory. Command failure,\nmissing output, semantic-root drift, a non-`verified` verdict, incomplete\ncoverage, dirty source state, or a source revision unrelated to the release\nfails closed before release publication.\n\n`packageSet` records the ordered main-plus-platform package set.\n`publish.packages[]` summarizes each published npm package with its version,\ndist-tag, registry, role, platform, and digest, so agents do not need to stitch\nnpm facts back together from the lower-level evidence files.\n`buildSummary`, `platformArtifactManifests`, and `distTagPromotion` preserve the\nbuild and npm dist-tag evidence chain in the same passport. `buildFacts[]`\nrecords first-class module/product build facts, while\n`evidence.buildFacts[]` gives agents compact paths, SHA-256 hashes, contracts,\nids, and digests for quick audit traversal. See\n[`build-facts.md`](build-facts.md) for the fact collection and verification\ncontract.\n\n### KFD-1 contract-world release gate\n\nBuildchain can gate release artifacts with KFD-1 contract-world witnesses. This\nis a structured evidence protocol, not a request for consumers to shell out to\nthe Kungfu SDK. The authority chain is:\n\n1. KFD owns the standard metadata and schema ids in `@kungfu-tech/kfd`.\n2. Buildchain imports that metadata, owns the JSON formatting policy, freezes\n   the pre-build witness, and independently verifies post-build artifact bytes.\n3. Consumers only pass declarative witness JSON plus the artifact payloads their\n   build already produced.\n\nThis gives agents a concrete answer to \"what changed and can I trust it?\" A\nrelease can include both normal release passport evidence and KFD-1 evidence:\nthe passport proves the release transaction and artifacts are complete, while\nKFD-1 proves selected contract-world surfaces inside those artifacts are the\nbyte-for-byte surfaces the release intended to ship.\n\nThe witness JSON names the contract world, the canonical serialization policy,\nand the release surfaces that must be byte-for-byte verified:\n\n```json\n{\n  \"id\": \"kungfu-config\",\n  \"standard\": \"kfd-1\",\n  \"source\": \"kfd\",\n  \"contractWorld\": {\n    \"id\": \"kungfu-config\",\n    \"kind\": \"schema\",\n    \"name\": \"Kungfu config schema\"\n  },\n  \"canonicalPolicy\": {\n    \"format\": \"json\",\n    \"encoding\": \"utf-8\",\n    \"indent\": 2,\n    \"trailingNewline\": true\n  },\n  \"surfaces\": [\n    {\n      \"id\": \"kungfu-config-schema\",\n      \"artifactPath\": \"Contents/Resources/core/config.schema.json\",\n      \"expectedSha256\": \"...\"\n    }\n  ]\n}\n```\n\n`collect github-release` writes the result under the KFD-provided top-level key\ncurrently named `kfd-1`. Each contract world records the frozen witness digest,\nthe KFD package version, KFD schema ids, the Buildchain formatting policy, and\nthe actual artifact digest observed after the build. Verification fails closed\nwhen the witness is missing required facts, an artifact cannot be found, or a\npost-build digest does not match the frozen witness.\n\nFor the KFD repository itself, the KFD-1 witness can be a self-hosted standard\ncontract witness. In that mode KFD owns the standard-contract facts and\nBuildchain verifies declared source standard metadata, schemas, package\nexports, and site-consumption entrypoints against the packaged artifact. The\npassport records source and artifact hash summaries, schema ids, the\nself-hosting boundary, result, residual risk, and responsibility state for\nsource ownership, artifact verification, and release-passport proof ownership.\n\nGood KFD-1 witnesses should point at release payload surfaces, not at private\nbuild-machine state. For Buildchain itself, the natural witness set is the\nrelease passport schema and implementation, KFD-1 gate implementation,\n`dist/site/buildchain-contract.json`, and the npm package payload files that\nexpose the public CLI, reusable workflow/action contracts, and site facts.\nThe final `buildchain.release.json` file should not be used as an ordinary\nbyte-for-byte KFD surface because it contains KFD evidence; instead, the\npassport is audited through release-state SHA, `check-report.json`, and the\ncontract files that generate and verify it.\n\n### KFD-2 release trust passport audit\n\nBuildchain can write a KFD-2 release trust passport audit under the top-level\n`kfd-2` section. The section is generated automatically from KFD-1 and KFD-3\nrelease-gate evidence, and callers may add explicit public release claims with\n`--kfd-2-claim-json`.\n\nEvery public claim must bind:\n\n- declared sources;\n- machine-readable evidence;\n- source/evidence/artifact hashes;\n- artifact coordinates;\n- verification results;\n- audit boundary;\n- responsibility state;\n- residual risk, even when the array is empty.\n\nUnbound public claims fail release passport verification. Claims that are\nmachine-bound but only supported by prose downgrade the KFD-2 audit and produce\na warning, so agents can distinguish \"verified\", \"needs review\", and \"not\nbound to evidence\" without reading release notes.\n\nFor Buildchain's own releases, public release claims are not authored in prose\ninside the workflow. The source registry is\n`packages/core/buildchain-kfd-claims.js`, published as\n`dist/site/kfd-claims.json` and exported as\n`@kungfu-tech/buildchain/buildchain-kfd-claims`. That registry is the\nversion-invariant source of public claims and collaboration surfaces: it does\nnot store the exact release version, promotion SHA, or exact runtime contract\ndigest. Those run-specific facts belong in the release passport and generated\nwitnesses. During Buildchain promotion,\n`scripts/generate-buildchain-kfd-witnesses.mjs` binds the source registry to the\ncurrent source/artifact hashes and generates:\n\n- a KFD-1 self contract-world witness for the packaged docs, schemas, workflows,\n  actions, Node exports, and site-consumption facts;\n- one KFD-2 claim JSON per public Buildchain release claim;\n- KFD-3 pre-build and artifact witnesses for the same public collaboration\n  surfaces.\n\nThe generated claim set covers Buildchain's KFD release passport support,\nagent-first single source of truth, floating `@v3` contract drift protection,\nsemver GitHub Release evidence publication, channel-preserving release\npropagation, and npm publish evidence/finalization. Buildchain self promotion\npasses those files into `promote-buildchain-ref`; `verifyReleasePassport()` then\nfails closed if any claim is missing source bindings, machine evidence, hashes,\nartifact coordinates, verification result, audit boundary, responsibility, or\nresidual risk.\n\n### KFD-3 collaboration-interface release gate\n\nKFD-3 asks a different release question than KFD-1. KFD-1 proves that named\npayload bytes match one contract world. KFD-3 proves that a product's shipped\nparticipant-facing collaboration/control surface is closed over its declared\ninterface.\n\nFor Buildchain itself, the declared interface starts in\n`packages/core/buildchain-kfd-claims.js`, not in this Markdown file. The\nregistry enumerates public human/agent surfaces across manuals, schema and\nstandard metadata, package exports, site-consumption contracts, workflows, and\nactions. `dist/site/kfd-claims.json` is the packaged machine-readable form used\nby downstream sites and by Buildchain's own release passport. Exact release\nversion/SHA binding is deliberately deferred to the promotion witness, so the\nsource registry can remain stable across semver version-state bumps.\n\nBuildchain also performs a reverse audit before that witness is used. The\ngenerated `dist/site/public-surface-audit.json` enumerates real CLI commands\nfrom `bin/buildchain.mjs`, workflow inputs, action inputs, site pages, and docs\ncommand references, then compares them with the generated registries. Buildchain\nself KFD witnesses include that audit result and classify the collaboration\ninterface as closed-world only when the reverse audit passes. If a public\ncommand, workflow input, action input, or site page is exposed without a\nregistry entry, `pnpm run check` fails before release promotion can produce a\npassport.\n\nThe product remains the fact source. Before build/publish, the product writes a\npre-build witness:\n\n```bash\nkungfu sdk collaboration-interface witness --json \\\n  > .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json\n```\n\nThat witness must contain, or point to, the product-owned KFD-3 collaboration\ninterface, registry digest, participants, and declared public shipped surfaces.\nKFD repository self-verification can declare the same facts as grouped machine\nsurfaces: docs, schemas, standards metadata, package exports, and\nsite-consumption contracts.\nAfter the artifact is built, the product also provides artifact-side evidence,\neither as a JSON file or a command:\n\n```bash\nbuildchain collect github-release \\\n  --kfd-3-prebuild-witness-json .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json \\\n  --kfd-3-artifact-verify-cmd \"kungfu agent verify --json\"\n```\n\nBuildchain imports the KFD-3 metadata from `@kungfu-tech/kfd`, freezes the\npre-build witness digest, ingests the artifact witness, and compares the two\nsets:\n\n- every declared `shipped` public participant-facing surface must appear in the\n  artifact witness;\n- every artifact-exposed public participant-facing surface must be declared by\n  the pre-build witness;\n- if both witnesses record `collaborationInterface.digest`, the digests must\n  match;\n- contradictory, missing, stale, or schema-incomplete evidence fails closed.\n\nThe generated release passport records the result under the KFD-provided\ntop-level key currently named `kfd-3`. The section includes the KFD package\nversion, schema ids/paths, pre-build witness digest, artifact witness digest,\ndeclared/exposed surface counts, missing declared shipped surfaces, and\nunclassified artifact public surfaces. Buildchain also projects the same\ncollaboration-interface evidence into the top-level `kfd-2` audit as a\nmachine-readable `trustProof` object on the generated `kfd-3:*` public claim.\nThat proof carries `releaseStatus`, witness file hashes and canonical hashes,\ndeclared capability verification, reverse audit result and boundary, residual\nrisk, and responsibility state.\n\nThe trust proof makes the strongest claim only when the witnesses justify it:\n`No unclassified reachable surface within the declared audit boundary.` If the\nproduct declares non-exhaustive surfaces, Buildchain keeps the passport\nverifiable but marks the interface `audited` instead of `enforced` and records\nthe residual risk explicitly. Draft or partial KFD-3 declarations are\ndowngraded; missing declared capabilities, undeclared public artifact surfaces,\nor stale collaboration-interface digests fail the proof.\n\nThis makes KFD-3 support usable by readers and agents immediately: they can\ninspect `buildchain.release.json` and know whether the released package\nactually exposes no more and no less than the declared collaboration interface,\ninstead of trusting docs or release notes.\n\n### KFD support projection\n\nPass `--kfd-support-matrix-json` together with three\n`--kfd-product-gate-json` arguments for KFD-4, KFD-5, and KFD-7. The collector\nverifies the product-owned KFD-1..13 matrix against the installed\n`@kungfu-tech/kfd` standards, binds each gate to the exact release source and\nfresh evidence cut, and emits `kfd-support.json`. The identical projection is\nembedded as `kfdSupport` in `buildchain.release.json`.\n\nRelease verification fails closed when the sibling is missing or differs,\nwhen a gate expires, when matrix and gate status disagree, or when a matrix\nwidens KFD-4/5 candidate, KFD-6 unsupported, KFD-8..13 draft, or any non-shipped\nstate. A passed projection is release evidence only; product qualification,\nactivation, certification, and support ownership remain outside Buildchain.\n\n### Floating Buildchain contract lock\n\nKFD-1 protects release payload surfaces. Floating ref contract locks protect the\nconsumer's relationship to Buildchain itself. A consumer can keep\n`.buildchain/contract-lock.json` with the Buildchain floating ref it accepted,\nthe resolved SHA, the contract digest, and the compatibility policy. Each\nBuildchain run reads the actual contract from the checked-out Buildchain ref\nand compares it before heavy build or publish work begins.\n\nCompatible drift, such as optional inputs or extra diagnostics, continues and\ncreates a consumer-local issue for review. Breaking drift fails fast. This means\nconsumers can use `@v3` without silently accepting incompatible changes, while\nBuildchain maintainers can still ship compatible improvements under the same\nmajor floating tag.\n\n`impact.json` can be supplied with `--impact-json`. Production release\npassports (`release/*`) and major publish-gate passports require\n`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep the field\noptional. When `surfaceImpacts[]` is required or supplied, verification fails\nclosed unless each entry has an id, impact, and rationale, and\n`versionImpact.final` matches the highest surface impact. For example, KFD-2\ncontent can remain patch while an additive `registry.kind` field on the\nmachine-consumed KFD registry schema records a minor `kfd-registry-schema`\nsurface impact.\n\nPromote-only stable publication may omit an explicit impact ledger only when\nthe downloaded PR-stage release-candidate passport proves exact tree\nequivalence. Buildchain then records a patch-level release-governance impact\nbound to that candidate. Missing, stale, or non-equivalent candidate evidence\ndoes not receive this fallback and remains fail-closed.\n\nVerify a release passport:\n\n```bash\nbuildchain verify release-passport .buildchain/release-passport/buildchain.release.json\n```\n\nVerify a specific artifact by discovering its detached passport:\n\n```bash\nbuildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe\n```\n\nArtifact verification is subject-centric. Buildchain identifies the subject,\ncomputes or obtains its digest, discovers a detached `buildchain.release.json`,\nverifies that release passport and its evidence, then proves the subject digest\nappears in the passport's artifacts, package set, publish evidence, or artifact\nevidence. The command returns `pass`, `fail`, or `unverifiable`; missing\npassports and digest mismatches fail closed.\n\nFor npm subjects, Buildchain treats the registry as the package digest source:\n`npm:<name>@<version>` resolves `dist.integrity` and matches it against\n`packageSet.main.digest`, `packageSet.platforms[].digest`, and publish evidence.\nUse `--npm-registry <url>` when the package comes from a non-default registry.\n\nDiscovery is ordered and auditable:\n\n1. explicit `--passport`;\n2. sidecar pointer;\n3. embedded/package pointer;\n4. local config or org index;\n5. GitHub Release default from artifact naming/repository/tag hints;\n6. custom locator;\n7. unverifiable with retry guidance.\n\nFor Buildchain-managed GitHub Release lanes, release passport files are\npublished as release assets by default when the upload backend is enabled, so a\nGitHub Release asset URL can discover the sibling `buildchain.release.json`\nwithout a consumer copying YAML resolver logic.\n\nExplain a release to an agent:\n\n```bash\nbuildchain explain release \\\n  --passport .buildchain/release-passport/buildchain.release.json \\\n  --for agent \\\n  --json\n```\n\nThe verifier fails closed when a passport omits artifacts, omits evidence, has\ndigest mismatches, or misses required protocol files.\n\n## Binary Distribution\n\nInitial binary distribution stays lightweight:\n\n- GitHub Release assets.\n- `checksums.txt`.\n- release passport artifacts.\n- a single release evidence bundle.\n- install scripts and Homebrew tap fixtures after the passport path is reliable.\n\nBuildchain publishes platform-specific archives, not loose top-level\nexecutables:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n\nThe executable name inside each archive stays natural for the platform\n(`buildchain` or `buildchain.exe`). Top-level loose executable assets are not\nuploaded, because Linux and macOS would otherwise collide when GitHub Actions\nmatrix artifacts are merged.\n\nHeavy package manager channels such as apt, yum, winget, choco, Scoop, mise, or\nasdf are out of the P0/P1 scope until there is real external demand.\n\nStandalone binaries are a distribution shape, not a second implementation. The\nsource of truth remains the Node/ESM CLI and core library.\n\nThe standalone binary builder imports `@kungfu-tech/buildchain/logging` directly\nand records setup, SEA blob generation, injection, signing, archiving, manifest,\nand evidence phases. The GitHub workflow wraps the same build and passport\nsteps with `buildchain mark`, `buildchain span`,\n`buildchain verify observability-log`, and `buildchain log summary`. Logging is\na hard release gate: missing events, error events, or missing required phases\nfail the job before assets are uploaded. The verified logs are release assets\nand are covered by the release passport digest checks.\n\nSee also [`binary-distribution.md`](binary-distribution.md) for asset naming and\nbundle details, and [`install.md`](install.md) for consumer commands."
+      "markdown": "# Release Passport\n\nBuildchain Release Passport is the core product mechanism: a mature product\nrelease record for artifacts that users or agents depend on.\n\nThe protocol is GitHub-native because it uses protected refs, reviewed\npromotion PRs, exact tags, GitHub Releases, npm Trusted Publishing, and\nmachine-readable evidence. A project can keep its existing build system and use\nBuildchain to make the release record auditable.\n\nLinux release artifacts can additionally carry a GitHub keyless attestation\npolicy in `githubArtifactAttestations[]`. The policy binds the exact subject,\nconsumer source, original Linux build evidence, immutable Buildchain signer\nworkflow, and minimum permissions before the provider attestation exists. The\ncompleted provider bundle and attestation identifier remain separate evidence,\navoiding a Passport hash cycle. See\n[`github-artifact-attestation.md`](github-artifact-attestation.md).\n\nRelease-candidate and final passports may also include compact\n`controllerReceipts[]` references. These bind a real reusable-workflow receipt\nto its plan digest, consumer source SHA, and exact Buildchain runtime SHA; they\ndo not infer execution evidence from a green job. See\n[`controller-evidence.md`](controller-evidence.md).\n\n## Contract\n\nThe release passport surface is a welded contract. Additive fields are allowed;\nbreaking semantic changes require a new major line.\n\nIndependent verifiers can pin two package-owned, standalone files without\nscraping this implementation:\n\n- `dist/site/schemas/release-passport-v1.schema.json` is the self-contained\n  JSON Schema for the Buildchain-owned envelope;\n- `dist/site/release-passport-check-manifest.json` names the normative checker,\n  required and conditional sibling evidence, local-resolution rules,\n  Buildchain aggregation fields, canonical KFD subsection schema authorities,\n  and forward-compatibility policy.\n\nThe same files are exported as\n`@kungfu-tech/buildchain/site/schemas/release-passport-v1.schema.json` and\n`@kungfu-tech/buildchain/site/release-passport-check-manifest.json`. The schema\nchecks the envelope shape. `buildchain verify release-passport` remains the\nnormative semantic checker: it resolves sibling evidence relative to the\npassport and fails closed on missing evidence, digest drift, or inconsistent\nrelease facts. Buildchain owns envelope aggregation; KFD retains schema and\ncompatibility authority for the `kfd-1`, `kfd-2`, and `kfd-3` subsections.\n\nP0 protocol artifacts:\n\n- `product-mechanism.json`\n- `buildchain.release.json`\n- `artifact-evidence.json`\n- `impact.json`\n- `agent-index.json`\n- `check-report.json`\n- `llms.txt`\n- `buildchain-release-bundle.json`\n- `buildchain-release-bundle.tar.gz`\n\n`buildchain.release.json` is the first file an agent should read. It points to\nartifact evidence, impact, recovery, product mechanism, and agent index facts.\nIt is also the unified release responsibility summary: when publish\ntransactions are used, the same passport records the package set, npm dist-tags,\nrelease source refs, release-state ref, anchor manifest, registry artifact\ndigests, trusted publishing evidence, and transaction result.\n\nAdditive passport sections:\n\n- `release`: public release tag, internal transaction tag, line, channel,\n  source SHA, target ref, release SHA, release material SHA, publish tooling\n  SHA, and durable release-state ref. Anchored/manual package releases use the\n  published package version for the public tag while preserving the internal\n  exact transaction tag for Buildchain recovery.\n- `versionImpact`: final patch/minor/major classification, source, and\n  rationale.\n- `surfaceImpacts`: per registered surface classification. The final impact is\n  the highest entry in this list.\n- `packageSet`: main package, platform packages, package-set order, registry,\n  versions, dist-tags, and package digests.\n- `anchorManifest`: anchored/manual version manifest path, digest, and fields.\n- `trustedPublishing`: provider, auth mode, workflow run evidence, and whether\n  trusted publishing was enabled.\n- `transaction`: durable Buildchain release transaction id, state, exact tag,\n  release SHA, state ref, and state SHA.\n- `surfaceTimestampPolicy`: the common Buildchain surface manifest timestamp\n  policy. It records real CI/release generation and publication times,\n  reproducibility inputs, source revision or source-date-epoch, and whether\n  timestamp fields participate in the release artifact digest.\n- `buildFacts`: module/product build facts that bind Git source digests,\n  version sources, lifecycle invocations, platforms, outputs, product\n  artifacts, and verification results to the release.\n- `artifacts`: release assets and registry artifacts in one list, each pointing\n  back to the evidence file that proves its digest. Registry artifacts retain\n  optional built/reused action, content and current-release coordinates,\n  platform/contract/parent metadata, and fail-closed verification evidence.\n- `invariantPassports`: product-owned invariant verification results admitted\n  by Buildchain. Each entry binds the product contract and registry roots,\n  semantic Passport root, exact clean source revision, complete platform\n  coverage, verdict, and residual risk. Buildchain owns release admission, not\n  the meaning of the product invariants.\n- `releaseEvidence`: typed references to product-owned JSON evidence copied\n  beside the Passport. Buildchain does not interpret product or legal meaning;\n  it binds each document's canonical JSON digest and exact source SHA, tag, and\n  channel, then independently re-verifies the sibling document.\n- `githubArtifactAttestations`: expected GitHub keyless attestation identities\n  for Linux release artifacts, including subject, caller source, original build\n  evidence, exact Buildchain signer workflow digest, and least-privilege\n  permissions. Dynamic provider evidence is stored beside the Passport.\n\nBuildchain's own binary lane also publishes observability artifacts generated by\nthe Buildchain logging API and CLI:\n\n- `buildchain-log-events-<platform>.jsonl`\n- `buildchain-log-summary-<platform>.json`\n- `buildchain-log-events-passport.jsonl`\n- `buildchain-log-summary-passport.json`\n\n`buildchain-release-bundle.tar.gz` is the single evidence bundle for consumers\nthat want one file for offline inspection, mirroring, or site ingestion.\n`buildchain-release-bundle.json` records its digest and the digest of every\nincluded file.\n\n## Runner Policy\n\nProduction binary distribution should use GitHub-hosted runners by default:\n\n- `ubuntu-24.04`\n- `macos-latest`\n- `windows-2022`\n\nThis keeps the public release path easy for other projects to reproduce.\nSelf-hosted runners remain compatibility fixtures: they prove that the protocol\ndoes not depend on GitHub-hosted images, but they are not the default public\ndistribution lane.\n\nThe protocol records runner facts in `artifact-evidence.json`; it does not\nrequire a specific runner class.\n\n## CLI\n\nGenerate a local release passport bundle from release assets:\n\n```bash\nbuildchain collect github-release \\\n  --tag v3.0.0 \\\n  --repository kungfu-systems/buildchain \\\n  --assets-dir dist \\\n  --publish-evidence-json .buildchain/release-evidence/v3.0.0/evidence.json \\\n  --transaction-json .buildchain/release-state/v3.0.0/state.json \\\n  --package-set-json package-set.json \\\n  --anchor-manifest-json libnode.release.json \\\n  --build-summary-json .buildchain/artifacts/build-summary.json \\\n  --build-facts-json .buildchain/facts/native-core.json \\\n  --build-facts-json .buildchain/facts/product.json \\\n  --platform-manifest-json .buildchain/artifacts/linux-x64/manifest.json \\\n  --platform-manifest-json .buildchain/artifacts/darwin-arm64/manifest.json \\\n  --platform-manifest-json .buildchain/artifacts/win32-x64/manifest.json \\\n  --dist-tag-evidence-json .buildchain/release-evidence/v3.0.0/dist-tag-evidence.json \\\n  --kfd-1-witness-json .buildchain/kfd/kfd-1/contract-world.witness.json \\\n  --kfd-2-claim-json .buildchain/kfd/kfd-2/release-claims.json \\\n  --invariant-passport-json product/release/qualification/invariant-passport.json \\\n  --github-artifact-attestation-policy-json .buildchain/github-artifact-attestation/policy.json \\\n  --output-dir .buildchain/release-passport\n```\n\nFor a promotion workflow, consumers can instead use\n`release-passport-invariant-passport-command`. The command must emit exactly one\ncanonical JSON object on stdout; for example:\n\n```yaml\nrelease-passport-invariant-passport-command: >-\n  node scripts/kungfu-invariant.mjs --collect-evidence .\n  --passport product/release/qualification/invariant-passport.json --json\n```\n\nSupplying the input makes the invariant gate mandatory. Command failure,\nmissing output, semantic-root drift, a non-`verified` verdict, incomplete\ncoverage, dirty source state, or a source revision unrelated to the release\nfails closed before release publication.\n\n`packageSet` records the ordered main-plus-platform package set.\n`publish.packages[]` summarizes each published npm package with its version,\ndist-tag, registry, role, platform, and digest, so agents do not need to stitch\nnpm facts back together from the lower-level evidence files.\n`buildSummary`, `platformArtifactManifests`, and `distTagPromotion` preserve the\nbuild and npm dist-tag evidence chain in the same passport. `buildFacts[]`\nrecords first-class module/product build facts, while\n`evidence.buildFacts[]` gives agents compact paths, SHA-256 hashes, contracts,\nids, and digests for quick audit traversal. See\n[`build-facts.md`](build-facts.md) for the fact collection and verification\ncontract.\n\n### KFD-1 contract-world release gate\n\nBuildchain can gate release artifacts with KFD-1 contract-world witnesses. This\nis a structured evidence protocol, not a request for consumers to shell out to\nthe Kungfu SDK. The authority chain is:\n\n1. KFD owns the standard metadata and schema ids in `@kungfu-tech/kfd`.\n2. Buildchain imports that metadata, owns the JSON formatting policy, freezes\n   the pre-build witness, and independently verifies post-build artifact bytes.\n3. Consumers only pass declarative witness JSON plus the artifact payloads their\n   build already produced.\n\nThis gives agents a concrete answer to \"what changed and can I trust it?\" A\nrelease can include both normal release passport evidence and KFD-1 evidence:\nthe passport proves the release transaction and artifacts are complete, while\nKFD-1 proves selected contract-world surfaces inside those artifacts are the\nbyte-for-byte surfaces the release intended to ship.\n\nThe witness JSON names the contract world, the canonical serialization policy,\nand the release surfaces that must be byte-for-byte verified:\n\n```json\n{\n  \"id\": \"kungfu-config\",\n  \"standard\": \"kfd-1\",\n  \"source\": \"kfd\",\n  \"contractWorld\": {\n    \"id\": \"kungfu-config\",\n    \"kind\": \"schema\",\n    \"name\": \"Kungfu config schema\"\n  },\n  \"canonicalPolicy\": {\n    \"format\": \"json\",\n    \"encoding\": \"utf-8\",\n    \"indent\": 2,\n    \"trailingNewline\": true\n  },\n  \"surfaces\": [\n    {\n      \"id\": \"kungfu-config-schema\",\n      \"artifactPath\": \"Contents/Resources/core/config.schema.json\",\n      \"expectedSha256\": \"...\"\n    }\n  ]\n}\n```\n\n`collect github-release` writes the result under the KFD-provided top-level key\ncurrently named `kfd-1`. Each contract world records the frozen witness digest,\nthe KFD package version, KFD schema ids, the Buildchain formatting policy, and\nthe actual artifact digest observed after the build. Verification fails closed\nwhen the witness is missing required facts, an artifact cannot be found, or a\npost-build digest does not match the frozen witness.\n\nFor the KFD repository itself, the KFD-1 witness can be a self-hosted standard\ncontract witness. In that mode KFD owns the standard-contract facts and\nBuildchain verifies declared source standard metadata, schemas, package\nexports, and site-consumption entrypoints against the packaged artifact. The\npassport records source and artifact hash summaries, schema ids, the\nself-hosting boundary, result, residual risk, and responsibility state for\nsource ownership, artifact verification, and release-passport proof ownership.\n\nGood KFD-1 witnesses should point at release payload surfaces, not at private\nbuild-machine state. For Buildchain itself, the natural witness set is the\nrelease passport schema and implementation, KFD-1 gate implementation,\n`dist/site/buildchain-contract.json`, and the npm package payload files that\nexpose the public CLI, reusable workflow/action contracts, and site facts.\nThe final `buildchain.release.json` file should not be used as an ordinary\nbyte-for-byte KFD surface because it contains KFD evidence; instead, the\npassport is audited through release-state SHA, `check-report.json`, and the\ncontract files that generate and verify it.\n\n### KFD-2 release trust passport audit\n\nBuildchain can write a KFD-2 release trust passport audit under the top-level\n`kfd-2` section. The section is generated automatically from KFD-1 and KFD-3\nrelease-gate evidence, and callers may add explicit public release claims with\n`--kfd-2-claim-json`.\n\nEvery public claim must bind:\n\n- declared sources;\n- machine-readable evidence;\n- source/evidence/artifact hashes;\n- artifact coordinates;\n- verification results;\n- audit boundary;\n- responsibility state;\n- residual risk, even when the array is empty.\n\nUnbound public claims fail release passport verification. Claims that are\nmachine-bound but only supported by prose downgrade the KFD-2 audit and produce\na warning, so agents can distinguish \"verified\", \"needs review\", and \"not\nbound to evidence\" without reading release notes.\n\nFor Buildchain's own releases, public release claims are not authored in prose\ninside the workflow. The source registry is\n`packages/core/buildchain-kfd-claims.js`, published as\n`dist/site/kfd-claims.json` and exported as\n`@kungfu-tech/buildchain/buildchain-kfd-claims`. That registry is the\nversion-invariant source of public claims and collaboration surfaces: it does\nnot store the exact release version, promotion SHA, or exact runtime contract\ndigest. Those run-specific facts belong in the release passport and generated\nwitnesses. During Buildchain promotion,\n`scripts/generate-buildchain-kfd-witnesses.mjs` binds the source registry to the\ncurrent source/artifact hashes and generates:\n\n- a KFD-1 self contract-world witness for the packaged docs, schemas, workflows,\n  actions, Node exports, and site-consumption facts;\n- one KFD-2 claim JSON per public Buildchain release claim;\n- KFD-3 pre-build and artifact witnesses for the same public collaboration\n  surfaces.\n\nThe generated claim set covers Buildchain's KFD release passport support,\nagent-first single source of truth, floating `@v3` contract drift protection,\nsemver GitHub Release evidence publication, channel-preserving release\npropagation, and npm publish evidence/finalization. Buildchain self promotion\npasses those files into `promote-buildchain-ref`; `verifyReleasePassport()` then\nfails closed if any claim is missing source bindings, machine evidence, hashes,\nartifact coordinates, verification result, audit boundary, responsibility, or\nresidual risk.\n\n### KFD-3 collaboration-interface release gate\n\nKFD-3 asks a different release question than KFD-1. KFD-1 proves that named\npayload bytes match one contract world. KFD-3 proves that a product's shipped\nparticipant-facing collaboration/control surface is closed over its declared\ninterface.\n\nFor Buildchain itself, the declared interface starts in\n`packages/core/buildchain-kfd-claims.js`, not in this Markdown file. The\nregistry enumerates public human/agent surfaces across manuals, schema and\nstandard metadata, package exports, site-consumption contracts, workflows, and\nactions. `dist/site/kfd-claims.json` is the packaged machine-readable form used\nby downstream sites and by Buildchain's own release passport. Exact release\nversion/SHA binding is deliberately deferred to the promotion witness, so the\nsource registry can remain stable across semver version-state bumps.\n\nBuildchain also performs a reverse audit before that witness is used. The\ngenerated `dist/site/public-surface-audit.json` enumerates real CLI commands\nfrom `bin/buildchain.mjs`, workflow inputs, action inputs, site pages, and docs\ncommand references, then compares them with the generated registries. Buildchain\nself KFD witnesses include that audit result and classify the collaboration\ninterface as closed-world only when the reverse audit passes. If a public\ncommand, workflow input, action input, or site page is exposed without a\nregistry entry, `pnpm run check` fails before release promotion can produce a\npassport.\n\nThe product remains the fact source. Before build/publish, the product writes a\npre-build witness:\n\n```bash\nkungfu sdk collaboration-interface witness --json \\\n  > .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json\n```\n\nThat witness must contain, or point to, the product-owned KFD-3 collaboration\ninterface, registry digest, participants, and declared public shipped surfaces.\nKFD repository self-verification can declare the same facts as grouped machine\nsurfaces: docs, schemas, standards metadata, package exports, and\nsite-consumption contracts.\nAfter the artifact is built, the product also provides artifact-side evidence,\neither as a JSON file or a command:\n\n```bash\nbuildchain collect github-release \\\n  --kfd-3-prebuild-witness-json .buildchain/kfd/kfd-3/collaboration-interface.prebuild.json \\\n  --kfd-3-artifact-verify-cmd \"kungfu agent verify --json\"\n```\n\nBuildchain imports the KFD-3 metadata from `@kungfu-tech/kfd`, freezes the\npre-build witness digest, ingests the artifact witness, and compares the two\nsets:\n\n- every declared `shipped` public participant-facing surface must appear in the\n  artifact witness;\n- every artifact-exposed public participant-facing surface must be declared by\n  the pre-build witness;\n- if both witnesses record `collaborationInterface.digest`, the digests must\n  match;\n- contradictory, missing, stale, or schema-incomplete evidence fails closed.\n\nThe generated release passport records the result under the KFD-provided\ntop-level key currently named `kfd-3`. The section includes the KFD package\nversion, schema ids/paths, pre-build witness digest, artifact witness digest,\ndeclared/exposed surface counts, missing declared shipped surfaces, and\nunclassified artifact public surfaces. Buildchain also projects the same\ncollaboration-interface evidence into the top-level `kfd-2` audit as a\nmachine-readable `trustProof` object on the generated `kfd-3:*` public claim.\nThat proof carries `releaseStatus`, witness file hashes and canonical hashes,\ndeclared capability verification, reverse audit result and boundary, residual\nrisk, and responsibility state.\n\nThe trust proof makes the strongest claim only when the witnesses justify it:\n`No unclassified reachable surface within the declared audit boundary.` If the\nproduct declares non-exhaustive surfaces, Buildchain keeps the passport\nverifiable but marks the interface `audited` instead of `enforced` and records\nthe residual risk explicitly. Draft or partial KFD-3 declarations are\ndowngraded; missing declared capabilities, undeclared public artifact surfaces,\nor stale collaboration-interface digests fail the proof.\n\nThis makes KFD-3 support usable by readers and agents immediately: they can\ninspect `buildchain.release.json` and know whether the released package\nactually exposes no more and no less than the declared collaboration interface,\ninstead of trusting docs or release notes.\n\n### KFD support projection\n\nPass `--kfd-support-matrix-json` together with three\n`--kfd-product-gate-json` arguments for KFD-4, KFD-5, and KFD-7. The collector\nverifies the product-owned KFD-1..13 matrix against the installed\n`@kungfu-tech/kfd` standards, binds each gate to the exact release source and\nfresh evidence cut, and emits `kfd-support.json`. The identical projection is\nembedded as `kfdSupport` in `buildchain.release.json`.\n\nRelease verification fails closed when the sibling is missing or differs,\nwhen a gate expires, when matrix and gate status disagree, or when a matrix\nwidens KFD-4/5 candidate, KFD-6 unsupported, KFD-8..13 draft, or any non-shipped\nstate. A passed projection is release evidence only; product qualification,\nactivation, certification, and support ownership remain outside Buildchain.\n\n### Floating Buildchain contract lock\n\nKFD-1 protects release payload surfaces. Floating ref contract locks protect the\nconsumer's relationship to Buildchain itself. A consumer can keep\n`.buildchain/contract-lock.json` with the Buildchain floating ref it accepted,\nthe resolved SHA, the contract digest, and the compatibility policy. Each\nBuildchain run reads the actual contract from the checked-out Buildchain ref\nand compares it before heavy build or publish work begins.\n\nCompatible drift, such as optional inputs or extra diagnostics, continues and\ncreates a consumer-local issue for review. Breaking drift fails fast. This means\nconsumers can use `@v3` without silently accepting incompatible changes, while\nBuildchain maintainers can still ship compatible improvements under the same\nmajor floating tag.\n\n`impact.json` can be supplied with `--impact-json`. Production release\npassports (`release/*`) and major publish-gate passports require\n`surfaceImpacts[]`; alpha, local, and legacy passport contexts keep the field\noptional. When `surfaceImpacts[]` is required or supplied, verification fails\nclosed unless each entry has an id, impact, and rationale, and\n`versionImpact.final` matches the highest surface impact. For example, KFD-2\ncontent can remain patch while an additive `registry.kind` field on the\nmachine-consumed KFD registry schema records a minor `kfd-registry-schema`\nsurface impact.\n\nPromote-only stable publication may omit an explicit impact ledger only when\nthe downloaded PR-stage release-candidate passport proves exact tree\nequivalence. Buildchain then records a patch-level release-governance impact\nbound to that candidate. Missing, stale, or non-equivalent candidate evidence\ndoes not receive this fallback and remains fail-closed.\n\nVerify a release passport:\n\n```bash\nbuildchain verify release-passport .buildchain/release-passport/buildchain.release.json\n```\n\nVerify a specific artifact by discovering its detached passport:\n\n```bash\nbuildchain verify artifact ./Kungfu-2.8.0-windows-x64.exe\n```\n\nArtifact verification is subject-centric. Buildchain identifies the subject,\ncomputes or obtains its digest, discovers a detached `buildchain.release.json`,\nverifies that release passport and its evidence, then proves the subject digest\nappears in the passport's artifacts, package set, publish evidence, or artifact\nevidence. The command returns `pass`, `fail`, or `unverifiable`; missing\npassports and digest mismatches fail closed.\n\nFor npm subjects, Buildchain treats the registry as the package digest source:\n`npm:<name>@<version>` resolves `dist.integrity` and matches it against\n`packageSet.main.digest`, `packageSet.platforms[].digest`, and publish evidence.\nUse `--npm-registry <url>` when the package comes from a non-default registry.\n\nDiscovery is ordered and auditable:\n\n1. explicit `--passport`;\n2. sidecar pointer;\n3. embedded/package pointer;\n4. local config or org index;\n5. GitHub Release default from artifact naming/repository/tag hints;\n6. custom locator;\n7. unverifiable with retry guidance.\n\nFor Buildchain-managed GitHub Release lanes, release passport files are\npublished as release assets by default when the upload backend is enabled, so a\nGitHub Release asset URL can discover the sibling `buildchain.release.json`\nwithout a consumer copying YAML resolver logic.\n\nExplain a release to an agent:\n\n```bash\nbuildchain explain release \\\n  --passport .buildchain/release-passport/buildchain.release.json \\\n  --for agent \\\n  --json\n```\n\nThe verifier fails closed when a passport omits artifacts, omits evidence, has\ndigest mismatches, or misses required protocol files.\n\n## Binary Distribution\n\nInitial binary distribution stays lightweight:\n\n- GitHub Release assets.\n- `checksums.txt`.\n- release passport artifacts.\n- a single release evidence bundle.\n- install scripts and Homebrew tap fixtures after the passport path is reliable.\n\nBuildchain publishes platform-specific archives, not loose top-level\nexecutables:\n\n- `buildchain-x86_64-unknown-linux-gnu.tar.gz`\n- `buildchain-aarch64-apple-darwin.tar.gz`\n- `buildchain-x86_64-pc-windows-msvc.zip`\n\nThe executable name inside each archive stays natural for the platform\n(`buildchain` or `buildchain.exe`). Top-level loose executable assets are not\nuploaded, because Linux and macOS would otherwise collide when GitHub Actions\nmatrix artifacts are merged.\n\nHeavy package manager channels such as apt, yum, winget, choco, Scoop, mise, or\nasdf are out of the P0/P1 scope until there is real external demand.\n\nStandalone binaries are a distribution shape, not a second implementation. The\nsource of truth remains the Node/ESM CLI and core library.\n\nThe standalone binary builder imports `@kungfu-tech/buildchain/logging` directly\nand records setup, SEA blob generation, injection, signing, archiving, manifest,\nand evidence phases. The GitHub workflow wraps the same build and passport\nsteps with `buildchain mark`, `buildchain span`,\n`buildchain verify observability-log`, and `buildchain log summary`. Logging is\na hard release gate: missing events, error events, or missing required phases\nfail the job before assets are uploaded. The verified logs are release assets\nand are covered by the release passport digest checks.\n\nSee also [`binary-distribution.md`](binary-distribution.md) for asset naming and\nbundle details, and [`install.md`](install.md) for consumer commands."
     },
     {
       "id": "manual:release-propagation",
@@ -1889,7 +1970,7 @@
       ],
       "maturity": "preview",
       "sourcePath": "docs/release-propagation.md",
-      "digest": "sha256:b7d2deef7d50fc412aa21c7ef1019c4c2bd8b0392b9b323356b1c0b1fc2596b6",
+      "digest": "sha256:aea013d923a8d419fc76e99a81765f281640dd95141d32ae415b8572604e9d32",
       "headings": [
         {
           "level": 1,
@@ -1922,7 +2003,7 @@
           "anchor": "kfd-to-site-libkungfu-dev"
         }
       ],
-      "markdown": "# Release Propagation\n\nRelease propagation lets a finalized upstream release open a downstream update\nPR using the upstream release passport as the audit source. It is for product\nchains such as:\n\n```text\nkfd -> site-libkungfu-dev\nA -> B -> C\n```\n\nThe downstream repository receives an exact lock, not a floating dist-tag. A\nsite or app can then consume the upstream package, site bundle, or release\npassport as its single source of truth without hand-copying release facts.\n\n## Contract\n\nThe propagation graph is declarative JSON:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"contract\": \"kungfu-buildchain-release-propagation-graph\",\n  \"nodes\": [\n    {\n      \"id\": \"kfd\",\n      \"repository\": \"kungfu-systems/kfd\",\n      \"package\": \"@kungfu-tech/kfd\"\n    },\n    {\n      \"id\": \"site-libkungfu-dev\",\n      \"repository\": \"kungfu-systems/site-libkungfu-dev\",\n      \"lockPath\": \"buildchain.upstreams/kfd.release.json\",\n      \"baseRef\": \"dev/v2/v2.7\"\n    }\n  ],\n  \"edges\": [\n    {\n      \"id\": \"kfd-to-site\",\n      \"from\": \"kfd\",\n      \"to\": \"site-libkungfu-dev\",\n      \"channelPolicy\": \"preserve\"\n    }\n  ]\n}\n```\n\n`channelPolicy: \"preserve\"` is the default and maps:\n\n```text\nalpha   -> alpha\nrelease -> release\n```\n\nCross-channel mapping is allowed only when an edge declares\n`channelPolicy: \"explicit\"` and a `channelMap`. Buildchain rejects cycles so a\nchain can fan out or continue as `A -> B -> C`, but cannot loop back into an\nalready visited release line.\n\n## Upstream Release Envelope\n\nThe upstream release envelope is the post-finalization fact set:\n\n```json\n{\n  \"repository\": \"kungfu-systems/kfd\",\n  \"channel\": \"alpha\",\n  \"tag\": \"v1.4.0-alpha.3\",\n  \"sourceSha\": \"1111111111111111111111111111111111111111\",\n  \"package\": {\n    \"name\": \"@kungfu-tech/kfd\",\n    \"version\": \"1.4.0-alpha.3\",\n    \"integrity\": \"sha512-...\"\n  },\n  \"releasePassport\": {\n    \"url\": \"https://github.com/kungfu-systems/kfd/releases/download/v1.4.0-alpha.3/buildchain.release.json\",\n    \"sha256\": \"2222222222222222222222222222222222222222222222222222222222222222\"\n  },\n  \"siteBundle\": {\n    \"manifestSha256\": \"3333333333333333333333333333333333333333333333333333333333333333\"\n  }\n}\n```\n\nThe package version and integrity must be exact. Downstream build logic should\ninstall that version directly, not resolve `alpha` or `latest` again.\n\nPublication repositories can propagate immutable publication archive evidence\nwithout npm package facts. The upstream envelope then includes\n`publicationArtifact`:\n\n```json\n{\n  \"repository\": \"kungfu-systems/paper-observer-declared-timelines\",\n  \"channel\": \"alpha\",\n  \"tag\": \"v0.1.0-alpha.1\",\n  \"sourceSha\": \"4444444444444444444444444444444444444444\",\n  \"releasePassport\": {\n    \"url\": \"https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/buildchain.release.json\",\n    \"sha256\": \"5555555555555555555555555555555555555555555555555555555555555555\"\n  },\n  \"publicationArtifact\": {\n    \"id\": \"observer-declared-timelines\",\n    \"kind\": \"paper\",\n    \"version\": \"0.1.0-alpha.1\",\n    \"canonicalUrl\": \"https://papers.libkungfu.dev/observer-declared-timelines/\",\n    \"latestUrl\": \"https://papers.libkungfu.dev/observer-declared-timelines/latest/\",\n    \"latestEvidenceUrl\": \"https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json\",\n    \"immutableVersionUrl\": \"https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0-alpha.1/\",\n    \"registry\": {\n      \"url\": \"https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/publication-registry.json\",\n      \"sha256\": \"6666666666666666666666666666666666666666666666666666666666666666\"\n    },\n    \"manifest\": {\n      \"url\": \"https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/publication-artifact.json\",\n      \"sha256\": \"7777777777777777777777777777777777777777777777777777777777777777\"\n    },\n    \"passport\": {\n      \"url\": \"https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/publication-artifact-passport.json\",\n      \"sha256\": \"8888888888888888888888888888888888888888888888888888888888888888\"\n    },\n    \"primaryArtifact\": {\n      \"path\": \"_build/main.pdf\",\n      \"url\": \"https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0-alpha.1/main.pdf\",\n      \"sha256\": \"9999999999999999999999999999999999999999999999999999999999999999\"\n    }\n  }\n}\n```\n\nThis lets a site repository render the latest reader page and historical\nversion index from release facts while keeping old PDFs, source bundles,\nmanifests, and passports immutable.\n\n## CLI\n\nGenerate a propagation plan:\n\n```bash\nbuildchain release-propagation plan \\\n  --graph buildchain.release-propagation.json \\\n  --upstream-release .buildchain/upstream-release.json \\\n  --output .buildchain/release-propagation-plan.json \\\n  --json\n```\n\nWrite the downstream lock:\n\n```bash\nbuildchain release-propagation write-lock \\\n  --plan .buildchain/release-propagation-plan.json \\\n  --target site-libkungfu-dev \\\n  --cwd downstream-checkout \\\n  --json\n```\n\nThe written lock has contract\n`kungfu-buildchain-release-propagation-lock` and records:\n\n- upstream repository, channel, exact tag, source SHA;\n- optional npm package name, exact version, and sha512 integrity;\n- optional publication artifact canonical/latest/immutable URLs, registry,\n  manifest, passport, source bundle, and primary artifact digests;\n- release passport URL and SHA-256;\n- optional site bundle manifest SHA-256;\n- downstream repository, channel, base ref, lock path;\n- edge id and channel policy.\n\n## Reusable Workflow\n\nUpstream repositories can call\n`.github/workflows/release-propagation.yml@v3` after release finalization:\n\n```yaml\njobs:\n  propagate-site:\n    uses: kungfu-systems/buildchain/.github/workflows/release-propagation.yml@v3\n    with:\n      buildchain-ref: v3\n      graph-json: ${{ needs.release.outputs.propagation-graph-json }}\n      upstream-release-json: ${{ needs.release.outputs.upstream-release-json }}\n      downstream-target: site-libkungfu-dev\n      downstream-repository: kungfu-systems/site-libkungfu-dev\n      downstream-base-ref: main\n      downstream-prepare-command: pnpm install --frozen-lockfile --ignore-scripts\n      downstream-verify-command: pnpm run check\n      dry-run: false\n    secrets:\n      propagation-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n```\n\nThe downstream branch name may be reused across upstream releases. Before\nreplacing an existing managed branch, the workflow reads its exact remote SHA\nand pushes with an explicit `--force-with-lease=<ref>:<sha>`. A surviving branch\nfrom a merged PR is therefore reconciled without manual deletion, while a\nconcurrent writer makes the lease fail closed. The controller receipt includes a\n`propagation-branch-reconciliation` evidence file recording the branch, observed\nremote SHA, pushed SHA, lease mode, and the deterministically created or updated\nopen PR.\n\nThe workflow checks out the Buildchain runtime selected by\n`buildchain-repository` and `buildchain-ref` into `.buildchain/runtime`, invokes\nthat runtime for the propagation plan and lock write, then checks out the\ndownstream repository and writes the exact lock. A consumer that must pin the\nexact upstream package or regenerate deterministic files declares\n`downstream-prepare-command`. The command receives\n`BUILDCHAIN_UPSTREAM_PACKAGE_NAME`, `BUILDCHAIN_UPSTREAM_PACKAGE_VERSION`, and\n`BUILDCHAIN_UPSTREAM_RELEASE_LOCK`. After preparation, Buildchain refreshes an\nexisting `<!-- buildchain:badges:start -->` README block by default. Consumers\ncan disable that step with `refresh-managed-readme-badges: false`.\n\n`downstream-verify-command` runs against the final tree before any commit or\npush, so consumers can use the same check as their PR workflow. Preparation,\nbadge refresh, and verification failures all fail closed. The workflow stages\nthe complete deterministic result, signs the propagation commit with DCO, and\nthen opens or updates the PR. It does not publish the downstream release\ndirectly. The downstream repository keeps its normal Buildchain governance: the\nPR updates source-of-truth facts, then downstream alpha or release publication\nruns through its own protected channel. A byte-identical rerun is an explicit\nsuccessful no-op.\nFor unreleased runtime validation, keep the caller's reusable workflow reference\non `@v3` and pass a temporary train ref through `buildchain-ref`.\n\n## kfd to site-libkungfu-dev\n\nFor `kfd -> site-libkungfu-dev`, the graph should preserve channels:\n\n- a `kfd` alpha release produces a downstream alpha lock and downstream alpha\n  publication consumes the exact `@kungfu-tech/kfd@...-alpha.N` package;\n- a `kfd` stable release produces a downstream release lock and downstream\n  stable publication consumes the exact stable package.\n\nThis keeps the site synchronized to the package truth without allowing the site\nto drift onto a floating npm dist-tag."
+      "markdown": "# Release Propagation\n\nRelease propagation lets a finalized upstream release open a downstream update\nPR using the upstream release passport as the audit source. It is for product\nchains such as:\n\n```text\nkfd -> site-libkungfu-dev\nA -> B -> C\n```\n\nThe downstream repository receives an exact lock, not a floating dist-tag. A\nsite or app can then consume the upstream package, site bundle, or release\npassport as its single source of truth without hand-copying release facts.\n\n## Contract\n\nThe propagation graph is declarative JSON:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"contract\": \"kungfu-buildchain-release-propagation-graph\",\n  \"nodes\": [\n    {\n      \"id\": \"kfd\",\n      \"repository\": \"kungfu-systems/kfd\",\n      \"package\": \"@kungfu-tech/kfd\"\n    },\n    {\n      \"id\": \"site-libkungfu-dev\",\n      \"repository\": \"kungfu-systems/site-libkungfu-dev\",\n      \"lockPath\": \"buildchain.upstreams/kfd.release.json\",\n      \"baseRef\": \"dev/v2/v2.7\"\n    }\n  ],\n  \"edges\": [\n    {\n      \"id\": \"kfd-to-site\",\n      \"from\": \"kfd\",\n      \"to\": \"site-libkungfu-dev\",\n      \"channelPolicy\": \"preserve\"\n    }\n  ]\n}\n```\n\n`channelPolicy: \"preserve\"` is the default and maps:\n\n```text\nalpha   -> alpha\nrelease -> release\n```\n\nCross-channel mapping is allowed only when an edge declares\n`channelPolicy: \"explicit\"` and a `channelMap`. Buildchain rejects cycles so a\nchain can fan out or continue as `A -> B -> C`, but cannot loop back into an\nalready visited release line.\n\n## Upstream Release Envelope\n\nThe upstream release envelope is the post-finalization fact set:\n\n```json\n{\n  \"repository\": \"kungfu-systems/kfd\",\n  \"channel\": \"alpha\",\n  \"tag\": \"v1.4.0-alpha.3\",\n  \"sourceSha\": \"1111111111111111111111111111111111111111\",\n  \"package\": {\n    \"name\": \"@kungfu-tech/kfd\",\n    \"version\": \"1.4.0-alpha.3\",\n    \"integrity\": \"sha512-...\"\n  },\n  \"releasePassport\": {\n    \"url\": \"https://github.com/kungfu-systems/kfd/releases/download/v1.4.0-alpha.3/buildchain.release.json\",\n    \"sha256\": \"2222222222222222222222222222222222222222222222222222222222222222\"\n  },\n  \"siteBundle\": {\n    \"manifestSha256\": \"3333333333333333333333333333333333333333333333333333333333333333\"\n  }\n}\n```\n\nThe package version and integrity must be exact. Downstream build logic should\ninstall that version directly, not resolve `alpha` or `latest` again.\n\nPublication repositories can propagate immutable publication archive evidence\nwithout npm package facts. The upstream envelope then includes\n`publicationArtifact`:\n\n```json\n{\n  \"repository\": \"kungfu-systems/paper-observer-declared-timelines\",\n  \"channel\": \"alpha\",\n  \"tag\": \"v0.1.0-alpha.1\",\n  \"sourceSha\": \"4444444444444444444444444444444444444444\",\n  \"releasePassport\": {\n    \"url\": \"https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/buildchain.release.json\",\n    \"sha256\": \"5555555555555555555555555555555555555555555555555555555555555555\"\n  },\n  \"publicationArtifact\": {\n    \"id\": \"observer-declared-timelines\",\n    \"kind\": \"paper\",\n    \"version\": \"0.1.0-alpha.1\",\n    \"canonicalUrl\": \"https://papers.libkungfu.dev/observer-declared-timelines/\",\n    \"latestUrl\": \"https://papers.libkungfu.dev/observer-declared-timelines/latest/\",\n    \"latestEvidenceUrl\": \"https://papers.libkungfu.dev/observer-declared-timelines/latest/buildchain.release.json\",\n    \"immutableVersionUrl\": \"https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0-alpha.1/\",\n    \"registry\": {\n      \"url\": \"https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/publication-registry.json\",\n      \"sha256\": \"6666666666666666666666666666666666666666666666666666666666666666\"\n    },\n    \"manifest\": {\n      \"url\": \"https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/publication-artifact.json\",\n      \"sha256\": \"7777777777777777777777777777777777777777777777777777777777777777\"\n    },\n    \"passport\": {\n      \"url\": \"https://github.com/kungfu-systems/paper-observer-declared-timelines/releases/download/v0.1.0-alpha.1/publication-artifact-passport.json\",\n      \"sha256\": \"8888888888888888888888888888888888888888888888888888888888888888\"\n    },\n    \"primaryArtifact\": {\n      \"path\": \"_build/main.pdf\",\n      \"url\": \"https://papers.libkungfu.dev/archive/observer-declared-timelines/v0.1.0-alpha.1/main.pdf\",\n      \"sha256\": \"9999999999999999999999999999999999999999999999999999999999999999\"\n    }\n  }\n}\n```\n\nThis lets a site repository render the latest reader page and historical\nversion index from release facts while keeping old PDFs, source bundles,\nmanifests, and passports immutable.\n\nWhen the downstream consumer is expected to update an exact npm paper pin, the\nupstream envelope must carry both `package` and `publicationArtifact`. The\nconsumer can then prove that package name, version, sha512 integrity,\npublication URLs, and immutable artifact digests all describe the same release.\n`publicationArtifact` without `package` remains valid for evidence-only\npropagation, but it cannot qualify a package-pin fast path.\n\n## CLI\n\nGenerate a propagation plan:\n\n```bash\nbuildchain release-propagation plan \\\n  --graph buildchain.release-propagation.json \\\n  --upstream-release .buildchain/upstream-release.json \\\n  --output .buildchain/release-propagation-plan.json \\\n  --json\n```\n\nWrite the downstream lock:\n\n```bash\nbuildchain release-propagation write-lock \\\n  --plan .buildchain/release-propagation-plan.json \\\n  --target site-libkungfu-dev \\\n  --cwd downstream-checkout \\\n  --json\n```\n\nThe written lock has contract\n`kungfu-buildchain-release-propagation-lock` and records:\n\n- upstream repository, channel, exact tag, source SHA;\n- optional npm package name, exact version, and sha512 integrity;\n- optional publication artifact canonical/latest/immutable URLs, registry,\n  manifest, passport, source bundle, and primary artifact digests;\n- release passport URL and SHA-256;\n- optional site bundle manifest SHA-256;\n- downstream repository, channel, base ref, lock path;\n- edge id and channel policy;\n- a deterministic propagation key and branch derived from the exact upstream\n  repository/version/channel plus downstream repository.\n\nRepeated runs for the same release identity reuse that branch and lock. A\ndifferent release version or channel receives a different branch, so concurrent\nreleases cannot collapse into one mutable propagation PR.\n\nCreate the exact propagation receipt after the lock/PR outcome is known:\n\n```bash\nbuildchain release-propagation receipt \\\n  --plan .buildchain/release-propagation-plan.json \\\n  --lock-result .buildchain/release-propagation-write-lock.json \\\n  --pr-outcome .buildchain/release-propagation-pr-outcome.json \\\n  --target site-libkungfu-dev \\\n  --output .buildchain/release-propagation-receipt.json \\\n  --json\n```\n\nThe receipt keeps four machine states separate:\n\n- `package-published`: exact npm name/version/integrity exists;\n- `alpha-complete`: the upstream alpha passport/tag is complete;\n- `staging-visible`: the downstream staging surface is actually visible;\n- `production-visible`: the production surface is actually visible.\n\nPackage publication or alpha completion never implies either visibility state.\n\n## Reusable Workflow\n\nUpstream repositories can call\n`.github/workflows/release-propagation.yml@v3` after release finalization:\n\n```yaml\njobs:\n  propagate-site:\n    uses: kungfu-systems/buildchain/.github/workflows/release-propagation.yml@v3\n    with:\n      buildchain-ref: v3\n      graph-json: ${{ needs.release.outputs.propagation-graph-json }}\n      upstream-release-json: ${{ needs.release.outputs.upstream-release-json }}\n      downstream-target: site-libkungfu-dev\n      downstream-repository: kungfu-systems/site-libkungfu-dev\n      downstream-base-ref: dev/v2/v2.7\n      downstream-update-command: >-\n        node scripts/paper-propagation.cjs consume\n        --lock \"$BUILDCHAIN_PROPAGATION_LOCK_PATH\"\n        && corepack pnpm install --lockfile-only --ignore-scripts\n      downstream-prepare-command: pnpm install --frozen-lockfile --ignore-scripts\n      downstream-verify-command: pnpm run check\n      dry-run: false\n    secrets:\n      propagation-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n```\n\nThe downstream branch name may be reused across upstream releases. Before\nreplacing an existing managed branch, the workflow reads its exact remote SHA\nand pushes with an explicit `--force-with-lease=<ref>:<sha>`. A surviving branch\nfrom a merged PR is therefore reconciled without manual deletion, while a\nconcurrent writer makes the lease fail closed. The controller receipt includes a\n`propagation-branch-reconciliation` evidence file recording the branch, observed\nremote SHA, pushed SHA, lease mode, and the deterministically created or updated\nopen PR.\n\nThe workflow checks out the Buildchain runtime selected by\n`buildchain-repository` and `buildchain-ref` into `.buildchain/runtime`, invokes\nthat runtime for the propagation plan and lock write, then checks out the\ndownstream repository and writes the exact lock. If\n`downstream-update-command` is set, Buildchain runs that consumer-owned command\nafter writing the lock and exposes the exact lock path, lock SHA-256,\npropagation key, branch, and upstream release JSON as\n`BUILDCHAIN_PROPAGATION_*` environment variables. The command is part of the\ndownstream PR diff; it is not a deployment hook.\n\nA consumer that must perform further deterministic preparation can declare\n`downstream-prepare-command`. The command receives\n`BUILDCHAIN_UPSTREAM_PACKAGE_NAME`, `BUILDCHAIN_UPSTREAM_PACKAGE_VERSION`, and\n`BUILDCHAIN_UPSTREAM_RELEASE_LOCK`. After preparation, Buildchain refreshes an\nexisting `<!-- buildchain:badges:start -->` README block by default. Consumers\ncan disable that step with `refresh-managed-readme-badges: false`.\n\n`downstream-verify-command` runs against the final tree before any commit or\npush, so consumers can use the same check as their PR workflow. Update,\npreparation, badge refresh, and verification failures all fail closed. The\nworkflow stages the complete deterministic result, signs the propagation\ncommit with DCO, and then opens or updates the PR. It does not publish the\ndownstream release directly. The downstream repository keeps its normal\nBuildchain governance: the PR updates source-of-truth facts, then downstream\nalpha or release publication runs through its own protected channel. A\nbyte-identical rerun is an explicit successful no-op.\n\nFor unreleased runtime validation, keep the caller's reusable workflow reference\non `@v3` and pass a temporary train ref through `buildchain-ref`.\n\n## kfd to site-libkungfu-dev\n\nFor `kfd -> site-libkungfu-dev`, the graph should preserve channels:\n\n- a `kfd` alpha release produces a downstream alpha lock and downstream alpha\n  publication consumes the exact `@kungfu-tech/kfd@...-alpha.N` package;\n- a `kfd` stable release produces a downstream release lock and downstream\n  stable publication consumes the exact stable package.\n\nThis keeps the site synchronized to the package truth without allowing the site\nto drift onto a floating npm dist-tag."
     },
     {
       "id": "manual:reusable-build-surface",
@@ -1936,7 +2017,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/reusable-build-surface.md",
-      "digest": "sha256:ea36ec722f811f5156735aa7471ed080cdc7e87d71c20c300243b226e233e675",
+      "digest": "sha256:8908e1f1589537ac8ef82ee1dacdd24072ca871e3e245825669e7cfbdebd2e3d",
       "headings": [
         {
           "level": 1,
@@ -1983,6 +2064,11 @@
           "title": "Locked Source Checkout Cache",
           "anchor": "locked-source-checkout-cache"
         },
+        {
+          "level": 2,
+          "title": "Auditable Compiler Cache",
+          "anchor": "auditable-compiler-cache"
+        },
         {
           "level": 2,
           "title": "Workflow Outputs",
@@ -2039,7 +2125,7 @@
           "anchor": "fixture"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-reusable-build\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-27\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-27\n  invisible_context: not asserted\n---\n\n# Reusable Build Surface\n\nBuildchain v2 provides a reusable build workflow for repositories that need\nBuildchain's release semantics but cannot be described as a simple Node package.\nThe first target shape is `libnode`: expensive native builds, multiple operating\nsystems, self-hosted runner labels, and release artifacts that must be auditable.\n\nFor Linux release artifacts, the build workflow can hand the sealed artifact,\nplatform manifest, and Release Passport to the separate GitHub-hosted keyless\nattester. The compiler runner remains the recorded build identity; the attester\nonly signs and verifies immutable data. See\n[`github-artifact-attestation.md`](github-artifact-attestation.md).\n\n## Automatic Channel Router\n\nThe preferred consumer surface is one reusable workflow call. After v2.12\nreaches the stable major ref, consumers keep this configuration for both alpha\ndevelopment and stable release work:\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v3\n    permissions:\n      contents: read\n      issues: write\n      id-token: write\n    with:\n      working-directory: .\n      artifact-name: libnode\n      runner-preset: kungfu-v4-self-hosted\n      publish-channel: none\n    secrets: inherit\n```\n\n`buildchain-channel` defaults to `auto`. Selection uses this precedence:\n\n1. an explicit `buildchain-ref` protected authority, train, SHA, or official channel;\n2. an explicit `buildchain-channel: alpha|stable`;\n3. `publish-channel: alpha|release|major`;\n4. GitHub release prerelease metadata;\n5. a canonical semver tag;\n6. non-release PR, push, dispatch, schedule, and workflow-run events default to\n   alpha.\n\nThe resolved runtime is `vN-alpha` for development and prerelease intent and\n`vN` for stable release intent. Unknown custom publish channels, malformed\nrelease events, and non-semver release-like tags fail before the build matrix;\nthey never guess alpha for a stable release.\n\nThe router automatically selects `.buildchain/alpha-contract-lock.json` for\nalpha and `.buildchain/contract-lock.json` for stable. A repository can override\nthe common path with `buildchain-contract-lock-path`, or override one channel\nwith `buildchain-alpha-contract-lock-path` /\n`buildchain-stable-contract-lock-path`.\n\nOnly repositories changing the default policy need extra routing input:\n\n```yaml\nwith:\n  buildchain-channel: stable\n```\n\nDuring the v2.12 prerelease evaluation window, canaries use\n`build.yml@v3-alpha`. The same router then selects `v3-alpha` or stable `v2` as\nthe runtime. Production consumers should adopt `build.yml@v3` after the router\nhas reached stable; this keeps the routing shell itself on a stable ref.\n\nThe router is generated from `.build.yml`'s input/output surface. Run\n`node scripts/generate-channel-build-workflow.mjs` after changing the advanced\nbuild workflow; inventory and unit tests reject a stale generated router.\n\n## Advanced Workflow\n\nConsumers that need direct workflow-shell or runtime control call the advanced\nsurface:\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    with:\n      working-directory: .\n      artifact-name: libnode\n      runner-preset: kungfu-v4-self-hosted\n      linux-container-preset: kungfu-verify\n      artifact-name-template: \"{artifact}-{platform}-{sha}\"\n      artifact-paths: |\n        dist\n        build/stage\n      expected-artifacts-json: >-\n        {\"minFiles\":2,\"requiredPaths\":[\"dist/libnode.tar.gz\",\"dist/checksums.txt\"]}\n      process-summary-path: .buildchain/diagnostics/process-summary.json\n      release-candidate: true\n      publish-channel: release\n      publish-source-ref: publish-gate/release/v22/v22.22/22.22.3-kf.0\n```\n\n`runner-preset` is the stable first-class surface for known runner fleets:\n\n| Preset                  | Platforms                                                                |\n| ----------------------- | ------------------------------------------------------------------------ |\n| `github-hosted`         | `ubuntu-24.04`, `macos-latest`, `windows-2022`                                                              |\n| `kungfu-v4-self-hosted` | Kungfu Linux x64, macOS ARM64, and Windows x64 self-hosted runner labels                                    |\n| `kungfu-v4-native`      | Kungfu Linux x64, Linux ARM64, macOS ARM64, and Windows x64; Linux ARM64 uses GitHub-hosted `ubuntu-24.04-arm` |\n| `custom`                | Requires `platforms-json`                                                                                   |\n\nCallers can still provide a custom matrix with `platforms-json`. Each platform\nobject has:\n\n| Field    | Meaning                                           |\n| -------- | ------------------------------------------------- |\n| `id`     | Stable artifact/platform key, such as `linux-x64` |\n| `name`   | Human-readable job name                           |\n| `runner` | JSON string passed to `runs-on` after `fromJSON`  |\n\nThe runner field is intentionally a JSON string so callers can pass either\nGitHub-hosted runners or multi-label self-hosted runners without Buildchain\nguessing the labels.\n\nOnly include platforms that should run. GitHub schedules matrix jobs before\nsteps execute, so a disabled entry with unavailable runner labels can still\nblock the workflow queue.\n\n`fail-fast` defaults to `false`, preserving the diagnostic behavior that\ncollects every platform result. Required promotion callers can set it to `true`\nto cancel sibling native, container, and relay matrix lanes after the first\nfailure. This input changes scheduling only: it does not reduce the declared\nplatform matrix, turn cancellation into a pass, or alter artifact and release\nadmission.\n\n## Linux Job Containers\n\nLinux build platforms can run inside a digest-pinned job container while macOS\nand Windows keep using native runners. This is the recommended way to remove\nmoving Linux runner prerequisites from Buildchain consumers: the Linux host only\nneeds a GitHub Actions runner, Docker, and network access; common verification\ntools come from the image contract.\n\nUse the Kungfu verification image for lifecycle stages that need Git, jq,\nPython, uv, and fnm, but do not need native compilation:\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    with:\n      runner-preset: kungfu-v4-self-hosted\n      linux-container-preset: kungfu-verify\n```\n\n`kungfu-verify` resolves to:\n\n```text\nghcr.io/kungfu-systems/build-images/kungfu-verify@sha256:11f0ba64267ce88174a4f73a9bf833ff4e9c59cd16ec3d08a6432a06c2be6fb1\n```\n\nCallers that own a different Linux image can pass it explicitly:\n\n```yaml\nwith:\n  linux-container-preset: custom\n  linux-container-image: ghcr.io/example/project-build@sha256:<digest>\n```\n\n`linux-container-image` should be pinned by digest. A floating tag makes the\nrunner surface mutable and weakens Buildchain's release evidence.\n\nThe workflow splits the matrix into two build jobs:\n\n- Linux platforms go to `build-linux-container` when a Linux container is\n  configured.\n- All other platforms go to `build-native`.\n\nArtifact names, manifest paths, expected artifact checks, publish-source locks,\nand aggregate summaries are the same in both jobs. The split is an execution\ndetail, not a different artifact contract.\n\n## Native Rust Toolchains\n\nNative lifecycle jobs can request an isolated Rust installation instead of\ndepending on a self-hosted runner user's PATH:\n\n```yaml\nwith:\n  setup-rust: true\n  rust-toolchain: \"1.96.0\"\n  rustup-dist-server: \"https://rsproxy.cn\"\n  rustup-update-root: \"https://rsproxy.cn/rustup\"\n  cargo-registry-index: ${{ vars.BUILDCHAIN_CARGO_REGISTRY_INDEX }}\n```\n\n`setup-rust` defaults to `false`, so existing consumers are unchanged. When it\nis enabled, Buildchain installs `rust-toolchain` before the install, build, and\nverify lifecycle stages on every native matrix platform. Windows uses the\nofficial rustup bootstrap through `cmd.exe` and `curl.exe` into runner-temporary\nCargo and rustup homes, so it works under a restrictive PowerShell execution\npolicy and the service account does not depend on another user's PATH or mutate\nhost toolchain state. Pin an exact toolchain for release builds. Linux container jobs continue\nto obtain Rust from their digest-pinned image contract; Buildchain does not\nmutate that container surface.\n\nThe rustup server inputs are optional and default to Rust's official servers.\nConsumers behind a slow cross-border link may select a trusted transport mirror;\nrustup still verifies the selected toolchain's distribution metadata and\ncomponent checksums.\n\n`cargo-registry-index` is also optional. When set, Buildchain exposes it to\nCargo as `CARGO_REGISTRIES_CRATES_IO_INDEX` for every native lifecycle stage,\nso a self-hosted runner can use a repository or organization variable without\ncommitting private LAN topology to public workflow YAML. The endpoint must be a\ncrates.io-compatible index whose `config.json` download contract serves the\nmatching checksum-verified crate archives. An empty value preserves Cargo's\nnormal crates.io behavior.\n\nThe container image provides `fnm` but does not preinstall Node. Buildchain uses\n`fnm` inside the container to install the requested `node-version` before it\nruns Buildchain runtime scripts or lifecycle actions.\n\nDo not use `kungfu-verify` for stages that need CMake, Ninja, ccache, Conan, or\nDocker image publishing. Those should use a heavier native-build image or remain\non a host runner until their image contract is explicit.\n\n## Buildchain Runtime Override\n\nStable consumers should keep the reusable workflow pinned to stable refs such as\n`@v3`. The optional `buildchain-ref` input is empty by default; empty means\nBuildchain resolves and executes the stable runtime selected by the workflow\nshell. The full train validation protocol is documented in\n[`runtime-train-validation.md`](runtime-train-validation.md).\n\nFor one-off manual validation, a trusted maintainer can run the caller workflow\nwith a temporary runtime override:\n\n```yaml\non:\n  workflow_dispatch:\n    inputs:\n      buildchain-ref:\n        description: \"Temporary Buildchain runtime ref for trusted manual validation\"\n        required: false\n        default: \"\"\n\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    with:\n      buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n```\n\nAllowed override refs are deliberately narrow:\n\n| Ref form | Meaning |\n| --- | --- |\n| `train/v3/v3.0/<capability>` | Temporary capability train under the active minor line |\n| `refs/heads/train/v3/v3.0/<capability>` | Explicit branch ref for the same train |\n| `<40-character SHA>` | Exact immutable Buildchain runtime commit |\n\nOverride requests fail closed unless the event is `workflow_dispatch` and the\nactor has write, maintain, or admin permission on the caller repository.\nPull requests, including same-repository pull requests and fork-originated pull\nrequests, cannot use `buildchain-ref` override. This keeps automated PR builds on\nthe stable runtime surface.\n\nEvery run resolves the runtime ref to an immutable SHA before checkout. The job\nsummary and aggregate build summary record the workflow shell ref, requested\nruntime ref, resolved runtime ref, runtime SHA, stability class, trust decision,\nand rollback ref. Train refs are development validation refs: they do not move\n`v2`, `vX.Y`, `vX.Y-alpha`, npm dist-tags, or production release refs, and they\nmust not be pinned as long-term production dependencies.\n\nRuntime override validates Buildchain runtime scripts, CLI code, local actions,\nconfig parsing, and lifecycle behavior. It cannot validate changes that require\nthe outer reusable workflow YAML itself to change, such as new jobs,\npermissions, workflow outputs, or matrix topology. Those changes need a canary\nworkflow path or a temporary explicit workflow ref.\n\n## Floating Ref Contract Lock\n\nStable consumers should use floating major refs such as `@v3`, but a floating\nref is not blind trust. Each released Buildchain ref carries a package-owned\nruntime contract world in `dist/site/buildchain-contract.json`. Consumers may\nkeep a small lock file, `.buildchain/contract-lock.json`, recording the\nBuildchain ref, resolved SHA, contract digest, compatibility digest, accepted\nmajor line, and compatibility policy they reviewed.\n\nThe reusable build trust gate checks this lock before any heavy matrix job:\n\n1. resolve the Buildchain runtime ref, for example `v2`, to an immutable SHA;\n2. read `dist/site/buildchain-contract.json` from that checked-out Buildchain\n   ref;\n3. read the consumer's `.buildchain/contract-lock.json`;\n4. compare the accepted contract with the current contract.\n\nSHA drift alone is not a failure. `v2` is expected to advance. Buildchain only\nfails fast when the accepted contract is no longer compatible, for example a\nrequired input is removed, a required output disappears, a protected behavior\npromise changes, or the major line changes. Additive changes such as optional\ninputs, optional outputs, diagnostics, or documentation updates continue under\nthe default `major-compatible` policy.\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    permissions:\n      contents: read\n      issues: write\n      id-token: write\n    with:\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n      buildchain-contract-compatibility-policy: major-compatible\n      buildchain-contract-drift-issue-mode: compatible-and-breaking\n```\n\nWhen compatible drift is detected, the build continues and Buildchain opens or\nupdates a low-priority issue in the consumer repository. The issue records the\nold SHA/digest, new SHA/digest, compatibility result, workflow run, and the next\naction: review the Buildchain release notes and update the lock. When breaking\ndrift is detected, the same issue path is used, but the trust gate fails before\nmatrix build or publish work starts. If the workflow token cannot write issues,\nBuildchain writes a copyable issue body into the job summary.\n\nThe lock is intentionally small. It does not copy the full contract. The full\ncontract remains in the Buildchain ref and package; the consumer records only\nwhat it accepted and the policy used to compare future floating-ref movement.\n\nAdvanced alpha-channel consumers select the matching workflow shell:\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3-alpha\n    with:\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe runtime follows the called workflow through `job.workflow_ref`. Callers may\nalso pass `buildchain-ref: v3-alpha` explicitly; official floating refs are\nordinary channel selections and are allowed on pull requests and pushes. Train\nrefs and exact SHAs remain trusted manual overrides.\n\n## Shifu Cache Profile Passthrough\n\nBuildchain can carry one trusted Shifu cache-profile reference and its exact\ndigest into lifecycle execution. Its contract is an opaque reference and digest\nonly. This surface is deliberately opaque:\nBuildchain does not fetch the profile, parse JSON, select cache services,\nrewrite bindings, decide fallback, or emit Shifu resolution evidence. Those\nsemantics remain owned by the consumer's pinned Shifu implementation.\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v3\n    with:\n      shifu-cache-profile-ref: ${{ vars.SHIFU_CACHE_PROFILE_REF }}\n      shifu-cache-profile-digest: ${{ vars.SHIFU_CACHE_PROFILE_DIGEST }}\n```\n\nThe reusable workflow passes the pair as `SHIFU_CACHE_PROFILE_REF` and\n`SHIFU_CACHE_PROFILE_DIGEST` to install, build, and verify lifecycle commands.\nThe consumer must invoke its Shifu cache-aware execution surface. An empty pair\npreserves existing behavior; a consumer Shifu should fail closed when exactly\none value is present or the resolved bytes do not match the expected digest.\n\nUse trusted repository or organization variables rather than PR-controlled\nfiles for private/LAN references. The variables must remain secret-free; any\ncredentials use a separate provider-approved secret surface and must not be\nembedded in the profile reference. This passthrough is separate from\nBuildchain's locked source checkout cache below: Buildchain owns checkout\ntransport and source identity, while Shifu owns post-checkout execution cache\nbindings and receipts.\n\n## Locked Source Checkout Cache\n\nSelf-hosted runners that build large repositories can opt into a locked checkout\ncache for both the consumer source and the Buildchain runtime. This changes only\nthe Git object transport. Buildchain still resolves `publish-source-sha` and the\nruntime SHA before any build runner starts, checks out those exact commits, and\nverifies each final `HEAD` plus the resolved consumer source tree SHA before\nlifecycle commands run.\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    with:\n      runner-preset: kungfu-v4-self-hosted\n      checkout-cache-mode: auto\n      checkout-cache-mirror-url-template: ${{ vars.BUILDCHAIN_CHECKOUT_CACHE_MIRROR_URL_TEMPLATE }}\n      checkout-cache-reference-repository-template: ${{ vars.BUILDCHAIN_CHECKOUT_CACHE_REFERENCE_REPOSITORY_TEMPLATE }}\n      checkout-cache-fallback: github\n      checkout-cache-timeout-seconds: 60\n      checkout-cache-github-timeout-seconds: 600\n      checkout-cache-fetch-attempts: 3\n```\n\n`checkout-cache-mode` accepts:\n\n| Mode | Behavior |\n| --- | --- |\n| `off` | Default. Buildchain fetches the locked commit from GitHub. |\n| `auto` | Try the trusted cache first; on miss, record the miss and fall back according to `checkout-cache-fallback`. |\n| `require` | Require the cache to provide the locked commit and fail before lifecycle work if unavailable. |\n\nThe cache can be a local/LAN mirror URL template or a runner-local bare\nreference repository template. Templates support `{owner}`, `{repo}`,\n`{repository}`, `{repositorySlug}`, and `{sha}`. The workflow also reads\nrepository or organization variables named\n`BUILDCHAIN_CHECKOUT_CACHE_MIRROR_URL_TEMPLATE` and\n`BUILDCHAIN_CHECKOUT_CACHE_REFERENCE_REPOSITORY_TEMPLATE`, so consumers can keep\nprivate LAN topology out of repository YAML.\n\nThe GitHub-hosted trust gate resolves the reusable workflow shell to an exact\ncommit and uploads that shell's small checkout bootstrap script. Native and\nLinux-container build jobs download the bootstrap, then use the same cache\npolicy to obtain both the selected Buildchain runtime and consumer source at\ntheir already resolved immutable SHAs. Keeping the bootstrap owned by the\nworkflow shell is important when `@vN-alpha` routes a stable release to an older\n`vN` runtime: the stable runtime does not need to already contain the newest\ncheckout transport implementation. This also prevents a large direct\n`actions/checkout` runtime clone from becoming a separate timeout path on\nconstrained self-hosted uplinks. The bootstrap artifact does not contain the\nruntime repository and cannot move either selected ref.\n\nDo not read cache URLs or reference paths from PR-controlled files such as\n`.buildchain/buildchain.toml`. These values are trusted workflow inputs or repo/org\nvariables. Buildchain does not pass GitHub credentials to cache mirrors or\nreference repositories. If it must fall back to GitHub, the workflow token is\nused only for the GitHub fetch path. Cache attempts use\n`checkout-cache-timeout-seconds`; the potentially larger GitHub fallback uses\nthe independent `checkout-cache-github-timeout-seconds` budget (600 seconds by\ndefault). Buildchain fetches the advertised source ref before trying an exact\nSHA, so a cache hit or stale-cache seed can contribute objects and the fallback\ndoes not first waste a full timeout on an unadvertised SHA. Retryable timeout\nand transient network failures use the bounded `checkout-cache-fetch-attempts`\nbudget; permanent failures stop immediately. Diagnostics record both timeout\nbudgets and the actual GitHub fetch attempts before exact HEAD/tree\nverification.\n\nEach platform diagnostics artifact includes `source-checkout.json` and embeds a\ncompact `sourceCheckout` summary in `diagnostics.json`: mode, transport,\nhit/miss, fallback reason, duration, final HEAD verification, and tree\nverification. Remote URLs are sanitized and local reference paths are represented\nby a short display name plus fingerprint, not by secret-bearing credentials.\nRuntime checkout evidence is uploaded separately as `runtime-checkout.json`,\nincluding cache transport, fallback attempts, and exact runtime `HEAD`\nverification, even when a later lifecycle step fails.\n\nWhen a Buildchain maintainer asks for downstream validation, the expected\nrequest is:\n\n```text\nBuildchain train ready: buildchain-ref=train/v3/v3.0/<capability>.\nKeep uses: ...@v3; run workflow_dispatch with that buildchain-ref and report the runtime evidence summary.\n```\n\nAfter validation succeeds, the Buildchain change should continue through the\nnormal mainline and release path. Do not treat the train as a pending merge\nitem; it is only a temporary fast-use, diagnostic, and rollback channel. It may\nremain for a retention window after release, with old trains handled by a\nseparate periodic cleanup task.\n\n## Workflow Outputs\n\nThe reusable workflow exposes the resolved contract:\n\n| Output                            | Meaning                                                                         |\n| --------------------------------- | ------------------------------------------------------------------------------- |\n| `runner-preset`                   | Resolved preset, or `custom` when `platforms-json` was provided                 |\n| `platforms-json`                  | Exact matrix JSON used by the build job                                         |\n| `platform-count`                  | Number of matrix platforms                                                      |\n| `linux-container-enabled`         | `true` when Linux platforms are routed through a job container                  |\n| `linux-container-image`           | Resolved digest-pinned Linux job container image                                |\n| `build-summary-artifact`          | Uploaded aggregate summary artifact name                                        |\n| `build-diagnostics-summary-artifact` | Uploaded aggregate diagnostics summary artifact name                         |\n| `release-candidate-passport-artifact` | Uploaded PR-stage release-candidate passport artifact name when `release-candidate` is enabled |\n| `release-candidate-passport-json` | Compact release-candidate passport JSON when `release-candidate` is enabled     |\n| `build-summary-json`              | Compact aggregate JSON with platform count, file count, and byte total          |\n| `build-diagnostics-summary-json`  | Compact aggregate diagnostics JSON with platform, lifecycle warning/error, diagnostics contract warning, and sidecar manifest warning totals |\n| `trusted-event`                   | `true` when the event is trusted enough to reach build runners                  |\n| `buildchain-runtime-ref`          | Runtime ref selected after applying the empty-default or override policy        |\n| `buildchain-runtime-sha`          | Immutable Buildchain runtime commit used by all runtime checkouts               |\n| `buildchain-runtime-class`        | `stable`, `alpha`, `authority`, `train`, `exact-sha`, or `development`          |\n| `buildchain-runtime-override`     | `true` when an authority, train, or exact-SHA `buildchain-ref` override was accepted |\n| `buildchain-runtime-trust-decision` | Runtime override trust decision                                               |\n| `buildchain-contract-lock-status` | `unchanged`, `compatible-drift`, `breaking-drift`, `missing-lock`, `non-floating-runtime`, or first-release `runtime-contract-unavailable` |\n| `buildchain-contract-lock-drift`  | `true` when the floating runtime SHA or contract digest changed                 |\n| `buildchain-contract-digest`      | Current Buildchain runtime contract digest                                      |\n| `publish-channel`                 | Resolved publish channel requested by the caller                                |\n| `publish-allowed`                 | `true` only when this event/ref may publish after verification                  |\n| `publish-reason`                  | Human-readable reason for the publish gate decision                             |\n| `publish-source-ref`              | Gate source ref that was resolved before checkout                               |\n| `publish-source-sha`              | Exact source commit used by checkout, build, verify, and artifacts              |\n| `publish-source-locked`           | `true` when a `publish-gate/*` source ref was explicitly locked                 |\n| `publish-source-channel`          | `alpha`, `release`, `anchor`, or `major` parsed from the source ref             |\n| `publish-source-line`             | Product line parsed from source refs such as `v22/v22.22`                       |\n| `publish-source-consumer-version` | Consumer package version parsed from source refs                                |\n| `release-manifest-json`           | Resolved release manifest including source lock, version state, and anchor data |\n\nThe aggregate summaries are intentionally artifacts as well as outputs. GitHub\nActions matrix outputs are not a reliable place to carry every platform's full\nmanifest, so Buildchain uploads each platform manifest and then emits one\naggregate build summary artifact after the matrix completes. Buildchain uploads\n`diagnostics-summary.json` as a separate aggregate diagnostics summary artifact,\na compact rollup of each platform's small diagnostics upload. The rollup keeps\nper-platform runner facts, checked tool versions/missing tools, package\nmanager/cache directory details, compiler-cache availability, lifecycle timing,\nprocess sampler context, and links back to the exact platform artifacts. Each\nplatform diagnostics upload includes `diagnostics.json`,\n`diagnostics-manifest.json`, the lifecycle `events.jsonl`, and process sampler\nsidecars when enabled, so slow-build diagnosis does not require downloading the\nbinary platform artifact or the aggregate build summary. The sidecar manifest\nrecords the uploaded diagnostics files with bytes and sha256 hashes. Each\n`diagnostics.json` also records the related binary artifact name, manifest\nartifact name, diagnostics artifact name, diagnostics sidecar manifest path, and\nplatform id in `links`, so a reviewer can navigate from the small diagnostics\nartifact back to the exact platform outputs when deeper inspection is needed.\nThe workflow output `build-diagnostics-summary-json` includes\n`diagnosticsContractWarningCount` and `diagnosticsManifestWarningCount` so\nrelease jobs can detect drifting diagnostics JSON contracts and missing or\ndrifting diagnostics sidecar manifests without downloading the per-platform\ndiagnostics artifacts first.\n\n## Artifact Signing Authority\n\nArtifact signing is a Buildchain capability, not a macOS application workflow.\nConsumers declare desired signature state next to their artifact facts; they do\nnot configure certificates, Team IDs, notary credentials, protected\nenvironments, authority roles, or signing jobs:\n\n```toml\n[[signing.artifacts]]\nid = \"native-engine\"\npath = \"dist/kungfu-engine\"\nprofile = \"auto\"\nkind = \"mach-o\"\nplatforms = [\"macos-arm64\", \"macos-x64\"]\n```\n\nEvery native and container build lane reads this declaration after the build\nlifecycle and before verification. Buildchain binds the exact artifact bytes or directory tree to\nthe caller repository, source commit, source tree, immutable runtime, platform,\nand requested signature semantics, then publishes a deterministic\n`<artifact>-signing-request-<platform>-<source-sha>` request. No consumer\nworkflow step is required.\n\n`profile = \"auto\"` resolves signable Apple artifacts such as Mach-O files,\n`.dylib`, `.framework`, `.app`, `.xpc`, `.plugin`, `.pkg`, and `.dmg` to the\nnative `apple-developer-id` provider. Windows `pe` and `binary` artifacts\nresolve to timestamped native `windows-authenticode`; Windows PE never falls\nback to a detached signature. Linux and other non-native binary files,\narchives, blobs, and directories resolve to `detached-signature-v1`. Buildchain records that as a\ndetached cryptographic signature and never misrepresents it as an operating\nsystem code signature. Explicit incompatible provider/kind/platform\ncombinations fail closed.\n\nThe request schema rejects credential and authority-infrastructure fields. The\nBuildchain-owned signing authority is responsible for credential selection,\nnative signing, notarization where applicable, immutable result delivery, and a\nreceipt bound to the request digest, runtime SHA, output digest, and signature\nevidence. Consumer repositories neither receive nor duplicate credential-island\nmaterial. The reusable workflow dispatches the sealed request to the\nBuildchain repository, waits for its protected authority workflow, verifies the\nimmutable result, replaces only the declared artifact with the returned final\nbytes, and then runs the consumer's normal verification. Platform manifests,\nKFD evidence, checksums, and Release Passport inputs therefore observe the\nfinal signed artifact rather than the pre-signing build output.\n\nThe durable v3 authority runtime is\n`authority/v3/v3.0/artifact-signing`. It is channel-neutral: alpha and stable\nrelease work use the same protected `buildchain-artifact-signing` environment\nand provider identities. The authority ref is protected independently from\nrelease channels and can advance only through reviewed, checked changes; the\ntemporary `train/v3/v3.0/artifact-signing-authority` ref is retained only as a\nbounded migration rollback.\n\nThe older `credential-island-macos-*` reusable-workflow inputs remain a\ncompatibility surface while existing callers migrate. They are not the target\nconsumer contract and must not be used to design new integrations.\n\n## Artifact Transfer Relay\n\nBy default, platform jobs upload payloads, manifests, and diagnostics directly\nto GitHub artifacts:\n\n```yaml\nwith:\n  artifact-transfer-mode: github-artifacts\n```\n\nLarge self-hosted native builds can opt into the first-class S3 relay path:\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    with:\n      runner-preset: kungfu-v4-self-hosted\n      artifact-transfer-mode: s3-to-github-artifacts\n      artifact-relay-s3-bucket: ${{ vars.BUILDCHAIN_ARTIFACT_RELAY_S3_BUCKET }}\n      artifact-relay-s3-region: ${{ vars.BUILDCHAIN_ARTIFACT_RELAY_S3_REGION }}\n      artifact-relay-s3-prefix: ${{ vars.BUILDCHAIN_ARTIFACT_RELAY_S3_PREFIX }}\n```\n\nIn relay mode, each self-hosted platform job uploads the heavy payload files to\nS3 and uploads only a small `relay-manifest.json` to GitHub. A GitHub-hosted\n`relay-artifacts` job then assumes the configured download role, downloads the\npayloads from S3, verifies every file by SHA256, and re-uploads the normal\nGitHub artifacts under the same artifact names that direct mode uses. Downstream\nsummary, release-candidate, and promote-only workflows therefore continue to\nconsume GitHub artifacts and do not need custom S3 logic.\nThe relay implementation uses Node.js plus the standard AWS environment\ncredentials from GitHub OIDC; runner images and build containers do not need the\nAWS CLI installed.\n\nAfter the GitHub artifact uploads succeed, Buildchain deletes the S3 objects\nlisted in the relay manifest for that platform. If any download, verification,\nor GitHub artifact upload fails, cleanup is skipped so maintainers can inspect\nthe retained S3 payload. Configure a short bucket lifecycle expiration as a\ncost and cleanup backstop.\n\nThe relay configuration is intentionally generic. Buildchain does not hard-code\norganization buckets, regions, or role ARNs. Callers may pass explicit inputs,\nor set repository/organization variables and secrets using these names:\n\n| Variable or secret | Meaning |\n| --- | --- |\n| `BUILDCHAIN_ARTIFACT_RELAY_S3_BUCKET` | Relay bucket name |\n| `BUILDCHAIN_ARTIFACT_RELAY_S3_REGION` | Relay bucket region |\n| `BUILDCHAIN_ARTIFACT_RELAY_S3_PREFIX` | Relay object prefix; defaults to `buildchain-artifacts` |\n| `BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN` | Shared OIDC role ARN for upload and download |\n| `BUILDCHAIN_ARTIFACT_RELAY_S3_UPLOAD_ROLE_ARN` | Upload OIDC role ARN for self-hosted build jobs |\n| `BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN` | Download OIDC role ARN for the GitHub-hosted relay job |\n| `BUILDCHAIN_ARTIFACT_RELAY_S3_OIDC_AUDIENCE` | Optional OIDC audience override |\n\nFor AWS China regions, Buildchain defaults the OIDC audience to\n`sts.amazonaws.com.cn`; other regions default to `sts.amazonaws.com`. The caller\nworkflow must allow `id-token: write`, and the target role trust policy should\nrestrict GitHub OIDC claims to the expected organization, repository, workflow,\nand branch/ref. The S3 permissions should be scoped to the relay bucket/prefix\nused by the repository.\nUpload roles need write/delete access under the relay prefix; download roles\nneed read access plus delete access for successful cleanup.\n\nRelay mode is opt-in and does not affect forks or open-source users that do not\nconfigure S3. Missing bucket, region, upload role, or download role values fail\nbefore the heavy build matrix is scheduled. Buildchain treats S3 as a transport\ncache, not as the final release evidence store; the final audit entry remains\nthe GitHub artifact set plus the Buildchain build summary and release-candidate\npassport.\n\nSet `release-candidate: true` when the successful reusable build is meant to be\nthe artifact source promoted later. Buildchain then uploads\n`release-candidate-passport.json` under the\n`<artifact-name>-release-candidate-<publish-source-sha>` artifact name. Promotion\njobs can pass that passport to `promote-buildchain-ref` with\n`promote-only-release-candidate: \"true\"` so source, channel, platforms, and the\naggregate build-summary hash are checked before publish-gate side effects. The\npassport records the locked commit's Git tree SHA, so a post-merge channel HEAD\ncan be accepted only when it is tree-equivalent to the PR-stage build evidence.\n\n## Publish Gate\n\nBuildchain separates \"may build/verify\" from \"may publish.\" A same-repository\npull request may be trusted enough to run the build matrix, but it still must\nnot publish packages, S3 objects, release pages, or preview aliases. Publishing\nis allowed only when the caller explicitly requests a channel and the current\nevent/ref matches that channel.\n\nUse `publish-channel` to request a channel:\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    with:\n      publish-channel: release\n\n  publish:\n    needs: build\n    if: ${{ needs.build.outputs.publish-allowed == 'true' }}\n    runs-on: ubuntu-24.04\n    steps:\n      - run: ./scripts/publish.sh\n```\n\nDefault channels are:\n\n| Channel   | Allowed refs                                                                                         |\n| --------- | ---------------------------------------------------------------------------------------------------- |\n| `none`    | Never publishes; this is the default                                                                 |\n| `alpha`   | `alpha/vN/vN.M` branches or exact `vN.M.P-alpha.K` tags                                              |\n| `release` | `release/vN/vN.M` branches or release tags such as `vN.M.P`, `vN.M`, `vN`                            |\n| `major`   | `publish-gate/major`, legacy `major-gate`, or next-major release tags such as `vN.0.0`, `vN.0`, `vN` |\n\nPull request events always produce `publish-allowed=false`, even when the PR is\nfrom the same repository. Untrusted fork events also produce\n`publish-allowed=false`; with the default `untrusted-policy: fail`, the workflow\nthen fails before any build runner starts.\n\nProjects with their own channel names can pass `publish-refs-json`:\n\n```yaml\nwith:\n  publish-channel: nightly\n  publish-refs-json: >-\n    {\"nightly\":[\"^refs/heads/nightly/v\\\\d+$\"]}\n```\n\nThe aggregate build summary includes the same publish gate decision under\n`publishGate`, so a downloaded artifact summary explains both what was built and\nwhy it was or was not eligible to publish.\n\n## Publish Source Lock\n\n`publish-channel` answers \"may this event publish?\" Source lock answers \"which\nsource tree is the publish decision about?\" A caller can pass `publish-source-ref`\nto bind a publish run to a reviewed gate branch before any checkout happens:\n\n| Ref                                              | Meaning                                                                     |\n| ------------------------------------------------ | --------------------------------------------------------------------------- |\n| `publish-gate/alpha/<line>/<consumer-version>`   | Build and publish an alpha candidate for a consumer line                    |\n| `publish-gate/release/<line>/<consumer-version>` | Build and publish a production candidate for a consumer line                |\n| `publish-gate/anchor`                            | Resolve an explicit anchor request; it does not publish artifacts by itself |\n| `publish-gate/major`                             | Gate the next major source state                                            |\n| `major-gate`                                     | Legacy compatibility alias for the major gate                               |\n\nFor alpha and release refs, `<line>` is intentionally allowed to contain `/`, so\nKungfu-style lines such as `v22/v22.22` stay readable. The final path segment is\nthe consumer-visible version, for example `22.22.3-kf.0`.\n\nThe reusable workflow resolves the branch tip to `publish-source-sha`, checks out\nthat SHA in every build job, and uses the same SHA in artifact names, manifests,\nand aggregate summaries. Reruns therefore rebuild the same source tree even if a\ngate branch moves later.\n\nBefore any heavy build matrix is scheduled, the workflow also verifies that the\ntarget channel ref implied by the source lock already points at\n`publish-source-sha` and that the target channel HEAD came from the required\nmerged same-repository channel PR. `publish-gate/alpha/<line>/<version>` must\nmatch `alpha/<line>` and have PR lineage `dev/<line> -> alpha/<line>`;\n`publish-gate/release/<line>/<version>` must match `release/<line>` and have PR\nlineage `alpha/<line> -> release/<line>`. If either check fails, the run fails\nfast with a diagnostic telling maintainers to merge the source commit through\nthe channel PR first. This keeps verify from spending runner time on a source\ntree that cannot legally enter the requested publish channel.\n\nThe resolved release manifest is uploaded as an artifact and emitted as\n`release-manifest-json`. It records:\n\n- source ref, source SHA, channel, line, and consumer version;\n- configured version strategy and configured version-state files;\n- each version file's value, with release gates failing closed if the configured\n  files do not equal the consumer version;\n- anchor manifest summary for anchored/manual projects;\n- explicit anchor request JSON for `publish-gate/anchor`;\n- publish registry, dist-tag, and gate visibility metadata.\n\nPublish side-effect jobs should verify the lock immediately before publishing:\n\n```yaml\n- name: Verify publish gate did not move\n  run: node .buildchain/runtime/scripts/verify-publish-source-lock.mjs\n  env:\n    BUILDCHAIN_PUBLISH_SOURCE_REF: ${{ needs.build.outputs.publish-source-ref }}\n    BUILDCHAIN_PUBLISH_SOURCE_SHA: ${{ needs.build.outputs.publish-source-sha }}\n    BUILDCHAIN_SOURCE_REPOSITORY: ${{ github.repository }}\n    GITHUB_TOKEN: ${{ github.token }}\n```\n\nIf the branch tip no longer matches the manifest SHA, the publish job must fail\nclosed. Moving a gate branch creates a new publish decision and should produce a\nnew build run.\n\n## Release Candidate Promote-Only\n\nFor native package sets, the PR build is the only heavy build. When a PR targets\n`alpha/<line>` or `release/<line>`, `.build.yml` uploads a release-candidate\nbundle next to the platform artifacts. The bundle contains:\n\n- `release-candidate.passport.json`;\n- the aggregate `build-summary.json`;\n- copied platform manifest evidence for the built platforms.\n\nThe passport records two separate source identities:\n\n- `builtSourceSha` / `builtSourceTreeSha`: the PR-stage source that produced the\n  artifacts, usually the PR merge ref;\n- `promotionChannelSha` / `promotionChannelTreeSha`: the post-merge channel\n  commit used for publish authority.\n\nThe reusable promote wrapper resolves the merged PR, finds exactly one matching\nPR-stage release-candidate artifact, downloads it with the build summary and\npayload artifacts from the same PR-stage run, validates the payload count,\ncompares the built tree with the promotion channel tree, locks\n`publish-gate/{alpha,release,major}` to the promotion channel commit, and then\ncalls `actions/promote-buildchain-ref` with\n`promote-only-release-candidate: \"true\"` and\n`require-publish-source-lock: \"true\"`. The wrapper passes the created\n`publish-gate/*` ref, target SHA, and `locked=true` into the promote action, so\nfloating `@v3` consumers receive publish-side source-lock drift protection by\ndefault. It also defaults `branch-protection-bypass-apps` to `github-actions`\nso the workflow automation can apply generated version-state and channel\nbookkeeping on protected `dev`/`alpha`/`release` branches after the reviewed\nchannel PR has merged. Other App slugs and all user or team bypass actors are\nrejected. The wrapper uses the run-scoped `github.token` as the generated ref\nupdate token for protected bookkeeping PATCH calls, so the exact GitHub Actions\nApp authority can sync dev immediately after alpha/release publish without a\npost-publish PR.\nIt does not call `.build.yml`, does not create a matrix, and must fail before\npublish if the RC evidence, payload set, or source-lock ref is missing or\nambiguous.\n\nThe public `release-candidate-promote.yml` is a generated channel router. It\nderives the publication lane from `target-ref`, then selects the matching\nadvanced workflow shell, runtime, and consumer lock before the advanced\npromotion starts:\n\n- alpha targets use `.release-candidate-promote.yml@vN-alpha`, runtime\n  `vN-alpha`, and `buildchain-alpha-contract-lock-path`;\n- release and major targets use `.release-candidate-promote.yml@vN`, runtime\n  `vN`, and `buildchain-stable-contract-lock-path`.\n\nThe generated router also owns the stable-shell layout transition through\n`.buildchain/promotion-shell-routing.json`. Stable `v2.14.13` contains the hidden\nadvanced workflow, so the stable lane calls that workflow at the exact immutable\nSHA behind the released `v2` state and forwards the complete internal promotion\nidentity surface. The logical shell identity remains `vN`, and the router\nretains it in the public audit outputs. The internal advanced-shell call receives\nthe exact call ref selected by the routing configuration, so its called-workflow\nref check and checkout SHA both bind to the same immutable identity. Updating the\nrouting pin after a stable release does not require any consumer declaration\nchange.\n\nThe router resolves immutable SHAs and the selected lock digest before candidate\ndownload. The advanced shell verifies the same router, shell, runtime, lock,\nchannel, and target binding again. Train and exact-SHA runtime overrides remain\nrestricted to trusted `workflow_dispatch` actors with write, maintain, or admin\npermission. Promotion controller evidence, the promotion copy of the release\ncandidate passport, and the final release passport record these identities.\n\n```yaml\njobs:\n  promote:\n    uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v3\n    secrets:\n      buildchain-issue-app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}\n      buildchain-issue-app-private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}\n    with:\n      buildchain-channel: auto\n      buildchain-alpha-contract-lock-path: .buildchain/alpha-contract-lock.json\n      buildchain-stable-contract-lock-path: .buildchain/contract-lock.json\n      channel: alpha\n      target-ref: alpha/v22/v22.22\n      artifact-name: libnode\n      # Defaults to build.yml / Build. Override only when the PR-stage build\n      # workflow uses a different file or display name.\n      release-candidate-workflow-file: build.yml\n      release-candidate-workflow-name: Build\n      package-manager: npm\n      publish-target: npm\n      runner-preset: github-hosted\n      trusted-publishing: true\n      github-release: true\n      required-status-check: check / check\n      required-artifact-count: 3\n      publish-dist-tag: alpha\n      publish-package-set-order: platforms-first-main-last\n      publish-package-main: \"@kungfu-tech/libnode\"\n      release-passport-product-name: Libnode\n      buildchain-contract-drift-issue-mode: compatible-and-breaking\n```\n\nExisting callers may keep `buildchain-contract-lock-path`; a non-empty explicit\npath overrides channel-specific selection for compatibility. Migration only\nrequires adding the two channel lock inputs and may retain the remaining common\npromotion declaration unchanged. Consumers must not call the dot-prefixed\nadvanced workflow directly.\n\n`buildchain-issue-app-id` and `buildchain-issue-app-private-key` are optional\nbut recommended for cross-repository consumers. They should identify a GitHub\nApp installation with `issues: write` on `kungfu-systems/buildchain`; the\nwrapper mints the installation token before calling\n`actions/report-buildchain-issue`. Consumers can also pass a pre-minted\n`buildchain-issue-token`. If both are omitted, the wrapper falls back to\n`BUILDCHAIN_ISSUE_TOKEN`, `BUILDCHAIN_PROMOTION_TOKEN`, and then the consumer\nworkflow's `github.token`; the last fallback can only report issues when it has\nwrite access to the target Buildchain repository.\n\n`publish-required-artifacts-json` can still be passed explicitly for custom\npublish targets. Custom OCI requirements may omit pre-publish refs and digests;\nthe action resolves the exact version ref and validates final digests and any\nbuilt/reused provenance after `lifecycle.publish`. For the default\n`publish-artifact-kind: npm` path, consumers do\nnot download artifacts or run repository scripts to build publish evidence. The\nwrapper downloads the PR-stage payload artifacts, finds the downloaded `.tgz`\npackages, reads each tarball's `package/package.json` for the real scoped\npackage name and version, computes the npm `sha512-...` integrity from the\ntarball bytes, marks the package matching `publish-package-main` as `role:\nmain`, marks the rest as `role: platform`, and passes the generated\n`publish-required-artifacts-json` to `promote-buildchain-ref` before any publish\nside effect. Downloaded platform manifests are still passed into the release\npassport unless `release-passport-platform-manifest-paths` is set explicitly.\nThe same Buildchain contract lock check runs before release-candidate\nresolution and before publish. A compatible `v2` drift leaves an issue in the\nconsumer repository but does not trigger a second heavy build; an incompatible\ndrift fails before publish side effects.\n\nThe wrapper publishes the public release tag as a GitHub Release by default.\nAfter `promote-buildchain-ref` reports a complete release transaction, the\nwrapper creates or updates the public release, marks semver prerelease tags\nsuch as `v1.2.3-alpha.0`, `v1.2.3-rc.1`, or `v22.22.3-kf.3-alpha.7` as\n`prerelease=true` and `make_latest=false`, marks stable semver tags as latest,\nand uploads the publish evidence file plus every file in the generated release\npassport directory, including `buildchain.release.json` and `check-report.json`.\nFor anchored/manual package releases, the public release tag is derived from the\npublished package version and the internal exact transaction tag remains\navailable in the release passport.\nConsumers do not need to hand-write `gh release` logic to trigger\n`release.published` propagation. Set `github-release: false` only for\nrepositories that intentionally do not maintain GitHub Releases.\nIf the transaction still needs protected-ref finalization, the wrapper defers\nGitHub Release creation until the later run that reaches `state=complete`.\n\nCustom publish jobs can also repeat the channel-ref preflight:\n\n```yaml\n- name: Verify publish channel ref still matches\n  run: node .buildchain/runtime/scripts/verify-publish-channel-ref.mjs\n  env:\n    BUILDCHAIN_PUBLISH_SOURCE_REF: ${{ needs.build.outputs.publish-source-ref }}\n    BUILDCHAIN_PUBLISH_SOURCE_SHA: ${{ needs.build.outputs.publish-source-sha }}\n    BUILDCHAIN_SOURCE_REPOSITORY: ${{ github.repository }}\n    GITHUB_TOKEN: ${{ github.token }}\n```\n\nAnchored/manual package release jobs should also make the Buildchain promotion\naction validate that publication is entering through the same\n`publish-gate/{alpha,release,major}` source-lock contract before any package\npublish side effect:\n\n```yaml\n- name: Promote release ref and publish npm package set\n  uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3\n  with:\n    sha: ${{ needs.build.outputs.publish-source-sha }}\n    target-ref: release/v22/v22.22\n    require-publish-source-lock: 'true'\n    publish-source-ref: ${{ needs.build.outputs.publish-source-ref }}\n    publish-source-sha: ${{ needs.build.outputs.publish-source-sha }}\n    publish-source-locked: ${{ needs.build.outputs.publish-source-locked }}\n```\n\n`target-ref` stays the Buildchain channel promotion target, such as\n`alpha/v22/v22.22`, `release/v22/v22.22`, or `publish-gate/major`.\n`publish-source-ref` is the reviewed source-lock branch that authorized this\nspecific package publication. For alpha and release package publications, the\nsource-lock branch must point at the exact channel-line commit that promotion is\nvalidating; it is not a replacement for `target-ref`.\n\nThis keeps the version bump commit, publish authorization, and auditable publish\nentrypoint on the Buildchain source-lock protocol. The CLI form\n`buildchain publish-source validate-anchored-release --json` is still useful for\ncustom publish scripts, but the preferred GitHub Actions gate is the promotion\naction input above. A publish job that still runs directly from `alpha/*` or\n`release/*` channel branches fails this check because those refs are channel\nstate, not publish-gate decisions.\n\n## Package-Set Publish Plan\n\nProjects that publish multiple packages should treat package publication as a\npackage-set operation. Buildchain's package-set planner uses these rules:\n\n- platform packages publish first;\n- the main package publishes last;\n- the dist-tag move happens only after the full package set is present;\n- reruns accept already-published packages only when package name, version, and\n  integrity match;\n- an existing package with different integrity is a hard failure.\n\nThis keeps a consumer from observing a floating dist-tag that points to a main\npackage before all platform artifacts for the same source SHA are available.\n\n## Command Sources\n\nThe workflow runs `.buildchain/buildchain.toml` lifecycle stages by default:\n\n```toml\n[lifecycle.install]\ncommand = \"corepack yarn install --immutable\"\n\n[lifecycle.build]\ncommands = [\n  \"corepack yarn make\",\n  \"corepack yarn build\",\n]\n\n[lifecycle.verify]\ncommand = \"corepack yarn test\"\n```\n\nCallers can override any stage for one invocation:\n\n```yaml\nwith:\n  build-command: cmake --build build --config Release\n  verify-command: ctest --test-dir build --output-on-failure\n```\n\nEvery native and container matrix job is bounded by\n`lifecycle-timeout-minutes`, which defaults to 120 minutes. The same input is\nthe fallback deadline for each install, build, and verify action, so a hung\ncommand fails with the lifecycle name and matrix platform before it can occupy\na self-hosted runner indefinitely. A stage-level `timeout_minutes` in\n`buildchain.toml` remains the more specific override for that stage.\n\n```yaml\nwith:\n  lifecycle-timeout-minutes: 90\n```\n\nThe reusable build workflow samples the build lifecycle by default and carries\nthe generated summary into the final verify diagnostics. Callers can override\nthe sidecar path or disable sampling:\n\n```yaml\nwith:\n  sample-process-tree: true\n  process-summary-path: .buildchain/diagnostics/process-summary.json\n  process-sample-interval-ms: 15000\n  requested-parallelism: 20\n```\n\nWhen `sample-process-tree` is true, Buildchain wraps either `build-command` or\nthe configured `lifecycle.build` stage with `buildchain sample process-tree`.\nThe path is relative to the checked-out workspace and is read again during the\nfinal verify lifecycle. Custom workflows can still write their own sampler\nsummary and pass `process-summary-path`; Buildchain reads the file after the\nlifecycle command finishes, so it may be produced during the same invocation.\nWhen the build stage is optional, the reusable workflow treats the default\nsampler path as optional during verify; an explicitly supplied\n`process-summary-path` remains required.\n\nFor custom workflows, use the action directly:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/run-lifecycle@v3\n  with:\n    stage: build\n    required: \"true\"\n    timeout-minutes: \"90\"\n    artifact-name: libnode-linux-x64-${{ github.sha }}\n    artifact-paths: |\n      dist\n      build/stage\n```\n\n## Artifact Contract\n\nEach platform upload uses `artifact-name-template`. The default is:\n\n```text\n{artifact}-{platform}-{sha}\n```\n\nSupported placeholders are `{artifact}`, `{artifactName}`, `{platform}`,\n`{platformId}`, `{platformName}`, `{sha}`, `{shortSha}`, `{ref}`, `{runId}`,\nand `{runAttempt}`. Invalid GitHub artifact name characters are normalized to\n`-`, so `{ref}` remains deterministic even for refs such as\n`refs/heads/dev/v2/v2.0`.\n\nEach platform also writes and uploads:\n\n```text\n.buildchain/artifacts/<platform-id>/manifest.json\n.buildchain/artifacts/<platform-id>/summary.json\n```\n\nThe manifest schema is:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"contract\": \"kungfu-buildchain-artifact\",\n  \"artifactName\": \"libnode-linux-x64-<sha>\",\n  \"platform\": {\n    \"id\": \"linux-x64\",\n    \"name\": \"Linux x64\",\n    \"os\": \"Linux\",\n    \"arch\": \"X64\"\n  },\n  \"git\": {\n    \"repository\": \"kungfu-systems/libnode\",\n    \"sha\": \"<sha>\",\n    \"ref\": \"<ref>\",\n    \"runId\": \"<run id>\",\n    \"runAttempt\": \"<attempt>\"\n  },\n  \"lifecycle\": {\n    \"stage\": \"verify\",\n    \"commandSource\": \"buildchain.toml\",\n    \"executed\": true\n  },\n  \"summary\": {\n    \"contract\": \"kungfu-buildchain-artifact-summary\",\n    \"artifactName\": \"libnode-linux-x64-<sha>\",\n    \"fileCount\": 1,\n    \"totalBytes\": 1234,\n    \"digest\": \"<hex>\"\n  },\n  \"expectedArtifacts\": {\n    \"ok\": true,\n    \"source\": \"expected-artifacts-json\",\n    \"checks\": []\n  },\n  \"files\": [\n    {\n      \"path\": \"dist/example.zip\",\n      \"size\": 1234,\n      \"sha256\": \"<hex>\"\n    }\n  ]\n}\n```\n\nArtifact names do not include actor names, timestamps, or retry counters. Reruns\nproduce a new GitHub Actions run but keep the same source SHA/platform contract.\n\n`expected-artifacts-json` fails the build before upload when the artifact does\nnot match the caller's declared contract. Supported checks are:\n\n| Field           | Meaning                              |\n| --------------- | ------------------------------------ |\n| `minFiles`      | Minimum number of manifest files     |\n| `maxFiles`      | Maximum number of manifest files     |\n| `minTotalBytes` | Minimum total byte count             |\n| `requiredPaths` | Exact manifest paths that must exist |\n\n## Trusted Event Gate\n\nThe workflow has an explicit `trust-gate` job. By default, pull requests from\nforks fail before any build job can reach self-hosted runners, secrets,\npublishing credentials, or heavyweight build commands. Same-repository PRs,\nworkflow dispatches, and protected branch events can proceed.\n\nIf a repository wants fork PRs to skip rather than fail, it can set:\n\n```yaml\nwith:\n  untrusted-policy: skip\n```\n\nDo not set `require-trusted-event: false` for workflows that use self-hosted\nrunners or secrets.\n\nThe build matrix and the workflow control plane are routed independently. The\nmatrix continues to use `runner-preset` and `platforms-json`. Consumers with a\ngoverned runner may also move channel resolution, trust evaluation, contract\nresolution, controller evidence, artifact transfer, and aggregation off the\ndefault GitHub-hosted runner:\n\n```yaml\nwith:\n  control-runner-json: '[\"self-hosted\",\"agent-120\"]'\n  runner-preset: custom\n  platforms-json: '[{\"id\":\"linux-x64\",\"name\":\"Linux x64\",\"runner\":\"[\\\"self-hosted\\\",\\\"agent-120\\\"]\"}]'\n```\n\n`control-runner-json` is additive and defaults to `[\"ubuntu-24.04\"]`. Keep\n`require-trusted-event: true` whenever either runner input selects\n`self-hosted`; a self-hosted control plane must not be exposed to untrusted fork\nevents or arbitrary caller-controlled workflow code.\n\n`require-trusted-event` controls access to build runners. It does not override\nthe publish gate: pull requests remain non-publishing events.\n\n## Fixture\n\n`fixtures/libnode-shaped` is the contract fixture. It has:\n\n- `package.json` version state;\n- `.buildchain/buildchain.toml` with `install`, `build`, `verify`, and `publish`;\n- cross-platform Node scripts that create small `dist/` outputs;\n- `Build Surface Fixture` workflow coverage.\n\nThe fixture proves the reusable surface without running the real libnode native\nbuild."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-reusable-build\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-30\n  invisible_context: not asserted\n---\n\n# Reusable Build Surface\n\nBuildchain v3 provides a reusable build workflow for repositories that need\nBuildchain's release semantics but cannot be described as a simple Node package.\nThe first target shape is `libnode`: expensive native builds, multiple operating\nsystems, self-hosted runner labels, and release artifacts that must be auditable.\n\nFor Linux release artifacts, the build workflow can hand the sealed artifact,\nplatform manifest, and Release Passport to the separate GitHub-hosted keyless\nattester. The compiler runner remains the recorded build identity; the attester\nonly signs and verifies immutable data. See\n[`github-artifact-attestation.md`](github-artifact-attestation.md).\n\n## Automatic Channel Router\n\nThe preferred consumer surface is one reusable workflow call. Consumers keep\nthis configuration for both alpha development and stable release work:\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v3\n    permissions:\n      contents: read\n      issues: write\n      id-token: write\n    with:\n      working-directory: .\n      artifact-name: libnode\n      runner-preset: kungfu-v4-self-hosted\n      publish-channel: none\n    secrets: inherit\n```\n\n`buildchain-channel` defaults to `auto`. Selection uses this precedence:\n\n1. an explicit `buildchain-ref` protected authority, train, SHA, or official channel;\n2. an explicit `buildchain-channel: alpha|stable`;\n3. `publish-channel: alpha|release|major`;\n4. GitHub release prerelease metadata;\n5. a canonical semver tag;\n6. non-release PR, push, dispatch, schedule, and workflow-run events default to\n   alpha.\n\nThe resolved runtime is `vN-alpha` for development and prerelease intent and\n`vN` for stable release intent. Unknown custom publish channels, malformed\nrelease events, and non-semver release-like tags fail before the build matrix;\nthey never guess alpha for a stable release.\n\nThe router automatically selects `.buildchain/alpha-contract-lock.json` for\nalpha and `.buildchain/contract-lock.json` for stable. A repository can override\nthe common path with `buildchain-contract-lock-path`, or override one channel\nwith `buildchain-alpha-contract-lock-path` /\n`buildchain-stable-contract-lock-path`.\n\nOnly repositories changing the default policy need extra routing input:\n\n```yaml\nwith:\n  buildchain-channel: stable\n```\n\nDuring v3 prerelease evaluation windows, canaries use `build.yml@v3-alpha`.\nThe same router then selects `v3-alpha` or stable `v3` as the runtime.\nProduction consumers use `build.yml@v3`; this keeps the routing shell itself on\na stable ref.\n\nThe router is generated from `.build.yml`'s input/output surface. Run\n`node scripts/generate-channel-build-workflow.mjs` after changing the advanced\nbuild workflow; inventory and unit tests reject a stale generated router.\n\n## Advanced Workflow\n\nConsumers that need direct workflow-shell or runtime control call the advanced\nsurface:\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    with:\n      working-directory: .\n      artifact-name: libnode\n      runner-preset: kungfu-v4-self-hosted\n      linux-container-preset: kungfu-verify\n      artifact-name-template: \"{artifact}-{platform}-{sha}\"\n      artifact-paths: |\n        dist\n        build/stage\n      expected-artifacts-json: >-\n        {\"minFiles\":2,\"requiredPaths\":[\"dist/libnode.tar.gz\",\"dist/checksums.txt\"]}\n      process-summary-path: .buildchain/diagnostics/process-summary.json\n      release-candidate: true\n      publish-channel: release\n      publish-source-ref: publish-gate/release/v22/v22.22/22.22.3-kf.0\n```\n\n`runner-preset` is the stable first-class surface for known runner fleets:\n\n| Preset                  | Platforms                                                                                                      |\n| ----------------------- | -------------------------------------------------------------------------------------------------------------- |\n| `github-hosted`         | `ubuntu-24.04`, `macos-latest`, `windows-2022`                                                                 |\n| `kungfu-v4-self-hosted` | Kungfu Linux x64, macOS ARM64, and Windows x64 self-hosted runner labels                                       |\n| `kungfu-v4-native`      | Kungfu Linux x64, Linux ARM64, macOS ARM64, and Windows x64; Linux ARM64 uses GitHub-hosted `ubuntu-24.04-arm` |\n| `custom`                | Requires `platforms-json`                                                                                      |\n\nSet `self-hosted-offline-fallback: true` to inspect every exact-label\nself-hosted lane from the trusted Buildchain workflow shell before the matrix\nstarts. A lane with no matching online runner is replaced independently by its\nsupported GitHub-hosted runner: Kungfu Linux x64 uses `ubuntu-24.04`, macOS ARM64\nuses `macos-15`, and Windows x64 uses `windows-2022`. Online-but-busy runners\nremain online and keep their declared self-hosted route. Organization-owned\nrepositories inspect organization runner inventory so selected-repository runner\ngroups are not mistaken for an empty repository runner inventory. If the\ninventory token, permission, or API is unavailable, Buildchain preserves the\noriginal matrix instead of guessing that the fleet is offline. The public\nworkflow output `runner-routing-json` records only de-identified counts,\ninventory scope, and routing decisions.\n\n```yaml\nwith:\n  runner-preset: kungfu-v4-native\n  self-hosted-offline-fallback: true\nsecrets:\n  BUILDCHAIN_PROMOTION_TOKEN: ${{ secrets.KUNGFU_GITHUB_TOKEN }}\n```\n\nCallers can still provide a custom matrix with `platforms-json`. Each platform\nobject has:\n\n| Field    | Meaning                                           |\n| -------- | ------------------------------------------------- |\n| `id`     | Stable artifact/platform key, such as `linux-x64` |\n| `name`   | Human-readable job name                           |\n| `runner` | JSON string passed to `runs-on` after `fromJSON`  |\n\nThe runner field is intentionally a JSON string so callers can pass either\nGitHub-hosted runners or multi-label self-hosted runners without Buildchain\nguessing the labels.\n\nOnly include platforms that should run. GitHub schedules matrix jobs before\nsteps execute, so a disabled entry with unavailable runner labels can still\nblock the workflow queue.\n\n`fail-fast` defaults to `false`, preserving the diagnostic behavior that\ncollects every platform result. Required promotion callers can set it to `true`\nto cancel sibling native, container, and relay matrix lanes after the first\nfailure. This input changes scheduling only: it does not reduce the declared\nplatform matrix, turn cancellation into a pass, or alter artifact and release\nadmission.\n\n## Linux Job Containers\n\nLinux build platforms can run inside a digest-pinned job container while macOS\nand Windows keep using native runners. This is the recommended way to remove\nmoving Linux runner prerequisites from Buildchain consumers: the Linux host only\nneeds a GitHub Actions runner, Docker, and network access; common verification\ntools come from the image contract.\n\nUse the Kungfu verification image for lifecycle stages that need Git, jq,\nPython, uv, and fnm, but do not need native compilation:\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    with:\n      runner-preset: kungfu-v4-self-hosted\n      linux-container-preset: kungfu-verify\n```\n\n`kungfu-verify` resolves to:\n\n```text\nghcr.io/kungfu-systems/build-images/kungfu-verify@sha256:11f0ba64267ce88174a4f73a9bf833ff4e9c59cd16ec3d08a6432a06c2be6fb1\n```\n\nCallers that own a different Linux image can pass it explicitly:\n\n```yaml\nwith:\n  linux-container-preset: custom\n  linux-container-image: ghcr.io/example/project-build@sha256:<digest>\n```\n\n`linux-container-image` should be pinned by digest. A floating tag makes the\nrunner surface mutable and weakens Buildchain's release evidence.\n\nThe workflow splits the matrix into two build jobs:\n\n- Linux platforms go to `build-linux-container` when a Linux container is\n  configured.\n- All other platforms go to `build-native`.\n\nArtifact names, manifest paths, expected artifact checks, publish-source locks,\nand aggregate summaries are the same in both jobs. The split is an execution\ndetail, not a different artifact contract.\n\n## Native Rust Toolchains\n\nNative lifecycle jobs can request an isolated Rust installation instead of\ndepending on a self-hosted runner user's PATH:\n\n```yaml\nwith:\n  setup-rust: true\n  rust-toolchain: \"1.96.0\"\n  rustup-dist-server: \"https://rsproxy.cn\"\n  rustup-update-root: \"https://rsproxy.cn/rustup\"\n  cargo-registry-index: ${{ vars.BUILDCHAIN_CARGO_REGISTRY_INDEX }}\n```\n\n`setup-rust` defaults to `false`, so existing consumers are unchanged. When it\nis enabled, Buildchain installs `rust-toolchain` before the install, build, and\nverify lifecycle stages on every native matrix platform. Windows uses the\nofficial rustup bootstrap through `cmd.exe` and `curl.exe` into runner-temporary\nCargo and rustup homes, so it works under a restrictive PowerShell execution\npolicy and the service account does not depend on another user's PATH or mutate\nhost toolchain state. Pin an exact toolchain for release builds. Linux container jobs continue\nto obtain Rust from their digest-pinned image contract; Buildchain does not\nmutate that container surface.\n\nThe rustup server inputs are optional and default to Rust's official servers.\nConsumers behind a slow cross-border link may select a trusted transport mirror;\nrustup still verifies the selected toolchain's distribution metadata and\ncomponent checksums.\n\n`cargo-registry-index` is also optional. When set, Buildchain exposes it to\nCargo as `CARGO_REGISTRIES_CRATES_IO_INDEX` for every native lifecycle stage,\nso a self-hosted runner can use a repository or organization variable without\ncommitting private LAN topology to public workflow YAML. The endpoint must be a\ncrates.io-compatible index whose `config.json` download contract serves the\nmatching checksum-verified crate archives. An empty value preserves Cargo's\nnormal crates.io behavior.\n\nThe container image provides `fnm` but does not preinstall Node. Buildchain uses\n`fnm` inside the container to install the requested `node-version` before it\nruns Buildchain runtime scripts or lifecycle actions.\n\nDo not use `kungfu-verify` for stages that need CMake, Ninja, ccache, Conan, or\nDocker image publishing. Those should use a heavier native-build image or remain\non a host runner until their image contract is explicit.\n\n## Buildchain Runtime Override\n\nStable consumers should keep the reusable workflow pinned to stable refs such as\n`@v3`. The optional `buildchain-ref` input is empty by default; empty means\nBuildchain resolves and executes the stable runtime selected by the workflow\nshell. The full train validation protocol is documented in\n[`runtime-train-validation.md`](runtime-train-validation.md).\n\nFor one-off manual validation, a trusted maintainer can run the caller workflow\nwith a temporary runtime override:\n\n```yaml\non:\n  workflow_dispatch:\n    inputs:\n      buildchain-ref:\n        description: \"Temporary Buildchain runtime ref for trusted manual validation\"\n        required: false\n        default: \"\"\n\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    with:\n      buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n```\n\nAllowed override refs are deliberately narrow:\n\n| Ref form                                | Meaning                                                |\n| --------------------------------------- | ------------------------------------------------------ |\n| `train/v3/v3.0/<capability>`            | Temporary capability train under the active minor line |\n| `refs/heads/train/v3/v3.0/<capability>` | Explicit branch ref for the same train                 |\n| `<40-character SHA>`                    | Exact immutable Buildchain runtime commit              |\n\nOverride requests fail closed unless the event is `workflow_dispatch` and the\nactor has write, maintain, or admin permission on the caller repository. One\nnon-override exact-pin case is also admitted: when the reusable workflow itself\nis invoked from an exact Buildchain SHA and `buildchain-ref` names that identical\nSHA, the run records `pinned-self`. The input cannot select code other than the\nalready-running workflow shell, so protected push and pull-request publication\njobs can retain one immutable runtime root. Different SHA and train requests\nstill fail closed outside trusted manual dispatch.\n\nPull requests, including same-repository pull requests and fork-originated pull\nrequests, cannot select an independent `buildchain-ref` override. This keeps\nautomated PR builds on the stable or exact pinned-self runtime surface.\n\nEvery run resolves the runtime ref to an immutable SHA before checkout. The job\nsummary and aggregate build summary record the workflow shell ref, requested\nruntime ref, resolved runtime ref, runtime SHA, stability class, trust decision,\nand rollback ref. Train refs are development validation refs: they do not move\n`v3`, `vX.Y`, `vX.Y-alpha`, npm dist-tags, or production release refs, and they\nmust not be pinned as long-term production dependencies.\n\nRuntime override validates Buildchain runtime scripts, CLI code, local actions,\nconfig parsing, and lifecycle behavior. It cannot validate changes that require\nthe outer reusable workflow YAML itself to change, such as new jobs,\npermissions, workflow outputs, or matrix topology. Those changes need a canary\nworkflow path or a temporary explicit workflow ref.\n\n## Floating Ref Contract Lock\n\nStable consumers should use floating major refs such as `@v3`, but a floating\nref is not blind trust. Each released Buildchain ref carries a package-owned\nruntime contract world in `dist/site/buildchain-contract.json`. Consumers may\nkeep a small lock file, `.buildchain/contract-lock.json`, recording the\nBuildchain ref, resolved SHA, contract digest, compatibility digest, accepted\nmajor line, and compatibility policy they reviewed.\n\nThe reusable build trust gate checks this lock before any heavy matrix job:\n\n1. resolve the Buildchain runtime ref, for example `v3`, to an immutable SHA;\n2. read `dist/site/buildchain-contract.json` from that checked-out Buildchain\n   ref;\n3. read the consumer's `.buildchain/contract-lock.json`;\n4. compare the accepted contract with the current contract.\n\nSHA drift alone is not a failure. `v3` is expected to advance. Buildchain only\nfails fast when the accepted contract is no longer compatible, for example a\nrequired input is removed, a required output disappears, a protected behavior\npromise changes, or the major line changes. Additive changes such as optional\ninputs, optional outputs, diagnostics, or documentation updates continue under\nthe default `major-compatible` policy.\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    permissions:\n      contents: read\n      issues: write\n      id-token: write\n    with:\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n      buildchain-contract-compatibility-policy: major-compatible\n      buildchain-contract-drift-issue-mode: compatible-and-breaking\n```\n\nWhen compatible drift is detected, the build continues and Buildchain opens or\nupdates a low-priority issue in the consumer repository. The issue records the\nold SHA/digest, new SHA/digest, compatibility result, workflow run, and the next\naction: review the Buildchain release notes and update the lock. When breaking\ndrift is detected, the same issue path is used, but the trust gate fails before\nmatrix build or publish work starts. If the workflow token cannot write issues,\nBuildchain writes a copyable issue body into the job summary.\n\nThe lock is intentionally small. It does not copy the full contract. The full\ncontract remains in the Buildchain ref and package; the consumer records only\nwhat it accepted and the policy used to compare future floating-ref movement.\n\nAdvanced alpha-channel consumers select the matching workflow shell:\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3-alpha\n    with:\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n```\n\nThe runtime follows the called workflow through `job.workflow_ref`. Callers may\nalso pass `buildchain-ref: v3-alpha` explicitly; official floating refs are\nordinary channel selections and are allowed on pull requests and pushes. Train\nrefs and exact SHAs remain trusted manual overrides.\n\n## Shifu Cache Profile Passthrough\n\nBuildchain can carry one trusted Shifu cache-profile reference and its exact\ndigest into lifecycle execution. Its contract is an opaque reference and digest\nonly. This surface is deliberately opaque:\nBuildchain does not fetch the profile, parse JSON, select cache services,\nrewrite bindings, decide fallback, or emit Shifu resolution evidence. Those\nsemantics remain owned by the consumer's pinned Shifu implementation.\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v3\n    with:\n      shifu-cache-profile-ref: ${{ vars.SHIFU_CACHE_PROFILE_REF }}\n      shifu-cache-profile-digest: ${{ vars.SHIFU_CACHE_PROFILE_DIGEST }}\n```\n\nThe reusable workflow passes the pair as `SHIFU_CACHE_PROFILE_REF` and\n`SHIFU_CACHE_PROFILE_DIGEST` to install, build, and verify lifecycle commands.\nThe consumer must invoke its Shifu cache-aware execution surface. An empty pair\npreserves existing behavior; a consumer Shifu should fail closed when exactly\none value is present or the resolved bytes do not match the expected digest.\n\nUse trusted repository or organization variables rather than PR-controlled\nfiles for private/LAN references. The variables must remain secret-free; any\ncredentials use a separate provider-approved secret surface and must not be\nembedded in the profile reference. This passthrough is separate from\nBuildchain's locked source checkout cache below: Buildchain owns checkout\ntransport and source identity, while Shifu owns post-checkout execution cache\nbindings and receipts.\n\n## Locked Source Checkout Cache\n\nSelf-hosted runners that build large repositories can opt into a locked checkout\ncache for both the consumer source and the Buildchain runtime. This changes only\nthe Git object transport. Buildchain still resolves `publish-source-sha` and the\nruntime SHA before any build runner starts, checks out those exact commits, and\nverifies each final `HEAD` plus the resolved consumer source tree SHA before\nlifecycle commands run.\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    with:\n      runner-preset: kungfu-v4-self-hosted\n      checkout-cache-mode: auto\n      checkout-cache-mirror-url-template: ${{ vars.BUILDCHAIN_CHECKOUT_CACHE_MIRROR_URL_TEMPLATE }}\n      checkout-cache-reference-repository-template: ${{ vars.BUILDCHAIN_CHECKOUT_CACHE_REFERENCE_REPOSITORY_TEMPLATE }}\n      checkout-cache-fallback: github\n      checkout-cache-timeout-seconds: 60\n      checkout-cache-github-timeout-seconds: 600\n      checkout-cache-fetch-attempts: 3\n```\n\n`checkout-cache-mode` accepts:\n\n| Mode      | Behavior                                                                                                    |\n| --------- | ----------------------------------------------------------------------------------------------------------- |\n| `off`     | Default. Buildchain fetches the locked commit from GitHub.                                                  |\n| `auto`    | Try the trusted cache first; on miss, record the miss and fall back according to `checkout-cache-fallback`. |\n| `require` | Require the cache to provide the locked commit and fail before lifecycle work if unavailable.               |\n\nThe cache can be a local/LAN mirror URL template or a runner-local bare\nreference repository template. Templates support `{owner}`, `{repo}`,\n`{repository}`, `{repositorySlug}`, and `{sha}`. The workflow also reads\nrepository or organization variables named\n`BUILDCHAIN_CHECKOUT_CACHE_MIRROR_URL_TEMPLATE` and\n`BUILDCHAIN_CHECKOUT_CACHE_REFERENCE_REPOSITORY_TEMPLATE`, so consumers can keep\nprivate LAN topology out of repository YAML.\n\nThe GitHub-hosted trust gate resolves the reusable workflow shell to an exact\ncommit and uploads that shell's small checkout bootstrap script. Native and\nLinux-container build jobs download the bootstrap, then use the same cache\npolicy to obtain both the selected Buildchain runtime and consumer source at\ntheir already resolved immutable SHAs. Keeping the bootstrap owned by the\nworkflow shell is important when `@vN-alpha` routes a stable release to an older\n`vN` runtime: the stable runtime does not need to already contain the newest\ncheckout transport implementation. This also prevents a large direct\n`actions/checkout` runtime clone from becoming a separate timeout path on\nconstrained self-hosted uplinks. The bootstrap artifact does not contain the\nruntime repository and cannot move either selected ref.\n\nDo not read cache URLs or reference paths from PR-controlled files such as\n`.buildchain/buildchain.toml`. These values are trusted workflow inputs or repo/org\nvariables. Buildchain does not pass GitHub credentials to cache mirrors or\nreference repositories. If it must fall back to GitHub, the workflow token is\nused only for the GitHub fetch path. Cache attempts use\n`checkout-cache-timeout-seconds`; the potentially larger GitHub fallback uses\nthe independent `checkout-cache-github-timeout-seconds` budget (600 seconds by\ndefault). Buildchain fetches the advertised source ref before trying an exact\nSHA, so a cache hit or stale-cache seed can contribute objects and the fallback\ndoes not first waste a full timeout on an unadvertised SHA. Retryable timeout\nand transient network failures use the bounded `checkout-cache-fetch-attempts`\nbudget; permanent failures stop immediately. Diagnostics record both timeout\nbudgets and the actual GitHub fetch attempts before exact HEAD/tree\nverification.\n\nEach platform diagnostics artifact includes `source-checkout.json` and embeds a\ncompact `sourceCheckout` summary in `diagnostics.json`: mode, transport,\nhit/miss, fallback reason, duration, final HEAD verification, and tree\nverification. Remote URLs are sanitized and local reference paths are represented\nby a short display name plus fingerprint, not by secret-bearing credentials.\nRuntime checkout evidence is uploaded separately as `runtime-checkout.json`,\nincluding cache transport, fallback attempts, and exact runtime `HEAD`\nverification, even when a later lifecycle step fails.\n\n## Auditable Compiler Cache\n\nConsumers can prepare `sccache` on selected platforms after the install\nlifecycle and before compilation:\n\n```yaml\nwith:\n  compiler-cache-provider: sccache\n  compiler-cache-platforms-json: '[\"windows-x64\"]'\n  compiler-cache-required: true\n```\n\nThe consumer remains responsible for installing and pinning the tool before\nthe preparation step. Buildchain probes its version, runs `sccache\n--zero-stats`, and writes\n`compiler-cache-preparation.json`. The receipt binds the source commit/tree,\nBuildchain runtime, platform, cache profile, and any declared dependency,\ntoolchain, or policy roots. It resets counters only; it does not delete cached\ncompiler outputs.\n\nFinal diagnostics admit sccache hit/miss outcomes as current-run evidence only\nwhen that preparation receipt is present and valid. A bare `sccache\n--show-stats` result without the reset receipt remains cumulative and is\nreported as unavailable for the current run. The preparation receipt is copied\ninto the small diagnostics artifact and sealed by\n`diagnostics-manifest.json`.\n\nWhen a Buildchain maintainer asks for downstream validation, the expected\nrequest is:\n\n```text\nBuildchain train ready: buildchain-ref=train/v3/v3.0/<capability>.\nKeep uses: ...@v3; run workflow_dispatch with that buildchain-ref and report the runtime evidence summary.\n```\n\nAfter validation succeeds, the Buildchain change should continue through the\nnormal mainline and release path. Do not treat the train as a pending merge\nitem; it is only a temporary fast-use, diagnostic, and rollback channel. It may\nremain for a retention window after release, with old trains handled by a\nseparate periodic cleanup task.\n\n## Workflow Outputs\n\nThe reusable workflow exposes the resolved contract:\n\n| Output                                | Meaning                                                                                                                                      |\n| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |\n| `runner-preset`                       | Resolved preset, or `custom` when `platforms-json` was provided                                                                              |\n| `platforms-json`                      | Exact matrix JSON used by the build job                                                                                                      |\n| `platform-count`                      | Number of matrix platforms                                                                                                                   |\n| `linux-container-enabled`             | `true` when Linux platforms are routed through a job container                                                                               |\n| `linux-container-image`               | Resolved digest-pinned Linux job container image                                                                                             |\n| `build-summary-artifact`              | Uploaded aggregate summary artifact name                                                                                                     |\n| `build-diagnostics-summary-artifact`  | Uploaded aggregate diagnostics summary artifact name                                                                                         |\n| `release-candidate-passport-artifact` | Uploaded PR-stage release-candidate passport artifact name when `release-candidate` is enabled                                               |\n| `release-candidate-passport-json`     | Compact release-candidate passport JSON when `release-candidate` is enabled                                                                  |\n| `build-summary-json`                  | Compact aggregate JSON with platform count, file count, and byte total                                                                       |\n| `build-diagnostics-summary-json`      | Compact aggregate diagnostics JSON with platform, lifecycle warning/error, diagnostics contract warning, and sidecar manifest warning totals |\n| `trusted-event`                       | `true` when the event is trusted enough to reach build runners                                                                               |\n| `buildchain-runtime-ref`              | Runtime ref selected after applying the empty-default or override policy                                                                     |\n| `buildchain-runtime-sha`              | Immutable Buildchain runtime commit used by all runtime checkouts                                                                            |\n| `buildchain-runtime-class`            | `stable`, `alpha`, `authority`, `train`, `exact-sha`, or `development`                                                                       |\n| `buildchain-runtime-override`         | `true` when an authority, train, or exact-SHA `buildchain-ref` override was accepted                                                         |\n| `buildchain-runtime-trust-decision`   | Runtime override trust decision                                                                                                              |\n| `buildchain-contract-lock-status`     | `unchanged`, `compatible-drift`, `breaking-drift`, `missing-lock`, `non-floating-runtime`, or first-release `runtime-contract-unavailable`   |\n| `buildchain-contract-lock-drift`      | `true` when the floating runtime SHA or contract digest changed                                                                              |\n| `buildchain-contract-digest`          | Current Buildchain runtime contract digest                                                                                                   |\n| `publish-channel`                     | Resolved publish channel requested by the caller                                                                                             |\n| `publish-allowed`                     | `true` only when this event/ref may publish after verification                                                                               |\n| `publish-reason`                      | Human-readable reason for the publish gate decision                                                                                          |\n| `publish-source-ref`                  | Gate source ref that was resolved before checkout                                                                                            |\n| `publish-source-sha`                  | Exact source commit used by checkout, build, verify, and artifacts                                                                           |\n| `publish-source-locked`               | `true` when a `publish-gate/*` source ref was explicitly locked                                                                              |\n| `publish-source-channel`              | `alpha`, `release`, `anchor`, or `major` parsed from the source ref                                                                          |\n| `publish-source-line`                 | Product line parsed from source refs such as `v22/v22.22`                                                                                    |\n| `publish-source-consumer-version`     | Consumer package version parsed from source refs                                                                                             |\n| `release-manifest-json`               | Resolved release manifest including source lock, version state, and anchor data                                                              |\n\nThe aggregate summaries are intentionally artifacts as well as outputs. GitHub\nActions matrix outputs are not a reliable place to carry every platform's full\nmanifest, so Buildchain uploads each platform manifest and then emits one\naggregate build summary artifact after the matrix completes. Buildchain uploads\n`diagnostics-summary.json` as a separate aggregate diagnostics summary artifact,\na compact rollup of each platform's small diagnostics upload. The rollup keeps\nper-platform runner facts, checked tool versions/missing tools, package\nmanager/cache directory details, compiler-cache availability, lifecycle timing,\nprocess sampler context, and links back to the exact platform artifacts. Each\nplatform diagnostics upload includes `diagnostics.json`,\n`diagnostics-manifest.json`, the lifecycle `events.jsonl`, and process sampler\nsidecars when enabled, so slow-build diagnosis does not require downloading the\nbinary platform artifact or the aggregate build summary. The sidecar manifest\nrecords the uploaded diagnostics files with bytes and sha256 hashes. Each\n`diagnostics.json` also records the related binary artifact name, manifest\nartifact name, diagnostics artifact name, diagnostics sidecar manifest path, and\nplatform id in `links`, so a reviewer can navigate from the small diagnostics\nartifact back to the exact platform outputs when deeper inspection is needed.\nThe workflow output `build-diagnostics-summary-json` includes\n`diagnosticsContractWarningCount` and `diagnosticsManifestWarningCount` so\nrelease jobs can detect drifting diagnostics JSON contracts and missing or\ndrifting diagnostics sidecar manifests without downloading the per-platform\ndiagnostics artifacts first.\n\n## Artifact Signing Authority\n\nArtifact signing is a Buildchain capability, not a macOS application workflow.\nConsumers declare desired signature state next to their artifact facts; they do\nnot configure certificates, Team IDs, notary credentials, protected\nenvironments, authority roles, or signing jobs:\n\n```toml\n[[signing.artifacts]]\nid = \"native-engine\"\npath = \"dist/kungfu-engine\"\nprofile = \"auto\"\nkind = \"mach-o\"\nplatforms = [\"macos-arm64\", \"macos-x64\"]\n```\n\nEvery native and container build lane reads this declaration after the build\nlifecycle and before verification. Buildchain binds the exact artifact bytes or directory tree to\nthe caller repository, source commit, source tree, immutable runtime, platform,\nand requested signature semantics, then publishes a deterministic\n`<artifact>-signing-request-<platform>-<source-sha>` request. No consumer\nworkflow step is required. The lifecycle runner automatically adds declarations\nselected for the current platform to the `build` manifest scan, including\nsubjects outside the caller's ordinary `artifact-paths`; this extends the\nevidence preimage without silently adding those subjects to the ordinary\nartifact upload.\n\nThe request root is a Buildchain-owned generated output. After the declaration,\nlifecycle manifest, and source paths pass validation, sealing replaces that root\nbefore materializing the current request set. This keeps repeated jobs on a\nself-hosted runner idempotent and prevents stale requests from an earlier run\nfrom entering the uploaded request artifact. An output root that contains the\nworkspace, working directory, lifecycle manifest, or any declared subject is\nrejected before cleanup.\n\nSelf-hosted runners whose network requires different routes for Artifact upload\nand download can scope an upload-only proxy bypass to the sealed signing request:\n\n```yaml\nwith:\n  artifact-signing-request-upload-no-proxy: \".blob.core.windows.net\"\n```\n\nThe caller repository variable\n`BUILDCHAIN_ARTIFACT_SIGNING_REQUEST_UPLOAD_NO_PROXY` provides the same value\nwithout changing a consumer workflow; an explicit workflow input takes\nprecedence. When neither is set, Buildchain preserves the runner's existing\n`NO_PROXY` and `no_proxy` values. The resolved value applies only to the\nBuildchain-owned signing-request upload. Authority dispatch and immutable\nsigned-result download keep the runner's original proxy route. This is a\ntransport control only: it does not change request bytes, signing authority,\nartifact identity, or verification policy.\n\n`profile = \"auto\"` resolves signable Apple artifacts such as Mach-O files,\n`.dylib`, `.framework`, `.app`, `.xpc`, `.plugin`, `.pkg`, `.dmg`, and macOS\narchives containing native code to the native `apple-developer-id` provider.\nFor a declared macOS `archive`, the authority safely extracts the sealed\ncontainer, signs and verifies every Mach-O payload, signs Mach-O payloads inside\nembedded Python wheels, rebuilds each affected wheel's PEP 427 `RECORD`, and\nrecreates the original zip or tar.gz before returning the exact final bytes.\nWindows `pe` and `binary` artifacts\nresolve to timestamped native `windows-authenticode`; Windows PE never falls\nback to a detached signature. Linux and other non-native binary files,\narchives, blobs, and directories resolve to `detached-signature-v1`. Buildchain records that as a\ndetached cryptographic signature and never misrepresents it as an operating\nsystem code signature. Explicit incompatible provider/kind/platform\ncombinations fail closed.\n\nThe request schema rejects credential and authority-infrastructure fields. The\nBuildchain-owned signing authority is responsible for credential selection,\nnative signing, notarization where applicable, immutable result delivery, and a\nreceipt bound to the request digest, runtime SHA, output digest, and signature\nevidence. Consumer repositories neither receive nor duplicate credential-island\nmaterial. The reusable workflow dispatches the sealed request to the\nBuildchain repository, waits for its protected authority workflow, verifies the\nimmutable result, replaces only the declared artifact with the returned final\nbytes. The ordinary platform lane completes the consumer's functional\nverification before delegation. A GitHub-hosted finalization lane then verifies\nthe authority result against the sealed request, imports the exact signed bytes,\nand recomputes the final manifest before replacing the deterministic artifact.\nThe signing result is never downloaded back to a self-hosted native runner.\nPlatform manifests, KFD evidence, checksums, and Release Passport inputs\ntherefore observe the final signed artifact rather than the pre-signing build\noutput.\n\nFor a standalone Mach-O request, the authority requires strict Developer ID\nverification, the declared Team ID, hardened runtime, and an `Accepted`\n`notarytool` result for the exact submission. Apple creates the notarization\nticket for that binary and publishes it online, but\n[standalone binaries do not support stapling](https://developer.apple.com/documentation/security/customizing-the-notarization-workflow).\nBuildchain therefore records\n`standalone-notary-ticket-online` and does not misapply app-bundle\n`spctl --assess --type execute` semantics to the raw executable.\n\nFor a compound archive request, the authority notarizes the complete extracted\nsigned product tree and records `compound-notary-ticket-online`. A generic\narchive container cannot carry a stapled ticket and is not itself a Gatekeeper\nexecution target; Gatekeeper evaluates the extracted signed code. Archive path\nand symlink validation fail closed before any payload is signed.\n\nFor a declared `app-bundle`, the same protected authority extracts the sealed\napplication, derives and verifies its bundle identity, signs nested native code,\nsubmits both the application and disk image for notarization, staples and\nGatekeeper-assesses both deliverables, and returns a ZIP, DMG, evidence document,\nand source-bound manifest. The reusable workflow verifies those returned bytes\non GitHub-hosted infrastructure, adds them to the normal macOS platform payload,\nand publishes a separate `<artifact>-macos-credential-<source-sha>` projection\nfor release pipelines that consume the credential-island evidence contract.\nConsumers declare the `.app` under `[[signing.artifacts]]`; they do not configure\nan environment, certificate, notary credential, or authority workflow.\n\nThe durable v3 authority runtime is\n`authority/v3/v3.0/artifact-signing`. It is channel-neutral: alpha and stable\nrelease work use the same protected `buildchain-artifact-signing` environment\nand provider identities. The authority ref is protected independently from\nrelease channels and can advance only through reviewed, checked changes; the\ntemporary `train/v3/v3.0/artifact-signing-authority` ref is retained only as a\nbounded migration rollback.\n\nThe older `credential-island-macos-*` reusable-workflow inputs remain a\ncompatibility surface while existing callers migrate. They are not the target\nconsumer contract and must not be used to design new integrations.\n\n## Artifact Transfer Relay\n\nBy default, platform jobs upload payloads, manifests, and diagnostics directly\nto GitHub artifacts:\n\n```yaml\nwith:\n  artifact-transfer-mode: github-artifacts\n  artifact-compression-level: 0\n```\n\nDirect GitHub Artifact payloads default to compression level `0`. Buildchain\nartifacts are commonly already-compressed archives; storing them without a\nsecond compression pass shortens the upload window while preserving the same\nartifact name, run/id/digest binding, retention, and no-overwrite behavior.\nCallers may select `1` through `9` for payloads that materially benefit from\ncompression. Manifests and diagnostics retain their existing small-artifact\nbehavior.\n\nLarge self-hosted native builds can opt into the first-class S3 relay path:\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    with:\n      runner-preset: kungfu-v4-self-hosted\n      artifact-transfer-mode: s3-to-github-artifacts\n      artifact-relay-s3-bucket: ${{ vars.BUILDCHAIN_ARTIFACT_RELAY_S3_BUCKET }}\n      artifact-relay-s3-region: ${{ vars.BUILDCHAIN_ARTIFACT_RELAY_S3_REGION }}\n      artifact-relay-s3-prefix: ${{ vars.BUILDCHAIN_ARTIFACT_RELAY_S3_PREFIX }}\n```\n\nIn relay mode, each self-hosted platform job uploads the heavy payload files to\nS3 and uploads only a small `relay-manifest.json` to GitHub. A GitHub-hosted\n`relay-artifacts` job then assumes the configured download role, downloads the\npayloads from S3, verifies every file by SHA256, and re-uploads the normal\nGitHub artifacts under the same artifact names that direct mode uses. Downstream\nsummary, release-candidate, and promote-only workflows therefore continue to\nconsume GitHub artifacts and do not need custom S3 logic.\nThe relay implementation uses Node.js plus the standard AWS environment\ncredentials from GitHub OIDC; runner images and build containers do not need the\nAWS CLI installed.\n\nAfter the GitHub artifact uploads succeed, Buildchain deletes the S3 objects\nlisted in the relay manifest for that platform. If any download, verification,\nor GitHub artifact upload fails, cleanup is skipped so maintainers can inspect\nthe retained S3 payload. Configure a short bucket lifecycle expiration as a\ncost and cleanup backstop.\n\nThe relay configuration is intentionally generic. Buildchain does not hard-code\norganization buckets, regions, or role ARNs. Callers may pass explicit inputs,\nor set repository/organization variables and secrets using these names:\n\n| Variable or secret                               | Meaning                                                 |\n| ------------------------------------------------ | ------------------------------------------------------- |\n| `BUILDCHAIN_ARTIFACT_RELAY_S3_BUCKET`            | Relay bucket name                                       |\n| `BUILDCHAIN_ARTIFACT_RELAY_S3_REGION`            | Relay bucket region                                     |\n| `BUILDCHAIN_ARTIFACT_RELAY_S3_PREFIX`            | Relay object prefix; defaults to `buildchain-artifacts` |\n| `BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN`          | Shared OIDC role ARN for upload and download            |\n| `BUILDCHAIN_ARTIFACT_RELAY_S3_UPLOAD_ROLE_ARN`   | Upload OIDC role ARN for self-hosted build jobs         |\n| `BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN` | Download OIDC role ARN for the GitHub-hosted relay job  |\n| `BUILDCHAIN_ARTIFACT_RELAY_S3_OIDC_AUDIENCE`     | Optional OIDC audience override                         |\n\nFor AWS China regions, Buildchain defaults the OIDC audience to\n`sts.amazonaws.com.cn`; other regions default to `sts.amazonaws.com`. The caller\nworkflow must allow `id-token: write`, and the target role trust policy should\nrestrict GitHub OIDC claims to the expected organization, repository, workflow,\nand branch/ref. The S3 permissions should be scoped to the relay bucket/prefix\nused by the repository.\nUpload roles need write/delete access under the relay prefix; download roles\nneed read access plus delete access for successful cleanup.\n\nRelay mode is opt-in and does not affect forks or open-source users that do not\nconfigure S3. Missing bucket, region, upload role, or download role values fail\nbefore the heavy build matrix is scheduled. Buildchain treats S3 as a transport\ncache, not as the final release evidence store; the final audit entry remains\nthe GitHub artifact set plus the Buildchain build summary and release-candidate\npassport.\n\nSet `release-candidate: true` when the successful reusable build is meant to be\nthe artifact source promoted later. Buildchain then uploads\n`release-candidate-passport.json` under the\n`<artifact-name>-release-candidate-<publish-source-sha>` artifact name. Promotion\njobs can pass that passport to `promote-buildchain-ref` with\n`promote-only-release-candidate: \"true\"` so source, channel, platforms, and the\naggregate build-summary hash are checked before publish-gate side effects. The\npassport records the locked commit's Git tree SHA, so a post-merge channel HEAD\ncan be accepted only when it is tree-equivalent to the PR-stage build evidence.\n\n## Publish Gate\n\nBuildchain separates \"may build/verify\" from \"may publish.\" A same-repository\npull request may be trusted enough to run the build matrix, but it still must\nnot publish packages, S3 objects, release pages, or preview aliases. Publishing\nis allowed only when the caller explicitly requests a channel and the current\nevent/ref matches that channel.\n\nUse `publish-channel` to request a channel:\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    with:\n      publish-channel: release\n\n  publish:\n    needs: build\n    if: ${{ needs.build.outputs.publish-allowed == 'true' }}\n    runs-on: ubuntu-24.04\n    steps:\n      - run: ./scripts/publish.sh\n```\n\nDefault channels are:\n\n| Channel   | Allowed refs                                                                                         |\n| --------- | ---------------------------------------------------------------------------------------------------- |\n| `none`    | Never publishes; this is the default                                                                 |\n| `alpha`   | `alpha/vN/vN.M` branches or exact `vN.M.P-alpha.K` tags                                              |\n| `release` | `release/vN/vN.M` branches or release tags such as `vN.M.P`, `vN.M`, `vN`                            |\n| `major`   | `publish-gate/major`, legacy `major-gate`, or next-major release tags such as `vN.0.0`, `vN.0`, `vN` |\n\nPull request events always produce `publish-allowed=false`, even when the PR is\nfrom the same repository. Untrusted fork events also produce\n`publish-allowed=false`; with the default `untrusted-policy: fail`, the workflow\nthen fails before any build runner starts.\n\nProjects with their own channel names can pass `publish-refs-json`:\n\n```yaml\nwith:\n  publish-channel: nightly\n  publish-refs-json: >-\n    {\"nightly\":[\"^refs/heads/nightly/v\\\\d+$\"]}\n```\n\nThe aggregate build summary includes the same publish gate decision under\n`publishGate`, so a downloaded artifact summary explains both what was built and\nwhy it was or was not eligible to publish.\n\n## Publish Source Lock\n\n`publish-channel` answers \"may this event publish?\" Source lock answers \"which\nsource tree is the publish decision about?\" A caller can pass `publish-source-ref`\nto bind a publish run to a reviewed gate branch before any checkout happens:\n\n| Ref                                              | Meaning                                                                     |\n| ------------------------------------------------ | --------------------------------------------------------------------------- |\n| `publish-gate/alpha/<line>/<consumer-version>`   | Build and publish an alpha candidate for a consumer line                    |\n| `publish-gate/release/<line>/<consumer-version>` | Build and publish a production candidate for a consumer line                |\n| `publish-gate/anchor`                            | Resolve an explicit anchor request; it does not publish artifacts by itself |\n| `publish-gate/major`                             | Gate the next major source state                                            |\n| `major-gate`                                     | Legacy compatibility alias for the major gate                               |\n\nFor alpha and release refs, `<line>` is intentionally allowed to contain `/`, so\nKungfu-style lines such as `v22/v22.22` stay readable. The final path segment is\nthe consumer-visible version, for example `22.22.3-kf.0`.\n\nThe reusable workflow resolves the branch tip to `publish-source-sha`, checks out\nthat SHA in every build job, and uses the same SHA in artifact names, manifests,\nand aggregate summaries. Reruns therefore rebuild the same source tree even if a\ngate branch moves later.\n\nBefore any heavy build matrix is scheduled, the workflow also verifies that the\ntarget channel ref implied by the source lock already points at\n`publish-source-sha` and that the target channel HEAD came from the required\nmerged same-repository channel PR. `publish-gate/alpha/<line>/<version>` must\nmatch `alpha/<line>` and have PR lineage `dev/<line> -> alpha/<line>`;\n`publish-gate/release/<line>/<version>` must match `release/<line>` and have PR\nlineage `alpha/<line> -> release/<line>`. If either check fails, the run fails\nfast with a diagnostic telling maintainers to merge the source commit through\nthe channel PR first. This keeps verify from spending runner time on a source\ntree that cannot legally enter the requested publish channel.\n\nThe resolved release manifest is uploaded as an artifact and emitted as\n`release-manifest-json`. It records:\n\n- source ref, source SHA, channel, line, and consumer version;\n- configured version strategy and configured version-state files;\n- each version file's value, with release gates failing closed if the configured\n  files do not equal the consumer version;\n- anchor manifest summary for anchored/manual projects;\n- explicit anchor request JSON for `publish-gate/anchor`;\n- publish registry, dist-tag, and gate visibility metadata.\n\nPublish side-effect jobs should verify the lock immediately before publishing:\n\n```yaml\n- name: Verify publish gate did not move\n  run: node .buildchain/runtime/scripts/verify-publish-source-lock.mjs\n  env:\n    BUILDCHAIN_PUBLISH_SOURCE_REF: ${{ needs.build.outputs.publish-source-ref }}\n    BUILDCHAIN_PUBLISH_SOURCE_SHA: ${{ needs.build.outputs.publish-source-sha }}\n    BUILDCHAIN_SOURCE_REPOSITORY: ${{ github.repository }}\n    GITHUB_TOKEN: ${{ github.token }}\n```\n\nIf the branch tip no longer matches the manifest SHA, the publish job must fail\nclosed. Moving a gate branch creates a new publish decision and should produce a\nnew build run.\n\n## Release Candidate Promote-Only\n\nFor native package sets, the PR build is the only heavy build. When a PR targets\n`alpha/<line>` or `release/<line>`, `.build.yml` uploads a release-candidate\nbundle next to the platform artifacts. The bundle contains:\n\n- `release-candidate.passport.json`;\n- the aggregate `build-summary.json`;\n- copied platform manifest evidence for the built platforms.\n\nThe passport records two separate source identities:\n\n- `builtSourceSha` / `builtSourceTreeSha`: the PR-stage source that produced the\n  artifacts, usually the PR merge ref;\n- `promotionChannelSha` / `promotionChannelTreeSha`: the post-merge channel\n  commit used for publish authority.\n\nThe reusable promote wrapper resolves the merged PR, finds exactly one matching\nPR-stage release-candidate artifact, downloads it with the build summary and\npayload artifacts from the same PR-stage run, validates the payload count,\ncompares the built tree with the promotion channel tree, locks\n`publish-gate/{alpha,release,major}` to the promotion channel commit, and then\ncalls `actions/promote-buildchain-ref` with\n`promote-only-release-candidate: \"true\"` and\n`require-publish-source-lock: \"true\"`. The wrapper passes the created\n`publish-gate/*` ref, target SHA, and `locked=true` into the promote action, so\nfloating `@v3` consumers receive publish-side source-lock drift protection by\ndefault. It also defaults `branch-protection-bypass-apps` to `github-actions`\nso the workflow automation can apply generated version-state and channel\nbookkeeping on protected `dev`/`alpha`/`release` branches after the reviewed\nchannel PR has merged. Other App slugs and all user or team bypass actors are\nrejected. The wrapper uses the run-scoped `github.token` as the generated ref\nupdate token for protected bookkeeping PATCH calls, so the exact GitHub Actions\nApp authority can sync dev immediately after alpha/release publish without a\npost-publish PR.\nIt does not call `.build.yml`, does not create a matrix, and must fail before\npublish if the RC evidence, payload set, or source-lock ref is missing or\nambiguous.\n\nThe public `release-candidate-promote.yml` is a generated channel router. It\nderives the publication lane from `target-ref`, then selects the matching\nadvanced workflow shell, runtime, and consumer lock before the advanced\npromotion starts:\n\n- alpha targets use `.release-candidate-promote.yml@vN-alpha`, runtime\n  `vN-alpha`, and `buildchain-alpha-contract-lock-path`;\n- release and major targets use `.release-candidate-promote.yml@vN`, runtime\n  `vN`, and `buildchain-stable-contract-lock-path`.\n\nThe generated router also owns the stable-shell layout transition through\n`.buildchain/promotion-shell-routing.json`. The v3 stable and alpha lanes call\nthe hidden advanced workflow at the exact immutable SHA behind their selected\nv3 channel state and forward the complete internal promotion identity surface.\nThe logical shell identity remains `vN`, and the router retains it in the public\naudit outputs. The internal advanced-shell call receives the exact call ref\nselected by the routing configuration, so its called-workflow ref check and\ncheckout SHA both bind to the same immutable identity. Updating a routing pin\nafter a release does not require any consumer declaration change.\n\nThe router resolves immutable SHAs and the selected lock digest before candidate\ndownload. The advanced shell verifies the same router, shell, runtime, lock,\nchannel, and target binding again. Train and exact-SHA runtime overrides remain\nrestricted to trusted `workflow_dispatch` actors with write, maintain, or admin\npermission. Promotion controller evidence, the promotion copy of the release\ncandidate passport, and the final release passport record these identities.\n\n```yaml\njobs:\n  promote:\n    uses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v3\n    secrets:\n      buildchain-issue-app-id: ${{ secrets.BUILDCHAIN_ISSUE_APP_ID }}\n      buildchain-issue-app-private-key: ${{ secrets.BUILDCHAIN_ISSUE_APP_PRIVATE_KEY }}\n    with:\n      buildchain-channel: auto\n      buildchain-alpha-contract-lock-path: .buildchain/alpha-contract-lock.json\n      buildchain-stable-contract-lock-path: .buildchain/contract-lock.json\n      channel: alpha\n      target-ref: alpha/v22/v22.22\n      artifact-name: libnode\n      # Defaults to build.yml / Build. Override only when the PR-stage build\n      # workflow uses a different file or display name.\n      release-candidate-workflow-file: build.yml\n      release-candidate-workflow-name: Build\n      package-manager: npm\n      publish-target: npm\n      runner-preset: github-hosted\n      trusted-publishing: true\n      github-release: true\n      required-status-check: check / check\n      required-artifact-count: 3\n      publish-dist-tag: alpha\n      publish-package-set-order: platforms-first-main-last\n      publish-package-main: \"@kungfu-tech/libnode\"\n      release-passport-product-name: Libnode\n      buildchain-contract-drift-issue-mode: compatible-and-breaking\n```\n\nExisting callers may keep `buildchain-contract-lock-path`; a non-empty explicit\npath overrides channel-specific selection for compatibility. Migration only\nrequires adding the two channel lock inputs and may retain the remaining common\npromotion declaration unchanged. Consumers must not call the dot-prefixed\nadvanced workflow directly.\n\n`buildchain-issue-app-id` and `buildchain-issue-app-private-key` are optional\nbut recommended for cross-repository consumers. They should identify a GitHub\nApp installation with `issues: write` on `kungfu-systems/buildchain`; the\nwrapper mints the installation token before calling\n`actions/report-buildchain-issue`. Consumers can also pass a pre-minted\n`buildchain-issue-token`. If both are omitted, the wrapper falls back to\n`BUILDCHAIN_ISSUE_TOKEN`, `BUILDCHAIN_PROMOTION_TOKEN`, and then the consumer\nworkflow's `github.token`; the last fallback can only report issues when it has\nwrite access to the target Buildchain repository.\n\n`publish-required-artifacts-json` can still be passed explicitly for custom\npublish targets. Custom OCI requirements may omit pre-publish refs and digests;\nthe action resolves the exact version ref and validates final digests and any\nbuilt/reused provenance after `lifecycle.publish`. For the default\n`publish-artifact-kind: npm` path, consumers do\nnot download artifacts or run repository scripts to build publish evidence. The\nwrapper downloads the PR-stage payload artifacts, finds the downloaded `.tgz`\npackages, reads each tarball's `package/package.json` for the real scoped\npackage name and version, computes the npm `sha512-...` integrity from the\ntarball bytes, marks the package matching `publish-package-main` as `role:\nmain`, marks the rest as `role: platform`, and passes the generated\n`publish-required-artifacts-json` to `promote-buildchain-ref` before any publish\nside effect. Downloaded platform manifests are still passed into the release\npassport unless `release-passport-platform-manifest-paths` is set explicitly.\nThe same Buildchain contract lock check runs before release-candidate\nresolution and before publish. A compatible `v3` drift leaves an issue in the\nconsumer repository but does not trigger a second heavy build; an incompatible\ndrift fails before publish side effects.\n\nThe wrapper publishes the public release tag as a GitHub Release by default.\nAfter `promote-buildchain-ref` reports a complete release transaction, the\nwrapper creates or updates the public release, marks semver prerelease tags\nsuch as `v1.2.3-alpha.0`, `v1.2.3-rc.1`, or `v22.22.3-kf.3-alpha.7` as\n`prerelease=true` and `make_latest=false`, marks stable semver tags as latest,\nand uploads the publish evidence file plus every file in the generated release\npassport directory, including `buildchain.release.json` and `check-report.json`.\nFor anchored/manual package releases, the public release tag is derived from the\npublished package version and the internal exact transaction tag remains\navailable in the release passport.\nConsumers do not need to hand-write `gh release` logic to trigger\n`release.published` propagation. Set `github-release: false` only for\nrepositories that intentionally do not maintain GitHub Releases.\nIf the transaction still needs protected-ref finalization, the wrapper defers\nGitHub Release creation until the later run that reaches `state=complete`.\n\nCustom publish jobs can also repeat the channel-ref preflight:\n\n```yaml\n- name: Verify publish channel ref still matches\n  run: node .buildchain/runtime/scripts/verify-publish-channel-ref.mjs\n  env:\n    BUILDCHAIN_PUBLISH_SOURCE_REF: ${{ needs.build.outputs.publish-source-ref }}\n    BUILDCHAIN_PUBLISH_SOURCE_SHA: ${{ needs.build.outputs.publish-source-sha }}\n    BUILDCHAIN_SOURCE_REPOSITORY: ${{ github.repository }}\n    GITHUB_TOKEN: ${{ github.token }}\n```\n\nAnchored/manual package release jobs should also make the Buildchain promotion\naction validate that publication is entering through the same\n`publish-gate/{alpha,release,major}` source-lock contract before any package\npublish side effect:\n\n```yaml\n- name: Promote release ref and publish npm package set\n  uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3\n  with:\n    sha: ${{ needs.build.outputs.publish-source-sha }}\n    target-ref: release/v22/v22.22\n    require-publish-source-lock: \"true\"\n    publish-source-ref: ${{ needs.build.outputs.publish-source-ref }}\n    publish-source-sha: ${{ needs.build.outputs.publish-source-sha }}\n    publish-source-locked: ${{ needs.build.outputs.publish-source-locked }}\n```\n\n`target-ref` stays the Buildchain channel promotion target, such as\n`alpha/v22/v22.22`, `release/v22/v22.22`, or `publish-gate/major`.\n`publish-source-ref` is the reviewed source-lock branch that authorized this\nspecific package publication. For alpha and release package publications, the\nsource-lock branch must point at the exact channel-line commit that promotion is\nvalidating; it is not a replacement for `target-ref`.\n\nThis keeps the version bump commit, publish authorization, and auditable publish\nentrypoint on the Buildchain source-lock protocol. The CLI form\n`buildchain publish-source validate-anchored-release --json` is still useful for\ncustom publish scripts, but the preferred GitHub Actions gate is the promotion\naction input above. A publish job that still runs directly from `alpha/*` or\n`release/*` channel branches fails this check because those refs are channel\nstate, not publish-gate decisions.\n\n## Package-Set Publish Plan\n\nProjects that publish multiple packages should treat package publication as a\npackage-set operation. Buildchain's package-set planner uses these rules:\n\n- platform packages publish first;\n- the main package publishes last;\n- the dist-tag move happens only after the full package set is present;\n- reruns accept already-published packages only when package name, version, and\n  integrity match;\n- an existing package with different integrity is a hard failure.\n\nThis keeps a consumer from observing a floating dist-tag that points to a main\npackage before all platform artifacts for the same source SHA are available.\n\n## Command Sources\n\nThe workflow runs `.buildchain/buildchain.toml` lifecycle stages by default:\n\n```toml\n[lifecycle.install]\ncommand = \"corepack yarn install --immutable\"\n\n[lifecycle.build]\ncommands = [\n  \"corepack yarn make\",\n  \"corepack yarn build\",\n]\n\n[lifecycle.verify]\ncommand = \"corepack yarn test\"\n```\n\nCallers can override any stage for one invocation:\n\n```yaml\nwith:\n  build-command: cmake --build build --config Release\n  verify-command: ctest --test-dir build --output-on-failure\n```\n\nEvery native and container matrix job is bounded by\n`lifecycle-timeout-minutes`, which defaults to 120 minutes. The same input is\nthe fallback deadline for each install, build, and verify action, so a hung\ncommand fails with the lifecycle name and matrix platform before it can occupy\na self-hosted runner indefinitely. A stage-level `timeout_minutes` in\n`buildchain.toml` remains the more specific override for that stage.\n\n```yaml\nwith:\n  lifecycle-timeout-minutes: 90\n```\n\nThe reusable build workflow samples the build lifecycle by default and carries\nthe generated summary into the final verify diagnostics. Callers can override\nthe sidecar path or disable sampling:\n\n```yaml\nwith:\n  sample-process-tree: true\n  process-summary-path: .buildchain/diagnostics/process-summary.json\n  process-sample-interval-ms: 15000\n  requested-parallelism: 20\n```\n\nWhen `sample-process-tree` is true, Buildchain wraps either `build-command` or\nthe configured `lifecycle.build` stage with `buildchain sample process-tree`.\nThe path is relative to the checked-out workspace and is read again during the\nfinal verify lifecycle. Custom workflows can still write their own sampler\nsummary and pass `process-summary-path`; Buildchain reads the file after the\nlifecycle command finishes, so it may be produced during the same invocation.\nWhen the build stage is optional, the reusable workflow treats the default\nsampler path as optional during verify; an explicitly supplied\n`process-summary-path` remains required.\n\nFor custom workflows, use the action directly:\n\n```yaml\n- uses: kungfu-systems/buildchain/actions/run-lifecycle@v3\n  with:\n    stage: build\n    required: \"true\"\n    timeout-minutes: \"90\"\n    artifact-name: libnode-linux-x64-${{ github.sha }}\n    artifact-paths: |\n      dist\n      build/stage\n```\n\n## Artifact Contract\n\nEach platform upload uses `artifact-name-template`. The default is:\n\n```text\n{artifact}-{platform}-{sha}\n```\n\nSupported placeholders are `{artifact}`, `{artifactName}`, `{platform}`,\n`{platformId}`, `{platformName}`, `{sha}`, `{shortSha}`, `{ref}`, `{runId}`,\nand `{runAttempt}`. Invalid GitHub artifact name characters are normalized to\n`-`, so `{ref}` remains deterministic even for refs such as\n`refs/heads/dev/v3/v3.0`.\n\nEach platform also writes and uploads:\n\n```text\n.buildchain/artifacts/<platform-id>/manifest.json\n.buildchain/artifacts/<platform-id>/summary.json\n```\n\nThe manifest schema is:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"contract\": \"kungfu-buildchain-artifact\",\n  \"artifactName\": \"libnode-linux-x64-<sha>\",\n  \"platform\": {\n    \"id\": \"linux-x64\",\n    \"name\": \"Linux x64\",\n    \"os\": \"Linux\",\n    \"arch\": \"X64\"\n  },\n  \"git\": {\n    \"repository\": \"kungfu-systems/libnode\",\n    \"sha\": \"<sha>\",\n    \"ref\": \"<ref>\",\n    \"runId\": \"<run id>\",\n    \"runAttempt\": \"<attempt>\"\n  },\n  \"lifecycle\": {\n    \"stage\": \"verify\",\n    \"commandSource\": \"buildchain.toml\",\n    \"executed\": true\n  },\n  \"summary\": {\n    \"contract\": \"kungfu-buildchain-artifact-summary\",\n    \"artifactName\": \"libnode-linux-x64-<sha>\",\n    \"fileCount\": 1,\n    \"totalBytes\": 1234,\n    \"digest\": \"<hex>\"\n  },\n  \"expectedArtifacts\": {\n    \"ok\": true,\n    \"source\": \"expected-artifacts-json\",\n    \"checks\": []\n  },\n  \"files\": [\n    {\n      \"path\": \"dist/example.zip\",\n      \"size\": 1234,\n      \"sha256\": \"<hex>\"\n    }\n  ]\n}\n```\n\nArtifact names do not include actor names, timestamps, or retry counters. Reruns\nproduce a new GitHub Actions run but keep the same source SHA/platform contract.\n\n`expected-artifacts-json` fails the build before upload when the artifact does\nnot match the caller's declared contract. Supported checks are:\n\n| Field           | Meaning                              |\n| --------------- | ------------------------------------ |\n| `minFiles`      | Minimum number of manifest files     |\n| `maxFiles`      | Maximum number of manifest files     |\n| `minTotalBytes` | Minimum total byte count             |\n| `requiredPaths` | Exact manifest paths that must exist |\n\n## Trusted Event Gate\n\nThe workflow has an explicit `trust-gate` job. By default, pull requests from\nforks fail before any build job can reach self-hosted runners, secrets,\npublishing credentials, or heavyweight build commands. Same-repository PRs,\nworkflow dispatches, and protected branch events can proceed.\n\nIf a repository wants fork PRs to skip rather than fail, it can set:\n\n```yaml\nwith:\n  untrusted-policy: skip\n```\n\nDo not set `require-trusted-event: false` for workflows that use self-hosted\nrunners or secrets.\n\nThe build matrix and the workflow control plane are routed independently. The\nmatrix continues to use `runner-preset` and `platforms-json`. Consumers with a\ngoverned runner may also move channel resolution, trust evaluation, contract\nresolution, controller evidence, artifact transfer, and aggregation off the\ndefault GitHub-hosted runner:\n\n```yaml\nwith:\n  control-runner-json: '[\"self-hosted\",\"agent-120\"]'\n  runner-preset: custom\n  platforms-json: '[{\"id\":\"linux-x64\",\"name\":\"Linux x64\",\"runner\":\"[\\\"self-hosted\\\",\\\"agent-120\\\"]\"}]'\n```\n\n`control-runner-json` is additive and defaults to `[\"ubuntu-24.04\"]`. Keep\n`require-trusted-event: true` whenever either runner input selects\n`self-hosted`; a self-hosted control plane must not be exposed to untrusted fork\nevents or arbitrary caller-controlled workflow code.\n\n`require-trusted-event` controls access to build runners. It does not override\nthe publish gate: pull requests remain non-publishing events.\n\n## Fixture\n\n`fixtures/libnode-shaped` is the contract fixture. It has:\n\n- `package.json` version state;\n- `.buildchain/buildchain.toml` with `install`, `build`, `verify`, and `publish`;\n- cross-platform Node scripts that create small `dist/` outputs;\n- `Build Surface Fixture` workflow coverage.\n\nThe fixture proves the reusable surface without running the real libnode native\nbuild."
     },
     {
       "id": "manual:runtime-train-validation",
@@ -2053,7 +2139,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/runtime-train-validation.md",
-      "digest": "sha256:c9ebf451294f92a2be3aa2ac4b2ec7afb3cc17bbeae2ece7879b800c0f274a40",
+      "digest": "sha256:1a4ce3fc2c150f88bc4d32123a108478ba5d73d0d69b8a95bf0d6670e32618a0",
       "headings": [
         {
           "level": 1,
@@ -2091,7 +2177,7 @@
           "anchor": "trust-and-limitation"
         }
       ],
-      "markdown": "# Runtime Train Validation\n\nBuildchain consumers should keep stable workflow refs such as `@v3` in\ncommitted workflow YAML. Runtime trains provide a temporary validation pointer\nfor Buildchain changes that are ready for downstream testing but not yet\npromoted through the normal `dev -> alpha -> release` chain.\n\nOfficial floating channels are not runtime overrides. A consumer that\ndeliberately follows `@v3-alpha` gets the matching runtime on pull requests and\npushes because the reusable workflow reads the called workflow identity from\n`job.workflow_ref`. Passing `buildchain-ref: v3-alpha` explicitly is also\naccepted when the caller wants the channel binding visible in its input set.\nThe caller's `github.workflow_ref` is not used for this inference because it\nidentifies the caller workflow during reusable calls.\n\n## Train refs\n\nA train ref is a branch in the Buildchain repository:\n\n```text\ntrain/v3/v3.0/<capability>\n```\n\nIt is a validation pointer, not a release channel:\n\n- it does not move `v2`, `vX.Y`, `vX.Y-alpha`, exact tags, npm dist-tags, or\n  production refs;\n- it must not be pinned as a long-term production dependency;\n- it should point at the Buildchain commit that downstream maintainers are\n  expected to validate;\n- it is not a pending merge target or a delivery state;\n- the final durable path is still a pull request into the active `dev/*`\n  channel, followed by the requested alpha or release promotion.\n- it may remain for a retention window after release so initiating repositories\n  have a stable fast-use and rollback channel while stable refs, caches, or\n  rollout windows settle.\n\n## Buildchain contributor requirement\n\nWhen a Buildchain change needs downstream validation before stable refs move,\npublish a train ref before asking consumers to test it:\n\n```sh\ngit push origin HEAD:refs/heads/train/v3/v3.0/<capability>\n```\n\nUse a capability slug that names the behavior being validated, for example:\n\n```text\ntrain/v3/v3.0/runtime-loader\ntrain/v3/v3.0/toolkit-diagnostics\ntrain/v3/v3.0/site-source-of-truth\n```\n\nThe pull request or validation request should include the train ref, the exact\ncommit SHA it points to, and the downstream evidence expected from consumers.\nIf the train is refreshed, state the new SHA in the validation thread.\n\nAfter downstream validation succeeds, close out through the normal release\npath. Merge the Buildchain pull request into the active `dev/*` mainline, run\nthe requested alpha or release promotion, and record the final mainline commit\nplus release ref or tag in the delivery thread. Do not leave the train as the\nitem that still needs to be merged; it is only a temporary fast-use,\ndiagnostic, and rollback channel for initiating repositories. Retained trains\nare cleaned up by a separate periodic Buildchain cleanup task.\n\n## Formal artifact-signing authority ref\n\nArtifact signing uses a durable, channel-neutral authority ref after its\nruntime has passed downstream validation:\n\n```text\nauthority/v3/v3.0/artifact-signing\n```\n\nUnlike a train, this ref is a protected execution boundary. Alpha and stable\nrelease intent use the same authority ref and the same\n`buildchain-artifact-signing` environment; channel promotion never selects a\ndifferent certificate environment. Updates to the authority ref require a\nreviewed pull request, the normal `check` and `verify` status contexts, and a\nfast-forward-safe protected branch policy. Deletion and non-fast-forward\nupdates are forbidden.\n\nThe temporary `train/v3/v3.0/artifact-signing-authority` ref remains a bounded\nrollback and diagnostic pointer during migration. It is not the production\nidentity and must not regain credential ownership.\n\n## Consumer workflow requirement\n\nConsumers keep their reusable workflow pinned to the stable shell:\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n```\n\nTo validate a train without committing temporary workflow refs, expose a\ntrusted manual pass-through once:\n\n```yaml\non:\n  workflow_dispatch:\n    inputs:\n      buildchain-ref:\n        description: \"Temporary Buildchain runtime ref for trusted manual validation\"\n        required: false\n        default: \"\"\n\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    with:\n      buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n```\n\nBuildchain initializes new package workflows with this pass-through. Existing\nconsumers that do not have it should add it once before validating a train.\n\n## Validation request\n\nUse this short request when a train is ready:\n\n```text\nBuildchain train ready: buildchain-ref=train/v3/v3.0/<capability>.\nKeep uses: ...@v3; run workflow_dispatch with that buildchain-ref and report the runtime evidence summary.\n```\n\nThe consumer should run a trusted `workflow_dispatch`, paste the train ref into\n`buildchain-ref`, and report the workflow summary or aggregate Buildchain\nsummary. The evidence should include:\n\n- workflow shell ref;\n- requested runtime ref;\n- resolved runtime ref;\n- resolved runtime SHA;\n- stability class;\n- trust decision;\n- rollback ref.\n\n## Trust and limitation\n\nOfficial floating channel refs such as `v2` and `v3-alpha` may be selected on\npull requests and pushes. Train refs and arbitrary exact-SHA overrides still\nfail closed unless the event is `workflow_dispatch` and the actor has write,\nmaintain, or admin permission on the caller repository. Pull requests,\nincluding fork-originated pull requests, cannot use train or exact-SHA\noverrides.\n\nRuntime train validation covers Buildchain runtime scripts, CLI code, local\nactions, configuration parsing, and lifecycle behavior. It cannot validate\nchanges that require the outer reusable workflow YAML itself to change, such as\nnew jobs, permissions, workflow outputs, or matrix topology. Those changes need\na canary workflow path or a temporary explicit workflow ref."
+      "markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-runtime-train-validation\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-31\n  invisible_context: not asserted\n---\n\n# Runtime Train Validation\n\nBuildchain consumers should keep stable workflow refs such as `@v3` in\ncommitted workflow YAML. Runtime trains provide a temporary validation pointer\nfor Buildchain changes that are ready for downstream testing but not yet\npromoted through the normal `dev -> alpha -> release` chain.\n\nOfficial floating channels are not runtime overrides. A consumer that\ndeliberately follows `@v3-alpha` gets the matching runtime on pull requests and\npushes because the reusable workflow reads the called workflow identity from\n`job.workflow_ref`. Passing `buildchain-ref: v3-alpha` explicitly is also\naccepted when the caller wants the channel binding visible in its input set.\nThe caller's `github.workflow_ref` is not used for this inference because it\nidentifies the caller workflow during reusable calls.\n\n## Train refs\n\nA train ref is a branch in the Buildchain repository:\n\n```text\ntrain/v3/v3.0/<capability>\n```\n\nIt is a validation pointer, not a release channel:\n\n- it does not move `v3`, `vX.Y`, `vX.Y-alpha`, exact tags, npm dist-tags, or\n  production refs;\n- it must not be pinned as a long-term production dependency;\n- it should point at the Buildchain commit that downstream maintainers are\n  expected to validate;\n- it is not a pending merge target or a delivery state;\n- the final durable path is still a pull request into the active `dev/*`\n  channel, followed by the requested alpha or release promotion.\n- it may remain for a retention window after release so initiating repositories\n  have a stable fast-use and rollback channel while stable refs, caches, or\n  rollout windows settle.\n\n## Buildchain contributor requirement\n\nWhen a Buildchain change needs downstream validation before stable refs move,\npublish a train ref before asking consumers to test it:\n\n```sh\ngit push origin HEAD:refs/heads/train/v3/v3.0/<capability>\n```\n\nUse a capability slug that names the behavior being validated, for example:\n\n```text\ntrain/v3/v3.0/runtime-loader\ntrain/v3/v3.0/toolkit-diagnostics\ntrain/v3/v3.0/site-source-of-truth\n```\n\nThe pull request or validation request should include the train ref, the exact\ncommit SHA it points to, and the downstream evidence expected from consumers.\nIf the train is refreshed, state the new SHA in the validation thread.\n\nAfter downstream validation succeeds, close out through the normal release\npath. Merge the Buildchain pull request into the active `dev/*` mainline, run\nthe requested alpha or release promotion, and record the final mainline commit\nplus release ref or tag in the delivery thread. Do not leave the train as the\nitem that still needs to be merged; it is only a temporary fast-use,\ndiagnostic, and rollback channel for initiating repositories. Retained trains\nare cleaned up by a separate periodic Buildchain cleanup task.\n\n## Formal artifact-signing authority ref\n\nArtifact signing uses a durable, channel-neutral authority ref after its\nruntime has passed downstream validation:\n\n```text\nauthority/v3/v3.0/artifact-signing\n```\n\nUnlike a train, this ref is a protected execution boundary. Alpha and stable\nrelease intent use the same authority ref and the same\n`buildchain-artifact-signing` environment; channel promotion never selects a\ndifferent certificate environment. Updates to the authority ref require a\nreviewed pull request, the normal `check` and `verify` status contexts, and a\nfast-forward-safe protected branch policy. Deletion and non-fast-forward\nupdates are forbidden.\n\nThe temporary `train/v3/v3.0/artifact-signing-authority` ref remains a bounded\nrollback and diagnostic pointer during migration. It is not the production\nidentity and must not regain credential ownership.\n\n## Consumer workflow requirement\n\nConsumers keep their reusable workflow pinned to the stable shell:\n\n```yaml\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n```\n\nTo validate a train without committing temporary workflow refs, expose a\ntrusted manual pass-through once:\n\n```yaml\non:\n  workflow_dispatch:\n    inputs:\n      buildchain-ref:\n        description: \"Temporary Buildchain runtime ref for trusted manual validation\"\n        required: false\n        default: \"\"\n\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/.build.yml@v3\n    with:\n      buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n```\n\nBuildchain initializes new package workflows with this pass-through. Existing\nconsumers that do not have it should add it once before validating a train.\n\n## Validation request\n\nUse this short request when a train is ready:\n\n```text\nBuildchain train ready: buildchain-ref=train/v3/v3.0/<capability>.\nKeep uses: ...@v3; run workflow_dispatch with that buildchain-ref and report the runtime evidence summary.\n```\n\nThe consumer should run a trusted `workflow_dispatch`, paste the train ref into\n`buildchain-ref`, and report the workflow summary or aggregate Buildchain\nsummary. The evidence should include:\n\n- workflow shell ref;\n- requested runtime ref;\n- resolved runtime ref;\n- resolved runtime SHA;\n- stability class;\n- trust decision;\n- rollback ref.\n\n## Trust and limitation\n\nOfficial floating channel refs such as `v3` and `v3-alpha` may be selected on\npull requests and pushes. Train refs and arbitrary exact-SHA overrides still\nfail closed unless the event is `workflow_dispatch` and the actor has write,\nmaintain, or admin permission on the caller repository. Pull requests,\nincluding fork-originated pull requests, cannot use train or exact-SHA\noverrides.\n\nRuntime train validation covers Buildchain runtime scripts, CLI code, local\nactions, configuration parsing, and lifecycle behavior. It cannot validate\nchanges that require the outer reusable workflow YAML itself to change, such as\nnew jobs, permissions, workflow outputs, or matrix topology. Those changes need\na canary workflow path or a temporary explicit workflow ref."
     },
     {
       "id": "manual:shifu-gate-profiles",
@@ -2104,7 +2190,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/shifu-gate-profiles.md",
-      "digest": "sha256:155bf431ebbad8ca10b2ae8d200b3b89747d603bddf9f7105ed9319ec030cead",
+      "digest": "sha256:bba20085d84ea5dce9a63c0b3ba967d1fd7c3dc8003256557560375f0875f8ce",
       "headings": [
         {
           "level": 1,
@@ -2142,7 +2228,7 @@
           "anchor": "validation-boundary"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-shifu-gate-orchestration\ndoc_type: technical-manual\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: self-reviewed\nlast_reviewed: 2026-07-13\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-13\n  invisible_context_boundary: No private runner configuration, credentials, or unpublished Shifu implementation state was used.\n---\n\n# Shifu Gate profile orchestration\n\nBuildchain can schedule and aggregate a project-owned Shifu Gate profile without\nowning that project's gate ids, commands, dependencies, or dev/alpha/release\npolicy. The reusable workflow is\n`.github/workflows/.gate-profile.yml`.\n\n## Ownership boundary\n\n| Concern                                                                             | Owner                                 | Enforced surface                                                             |\n| ----------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------- |\n| Gate schema, profile planning, execution, receipt qualification                     | Shifu                                 | `shifu gate plan`, `shifu gate run --profile`, `shifu gate receipt validate` |\n| Concrete gate catalog and profile decisions                                         | Consumer project                      | project Gate registry and detailed Gate docs                                 |\n| Runner labels and declared capabilities                                             | Consumer workflow / Buildchain preset | `runner-preset` or `platforms-json`                                          |\n| Deterministic runner matrix, immutable checkout, receipt transport, aggregate check | Buildchain                            | `.gate-profile.yml` and `shifu-gate-profile.mjs`                             |\n| Whether a profile aggregate is required for dev, alpha, or release                  | Consumer project                      | protected-branch required-check policy and caller workflow                   |\n\nBuildchain treats the Shifu plan and receipt as versioned input contracts. It\ndoes not reimplement policy selection, execute raw shell strings, convert an\nexplicit diagnostic gate run into qualification, or mint missing evidence.\n\n## Runner matrix\n\nThe plan job asks the consumer's Shifu entrypoint for one plan per configured\nplatform. A platform is dispatchable only when:\n\n- the Shifu plan is qualifying;\n- every required selection is supported on that platform;\n- the runner declares every capability requested by the selected gates; and\n- all platform plans carry the same project id and registry digest.\n\nConfigured platforms are required by default. A required platform that cannot\nhost the profile fails before runner dispatch. A platform with\n`\"required\": false` may be omitted, but the omission and reasons remain in the\nmatrix and aggregate. Matrix entries retain the Shifu plan digest, ordered gate\ngroups, required/advisory modes, action ids, definition digests, skips, and\nunsupported selections.\n\n`github-hosted` declares only the inherent `node` capability. Projects that\nneed a native compiler, product artifacts, devices, or other facilities must\nuse a suitable preset or declare a custom matrix. Capabilities are scheduling\nclaims, not installation instructions.\n\n```json\n[\n  {\n    \"id\": \"linux-native\",\n    \"name\": \"Linux native\",\n    \"platform\": \"linux\",\n    \"runner\": \"[\\\"self-hosted\\\",\\\"Linux\\\",\\\"X64\\\",\\\"product-build\\\"]\",\n    \"capabilities\": [\"node\", \"native-toolchain\", \"product-artifacts\"]\n  }\n]\n```\n\n## Execution and receipts\n\nEvery matrix job checks out the exact source SHA planned by Buildchain, invokes\n`shifu gate run --profile`, writes the receipt outside the source checkout, and\nthen invokes `shifu gate receipt validate`. Buildchain uploads the original\nreceipt and validation result even when the run fails.\n\nBefore invoking the project-owned command, the workflow adds the runner\naccount's `~/.local/bin` directory to `PATH` on Windows, Linux, and macOS. This\nkeeps user-scoped tools such as `uv` available to strict Shifu cache profiles\nwithout assuming an administrator-managed system installation. The consumer or\nrunner owner remains responsible for provisioning the declared tools.\n\nThe fixed `Gate profile / aggregate` job fails closed for missing receipts,\ninvalid or stale Shifu validation, dirty or mismatched source SHA, registry or\nplan drift, missing required results, required failures/skips, or gate action\nand definition digest drift. Advisory failures remain visible but do not turn a\nShifu-qualifying receipt into a required failure. Buildchain's aggregate is\n`buildchain.shifu-gate-aggregate/v1`; its digest covers the matrix, receipts,\nper-gate evidence pointers, omissions, and issues.\n\n## Consumer workflow\n\n```yaml\njobs:\n  gates:\n    uses: kungfu-systems/buildchain/.github/workflows/.gate-profile.yml@v3\n    with:\n      gate-profile: alpha-pr\n      runner-preset: kungfu-v4-self-hosted\n      include-advisory: true\n\n  build:\n    needs: gates\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v3\n    with:\n      release-candidate: true\n      gate-profile-aggregate-json: ${{ needs.gates.outputs.gate-aggregate-json }}\n```\n\nThe command input is an argv map, not a shell string. The default supports the\nordinary Shifu launcher names on all three platforms. A project with a\ndifferent launcher can override it without teaching Buildchain project tasks:\n\n```yaml\ngate-command-json: >-\n  {\"linux\":[\"./tools/shifu\"],\"macos\":[\"./tools/shifu\"],\"windows\":[\"./tools/shifu.cmd\"]}\n```\n\n`gate-command-json` is the execution command. If execution needs a cache,\ncontainer, or other project-owned wrapper that should not make the read-only\nplan depend on that service, pass a separate lightweight argv map through\n`gate-plan-command-json`. It defaults to the execution command for backward\ncompatibility; Buildchain still treats both inputs as argv and never evaluates\na shell string.\n\nProjects may also pass non-sensitive scalar environment through\n`gate-environment-json`; Buildchain validates the JSON shape and forwards it\nwithout interpreting names or values. Cache profile references use the same\nopaque `shifu-cache-profile-ref` and `shifu-cache-profile-digest` inputs as the\nreusable build. Do not place tokens, credentials, or other secrets in workflow\ninputs or Gate receipts.\n\nWhen a qualifying aggregate is passed to the build workflow, the\nrelease-candidate passport binds its profile, source SHA, registry digest,\nmatrix digest, aggregate digest, receipt count, and result count. A failed,\nnon-qualifying, or source-mismatched aggregate cannot produce a valid passport.\nPromote-only release validation preserves that same Gate evidence summary in\nthe final Release Passport release identity, so promotion cannot silently drop\nthe qualified profile provenance.\n\n## Failure diagnosis and rollback\n\nStart with the aggregate artifact, then the platform receipt named in its\nissues. Reproduce the exact project decision with Shifu, for example:\n\n```bash\n./shifu gate explain <gate-id> --profile <profile>\n./shifu gate plan <profile> --platform <platform> --json\n./shifu gate receipt validate <receipt.json> --json\n```\n\nThe existing reusable build workflow remains usable without Gate inputs. To\nroll back Gate orchestration, remove the caller's `gates` job and\n`gate-profile-aggregate-json` handoff; this does not alter the consumer's Shifu\nregistry or its direct diagnostic commands.\n\n## Validation boundary\n\nUnit fixtures prove deterministic matrix generation and required/advisory,\ncapability, unsupported, missing, stale, failure, and definition-drift\npropagation. Because a train ref changes runtime scripts but not the outer\nreusable workflow topology, an unreleased `.gate-profile.yml` must also be\nvalidated through a trusted `workflow_dispatch` canary that references the\ntemporary workflow ref or exact SHA. See\n[`runtime-train-validation.md`](runtime-train-validation.md)."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-shifu-gate-orchestration\ndoc_type: technical-manual\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: self-reviewed\nlast_reviewed: 2026-07-29\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-13\n  invisible_context_boundary: No private runner configuration, credentials, or unpublished Shifu implementation state was used.\n---\n\n# Shifu Gate profile orchestration\n\nBuildchain can schedule and aggregate a project-owned Shifu Gate profile without\nowning that project's gate ids, commands, dependencies, or dev/alpha/release\npolicy. The reusable workflow is\n`.github/workflows/.gate-profile.yml`.\n\n## Ownership boundary\n\n| Concern                                                                             | Owner                                 | Enforced surface                                                             |\n| ----------------------------------------------------------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------- |\n| Gate schema, profile planning, execution, receipt qualification                     | Shifu                                 | `shifu gate plan`, `shifu gate run --profile`, `shifu gate receipt validate` |\n| Concrete gate catalog and profile decisions                                         | Consumer project                      | project Gate registry and detailed Gate docs                                 |\n| Runner labels and declared capabilities                                             | Consumer workflow / Buildchain preset | `runner-preset` or `platforms-json`                                          |\n| Deterministic runner matrix, immutable checkout, receipt transport, aggregate check | Buildchain                            | `.gate-profile.yml` and `shifu-gate-profile.mjs`                             |\n| Whether a profile aggregate is required for dev, alpha, or release                  | Consumer project                      | protected-branch required-check policy and caller workflow                   |\n\nBuildchain treats the Shifu plan and receipt as versioned input contracts. It\ndoes not reimplement policy selection, execute raw shell strings, convert an\nexplicit diagnostic gate run into qualification, or mint missing evidence.\n\n## Runner matrix\n\nThe plan job asks the consumer's Shifu entrypoint for one plan per configured\nplatform. A platform is dispatchable only when:\n\n- the Shifu plan is qualifying;\n- every required selection is supported on that platform;\n- the runner declares every capability requested by the selected gates; and\n- all platform plans carry the same project id and registry digest.\n\nConfigured platforms are required by default. A required platform that cannot\nhost the profile fails before runner dispatch. A platform with\n`\"required\": false` may be omitted, but the omission and reasons remain in the\nmatrix and aggregate. Matrix entries retain the Shifu plan digest, ordered gate\ngroups, required/advisory modes, action ids, definition digests, skips, and\nunsupported selections.\n\nEach matrix job timeout reserves the sum of the selected Gate action budgets\nplus 30 minutes for Buildchain-owned checkout, toolchain setup, plan download,\nreceipt validation, and artifact upload. The total remains capped at GitHub's\nsix-hour job limit. This control-plane allowance does not enlarge any Shifu\nGate's own declared action budget or change its definition digest.\n\n`github-hosted` declares only the inherent `node` capability. Projects that\nneed a native compiler, product artifacts, devices, or other facilities must\nuse a suitable preset or declare a custom matrix. Capabilities are scheduling\nclaims, not installation instructions.\n\n```json\n[\n  {\n    \"id\": \"linux-native\",\n    \"name\": \"Linux native\",\n    \"platform\": \"linux\",\n    \"runner\": \"[\\\"self-hosted\\\",\\\"Linux\\\",\\\"X64\\\",\\\"product-build\\\"]\",\n    \"capabilities\": [\"node\", \"native-toolchain\", \"product-artifacts\"]\n  }\n]\n```\n\n## Execution and receipts\n\nEvery matrix job checks out the exact source SHA planned by Buildchain, invokes\n`shifu gate run --profile`, writes the receipt outside the source checkout, and\nthen invokes `shifu gate receipt validate`. Buildchain uploads the original\nreceipt and validation result even when the run fails.\n\nBefore invoking the project-owned command, the workflow adds the runner\naccount's `~/.local/bin` directory to `PATH` on Windows, Linux, and macOS. This\nkeeps user-scoped tools such as `uv` available to strict Shifu cache profiles\nwithout assuming an administrator-managed system installation. The consumer or\nrunner owner remains responsible for provisioning the declared tools.\n\nThe fixed `Gate profile / aggregate` job fails closed for missing receipts,\ninvalid or stale Shifu validation, dirty or mismatched source SHA, registry or\nplan drift, missing required results, required failures/skips, or gate action\nand definition digest drift. Advisory failures remain visible but do not turn a\nShifu-qualifying receipt into a required failure. Buildchain's aggregate is\n`buildchain.shifu-gate-aggregate/v1`; its digest covers the matrix, receipts,\nper-gate evidence pointers, omissions, and issues.\n\n## Consumer workflow\n\n```yaml\njobs:\n  gates:\n    uses: kungfu-systems/buildchain/.github/workflows/.gate-profile.yml@v3\n    with:\n      gate-profile: alpha-pr\n      runner-preset: kungfu-v4-self-hosted\n      include-advisory: true\n\n  build:\n    needs: gates\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v3\n    with:\n      release-candidate: true\n      gate-profile-aggregate-json: ${{ needs.gates.outputs.gate-aggregate-json }}\n```\n\nThe command input is an argv map, not a shell string. The default supports the\nordinary Shifu launcher names on all three platforms. A project with a\ndifferent launcher can override it without teaching Buildchain project tasks:\n\n```yaml\ngate-command-json: >-\n  {\"linux\":[\"./tools/shifu\"],\"macos\":[\"./tools/shifu\"],\"windows\":[\"./tools/shifu.cmd\"]}\n```\n\n`gate-command-json` is the execution command. If execution needs a cache,\ncontainer, or other project-owned wrapper that should not make the read-only\nplan depend on that service, pass a separate lightweight argv map through\n`gate-plan-command-json`. It defaults to the execution command for backward\ncompatibility; Buildchain still treats both inputs as argv and never evaluates\na shell string.\n\nProjects may also pass non-sensitive scalar environment through\n`gate-environment-json`; Buildchain validates the JSON shape and forwards it\nwithout interpreting names or values. Cache profile references use the same\nopaque `shifu-cache-profile-ref` and `shifu-cache-profile-digest` inputs as the\nreusable build. Do not place tokens, credentials, or other secrets in workflow\ninputs or Gate receipts.\n\nWhen a qualifying aggregate is passed to the build workflow, the\nrelease-candidate passport binds its profile, source SHA, registry digest,\nmatrix digest, aggregate digest, receipt count, and result count. A failed,\nnon-qualifying, or source-mismatched aggregate cannot produce a valid passport.\nPromote-only release validation preserves that same Gate evidence summary in\nthe final Release Passport release identity, so promotion cannot silently drop\nthe qualified profile provenance.\n\n## Failure diagnosis and rollback\n\nStart with the aggregate artifact, then the platform receipt named in its\nissues. Reproduce the exact project decision with Shifu, for example:\n\n```bash\n./shifu gate explain <gate-id> --profile <profile>\n./shifu gate plan <profile> --platform <platform> --json\n./shifu gate receipt validate <receipt.json> --json\n```\n\nThe existing reusable build workflow remains usable without Gate inputs. To\nroll back Gate orchestration, remove the caller's `gates` job and\n`gate-profile-aggregate-json` handoff; this does not alter the consumer's Shifu\nregistry or its direct diagnostic commands.\n\n## Validation boundary\n\nUnit fixtures prove deterministic matrix generation and required/advisory,\ncapability, unsupported, missing, stale, failure, and definition-drift\npropagation. Because a train ref changes runtime scripts but not the outer\nreusable workflow topology, an unreleased `.gate-profile.yml` must also be\nvalidated through a trusted `workflow_dispatch` canary that references the\ntemporary workflow ref or exact SHA. See\n[`runtime-train-validation.md`](runtime-train-validation.md)."
     },
     {
       "id": "manual:site-bundle-contract",
@@ -2207,7 +2293,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/stable-candidate-patrol.md",
-      "digest": "sha256:86edec7063d23df5a2b267b5adcffe27a227f7ab906ced38c31014f469d9cc6e",
+      "digest": "sha256:fc3011acb007f60eae0f7035ed57e4828ab264951e47841d2f8835ca6ee0c60c",
       "headings": [
         {
           "level": 1,
@@ -2240,7 +2326,7 @@
           "anchor": "durable-recovery"
         }
       ],
-      "markdown": "---\nstatus: preview\nperiod: ongoing\ntheme: stable-candidate-patrol\ndoc_type: architecture-and-usage\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-07-11\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-11\n  visible_context: Buildchain candidate passport, stable gate, Patrol, publish transaction, exact source-lock PR contracts, tests, and user consensus.\n  invisible_context_boundary: No credentials, private logs, or unpublished consumer content were used.\n---\n\n# Stable Candidate Patrol\n\nBuildchain can treat every exact alpha as an independent stable candidate. A\nnew alpha creates a new candidate; it does not silently revoke an older alpha\nthat already completed its checks and soak interval.\n\n## Candidate lifecycle\n\nThe durable ledger contract is `kungfu-buildchain-stable-candidate-ledger`:\n\n```text\nregistered -> soaking -> qualified -> promoted\n                       \\-> revoked\n```\n\nEach entry binds an exact alpha version to one immutable commit SHA. Registering\nthe same version at another SHA fails closed. Qualification records the required\nchecks, their completion times, the derived soak start, and elapsed time.\n\nScheduled selection chooses the newest `qualified` candidate that is neither\n`revoked` nor already `promoted`. A newer alpha that is still `soaking` does not\nhide an older qualified candidate. Once a stable version is promoted, remaining\nalphas for that exact stable version are closed because that immutable stable\nversion has been consumed; their later product changes continue through the\nnext patch alpha prepared by the normal release transaction.\n\nFor Buildchain's own release line, successful Alpha Self-Dogfood starts an\nidempotent qualification producer for the exact alpha SHA. It dispatches the\nexisting `Build Surface Fixture` at the immutable exact tag, runs the existing\n`site-libkungfu-dev` no-apply canary with the exact SHA, and writes the declared\ncommit-status attestation only after that authoritative canary succeeds. The\nproducer creates evidence only: Patrol still owns qualification and selection,\nand the normal source-lock PR, stable gate, transaction, and branch protections\nremain mandatory.\n\nCross-repository dispatch and repository-local attestation use separate tokens.\nThe promotion token can start the no-apply consumer workflow, while the\nrepository-scoped Actions token writes the status as `github-actions[bot]` only\nafter the producer has observed the successful authoritative workflow run. The\nstable gate still verifies the workflow identity, exact runtime SHA, target URL,\nand allowed attestor before accepting that status.\n\nWhen a candidate changes the outer reusable-workflow YAML itself, the stable\nshell cannot exercise that change through a runtime override. A maintainer may\nmanually qualify it with `canary-ref` set to a dispatchable consumer branch or\ntag and `canary-sha` set to the exact 40-character commit that ref must resolve\nto. That consumer workflow pins the candidate's exact Buildchain SHA. The\nqualification producer verifies the ref binding before dispatch, accepts only a\nrun whose source SHA matches, and writes the normal candidate-bound status only\nafter success. The automatic path continues to use the consumer default branch.\n\n## Repository policy\n\nDeclare the default once in `.buildchain/buildchain.toml`:\n\n```toml\n[release.stable]\nstrategy = \"latest-qualified-alpha\"\ntimezone = \"Asia/Shanghai\"\npublish_at = \"03:00\"\nminimum_soak_seconds = 3600\nrequired_checks = [\n  \"alpha-release\",\n  \"workflow:Build\",\n  \"status:buildchain-canary/consumer\",\n]\nauto_promote = true\nauto_merge = true\n```\n\nCheck identifiers use these forms:\n\n- `alpha-release`: the exact GitHub prerelease publication fact;\n- `workflow:<name>`: a successful Actions workflow run on the exact candidate SHA;\n- `status:<context>`: a successful commit status on the exact candidate SHA;\n- an unprefixed value: an exact status context or check-run name.\n\nCandidate discovery uses immutable exact alpha Git tags. When a repository also\npublishes GitHub prereleases, `alpha-release` binds qualification to that public\nrelease fact. Repositories that intentionally disable GitHub Releases omit\n`alpha-release` and declare their own exact-SHA workflow/status evidence; tag\ncommit time remains the earliest possible soak start.\n\n`publish_at` and `timezone` are the auditable policy declaration. GitHub only\nstarts scheduled workflows from caller-owned cron, so the thin caller keeps the\nmatching UTC trigger:\n\n```yaml\nname: Stable Candidate Patrol\n\non:\n  schedule:\n    - cron: \"0 19 * * *\" # 03:00 Asia/Shanghai\n  workflow_dispatch:\n    inputs:\n      release-now:\n        description: Exact alpha selected by explicit human authority\n        required: false\n        default: \"\"\n\npermissions:\n  contents: write\n  pull-requests: write\n  checks: read\n  statuses: read\n\njobs:\n  stable:\n    uses: kungfu-systems/buildchain/.github/workflows/stable-candidate-patrol.yml@v3\n    with:\n      release-now: ${{ inputs.release-now }}\n      dry-run: false\n    secrets:\n      promotion-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n      approval-token: ${{ secrets.BUILDCHAIN_APPROVAL_TOKEN }}\n```\n\nThe promotion token must be repository-owned and capable of creating the\nmachine ledger branch, exact source-lock branch, and pull request. Repositories\nthat require an approving review can pass an independent repository-owned App,\nbot, or human service-account token as `approval-token`. The approval identity\nmust differ from the promotion token identity that opens the PR. When no\n`approval-token` is passed, `auto-approve: true` falls back to the caller\n`github.token` and therefore requires GitHub Actions approval permission. The\ngenerated PR may use auto-merge, but it never bypasses the target branch checks.\n\nBefore enabling `auto-approve` and `auto-merge`, the caller repository must\nprovide one approval path and enable auto-merge:\n\n- pass an independent `approval-token`; or enable **Actions > General >\n  Workflow permissions > Allow GitHub Actions to create and approve pull\n  requests**, so the caller `github.token` can approve independently from the\n  promotion token that opened the PR;\n- **General > Pull Requests > Allow auto-merge**, so Patrol can arm the\n  protected merge while required reviews and checks are still pending.\n\nGitHub rejects approval from the same identity that opened the pull request;\nPatrol propagates that review failure instead of reporting success.\n\nPatrol treats a GraphQL refusal to enable auto-merge as a hard failure. A run\nmust not report publication authority when GitHub accepted the HTTP request but\nreturned a GraphQL error in the response body.\n\n## Exact-source stable promotion\n\nFor a selected `2.12.0-alpha.4`, Patrol creates the immutable source branch:\n\n```text\npublish-gate/release/v2/v2.12/2.12.0-alpha.4\n```\n\nand opens it against `release/v2/v2.12`. This is an existing strict Buildchain\ngovernance path. The PR freezes the qualified candidate even if `v2.12-alpha`\nor `alpha/v2/v2.12` has already moved to alpha.5. Normal Verify,\nrelease-candidate resolution, source-tree equivalence, publish transaction,\npassport, registry, tag, and floating-ref checks still run.\n\n## Hold, revoke, and immediate release\n\nPersistent repository controls can be supplied as reusable-workflow inputs or\nrepository variables:\n\n```text\nBUILDCHAIN_STABLE_HOLD=true\nBUILDCHAIN_STABLE_HOLD_REASON=release freeze\nBUILDCHAIN_STABLE_REVOKED_ALPHA_VERSIONS=2.12.0-alpha.5,2.12.0-alpha.7\nBUILDCHAIN_STABLE_REVOKE_REASON=consumer regression\n```\n\nRevocation is explicit evidence; publishing a newer alpha alone is not\nrevocation. A manual `workflow_dispatch` `release-now` chooses one exact,\nnon-revoked candidate immediately. It may bypass the scheduled soak decision,\nbut cannot change candidate SHA, reuse a consumed stable version, or bypass the\nsource-lock PR and publish transaction.\n\nFor Buildchain's own stable gate, Patrol automatically projects that explicit\nhuman decision into the exact-candidate `BUILDCHAIN_STABLE_RELEASE_NOW` and\nreason variables. A later Patrol run removes them after it observes the public\nstable release. This is an internal compatibility projection, not a manual user\nstep; the durable authority record remains the candidate ledger entry and PR.\n\n## Durable recovery\n\nThe default ledger ref is derived from the release line, for example:\n\n```text\nbuildchain/candidate-ledger/v3/v3.0\n```\n\nIt stores `.buildchain/stable-candidate-ledger.json`. Patrol runs are serialized\nper repository and release line. Repeated runs reuse the same exact source-lock\nbranch and PR, while later runs observe the public stable release and mark the\ncandidate `promoted`.\n\nWhen Patrol is enabled after a stable version already exists, it reconstructs\nthat consumed patch from GitHub Release truth and closes historical alpha\ncandidates for the same stable version. It never attempts to republish an\nalready claimed exact stable version."
+      "markdown": "---\nstatus: preview\nperiod: ongoing\ntheme: stable-candidate-patrol\ndoc_type: architecture-and-usage\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-11\n  visible_context: Buildchain candidate passport, stable gate, Patrol, publish transaction, exact source-lock PR contracts, tests, and user consensus.\n  invisible_context_boundary: No credentials, private logs, or unpublished consumer content were used.\n---\n\n# Stable Candidate Patrol\n\nBuildchain can treat every exact alpha as an independent stable candidate. A\nnew alpha creates a new candidate; it does not silently revoke an older alpha\nthat already completed its checks and soak interval.\n\n## Candidate lifecycle\n\nThe durable ledger contract is `kungfu-buildchain-stable-candidate-ledger`:\n\n```text\nregistered -> soaking -> qualified -> promoted\n                       \\-> revoked\n```\n\nEach entry binds an exact alpha version to one immutable commit SHA. Registering\nthe same version at another SHA fails closed. Qualification records the required\nchecks, their completion times, the derived soak start, and elapsed time.\n\nScheduled selection chooses the newest `qualified` candidate that is neither\n`revoked` nor already `promoted`. A newer alpha that is still `soaking` does not\nhide an older qualified candidate. Once a stable version is promoted, remaining\nalphas for that exact stable version are closed because that immutable stable\nversion has been consumed; their later product changes continue through the\nnext patch alpha prepared by the normal release transaction.\n\nFor Buildchain's own release line, successful Alpha Self-Dogfood starts an\nidempotent qualification producer for the exact alpha SHA. It dispatches the\nexisting `Build Surface Fixture` at the immutable exact tag, runs the existing\n`site-libkungfu-dev` no-apply canary with the exact SHA, and writes the declared\ncommit-status attestation only after that authoritative canary succeeds. The\nproducer creates evidence only: Patrol still owns qualification and selection,\nand the normal source-lock PR, stable gate, transaction, and branch protections\nremain mandatory.\n\nCross-repository dispatch and repository-local attestation use separate tokens.\nThe promotion token can start the no-apply consumer workflow, while the\nrepository-scoped Actions token writes the status as `github-actions[bot]` only\nafter the producer has observed the successful authoritative workflow run. The\nstable gate still verifies the workflow identity, exact runtime SHA, target URL,\nand allowed attestor before accepting that status.\n\nWhen a candidate changes the outer reusable-workflow YAML itself, the stable\nshell cannot exercise that change through a runtime override. A maintainer may\nmanually qualify it with `canary-ref` set to a dispatchable consumer branch or\ntag and `canary-sha` set to the exact 40-character commit that ref must resolve\nto. That consumer workflow pins the candidate's exact Buildchain SHA. The\nqualification producer verifies the ref binding before dispatch, accepts only a\nrun whose source SHA matches, and writes the normal candidate-bound status only\nafter success. The automatic path continues to use the consumer default branch.\n\n## Repository policy\n\nDeclare the default once in `.buildchain/buildchain.toml`:\n\n```toml\n[release.stable]\nstrategy = \"latest-qualified-alpha\"\ntimezone = \"Asia/Shanghai\"\npublish_at = \"03:00\"\nminimum_soak_seconds = 3600\nrequired_checks = [\n  \"alpha-release\",\n  \"workflow:Build\",\n  \"status:buildchain-canary/consumer\",\n]\nauto_promote = true\nauto_merge = true\n```\n\nCheck identifiers use these forms:\n\n- `alpha-release`: the exact GitHub prerelease publication fact;\n- `workflow:<name>`: a successful Actions workflow run on the exact candidate SHA;\n- `status:<context>`: a successful commit status on the exact candidate SHA;\n- an unprefixed value: an exact status context or check-run name.\n\nCandidate discovery uses immutable exact alpha Git tags. When a repository also\npublishes GitHub prereleases, `alpha-release` binds qualification to that public\nrelease fact. Repositories that intentionally disable GitHub Releases omit\n`alpha-release` and declare their own exact-SHA workflow/status evidence; tag\ncommit time remains the earliest possible soak start.\n\n`publish_at` and `timezone` are the auditable policy declaration. GitHub only\nstarts scheduled workflows from caller-owned cron, so the thin caller keeps the\nmatching UTC trigger:\n\n```yaml\nname: Stable Candidate Patrol\n\non:\n  schedule:\n    - cron: \"0 19 * * *\" # 03:00 Asia/Shanghai\n  workflow_dispatch:\n    inputs:\n      release-now:\n        description: Exact alpha selected by explicit human authority\n        required: false\n        default: \"\"\n\npermissions:\n  contents: write\n  pull-requests: write\n  checks: read\n  statuses: read\n\njobs:\n  stable:\n    uses: kungfu-systems/buildchain/.github/workflows/stable-candidate-patrol.yml@v3\n    with:\n      release-now: ${{ inputs.release-now }}\n      dry-run: false\n    secrets:\n      promotion-token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}\n      approval-token: ${{ secrets.BUILDCHAIN_APPROVAL_TOKEN }}\n```\n\nThe promotion token must be repository-owned and capable of creating the\nmachine ledger branch, exact source-lock branch, and pull request. Repositories\nthat require an approving review can pass an independent repository-owned App,\nbot, or human service-account token as `approval-token`. The approval identity\nmust differ from the promotion token identity that opens the PR. When no\n`approval-token` is passed, `auto-approve: true` falls back to the caller\n`github.token` and therefore requires GitHub Actions approval permission. The\ngenerated PR may use auto-merge, but it never bypasses the target branch checks.\n\nBefore enabling `auto-approve` and `auto-merge`, the caller repository must\nprovide one approval path and enable auto-merge:\n\n- pass an independent `approval-token`; or enable **Actions > General >\n  Workflow permissions > Allow GitHub Actions to create and approve pull\n  requests**, so the caller `github.token` can approve independently from the\n  promotion token that opened the PR;\n- **General > Pull Requests > Allow auto-merge**, so Patrol can arm the\n  protected merge while required reviews and checks are still pending.\n\nGitHub rejects approval from the same identity that opened the pull request;\nPatrol propagates that review failure instead of reporting success.\n\nPatrol treats a GraphQL refusal to enable auto-merge as a hard failure. A run\nmust not report publication authority when GitHub accepted the HTTP request but\nreturned a GraphQL error in the response body.\n\n## Exact-source stable promotion\n\nFor a selected `3.0.2-alpha.4`, Patrol creates the immutable source branch:\n\n```text\npublish-gate/release/v3/v3.0/3.0.2-alpha.4\n```\n\nand opens it against `release/v3/v3.0`. This is an existing strict Buildchain\ngovernance path. The PR freezes the qualified candidate even if `v3.0-alpha`\nor `alpha/v3/v3.0` has already moved to alpha.5. Normal Verify,\nrelease-candidate resolution, source-tree equivalence, publish transaction,\npassport, registry, tag, and floating-ref checks still run.\n\n## Hold, revoke, and immediate release\n\nPersistent repository controls can be supplied as reusable-workflow inputs or\nrepository variables:\n\n```text\nBUILDCHAIN_STABLE_HOLD=true\nBUILDCHAIN_STABLE_HOLD_REASON=release freeze\nBUILDCHAIN_STABLE_REVOKED_ALPHA_VERSIONS=2.12.0-alpha.5,2.12.0-alpha.7\nBUILDCHAIN_STABLE_REVOKE_REASON=consumer regression\n```\n\nRevocation is explicit evidence; publishing a newer alpha alone is not\nrevocation. A manual `workflow_dispatch` `release-now` chooses one exact,\nnon-revoked candidate immediately. It may bypass the scheduled soak decision,\nbut cannot change candidate SHA, reuse a consumed stable version, or bypass the\nsource-lock PR and publish transaction.\n\nFor Buildchain's own stable gate, Patrol automatically projects that explicit\nhuman decision into the exact-candidate `BUILDCHAIN_STABLE_RELEASE_NOW` and\nreason variables. A later Patrol run removes them after it observes the public\nstable release. This is an internal compatibility projection, not a manual user\nstep; the durable authority record remains the candidate ledger entry and PR.\n\n## Durable recovery\n\nThe default ledger ref is derived from the release line, for example:\n\n```text\nbuildchain/candidate-ledger/v3/v3.0\n```\n\nIt stores `.buildchain/stable-candidate-ledger.json`. Patrol runs are serialized\nper repository and release line. Repeated runs reuse the same exact source-lock\nbranch and PR, while later runs observe the public stable release and mark the\ncandidate `promoted`.\n\nWhen Patrol is enabled after a stable version already exists, it reconstructs\nthat consumed patch from GitHub Release truth and closes historical alpha\ncandidates for the same stable version. It never attempts to republish an\nalready claimed exact stable version."
     },
     {
       "id": "manual:toolkit-observability",
@@ -2254,7 +2340,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/toolkit-observability.md",
-      "digest": "sha256:d7f4179c3912d7bbc5940bfba69e674fb03d020a740063c0b877a171bd5789e3",
+      "digest": "sha256:1a08331cdca2b48e622ecbb799a7465a59cc4a779dd73d36f559f9bc1b98578c",
       "headings": [
         {
           "level": 1,
@@ -2292,7 +2378,7 @@
           "anchor": "release-gate"
         }
       ],
-      "markdown": "# Toolkit Observability\n\nBuildchain ships a small logging toolkit for repository workflows and project\nscripts. The goal is to separate time spent in Buildchain's framework from time\nspent in the consumer's own build, test, packaging, and publish steps.\n\n## Choose API or CLI\n\n`@kungfu-tech/buildchain` is not only a CLI package. It exports ESM toolkit APIs\nthat project scripts can import directly:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n```\n\nUse the API inside JavaScript or TypeScript build code. Do not spawn\n`buildchain`, download the standalone binary, or shell out through `npx` from\ncode that can import the package. The CLI is for GitHub Actions steps, shell\nscripts, and non-JavaScript tools.\n\nWhen a script runs inside `buildchain lifecycle run`, the lifecycle runner sets\n`BUILDCHAIN_LOG_PATH` and `BUILDCHAIN_LOG_RUN_ID`. Imported loggers pick up those\nenvironment variables automatically, so events emitted deep inside the build are\ngrouped into the same lifecycle summary.\n\nOutside a Buildchain lifecycle or GitHub Actions run, the logger defaults to\nconsole output unless a path is provided. Pass `path` when local scripts should\nwrite a reusable JSONL log:\n\n```js\nconst logger = createBuildchainLogger({\n  path: \".buildchain/logs/native-build.jsonl\",\n  source: \"user\",\n  component: \"native-build\",\n});\n```\n\n## Library API\n\n```js\nimport {\n  createBuildchainLogger,\n  verifyBuildchainLogEvents,\n} from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n  source: \"user\",\n  component: \"native-build\",\n});\n\nlogger.mark(\"configure.ready\", {\n  phase: \"configure\",\n  attributes: { preset: \"release\" },\n});\n\nawait logger.span(\"native.compile\", {\n  phase: \"build\",\n  attributes: { target: \"release\" },\n}, async () => {\n  await compile();\n});\n\nlogger.spanSync(\"native.archive\", {\n  phase: \"build\",\n  attributes: { tool: \"libtool\" },\n}, () => {\n  archiveStaticLibraries();\n});\n\nlogger.spawnSync(\"native.build\", \"make\", [\"-j20\"], {\n  stdio: \"inherit\",\n}, {\n  phase: \"build\",\n  attributes: { requestedJobs: 20 },\n});\n\nconst report = verifyBuildchainLogEvents({\n  path: logger.path,\n  minEvents: 3,\n  requirePhases: [\"configure\", \"build\"],\n  requireEvents: [\n    \"configure.ready\",\n    \"native.compile.start\",\n    \"native.compile.end\",\n  ],\n});\n\nif (!report.ok) {\n  throw new Error(\"Buildchain observability verification failed\");\n}\n```\n\nUse the API when a build script has internal stages that are invisible to the\nouter workflow. Keep secret values out of attributes; known sensitive keys are\nredacted, but callers should still avoid logging private material.\n\n## Candidate timelines and critical-path-safe timing\n\nLifecycle diagnostics retain their existing summed-duration tables for\ncompatibility. Do not interpret those tables as elapsed time when spans are\nnested or jobs run in parallel. Use the candidate timeline contract when a\nchange must be followed from pull-request admission through Merge Queue attempts\nto its final merge:\n\n```js\nimport {\n  createCandidateTimeline,\n  formatCandidateTimelineReport,\n} from \"@kungfu-tech/buildchain/candidate-timeline\";\n\nconst timeline = createCandidateTimeline({\n  candidate: {\n    repository: \"owner/repository\",\n    baseBranch: \"dev/v4/v4.0\",\n    sourceSha,\n    pullRequest: 123,\n  },\n  events,\n});\n\nconsole.log(formatCandidateTimelineReport(timeline));\n```\n\nEach event binds a stable event id to one attempt id and may also bind a Gate\nid, merge-group SHA, workflow run, platform, partition, cache outcome, execution\nboundary, and parent span. Terminal execution states (`success`, `failure`, and\n`cancelled`) require start and completion timestamps. Non-executed states use\n`skipped`, `dependency-blocked`, or `not-required` without invented timings.\nRecord the clock and timestamp precision explicitly: GitHub Actions timestamps\nare normally provider wall-clock observations with one-second precision, while\nan in-process span may also carry a monotonic duration with millisecond or\nbetter precision.\n\nThe `buildchain.candidate-timeline/v1` artifact reports an independent critical\npath for every attempt. Its critical-path duration is the attempt's observed\nwall-clock envelope; its active duration and per-phase durations are interval\nunions. This prevents nested or parallel spans from being added twice, and it\ndoes not combine a failed or dequeued attempt with a later retry. Missing\nrequired measurements make that attempt `incomplete` instead of producing fake\nprecision.\n\nEach attempt also reports measured execution lanes, lane skew, cache outcome\ncounts, the ten longest actionable spans, and one falsifiable next optimization\ntarget. Queue residence, whole-workflow envelopes, and job parents are excluded\nfrom the actionable ranking so they cannot hide the build or qualification\nstage that can actually be changed. The target is an observation, not a causal\nclaim: repeat the same source-bound cohort and disprove it by reducing that span\nbelow the next measured span without increasing attempt elapsed time or\nfailures.\n\nShell and workflow consumers can generate the same machine artifact plus a\ncompact report:\n\n```sh\nbuildchain candidate timeline \\\n  --input .buildchain/candidate-timeline-input.json \\\n  --output .buildchain/candidate-timeline.json\n```\n\nThe input and output should contain only bounded correlation facts and timing\nreceipts. Do not include tokens, environment dumps, full commands, raw process\ndumps, or private absolute paths.\n\nCommonJS scripts should import Buildchain's ESM surfaces dynamically:\n\n```js\nconst { createBuildchainLogger } = await import(\"@kungfu-tech/buildchain/logging\");\nconst { collectRunnerDiagnostics } = await import(\"@kungfu-tech/buildchain/diagnostics\");\n```\n\n## Diagnostics API\n\nThe diagnostics surface collects local, non-telemetry build facts that are\nuseful when a native build is slow or flaky:\n\n```js\nimport {\n  collectBuildchainDiagnostics,\n  collectCacheDiagnostics,\n  collectCompilerCacheDiagnostics,\n  collectRunnerDiagnostics,\n  collectToolDiagnostics,\n  detectRequestedParallelism,\n  startProcessSampler,\n  summarizeDiagnosticsArtifacts,\n  summarizeLifecycleObservability,\n  summarizeProcessSamples,\n  validateAnchoredPackageRelease,\n  writeDiagnosticsArtifact,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n\nconst lifecycleObservability = summarizeLifecycleObservability({\n  logPath: \".buildchain/logs/events.jsonl\",\n});\nconst buildCommand = \"make\";\nconst buildArgs = [\"-j20\"];\nconst requestedParallelism = detectRequestedParallelism({\n  command: buildCommand,\n  args: buildArgs,\n});\nconst processSampler = startProcessSampler({\n  intervalMs: 15000,\n  label: \"native-build\",\n  command: buildCommand,\n  args: buildArgs,\n});\n// Run the long native build while the sampler is active.\nconst processSummary = summarizeProcessSamples({\n  requestedParallelism: requestedParallelism.value,\n  samples: processSampler.stop(),\n});\nconst cacheDiagnostics = collectCacheDiagnostics({ cwd: process.cwd() });\n\nwriteDiagnosticsArtifact(\".buildchain/artifacts/diagnostics.json\", {\n  contract: \"consumer-build-diagnostics\",\n  buildchain: collectBuildchainDiagnostics({ cwd: process.cwd() }),\n  runner: collectRunnerDiagnostics(),\n  tools: collectToolDiagnostics({ cwd: process.cwd() }),\n  cache: cacheDiagnostics,\n  lifecycleObservability,\n  process: processSummary,\n});\n```\n\n`collectCacheDiagnostics()` includes package-manager/workspace context, selected\ncache directory stats, and compiler-cache stats from `ccache --show-stats\n--json` plus `sccache --show-stats --stats-format json` when those tools are\npresent. If a ccache build does not support JSON stats, Buildchain falls back to\nplain `ccache --show-stats` and parses the text counters. Missing cache tools\nare recorded as unavailable instead of failing the diagnostics artifact. Call\n`collectCompilerCacheDiagnostics()` directly when a consumer script only needs\ncompiler cache data. Native diagnostics also expose `compilerCaches` and\n`nativeCacheDirs` as top-level fields in each diagnostics artifact and aggregate\nsummary, so reviewers do not have to dig through nested cache sections first.\n\nProcess samples are intentionally summarized before they become long-lived\nartifacts. The summary records requested parallelism, the source of that value\n(`command`, `process-tree`, `env:MAKEFLAGS`,\n`env:CMAKE_BUILD_PARALLEL_LEVEL`, or `explicit`), observed active process\nconcurrency, elapsed sample time, total sampled CPU, and conservative command\ncategories such as `compiler`, `archive`, `linker`, `build-tool`, and `cache`.\nThe sampler detects common `make -j N`, `ninja -j N`, CMake/MSBuild/Xcode job\nflags, and MAKEFLAGS. This lets native projects distinguish \"we asked for\n`make -j20`\" from \"the build graph only kept two active compiler or archive\nchildren busy during the sampled window\" without storing environment dumps.\n\nNative repositories can opt into a reusable diagnostics profile in\n`buildchain.toml`:\n\n```toml\n[diagnostics.native]\nenabled = true\nsample_process_tree = true\ncompiler_cache = \"auto\"\nexpected_tools = [\"ccache\", \"sccache\", \"clang\", \"cl\", \"cmake\", \"ninja\"]\nartifact_dirs = [\"build\", \"dist\", \"build/Release\"]\ncache_dirs = [\".ccache\", \".sccache\"]\n```\n\nWhen enabled, diagnostics artifacts include the normalized profile, selected\ntool versions, compiler-cache stats, and configured artifact/cache directory\nstats. The profile is data-driven: Buildchain does not assume a specific\nproject such as libnode. The reusable build workflow also exposes\n`sample-process-tree`, which wraps the build lifecycle with the process sampler\nand carries the generated summary into the final diagnostics artifact. Custom\nworkflows can call `buildchain sample process-tree` directly when they need a\ndifferent command boundary.\n\nAnchored/manual package projects can also run one higher-level release-shape\ncheck instead of assembling lower-level config calls:\n\n```js\nconst anchoredReport = validateAnchoredPackageRelease({\n  cwd: process.cwd(),\n  requireManifest: true,\n  requirePackageSetOrder: \"platforms-first-main-last\",\n  requireTrustedPublishing: true,\n});\n\nif (!anchoredReport.ok) {\n  throw new Error(\"Anchored package release contract failed\");\n}\n```\n\nIn an actual publish job, make that check source-lock aware:\n\n```js\nconst publishReady = validateAnchoredPackageRelease({\n  cwd: process.cwd(),\n  requirePublishGateSourceLock: true,\n});\n```\n\nThe source-lock inputs are read from `BUILDCHAIN_PUBLISH_SOURCE_REF`,\n`BUILDCHAIN_PUBLISH_SOURCE_SHA`, and `BUILDCHAIN_PUBLISH_SOURCE_LOCKED`, which\nthe reusable build workflow emits after resolving `publish-source-ref`. That\nturns direct channel-branch publication from `alpha/*` or `release/*` into a\nhard failure, while `publish-gate/alpha/<line>/<version>` and\n`publish-gate/release/<line>/<version>` also validate the requested consumer\nversion against configured version files and the anchor manifest.\n\n`buildchain lifecycle run` writes this small diagnostics artifact next to the\nplatform manifest by default. The per-platform diagnostics upload includes the\ncompact `diagnostics.json`, `diagnostics-manifest.json`, lifecycle\n`events.jsonl`, and, when process sampling is enabled, copied\n`process-summary.json` and `process-samples.jsonl` sidecars. The sidecar\nmanifest records each uploaded diagnostics file with its relative path, byte\ncount, and sha256 hash. It is intended to stay small enough to download without\nfetching large binary packages, and it should not include full environment dumps\nor secret-looking values.\n\nUse `summarizeDiagnosticsArtifacts()` when a matrix build uploads one\ndiagnostics artifact per platform. The summary keeps each platform's lifecycle\nstage table, adds a lifecycle total duration, carries the top slow spans, and\naggregates warning/error counts plus the slowest platforms. Per-platform rows\nalso include compact runner facts, checked tool versions/missing tools, package\nmanager/cache directory details, compiler cache availability, and a compact\nprocess sampler view with requested parallelism, observed max active processes,\nthe ratio between them, sample count, process categories, and top sampled\ncommand basenames. That gives release reviewers a small cross-platform timing,\nrunner, tool, cache, and concurrency view without downloading full build outputs\nor process sidecars.\n\nThe reusable build workflow writes that rollup as `diagnostics-summary.json` and\nuploads it in a separate aggregate diagnostics summary artifact. Consumers can\nread the `build-diagnostics-summary-artifact` output when they need only timing,\nwarning/error, runner, cache, and process-sampler context instead of the build\nsummary or binary artifacts. Per-platform rows keep the diagnostics `links`\nobject, including the binary artifact name, manifest artifact name, diagnostics\nartifact name, platform id, diagnostics sidecar manifest path, manifest path,\nsummary path, and process sidecar paths when present. They also keep compact\nrunner/tool/cache summaries so reviewers can tell whether a slow row ran on the\nexpected runner, missed an expected tool, or lacked useful compiler-cache stats.\nWhen the downloaded platform diagnostics include a sibling\n`diagnostics-manifest.json`, `summarizeDiagnosticsArtifacts()` carries a compact\n`diagnosticsManifest` section for that platform and verifies the manifest's\n`diagnostics.json` byte count and sha256. Missing or mismatched sidecar manifests\nincrement `diagnosticsManifestWarningCount`, so reviewers can distinguish\ndiagnostics sidecar drift from lifecycle warnings or build failures.\nThe same summary carries `diagnosticsContract` per platform and aggregates\n`diagnosticsContractWarningCount` when a downloaded `diagnostics.json` does not\nmatch `BUILDCHAIN_DIAGNOSTICS_CONTRACT`.\n\nThe diagnostics SDK also exports stable contract constants such as\n`BUILDCHAIN_DIAGNOSTICS_SUMMARY_CONTRACT`,\n`BUILDCHAIN_DIAGNOSTICS_MANIFEST_CONTRACT`,\n`BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT`,\n`BUILDCHAIN_PROCESS_SAMPLE_SUMMARY_CONTRACT`, and\n`BUILDCHAIN_ANCHORED_PACKAGE_RELEASE_VALIDATION_CONTRACT` from\n`@kungfu-tech/buildchain/diagnostics`; consumers should compare against those\nconstants instead of hardcoding contract strings.\n\nThe CLI exposes the same aggregation for shell and workflow steps:\n\n```bash\nbuildchain diagnostics summary \\\n  .buildchain/artifacts/linux-x64/diagnostics.json \\\n  .buildchain/artifacts/macos-arm64/diagnostics.json \\\n  --output .buildchain/artifacts/diagnostics-summary.json \\\n  --json\n```\n\nOmit `--json` when the workflow log should show a compact platform table with\nlifecycle stages, artifact scan/upload time, total time, requested jobs,\nobserved active processes, warnings, and errors.\n\nFor long native build commands, the CLI can also sample the child process tree\nwhile preserving the wrapped command's exit code:\n\n```bash\nbuildchain sample process-tree \\\n  --label native-build \\\n  --interval-ms 15000 \\\n  --output .buildchain/diagnostics/process-samples.jsonl \\\n  --summary-output .buildchain/diagnostics/process-summary.json \\\n  -- \\\n  make -j20\n```\n\nThe JSONL sample file stores timestamped process-tree snapshots with full\nredacted command lines, command basenames, CPU percentages when available,\nelapsed time, and requested parallelism context. Unix and macOS snapshots read\nthe full `ps args` field instead of truncated `comm` names. Windows snapshots\nread `Win32_Process` command lines through PowerShell so the sampler no longer\nreturns an empty process set on Windows runners. The summary file records\nobserved concurrency, total sampled CPU, command categories, and top command\nbasenames. This is intended for diagnosing low-utilization tails such as\narchive/link phases without logging full environment dumps.\n\nThe lifecycle observability summary is stage-wide, not just final-step timing:\nwhen install and build write to the same Buildchain log, the final platform\nmanifest can show both stages and the slowest spans.\n\n## CLI Logging\n\n```bash\nbuildchain mark \\\n  --event native.configure \\\n  --phase configure \\\n  --component cmake \\\n  --attribute preset=release\n\nbuildchain span \\\n  --event native.build \\\n  --phase build \\\n  --component cmake \\\n  -- cmake --build build --config Release\n\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4\n```\n\nEvery event records a timestamp. `span` records duration and preserves the\nwrapped command's exit code.\n\nBuildchain also records local control-plane outcome events for workflow-friction\nincident handling and production release-intent PR handling. `log summary`\nreports the observed incident reuse rate, release-intent suppression rate, and\nsuppression reasons. A reused incident means an equivalent occurrence found the\nsame fingerprint and was commented, cooled down, or otherwise reused; a\nsuppressed release intent means Buildchain proved that the source commit already\nhad a qualifying merged release PR. These are operational facts, not release\npolicy inputs, and logging failure remains non-fatal by default.\n\nThe reusable promotion workflow uploads `.buildchain/logs/events.jsonl` when a\nfriction report is produced. The web-surface production release PR handoff\nartifact includes the same path, so a real run can falsify the P0 claim instead\nof relying only on unit tests.\n\n## Release Gate\n\nBuildchain's own binary distribution lane verifies required log events before\nuploading release assets. Consumers can apply the same pattern:\n\n```bash\nbuildchain verify observability-log .buildchain/logs/events.jsonl \\\n  --require-phase build \\\n  --require-phase package \\\n  --require-component workflow \\\n  --require-event native.build.start \\\n  --require-event native.build.end\n```\n\nThis makes missing instrumentation a release failure instead of a dashboard\nafterthought."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-observability\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-31\n  invisible_context: not asserted\n---\n\n# Toolkit Observability\n\nBuildchain ships a small logging toolkit for repository workflows and project\nscripts. The goal is to separate time spent in Buildchain's framework from time\nspent in the consumer's own build, test, packaging, and publish steps.\n\n## Choose API or CLI\n\n`@kungfu-tech/buildchain` is not only a CLI package. It exports ESM toolkit APIs\nthat project scripts can import directly:\n\n```js\nimport { createBuildchainLogger } from \"@kungfu-tech/buildchain/logging\";\n```\n\nUse the API inside JavaScript or TypeScript build code. Do not spawn\n`buildchain`, download the standalone binary, or shell out through `npx` from\ncode that can import the package. The CLI is for GitHub Actions steps, shell\nscripts, and non-JavaScript tools.\n\nWhen a script runs inside `buildchain lifecycle run`, the lifecycle runner sets\n`BUILDCHAIN_LOG_PATH` and `BUILDCHAIN_LOG_RUN_ID`. Imported loggers pick up those\nenvironment variables automatically, so events emitted deep inside the build are\ngrouped into the same lifecycle summary.\n\nOutside a Buildchain lifecycle or GitHub Actions run, the logger defaults to\nconsole output unless a path is provided. Pass `path` when local scripts should\nwrite a reusable JSONL log:\n\n```js\nconst logger = createBuildchainLogger({\n  path: \".buildchain/logs/native-build.jsonl\",\n  source: \"user\",\n  component: \"native-build\",\n});\n```\n\n## Library API\n\n```js\nimport {\n  createBuildchainLogger,\n  verifyBuildchainLogEvents,\n} from \"@kungfu-tech/buildchain/logging\";\n\nconst logger = createBuildchainLogger({\n  source: \"user\",\n  component: \"native-build\",\n});\n\nlogger.mark(\"configure.ready\", {\n  phase: \"configure\",\n  attributes: { preset: \"release\" },\n});\n\nawait logger.span(\"native.compile\", {\n  phase: \"build\",\n  attributes: { target: \"release\" },\n}, async () => {\n  await compile();\n});\n\nlogger.spanSync(\"native.archive\", {\n  phase: \"build\",\n  attributes: { tool: \"libtool\" },\n}, () => {\n  archiveStaticLibraries();\n});\n\nlogger.spawnSync(\"native.build\", \"make\", [\"-j20\"], {\n  stdio: \"inherit\",\n}, {\n  phase: \"build\",\n  attributes: { requestedJobs: 20 },\n});\n\nconst report = verifyBuildchainLogEvents({\n  path: logger.path,\n  minEvents: 3,\n  requirePhases: [\"configure\", \"build\"],\n  requireEvents: [\n    \"configure.ready\",\n    \"native.compile.start\",\n    \"native.compile.end\",\n  ],\n});\n\nif (!report.ok) {\n  throw new Error(\"Buildchain observability verification failed\");\n}\n```\n\nUse the API when a build script has internal stages that are invisible to the\nouter workflow. Keep secret values out of attributes; known sensitive keys are\nredacted, but callers should still avoid logging private material.\n\n## Candidate timelines and critical-path-safe timing\n\nLifecycle diagnostics retain their existing summed-duration tables for\ncompatibility. Do not interpret those tables as elapsed time when spans are\nnested or jobs run in parallel. Use the candidate timeline contract when a\nchange must be followed from pull-request admission through Merge Queue attempts\nto its final merge:\n\n```js\nimport {\n  createCandidateTimeline,\n  formatCandidateTimelineReport,\n} from \"@kungfu-tech/buildchain/candidate-timeline\";\n\nconst timeline = createCandidateTimeline({\n  candidate: {\n    repository: \"owner/repository\",\n    baseBranch: \"dev/v4/v4.0\",\n    sourceSha,\n    pullRequest: 123,\n  },\n  events,\n});\n\nconsole.log(formatCandidateTimelineReport(timeline));\n```\n\nEach event binds a stable event id to one attempt id and may also bind a Gate\nid, merge-group SHA, workflow run, platform, partition, cache outcome, execution\nboundary, and parent span. Terminal execution states (`success`, `failure`, and\n`cancelled`) require start and completion timestamps. Non-executed states use\n`skipped`, `dependency-blocked`, or `not-required` without invented timings.\nRecord the clock and timestamp precision explicitly: GitHub Actions timestamps\nare normally provider wall-clock observations with one-second precision, while\nan in-process span may also carry a monotonic duration with millisecond or\nbetter precision.\n\nThe `buildchain.candidate-timeline/v1` artifact reports an independent critical\npath for every attempt. Its critical-path duration is the attempt's observed\nwall-clock envelope; its active duration and per-phase durations are interval\nunions. This prevents nested or parallel spans from being added twice, and it\ndoes not combine a failed or dequeued attempt with a later retry. Missing\nrequired measurements make that attempt `incomplete` instead of producing fake\nprecision.\n\nEach attempt also reports measured execution lanes, lane skew, cache outcome\ncounts, the ten longest actionable spans, and one falsifiable next optimization\ntarget. Queue residence, whole-workflow envelopes, and job parents are excluded\nfrom the actionable ranking so they cannot hide the build or qualification\nstage that can actually be changed. The target is an observation, not a causal\nclaim: repeat the same source-bound cohort and disprove it by reducing that span\nbelow the next measured span without increasing attempt elapsed time or\nfailures.\n\nShell and workflow consumers can generate the same machine artifact plus a\ncompact report:\n\n```sh\nbuildchain candidate timeline \\\n  --input .buildchain/candidate-timeline-input.json \\\n  --output .buildchain/candidate-timeline.json\n```\n\nThe input and output should contain only bounded correlation facts and timing\nreceipts. Do not include tokens, environment dumps, full commands, raw process\ndumps, or private absolute paths.\n\nCommonJS scripts should import Buildchain's ESM surfaces dynamically:\n\n```js\nconst { createBuildchainLogger } = await import(\"@kungfu-tech/buildchain/logging\");\nconst { collectRunnerDiagnostics } = await import(\"@kungfu-tech/buildchain/diagnostics\");\n```\n\n## Diagnostics API\n\nThe diagnostics surface collects local, non-telemetry build facts that are\nuseful when a native build is slow or flaky:\n\n```js\nimport {\n  collectBuildchainDiagnostics,\n  collectCacheDiagnostics,\n  collectCompilerCacheDiagnostics,\n  collectRunnerDiagnostics,\n  collectToolDiagnostics,\n  detectRequestedParallelism,\n  startProcessSampler,\n  summarizeDiagnosticsArtifacts,\n  summarizeLifecycleObservability,\n  summarizeProcessSamples,\n  validateAnchoredPackageRelease,\n  writeDiagnosticsArtifact,\n} from \"@kungfu-tech/buildchain/diagnostics\";\n\nconst lifecycleObservability = summarizeLifecycleObservability({\n  logPath: \".buildchain/logs/events.jsonl\",\n});\nconst buildCommand = \"make\";\nconst buildArgs = [\"-j20\"];\nconst requestedParallelism = detectRequestedParallelism({\n  command: buildCommand,\n  args: buildArgs,\n});\nconst processSampler = startProcessSampler({\n  intervalMs: 15000,\n  label: \"native-build\",\n  command: buildCommand,\n  args: buildArgs,\n});\n// Run the long native build while the sampler is active.\nconst processSummary = summarizeProcessSamples({\n  requestedParallelism: requestedParallelism.value,\n  samples: processSampler.stop(),\n});\nconst cacheDiagnostics = collectCacheDiagnostics({ cwd: process.cwd() });\n\nwriteDiagnosticsArtifact(\".buildchain/artifacts/diagnostics.json\", {\n  contract: \"consumer-build-diagnostics\",\n  buildchain: collectBuildchainDiagnostics({ cwd: process.cwd() }),\n  runner: collectRunnerDiagnostics(),\n  tools: collectToolDiagnostics({ cwd: process.cwd() }),\n  cache: cacheDiagnostics,\n  lifecycleObservability,\n  process: processSummary,\n});\n```\n\n`collectCacheDiagnostics()` includes package-manager/workspace context, selected\ncache directory stats, and compiler-cache stats from `ccache --show-stats\n--json` plus `sccache --show-stats --stats-format json` when those tools are\npresent. If a ccache build does not support JSON stats, Buildchain falls back to\nplain `ccache --show-stats` and parses the text counters. Missing cache tools\nare recorded as unavailable instead of failing the diagnostics artifact. Call\n`collectCompilerCacheDiagnostics()` directly when a consumer script only needs\ncompiler cache data. Native diagnostics also expose `compilerCaches` and\n`nativeCacheDirs` as top-level fields in each diagnostics artifact and aggregate\nsummary, so reviewers do not have to dig through nested cache sections first.\nFor reusable builds, sccache outcomes enter structured current-run evidence only\nwhen a sibling `compiler-cache-preparation.json` proves the counters were reset\nafter install and before build; cumulative stats without that receipt remain\nexplicitly unavailable.\n\nProcess samples are intentionally summarized before they become long-lived\nartifacts. The summary records requested parallelism, the source of that value\n(`command`, `process-tree`, `env:MAKEFLAGS`,\n`env:CMAKE_BUILD_PARALLEL_LEVEL`, or `explicit`), observed active process\nconcurrency, elapsed sample time, total sampled CPU, and conservative command\ncategories such as `compiler`, `archive`, `linker`, `build-tool`, and `cache`.\nThe sampler detects common `make -j N`, `ninja -j N`, CMake/MSBuild/Xcode job\nflags, and MAKEFLAGS. This lets native projects distinguish \"we asked for\n`make -j20`\" from \"the build graph only kept two active compiler or archive\nchildren busy during the sampled window\" without storing environment dumps.\n\nNative repositories can opt into a reusable diagnostics profile in\n`buildchain.toml`:\n\n```toml\n[diagnostics.native]\nenabled = true\nsample_process_tree = true\ncompiler_cache = \"auto\"\nexpected_tools = [\"ccache\", \"sccache\", \"clang\", \"cl\", \"cmake\", \"ninja\"]\nartifact_dirs = [\"build\", \"dist\", \"build/Release\"]\ncache_dirs = [\".ccache\", \".sccache\"]\n```\n\nWhen enabled, diagnostics artifacts include the normalized profile, selected\ntool versions, compiler-cache stats, and configured artifact/cache directory\nstats. The profile is data-driven: Buildchain does not assume a specific\nproject such as libnode. The reusable build workflow also exposes\n`sample-process-tree`, which wraps the build lifecycle with the process sampler\nand carries the generated summary into the final diagnostics artifact. Custom\nworkflows can call `buildchain sample process-tree` directly when they need a\ndifferent command boundary.\n\nAnchored/manual package projects can also run one higher-level release-shape\ncheck instead of assembling lower-level config calls:\n\n```js\nconst anchoredReport = validateAnchoredPackageRelease({\n  cwd: process.cwd(),\n  requireManifest: true,\n  requirePackageSetOrder: \"platforms-first-main-last\",\n  requireTrustedPublishing: true,\n});\n\nif (!anchoredReport.ok) {\n  throw new Error(\"Anchored package release contract failed\");\n}\n```\n\nIn an actual publish job, make that check source-lock aware:\n\n```js\nconst publishReady = validateAnchoredPackageRelease({\n  cwd: process.cwd(),\n  requirePublishGateSourceLock: true,\n});\n```\n\nThe source-lock inputs are read from `BUILDCHAIN_PUBLISH_SOURCE_REF`,\n`BUILDCHAIN_PUBLISH_SOURCE_SHA`, and `BUILDCHAIN_PUBLISH_SOURCE_LOCKED`, which\nthe reusable build workflow emits after resolving `publish-source-ref`. That\nturns direct channel-branch publication from `alpha/*` or `release/*` into a\nhard failure, while `publish-gate/alpha/<line>/<version>` and\n`publish-gate/release/<line>/<version>` also validate the requested consumer\nversion against configured version files and the anchor manifest.\n\n`buildchain lifecycle run` writes this small diagnostics artifact next to the\nplatform manifest by default. The per-platform diagnostics upload includes the\ncompact `diagnostics.json`, `diagnostics-manifest.json`, lifecycle\n`events.jsonl`, and, when process sampling is enabled, copied\n`process-summary.json` and `process-samples.jsonl` sidecars. The sidecar\nmanifest records each uploaded diagnostics file with its relative path, byte\ncount, and sha256 hash. It is intended to stay small enough to download without\nfetching large binary packages, and it should not include full environment dumps\nor secret-looking values.\n\nUse `summarizeDiagnosticsArtifacts()` when a matrix build uploads one\ndiagnostics artifact per platform. The summary keeps each platform's lifecycle\nstage table, adds a lifecycle total duration, carries the top slow spans, and\naggregates warning/error counts plus the slowest platforms. Per-platform rows\nalso include compact runner facts, checked tool versions/missing tools, package\nmanager/cache directory details, compiler cache availability, and a compact\nprocess sampler view with requested parallelism, observed max active processes,\nthe ratio between them, sample count, process categories, and top sampled\ncommand basenames. That gives release reviewers a small cross-platform timing,\nrunner, tool, cache, and concurrency view without downloading full build outputs\nor process sidecars.\n\nThe reusable build workflow writes that rollup as `diagnostics-summary.json` and\nuploads it in a separate aggregate diagnostics summary artifact. Consumers can\nread the `build-diagnostics-summary-artifact` output when they need only timing,\nwarning/error, runner, cache, and process-sampler context instead of the build\nsummary or binary artifacts. Per-platform rows keep the diagnostics `links`\nobject, including the binary artifact name, manifest artifact name, diagnostics\nartifact name, platform id, diagnostics sidecar manifest path, manifest path,\nsummary path, and process sidecar paths when present. They also keep compact\nrunner/tool/cache summaries so reviewers can tell whether a slow row ran on the\nexpected runner, missed an expected tool, or lacked useful compiler-cache stats.\nWhen the downloaded platform diagnostics include a sibling\n`diagnostics-manifest.json`, `summarizeDiagnosticsArtifacts()` carries a compact\n`diagnosticsManifest` section for that platform and verifies the manifest's\n`diagnostics.json` byte count and sha256. Missing or mismatched sidecar manifests\nincrement `diagnosticsManifestWarningCount`, so reviewers can distinguish\ndiagnostics sidecar drift from lifecycle warnings or build failures.\nThe same summary carries `diagnosticsContract` per platform and aggregates\n`diagnosticsContractWarningCount` when a downloaded `diagnostics.json` does not\nmatch `BUILDCHAIN_DIAGNOSTICS_CONTRACT`.\n\nThe diagnostics SDK also exports stable contract constants such as\n`BUILDCHAIN_DIAGNOSTICS_SUMMARY_CONTRACT`,\n`BUILDCHAIN_DIAGNOSTICS_MANIFEST_CONTRACT`,\n`BUILDCHAIN_PROCESS_SAMPLE_REPORT_CONTRACT`,\n`BUILDCHAIN_PROCESS_SAMPLE_SUMMARY_CONTRACT`, and\n`BUILDCHAIN_ANCHORED_PACKAGE_RELEASE_VALIDATION_CONTRACT` from\n`@kungfu-tech/buildchain/diagnostics`; consumers should compare against those\nconstants instead of hardcoding contract strings.\n\nThe CLI exposes the same aggregation for shell and workflow steps:\n\n```bash\nbuildchain diagnostics summary \\\n  .buildchain/artifacts/linux-x64/diagnostics.json \\\n  .buildchain/artifacts/macos-arm64/diagnostics.json \\\n  --output .buildchain/artifacts/diagnostics-summary.json \\\n  --json\n```\n\nOmit `--json` when the workflow log should show a compact platform table with\nlifecycle stages, artifact scan/upload time, total time, requested jobs,\nobserved active processes, warnings, and errors.\n\nFor long native build commands, the CLI can also sample the child process tree\nwhile preserving the wrapped command's exit code:\n\n```bash\nbuildchain sample process-tree \\\n  --label native-build \\\n  --interval-ms 15000 \\\n  --output .buildchain/diagnostics/process-samples.jsonl \\\n  --summary-output .buildchain/diagnostics/process-summary.json \\\n  -- \\\n  make -j20\n```\n\nThe JSONL sample file stores timestamped process-tree snapshots with full\nredacted command lines, command basenames, CPU percentages when available,\nelapsed time, and requested parallelism context. Unix and macOS snapshots read\nthe full `ps args` field instead of truncated `comm` names. Windows snapshots\nread `Win32_Process` command lines through PowerShell so the sampler no longer\nreturns an empty process set on Windows runners. The summary file records\nobserved concurrency, total sampled CPU, command categories, and top command\nbasenames. This is intended for diagnosing low-utilization tails such as\narchive/link phases without logging full environment dumps.\n\nThe lifecycle observability summary is stage-wide, not just final-step timing:\nwhen install and build write to the same Buildchain log, the final platform\nmanifest can show both stages and the slowest spans.\n\n## CLI Logging\n\n```bash\nbuildchain mark \\\n  --event native.configure \\\n  --phase configure \\\n  --component cmake \\\n  --attribute preset=release\n\nbuildchain span \\\n  --event native.build \\\n  --phase build \\\n  --component cmake \\\n  -- cmake --build build --config Release\n\nbuildchain log summary --json\nbuildchain verify observability-log .buildchain/logs/events.jsonl --min-events 4\n```\n\nEvery event records a timestamp. `span` records duration and preserves the\nwrapped command's exit code.\n\nBuildchain also records local control-plane outcome events for workflow-friction\nincident handling and production release-intent PR handling. `log summary`\nreports the observed incident reuse rate, release-intent suppression rate, and\nsuppression reasons. A reused incident means an equivalent occurrence found the\nsame fingerprint and was commented, cooled down, or otherwise reused; a\nsuppressed release intent means Buildchain proved that the source commit already\nhad a qualifying merged release PR. These are operational facts, not release\npolicy inputs, and logging failure remains non-fatal by default.\n\nThe reusable promotion workflow uploads `.buildchain/logs/events.jsonl` when a\nfriction report is produced. The web-surface production release PR handoff\nartifact includes the same path, so a real run can falsify the P0 claim instead\nof relying only on unit tests.\n\n## Release Gate\n\nBuildchain's own binary distribution lane verifies required log events before\nuploading release assets. Consumers can apply the same pattern:\n\n```bash\nbuildchain verify observability-log .buildchain/logs/events.jsonl \\\n  --require-phase build \\\n  --require-phase package \\\n  --require-component workflow \\\n  --require-event native.build.start \\\n  --require-event native.build.end\n```\n\nThis makes missing instrumentation a release failure instead of a dashboard\nafterthought."
     },
     {
       "id": "manual:versioning",
@@ -2305,7 +2391,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/versioning.md",
-      "digest": "sha256:4b40cb8675c111b7588297102a61cb241630f2b707a67a0384a6df7527b2c64c",
+      "digest": "sha256:5dd27f3c4a412a23093e5d33746a5d5d40353625c8ffe89a961978fc5de9c03e",
       "headings": [
         {
           "level": 1,
@@ -2333,7 +2419,7 @@
           "anchor": "runner-policy"
         }
       ],
-      "markdown": "# Buildchain Versioning\n\nBuildchain uses semantic version lines to describe public contracts, not only\ncode size. A release can be small in diff size and still open a new minor line\nwhen it adds a durable surface that consumers, workflows, or agents can depend\non.\n\n## Lines\n\n| Line | Meaning |\n| --- | --- |\n| Patch | Compatible fix, hardening, documentation correction, or implementation repair inside an existing surface. |\n| Minor | New compatible welded surface: reusable workflow output, CLI command family, config protocol, published subpath, evidence file, runner contract, or agent-readable artifact. |\n| Major | Breaking semantic change, removed stable surface, changed branch/tag governance, or incompatible protocol rewrite. |\n\nKungfu minor lines are long-lived trains. `v2.0`, `v2.1`, and `v2.2` can each\nreceive many patch releases. The major ref, such as `v2`, points at the\nselected stable major entrypoint; the minor ref, such as `v2.2`, points at the\nlatest stable production patch for that minor line.\n\n## Welded Surfaces\n\nThese surfaces are classified independently; the final release impact is the\nhighest impact across the affected registered surfaces:\n\n- reusable workflow inputs, outputs, and artifact contracts;\n- public CLI command families and their machine-readable JSON shapes;\n- public npm exports such as `@kungfu-tech/buildchain/logging`;\n- config protocols such as `buildchain.toml`;\n- release governance state machines and protected ref semantics;\n- release evidence contracts such as passport, artifact evidence, impact\n  ledger, and agent index files;\n- binary distribution shapes that users can install or automate against.\n\nFor each surface:\n\n- content, documentation, or implementation-only work that does not touch a\n  registered surface is patch;\n- additive fields, new commands, new exports, new evidence sections, or new\n  registered surfaces are minor;\n- removals, incompatible renames, changed meanings, newly required fields,\n  weakened trust gates, or changed ref flow are major.\n\nThe release passport records this as `surfaceImpacts[]` plus\n`versionImpact.final`. The final impact must equal the highest surface impact,\nso an agent cannot silently label a release patch when one machine surface needs\nminor review.\n\n`surfaceImpacts[]` is mandatory for production release passports (`release/*`)\nand major publish-gate passports. Alpha, local, and legacy passport contexts\nkeep the field optional so temporary validation can proceed without pretending\nto be a production release decision.\n\nExample: a KFD document such as KFD-2 is content and remains patch, but adding a\n`kind` field to the machine-consumed KFD `registry.json` is an additive change\nto the `kfd-registry-schema` surface and therefore requires minor-impact\nreview. This avoids both false shortcuts: \"new KFD means minor\" and \"all KFD\nrepository changes are patch\".\n\n## Decision Log\n\n| Date | Action | Line | Faces | Class | Rationale | PR |\n| --- | --- | --- | --- | --- | --- | --- |\n| 2026-07-28 | extend-minor | `v3.0` | auditable-demo-workflow, auditable-demo-media-profile, auditable-demo-media-receipt | additive | Add opt-in archive, web-delivery, and site-hero profiles; independently bind codec, container, audio, layout, byte-budget, role, and fast-start facts into a v2 media receipt while preserving the existing archive default. | |\n| 2026-07-26 | extend-minor | `v3.0` | auditable-demo-workflow, auditable-demo-evidence | additive | Forward-port the consumer-neutral reusable Gate that binds exact same-run GitHub Artifacts to checked-in adapters and immutable renderer evidence, with optional media rendering only from the exact passing Gate bundle. | #1862 |\n| 2026-07-23 | extend-minor | `v2.14` | credential-island-macos-input, protected-signer-job, macos-signing-evidence, action-subpaths | additive | The reusable build surface can seal an exact source-bound macOS app and hand it to a protected caller environment, where an immutable Buildchain action signs, notarizes, staples, Gatekeeper-assesses, and returns an auditable additional release-candidate platform without exposing credentials to consumer lifecycle jobs. | |\n| 2026-07-20 | extend-minor | `v2.14` | anchored-derived-version-material, build-controller-evidence, release-passport, package-subpaths, release-propagation-controller | additive | Anchored/manual consumers can declare derived version witnesses that Buildchain regenerates and verifies before heavy builds, binds to exact alpha/release trees and passports, and admits during protected promotion; propagation receipts now model their existing optional consumer stages. | |\n| 2026-07-17 | extend-minor | `v2.14` | merge-queue-config, release-line-governance-inheritance | additive | Buildchain config can explicitly enable, inherit, or disable exact dev-channel merge queues, and release-line bootstrap reconciles the declared or inherited policy before moving the repository default branch. | |\n| 2026-07-16 | open-minor | `v2.14` | dev-merge-queue-governance | additive | The public CLI adds a dry-run-first, idempotent merge-queue governance command that verifies required workflow event compatibility before applying an exact dev-channel ruleset and removing the strict up-to-date race. | |\n| 2026-07-15 | open-minor | `v2.13` | artifact-verification-envelope, package-subpaths | additive | The public envelope seals exact artifact, provenance, identity, lifecycle, revocation, and existing KFD assessment roots into one consumer-ready KFX admission input, with a dedicated Node API export and fail-closed verifier. | |\n| 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. | |\n| 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. | |\n| 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. | |\n| 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. | |\n| 2026-07-03 | open-minor | `v2.4` | infra-contract-lifecycle | additive | Infra contract lifecycle adds the provider-neutral `infra-contract` CLI command family, project type, adapter capability contract, lifecycle evidence bundle, propagation evidence, CI evidence mode, and consumer-facing contract artifacts. | |\n| 2026-07-02 | open-minor | `v2.3` | web-surface-host-mapping | additive | Web surface host mapping adds first-class multi-host surface bindings, reusable workflow URL outputs, per-surface deployment overrides, and an agent-readable fixture contract. | |\n| 2026-07-02 | open-minor | `v2.2` | release-passport, binary-distribution | additive | Release passport and binary distribution add agent-readable release passport files, artifact evidence, impact ledger, agent index, GitHub Release collection and verification commands, and standalone binary assets. | |\n| 2026-07-02 | open-minor | `v2.1` | logging-sdk, cli-observability, package-subpaths | additive | Buildchain toolkit observability adds the public logging SDK, CLI observability commands, and package subpaths that consumers can import. | |\n\n## Runner Policy\n\nThe `v2.2` binary distribution lane uses GitHub-hosted runners for production\nassets because that is the easiest release path for external users to reproduce:\n\n- `ubuntu-24.04`\n- `macos-latest`\n- `windows-2022`\n\nSelf-hosted runners remain compatibility fixtures. They prove Buildchain's\nprotocol does not depend on GitHub-hosted images, but they do not define the\npublic binary distribution path."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-versioning\ndoc_type: policy\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-31\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-30\n  invisible_context_boundary: Live release and provider state must be verified independently.\n---\n\n# Buildchain Versioning\n\nBuildchain uses semantic version lines to describe public contracts, not only\ncode size. A release can be small in diff size and still open a new minor line\nwhen it adds a durable surface that consumers, workflows, or agents can depend\non.\n\n## Lines\n\n| Line  | Meaning                                                                                                                                                                      |\n| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Patch | Compatible fix, hardening, documentation correction, or implementation repair inside an existing surface.                                                                    |\n| Minor | New compatible welded surface: reusable workflow output, CLI command family, config protocol, published subpath, evidence file, runner contract, or agent-readable artifact. |\n| Major | Breaking semantic change, removed stable surface, changed branch/tag governance, or incompatible protocol rewrite.                                                           |\n\nKungfu minor lines are long-lived trains. `v3.0`, `v3.1`, and `v3.2` can each\nreceive many patch releases. The major ref, such as `v3`, points at the\nselected stable major entrypoint; the minor ref, such as `v3.2`, points at the\nlatest stable production patch for that minor line.\n\n## Welded Surfaces\n\nThese surfaces are classified independently; the final release impact is the\nhighest impact across the affected registered surfaces:\n\n- reusable workflow inputs, outputs, and artifact contracts;\n- public CLI command families and their machine-readable JSON shapes;\n- public npm exports such as `@kungfu-tech/buildchain/logging`;\n- config protocols such as `buildchain.toml`;\n- release governance state machines and protected ref semantics;\n- release evidence contracts such as passport, artifact evidence, impact\n  ledger, and agent index files;\n- binary distribution shapes that users can install or automate against.\n\nFor each surface:\n\n- content, documentation, or implementation-only work that does not touch a\n  registered surface is patch;\n- additive fields, new commands, new exports, new evidence sections, or new\n  registered surfaces are minor;\n- removals, incompatible renames, changed meanings, newly required fields,\n  weakened trust gates, or changed ref flow are major.\n\nThe release passport records this as `surfaceImpacts[]` plus\n`versionImpact.final`. The final impact must equal the highest surface impact,\nso an agent cannot silently label a release patch when one machine surface needs\nminor review.\n\n`surfaceImpacts[]` is mandatory for production release passports (`release/*`)\nand major publish-gate passports. Alpha, local, and legacy passport contexts\nkeep the field optional so temporary validation can proceed without pretending\nto be a production release decision.\n\nExample: a KFD document such as KFD-2 is content and remains patch, but adding a\n`kind` field to the machine-consumed KFD `registry.json` is an additive change\nto the `kfd-registry-schema` surface and therefore requires minor-impact\nreview. This avoids both false shortcuts: \"new KFD means minor\" and \"all KFD\nrepository changes are patch\".\n\n## Decision Log\n\n| Date       | Action       | Line    | Faces                                                                                                                                                                        | Class    | Rationale                                                                                                                                                                                                                                                                                                                              | PR    |\n| ---------- | ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |\n| 2026-07-31 | extend-minor | `v3.0`  | auditable-demo-workflow, auditable-demo-media-profile, auditable-demo-media-receipt                                                                                          | additive | Add an opt-in responsive profile that binds source-resolution and exact 1280x720 MP4/WebM/GIF renditions to one Gate and receipt while rejecting upscales, aspect-ratio drift, and profile changes between Gate-only and full-render paths.                                                                                              |       |\n| 2026-07-31 | extend-minor | `v3.0`  | release-candidate-family-evidence, release-passport-evidence-attachment, promotion-action, release-passport-cli                                                             | additive | Restore all-ref v2 parity for optional Initiative-family candidate binding and typed product-owned release evidence attachments while retaining Kungfu native Family State authority and the newer v3 post-activation released-evidence stage.                                                                                         | #2089 |\n| 2026-07-30 | extend-minor | `v3.0`  | reusable-build-workflow, observed-evidence-bundle, release-passport-json-reader, web-surface-release-governance                                                               | additive | Add bounded artifact compression and remote-read controls plus transactional derived evidence projections while repairing release-PR runtime handoff so production remains protected-main-only.                                                                                                                                       |       |\n| 2026-07-29 | extend-minor | `v3.0`  | artifact-signing-config, apple-developer-id-authority, artifact-signing-evidence                                                                                             | additive | Extend the consumer-neutral signing declaration to macOS compound archives, including nested wheel Mach-O signing, PEP 427 RECORD repair, safe archive reconstruction, and whole-product notarization under the same protected authority.                                                                                              |       |\n| 2026-07-28 | extend-minor | `v3.0`  | auditable-demo-workflow, auditable-demo-media-profile, auditable-demo-media-receipt                                                                                          | additive | Add opt-in archive, web-delivery, and site-hero profiles; independently bind codec, container, audio, layout, byte-budget, role, and fast-start facts into a v2 media receipt while preserving the existing archive default.                                                                                                           |       |\n| 2026-07-26 | extend-minor | `v3.0`  | auditable-demo-workflow, auditable-demo-evidence                                                                                                                             | additive | Forward-port the consumer-neutral reusable Gate that binds exact same-run GitHub Artifacts to checked-in adapters and immutable renderer evidence, with optional media rendering only from the exact passing Gate bundle.                                                                                                              | #1862 |\n| 2026-07-23 | extend-minor | `v2.14` | credential-island-macos-input, protected-signer-job, macos-signing-evidence, action-subpaths                                                                                 | additive | The reusable build surface can seal an exact source-bound macOS app and hand it to a protected caller environment, where an immutable Buildchain action signs, notarizes, staples, Gatekeeper-assesses, and returns an auditable additional release-candidate platform without exposing credentials to consumer lifecycle jobs.        |       |\n| 2026-07-20 | extend-minor | `v2.14` | anchored-derived-version-material, build-controller-evidence, release-passport, package-subpaths, release-propagation-controller                                             | additive | Anchored/manual consumers can declare derived version witnesses that Buildchain regenerates and verifies before heavy builds, binds to exact alpha/release trees and passports, and admits during protected promotion; propagation receipts now model their existing optional consumer stages.                                         |       |\n| 2026-07-17 | extend-minor | `v2.14` | merge-queue-config, release-line-governance-inheritance                                                                                                                      | additive | Buildchain config can explicitly enable, inherit, or disable exact dev-channel merge queues, and release-line bootstrap reconciles the declared or inherited policy before moving the repository default branch.                                                                                                                       |       |\n| 2026-07-16 | open-minor   | `v2.14` | dev-merge-queue-governance                                                                                                                                                   | additive | The public CLI adds a dry-run-first, idempotent merge-queue governance command that verifies required workflow event compatibility before applying an exact dev-channel ruleset and removing the strict up-to-date race.                                                                                                               |       |\n| 2026-07-15 | open-minor   | `v2.13` | artifact-verification-envelope, package-subpaths                                                                                                                             | additive | The public envelope seals exact artifact, provenance, identity, lifecycle, revocation, and existing KFD assessment roots into one consumer-ready KFX admission input, with a dedicated Node API export and fail-closed verifier.                                                                                                       |       |\n| 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.                                              |       |\n| 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.                                                                                                                    |       |\n| 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. |       |\n| 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.                                                                                                                                                      |       |\n| 2026-07-03 | open-minor   | `v2.4`  | infra-contract-lifecycle                                                                                                                                                     | additive | Infra contract lifecycle adds the provider-neutral `infra-contract` CLI command family, project type, adapter capability contract, lifecycle evidence bundle, propagation evidence, CI evidence mode, and consumer-facing contract artifacts.                                                                                          |       |\n| 2026-07-02 | open-minor   | `v2.3`  | web-surface-host-mapping                                                                                                                                                     | additive | Web surface host mapping adds first-class multi-host surface bindings, reusable workflow URL outputs, per-surface deployment overrides, and an agent-readable fixture contract.                                                                                                                                                        |       |\n| 2026-07-02 | open-minor   | `v2.2`  | release-passport, binary-distribution                                                                                                                                        | additive | Release passport and binary distribution add agent-readable release passport files, artifact evidence, impact ledger, agent index, GitHub Release collection and verification commands, and standalone binary assets.                                                                                                                  |       |\n| 2026-07-02 | open-minor   | `v2.1`  | logging-sdk, cli-observability, package-subpaths                                                                                                                             | additive | Buildchain toolkit observability adds the public logging SDK, CLI observability commands, and package subpaths that consumers can import.                                                                                                                                                                                              |       |\n\n## Runner Policy\n\nThe `v2.2` binary distribution lane uses GitHub-hosted runners for production\nassets because that is the easiest release path for external users to reproduce:\n\n- `ubuntu-24.04`\n- `macos-latest`\n- `windows-2022`\n\nSelf-hosted runners remain compatibility fixtures. They prove Buildchain's\nprotocol does not depend on GitHub-hosted images, but they do not define the\npublic binary distribution path."
     },
     {
       "id": "manual:web-surface-deployments",
@@ -2347,7 +2433,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/web-surface-deployments.md",
-      "digest": "sha256:ed4ff02dcb6f66118a29084784f25d8008ca472f59005b2e014133524706a9c5",
+      "digest": "sha256:484e896746d2f4cca4f9f18d29c14784ec20143c12affc3dbb9ccfbf8f221b55",
       "headings": [
         {
           "level": 1,
@@ -2429,6 +2515,11 @@
           "title": "Immutable publication paths",
           "anchor": "immutable-publication-paths"
         },
+        {
+          "level": 3,
+          "title": "Qualified publication package-pin fast path",
+          "anchor": "qualified-publication-package-pin-fast-path"
+        },
         {
           "level": 2,
           "title": "Production Preflight And Health",
@@ -2460,7 +2551,7 @@
           "anchor": "boundaries"
         }
       ],
-      "markdown": "# Web-Surface Deployment Contract\n\nBuildchain supports `project.type = \"web-surface\"` for repositories that publish\nsites, docs, product pages, operator consoles, or browser apps. These projects\nneed auditable deployment semantics, but they are not package release lines and\nshould not be forced into `dev/alpha/release` version-state automation.\n\nThe release object for a web surface is:\n\n```text\nsource commit + build artifact + deploy target + channel + deployment manifest\n```\n\nThis keeps the evidence chain clear:\n\n- the source SHA explains what code was built;\n- the artifact hash explains exactly what was deployed;\n- the channel explains who can see it and whether it is promotable;\n- the deploy target and adapter explain where it would be published;\n- the deployment manifest records retention, rollback, security, and secret\n  reference metadata.\n\n## Configuration\n\n`.buildchain/buildchain.toml` is the source of truth. Web-surface projects must declare\npreview, staging, and production channels plus a deploy adapter for each.\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[channels.preview]\nurl_pattern = \"https://{alias}.preview.kungfu.tech\"\nvisibility = \"ephemeral\"\nrequires_auth = false\nnoindex = true\n\n[channels.staging]\nurl = \"https://staging.kungfu.tech\"\nvisibility = \"protected\"\naccess_control = \"managed-network\"\nedge_auth = \"none\"\nnoindex = true\npromotable = true\n\n[channels.production]\nurl = \"https://kungfu.tech\"\nvisibility = \"public\"\ncanonical = true\nnoindex = false\n\n[deploy.preview]\nadapter = \"aws-s3-cloudfront\"\nbucket = \"kungfu-tech-preview\"\ncloudfront_distribution = \"E-PREVIEW\"\nartifact_path = \"dist\"\nsecret_refs = [\"AWS_ROLE_ARN\"]\n# Optional. Defaults to \"buildchain\".\n# Use \"external\" when an existing viewer-request CloudFront Function already\n# owns preview alias, surface-prefix, and directory-index routing.\ndirectory_index_rewrite = \"buildchain\"\n# Optional. Defaults to HTTP for public channels and S3 object evidence for\n# managed-network channels. Use \"s3-object\" when CI should verify uploaded\n# objects and manifests instead of waiting for public edge convergence.\nhealth_strategy = \"http\"\n```\n\n### Multi-Surface Host Mapping\n\nSome site repositories publish more than one first-class web surface from the\nsame artifact. For example, `site-libkungfu-dev` has a hub plus separate\nhostnames for core, Buildchain, and Kung Fu Decisions. These are not just\nnavigation paths; staging, production preflight, and post-deploy health checks\nmust verify host-level behavior for each surface.\n\nDeclare named surfaces with per-channel URLs:\n\n```toml\n[surfaces.hub]\npath = \"/\"\nproduction_url = \"https://libkungfu.dev\"\nstaging_url = \"https://staging.libkungfu.dev\"\npreview_url_pattern = \"https://{alias}.preview.libkungfu.dev\"\n\n[surfaces.core]\npath = \"/core/\"\nproduction_url = \"https://core.libkungfu.dev\"\nstaging_url = \"https://core.staging.libkungfu.dev\"\npreview_url_pattern = \"https://core-{alias}.preview.libkungfu.dev\"\n\n[surfaces.buildchain]\npath = \"/buildchain/\"\nproduction_url = \"https://buildchain.libkungfu.dev\"\nstaging_url = \"https://buildchain.staging.libkungfu.dev\"\npreview_url_pattern = \"https://buildchain-{alias}.preview.libkungfu.dev\"\n\n[surfaces.kfd]\npath = \"/kfd/\"\nproduction_url = \"https://kfd.libkungfu.dev\"\nstaging_url = \"https://kfd.staging.libkungfu.dev\"\npreview_url_pattern = \"https://kfd-{alias}.preview.libkungfu.dev\"\n```\n\nBuildchain resolves every `(channel, surface)` pair. A preview alias such as\n`pr-12` becomes:\n\n```text\nhub:        https://pr-12.preview.libkungfu.dev\ncore:       https://core-pr-12.preview.libkungfu.dev\nbuildchain: https://buildchain-pr-12.preview.libkungfu.dev\nkfd:        https://kfd-pr-12.preview.libkungfu.dev\n```\n\nWhen `surfaces` is omitted, Buildchain preserves the legacy single-surface\ncontract by creating an implicit `default` surface from the channel URL. When a\nsurface is intentionally path-only, declare it explicitly:\n\n```toml\n[surfaces.docs]\npath = \"/docs/\"\npath_only = true\n```\n\n`path_only = true` is an exception, not the default. Without it, every named\nsurface must declare `preview_url_pattern`, `staging_url`, and\n`production_url`. This makes staging/production mismatches fail during\nvalidation instead of becoming invisible deploy drift.\n\nAdapter strategy remains explicit. The default `aws-s3-cloudfront` plan uses the\nchannel deploy target for every surface, and each binding records its own\nbucket, distribution id, object prefix, manifest key, source path, and URL. A\nchannel can override target details per surface:\n\n```toml\n[deploy.staging.surfaces.core]\nbucket = \"libkungfu-dev-core-staging\"\ncloudfront_distribution = \"E-CORE-STAGING\"\norigin_path = \"/core\"\n```\n\nBuildchain validates these hard constraints:\n\n- `channels.preview.url_pattern` is required and must contain the alias shape\n  used by preview deployments.\n- `channels.staging.access_control` must protect staging. Supported modes are\n  `managed-network`, `edge-basic-auth`, `oidc`, and `app-auth`.\n- `channels.staging.edge_auth` records whether the edge layer owns auth. Use\n  `edge_auth = \"none\"` when staging is protected by managed network controls\n  such as WAF/IP allowlists or VPN access.\n- `channels.staging.noindex = true` is required.\n- `channels.production.url` is required.\n- deploy adapters must be declared per channel.\n- named surfaces must declare first-class URLs for every channel unless\n  `path_only = true` is explicitly set.\n- secret material must be declared as reference names, such as\n  `secret_refs = [\"AWS_ROLE_ARN\"]`; inline secret-like deploy keys are rejected.\n\n### Floating Runtime Contract Lock\n\nWeb-surface repositories can consume the stable Buildchain workflow shell with a\nfloating ref, such as:\n\n```yaml\njobs:\n  web:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v3\n    with:\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n      buildchain-contract-compatibility-policy: major-compatible\n      buildchain-contract-drift-issue-mode: compatible-and-breaking\n      build-command: pnpm build\n      artifact-path: dist\n```\n\nThe caller repository commits `.buildchain/contract-lock.json` after reviewing an\naccepted Buildchain runtime SHA and contract digest. The reusable workflow then\nresolves the floating runtime to an immutable SHA, checks the lock before the\ncaller build command, and applies these rules:\n\n- unchanged lock: continue without feedback;\n- compatible drift: continue, write the drift summary, and open or update a\n  caller-repository issue when permissions allow;\n- breaking drift: fail closed before rendering, deployment planning, deploy\n  apply, or release publication.\n\nThe caller no longer needs to run `scripts/buildchain-contract-lock.mjs` inside\nits own build command. That check belongs to Buildchain because the actual\ncontract world is stored in the Buildchain runtime ref being used.\n\nSupported adapter names are:\n\n| Adapter | Initial use |\n| --- | --- |\n| `aws-s3-cloudfront` | Static site artifact sync plus CDN invalidation plan |\n| `aws-elastic-beanstalk` | Future dynamic app environment adapter |\n| `aws-ecs-service` | Future dynamic service adapter |\n\nThe channel ontology is independent of the adapter. A future dynamic staging\nenvironment still remains `channel = \"staging\"` with protected/noindex/security\nrequirements.\n\n## Preview Aliases\n\nPreview uses subdomains, not path prefixes:\n\n```text\nhttps://pr-123.preview.kungfu.tech\nhttps://sha-abcdef123456.preview.kungfu.tech\n```\n\nAlias semantics are explicit:\n\n| Alias | Meaning | Mutable | Retention |\n| --- | --- | --- | --- |\n| `pr-123` | Current preview for a pull request | yes | short-lived |\n| `sha-abcdef123456` | Immutable preview for one source SHA | no | longer-lived |\n\nThis allows PR comments to stay stable while preserving immutable evidence for a\nspecific source commit.\n\n## Deployment Manifest\n\nBuildchain emits a manifest with the deployment facts that matter for audit and\nrollback:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"contract\": \"kungfu-buildchain-web-surface-deployment\",\n  \"site\": \"libkungfu-dev\",\n  \"channel\": \"preview\",\n  \"alias\": \"sha-abcdef123456\",\n  \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n  \"generatedAt\": \"2026-07-01T00:00:00.000Z\",\n  \"publishedAt\": \"2026-07-01T00:00:00.000Z\",\n  \"reproducible\": true,\n  \"timestampPolicy\": \"ci-injected\",\n  \"deterministicInputs\": [\n    \"web-surface artifact content\",\n    \"buildchain.toml web-surface channels/deploy/surfaces\",\n    \"sourceSha\",\n    \"artifactHash\",\n    \"deployment channel\",\n    \"deployment alias\"\n  ],\n  \"sourceRevision\": \"...\",\n  \"timestampPolicyDetails\": {\n    \"contract\": \"kungfu-buildchain-surface-timestamp-policy\",\n    \"timestampFields\": [\"generatedAt\", \"publishedAt\", \"deployedAt\"],\n    \"timestampFieldsParticipateInArtifactDigest\": false,\n    \"artifactDigestScope\": \"web-surface artifactHash excludes deployment manifest timestamps\"\n  },\n  \"sourceSha\": \"...\",\n  \"artifactHash\": \"...\",\n  \"deployTarget\": \"libkungfu-dev-preview\",\n  \"adapter\": \"aws-s3-cloudfront\",\n  \"deployedAt\": \"2026-07-01T00:00:00.000Z\",\n  \"retentionClass\": \"preview-sha-immutable\",\n  \"expiresAt\": \"2026-09-29T00:00:00.000Z\",\n  \"accessControl\": \"none\",\n  \"edgeAuth\": \"none\",\n  \"noindex\": true,\n  \"secretRefs\": [\"AWS_ROLE_ARN\"],\n  \"surfaceBindings\": [\n    {\n      \"surface\": \"hub\",\n      \"channel\": \"preview\",\n      \"alias\": \"sha-abcdef123456\",\n      \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n      \"sourcePath\": \"/\",\n      \"artifactPathPrefix\": \"\",\n      \"viewerPathPrefix\": \"/\",\n      \"directoryIndex\": \"index.html\",\n      \"directoryIndexResolution\": true,\n      \"canonicalUrl\": \"https://libkungfu.dev\",\n      \"bucket\": \"libkungfu-dev-preview\",\n      \"distributionId\": \"E-PREVIEW\",\n      \"originPath\": \"\",\n      \"objectPrefix\": \"sha-abcdef123456\",\n      \"manifestKey\": \".buildchain/deployments/sha-abcdef123456/hub.json\",\n      \"routing\": {\n        \"contract\": \"kungfu-buildchain-web-surface-path-prefix-rewrite\",\n        \"viewerPathPrefix\": \"/\",\n        \"artifactPathPrefix\": \"\",\n        \"objectPrefix\": \"sha-abcdef123456\",\n        \"directoryIndex\": \"index.html\",\n        \"directoryIndexResolution\": true\n      },\n      \"smokeUrls\": [\n        {\n          \"kind\": \"root\",\n          \"requestPath\": \"/\",\n          \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev/\",\n          \"required\": true\n        }\n      ],\n      \"noindex\": true,\n      \"accessControl\": \"none\"\n    }\n  ]\n}\n```\n\nDynamic adapters can also fill `runtimeId`, `configFingerprint`,\n`healthCheck`, `migrationState`, `rollbackPointer`, and\n`rollbackLimitations`. Buildchain records secret reference names only, never\nsecret values.\n\nThe timestamp policy is shared with package site bundles. Public deployment\nmanifests should expose real workflow generation/publication times while\nseparately declaring why the deployed artifact remains reproducible. For\nweb-surface deployment manifests, `artifactHash` is the static site artifact\ndigest and does not include deployment timestamp fields; the manifest itself\nstill records those fields for human and agent audit.\n\n## Deploy Plans\n\nDeploy planning is the default behavior. It plans the adapter steps and writes\nmanifest JSON, but it does not touch AWS, DNS, CloudFront, or deployment\ncredentials.\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-plan \\\n  --cwd fixtures/web-surface-shaped \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --alias sha-aaaaaaaaaaaa\n```\n\nFor manifest-only output:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode manifest \\\n  --cwd fixtures/web-surface-shaped \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --alias pr-123 \\\n  --output .buildchain/web-surface-manifest.json\n```\n\nThe CLI emits GitHub outputs when `GITHUB_OUTPUT` is present:\n\n- `web-surface-channel`\n- `web-surface-alias`\n- `web-surface-url`\n- `web-surface-urls-json`\n- `web-surface-artifact-hash`\n- `web-surface-manifest-json`\n\nThe reusable workflow resolves that same effective channel before running the\ncaller build or verify command. Both steps receive\n`BUILDCHAIN_WEB_SURFACE_CHANNEL` (`preview`, `staging`, or `production`) and\n`BUILDCHAIN_PREVIEW_ALIAS` for previews. Compatibility aliases\n`BUILDCHAIN_SURFACE_CHANNEL` and `BUILDCHAIN_WEB_SURFACE_ALIAS` are also\nprovided. Callers should consume these variables instead of reconstructing the\nrelease-intent state machine from raw GitHub events.\nAn unapproved manual canary resolves to `staging`; a trusted manual dispatch\nwith `production-approved=true` resolves to `production` through the same path.\n\n## Explicit Apply\n\n`deploy-apply` and `cleanup-apply` are explicit execution modes for the\n`aws-s3-cloudfront` static-site adapter. They still default to `--dry-run true`;\nlive AWS mutation requires `--dry-run false`.\n\nDeploy apply syncs the artifact, writes the deployment manifest, and invalidates\nCloudFront when a distribution id is configured:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --channel staging \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --artifact-path dist \\\n  --dry-run false \\\n  --output .buildchain/web-surface-staging-apply.json\n```\n\n### Explicit cache classes\n\nThe S3/CloudFront adapter can declare cache metadata per deploy channel or\nsurface override:\n\n```toml\n[deploy.production]\nadapter = \"aws-s3-cloudfront\"\ncache_control_default = \"public,max-age=3600\"\ncache_control_mutable = \"public,max-age=300,must-revalidate\"\ncache_control_immutable = \"public,max-age=31536000,immutable\"\n```\n\n`cache_control_default` applies to the ordinary artifact sync.\n`cache_control_mutable` is then applied to HTML, JSON, XML, generated directory\nindex aliases, and the deployment manifest. `cache_control_immutable` applies\nto append-only publication roots discovered through the archive policy below.\nMutable metadata updates exclude those append-only roots, so HTML or JSON inside\nan immutable version archive keeps the immutable class.\nThe deploy plan, surface binding, apply operations, and deployment manifest all\nrecord the effective values. Existing consumers that omit these fields retain\ntheir prior upload behavior.\n\nCache metadata complements, rather than replaces, invalidation. Every deploy\nstill records and creates the exact surface wildcard and deployment-manifest\ninvalidation paths.\n\n### Immutable publication paths\n\nWhen a surface artifact contains `manifest.json` with\n`archivePolicy.contract = \"kungfu-buildchain-publication-archive-policy\"`,\nBuildchain treats every declared `publications[].versions[].immutablePath` as\nan append-only publication boundary. This applies identically to preview,\nstaging, and production adapters.\n\nThe adapter derives the protected archive root from those declared version\npaths and applies four ordered safeguards:\n\n1. every local immutable file is checked against an existing S3 object;\n2. missing files are uploaded with `aws s3 sync --no-overwrite` and a SHA-256\n   checksum;\n3. every immutable file is checked again after upload, closing the race between\n   the first check and the no-overwrite transfer;\n4. mutable site content keeps normal `sync --delete` behavior, but every parent\n   or owning surface sync excludes the protected archive root from deletion.\n\nAn existing object with a different SHA-256 digest fails apply before mutable\ncontent is changed. Older objects without a stored S3 SHA-256 checksum are read\nand byte-hashed for compatibility. Directory-index alias writes are skipped\nunder protected roots so they cannot overwrite immutable route objects; viewer\nrequest rewriting remains the directory-index authority.\n\nThe deploy plan and manifest record `immutablePublication`,\n`mutableDeleteExcludes`, and the parent-surface coverage. Apply output records\n`immutablePreservation` plus every pre-check, no-overwrite sync, post-check, and\nmutable sync operation. Health output adds an `__immutable__` check proving that\nthe owning and parent surface syncs carried their required delete exclusions.\nThe runner must provide an AWS CLI version whose `s3 sync` supports\n`--no-overwrite`.\n\nFor multi-surface sites, each surface host is treated as a root-relative view\nof that surface's artifact path prefix. For example, a `buildchain` surface with\n`path = \"/buildchain/\"` and preview URL\n`https://buildchain-pr-29.preview.libkungfu.dev` syncs the artifact subtree\n`dist/buildchain/` to the preview object prefix `pr-29/buildchain`. A viewer\nrequest for `https://buildchain-pr-29.preview.libkungfu.dev/docs/` therefore\nresolves against the artifact's `dist/buildchain/docs/index.html`, not\n`dist/docs/index.html` and not the hub surface root. The deployment manifest\nrecords this as `routing.contract =\n\"kungfu-buildchain-web-surface-path-prefix-rewrite\"` with\n`viewerPathPrefix = \"/\"`, `artifactPathPrefix = \"buildchain\"`, and\n`directoryIndexResolution = true`.\n\nWhen a surface uses an S3 object prefix, directory-index routing must be handled\nat the viewer-request layer. By default, `directory_index_rewrite =\n\"buildchain\"` makes Buildchain install or update one CloudFront Function per\ndistribution before uploading payloads. The function rewrites any request path\nending in `/` to the corresponding `index.html`, so\n`https://buildchain-pr-29.preview.libkungfu.dev/` resolves to\n`pr-29/buildchain/index.html` and\n`https://buildchain-pr-29.preview.libkungfu.dev/docs/` resolves to\n`pr-29/buildchain/docs/index.html`. This keeps multi-host preview roots\ncompatible with S3 REST origins, where copying alias objects such as\n`pr-29/buildchain` or `pr-29/buildchain/` is not a reliable substitute for an\nedge rewrite.\n\nIf the distribution already has a viewer-request function that owns preview\nalias routing and surface-prefix routing, set `directory_index_rewrite =\n\"external\"` on the deploy channel or surface override. In that mode Buildchain\ndoes not create, update, or attach a generic directory-index function. Instead,\nthe deployment manifest records `directoryIndexRewrite = \"external\"` and\n`directoryIndexStrategy = \"external-viewer-request-function\"`, then the normal\nhealth check still verifies every required root and nested surface URL. This is\nthe correct contract for shared preview distributions such as\n`site-libkungfu-dev`, where a generic function cannot replace the existing\nprefix router.\n\nBuildchain still writes directory-index alias objects during apply as\ncompatibility evidence, but root correctness comes from the viewer-request\nrewrite contract, not from extensionless S3 keys. If Buildchain-managed mode\nfinds a distribution with a different viewer-request function, apply fails\nclosed and records that conflict in the apply result instead of silently serving\n403s. If CloudFront rejects `UpdateDistribution` because its optimistic-lock\nETag became stale, Buildchain re-reads the distribution and retries with the\nnew ETag at most twice. A concurrent update that already attached the intended\nfunction is accepted as converged; a different viewer-request function or any\nnon-ETag AWS error still fails immediately. The reusable workflow uploads\n`buildchain-web-surface-*-diagnostics`\nartifacts containing the apply and health JSON so the failing AWS operation or\nHTTP check is visible from the consumer run.\n\nIt can also execute a previously saved deploy plan. In that mode Buildchain\nrecomputes the local artifact hash before running AWS commands and fails closed\nif the artifact no longer matches the saved plan. Before any adapter operation,\nit also checks channel-aware JSON manifests in the artifact: top-level\n`canonicalHost` and declared `pages[].host` facts must belong to the plan's\nsurface hosts. A production plan therefore rejects staging/preview host facts\nbefore AWS apply:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-staging-plan.json \\\n  --dry-run false \\\n  --output .buildchain/web-surface-staging-apply.json\n```\n\nCleanup apply deletes preview content, deletes the preview manifest, and\ninvalidates CloudFront:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --event pull-request-closed \\\n  --pull-number 123 \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --dry-run false \\\n  --output .buildchain/web-surface-cleanup-apply.json\n```\n\nCleanup apply can also execute a saved cleanup plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-cleanup-plan.json \\\n  --dry-run false \\\n  --output .buildchain/web-surface-cleanup-apply.json\n```\n\nApply output records the channel, alias, source SHA, artifact hash, target\nbucket, object prefix, manifest key, all surface URLs, all surface bindings, CDN\ninvalidation paths, actor/run metadata, immutable preservation evidence, and\nevery adapter operation with\n`executed`, `exitCode`, `stdout`, and `stderr`. If an operation fails,\nBuildchain records the failed operation, stops subsequent adapter operations,\nand exits non-zero after writing the result JSON. Buildchain records secret\nreference names only; the runner must provide the AWS CLI and credentials\noutside Buildchain, typically through OIDC and the declared `secret_refs`.\n\n## Production Preflight And Health\n\nProduction promotion is not just `deploy-apply --channel production`. Before a\nlive production apply, the reusable workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode production-preflight \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-production-plan.json \\\n  --execute true \\\n  --output .buildchain/web-surface-production-preflight.json\n```\n\nThe production preflight checks that:\n\n- `channels.production` is canonical and indexable;\n- every surface has concrete production bucket and CloudFront targets;\n- every production surface URL is HTTPS;\n- the production AWS role can inspect the declared bucket and distribution;\n- CloudFront aliases cover every surface host, including product hosts such as\n  `kfd.libkungfu.dev`;\n- DNS resolves for every surface host.\n\nAfter preview, staging, and production apply, the workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode health-check \\\n  --cwd fixtures/web-surface-shaped \\\n  --result .buildchain/web-surface-production-apply.json \\\n  --output .buildchain/web-surface-production-health.json\n```\n\nWhen the apply result includes CloudFront invalidations from the\n`aws-s3-cloudfront` adapter, health check waits for those invalidations to reach\n`Completed` before fetching public smoke URLs. This avoids reporting stale\nCloudFront 403 responses as deployment failures immediately after a successful\nS3 sync and invalidation request.\n\nAfter the invalidation wait, HTTP smoke checks also retry transient 403, 404, and\n5xx responses before recording failure. This keeps the public health signal\nstrict while absorbing short CloudFront edge propagation windows that can remain\nvisible after the invalidation waiter returns. By default, Buildchain attempts\neach HTTP smoke URL 12 times with a 10 second interval. Consumers can override\nthat window with `BUILDCHAIN_WEB_SURFACE_HEALTH_HTTP_RETRY_ATTEMPTS` and\n`BUILDCHAIN_WEB_SURFACE_HEALTH_HTTP_RETRY_INTERVAL_MS` when they need a\nsite-specific health policy.\n\nThe health check fetches every surface root URL and any nested smoke URLs\nrecorded in each surface binding. Nested smoke URLs are derived from nested HTML\nartifact files under the surface path prefix, with directory index resolution\nsuch as `dist/buildchain/docs/index.html` becoming `/docs/` on the buildchain\npreview host. If a surface has no nested HTML route, Buildchain records only\nthe root smoke URL; absence of nested HTML is not a deployment failure. When a\nnested route is present, the check fails closed if a deploy reports success but\nthat child page returns 403 or another unexpected status. Surface root checks\nexpect the apply result to have installed the directory-index rewrite, so a\nmulti-host preview root such as `https://buildchain-pr-29.preview.libkungfu.dev/`\nmust resolve to the surface `index.html`, not the bare prefix directory.\nProduction additionally fails if a response is unreachable, returns an\nunexpected status, or still sends `x-robots-tag: noindex`. The health check also\nverifies that each surface binding recorded a deployment manifest pointer. The\nproduction release passport embeds the deploy plan, apply result, production\npreflight, and health check so a reviewer or agent can audit why the production\nsite changed and whether every declared host and every existing nested route was\nactually covered.\n\nPublic channels can opt into object-level health with\n`deploy.<channel>.health_strategy = \"s3-object\"` when the deployment contract is\nalready covered by S3 manifest/object writes and public edge convergence is not\nthe right CI gate. This is useful for preview distributions whose viewer-request\nrouting is owned by an external CloudFront Function. The channel remains public;\nonly the CI health evidence changes from HTTP fetches to S3 `head-object`\nchecks.\n\nChannels declared with `access_control = \"managed-network\"` use a different\nhealth strategy by default. Buildchain does not require a GitHub-hosted runner\nto fetch a URL that is intentionally reachable only from an approved network.\nInstead, after a live apply the health check uses the deploy role to run S3\n`head-object` checks for each surface manifest and the smoke target object, such\nas the surface `index.html` or a nested `docs/index.html`. The check records\n`healthStrategy = \"s3-object\"` and skips the public HTTP fetch. Dry-run and\nplan-only checks fall back to deployment evidence: each surface must have a\nmanifest key, bucket, object prefix, `sync-static-artifact`, and\n`write-deployment-manifest` evidence, recorded as\n`healthStrategy = \"deployment-evidence\"`. If the workflow is running on a runner\nthat is allowed to reach the managed network, set\n`BUILDCHAIN_WEB_SURFACE_HEALTH_ALLOWED_RUNNER=true` or pass\n`--allowed-managed-network-runner true` to keep the normal HTTP smoke checks.\nSet `BUILDCHAIN_WEB_SURFACE_HEALTH_S3_OBJECTS=false` or pass\n`--managed-network-s3-object-verification false` only when an external channel\npolicy owns managed-network object verification.\n\n## Cleanup Plans\n\nPreview cleanup is an auditable cleanup contract. It can run as a dry-run plan,\nan apply-mode plan, or the explicit `cleanup-apply` executor with preview-only\ncredentials:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-plan \\\n  --cwd fixtures/web-surface-shaped \\\n  --event pull-request-closed \\\n  --pull-number 123 \\\n  --aliases pr-123,sha-abcdef123456\n```\n\nThe plan and apply result keep mutable PR aliases and immutable SHA aliases\ndistinct so a caller can expire them with different retention windows. Closed-PR\ncleanup can derive `pr-N` from `--pull-number`, records the event, source SHA,\nactor, run id, preview bucket/prefix, manifest key, and adapter steps, and is an\nauditable no-op when no aliases are requested.\n\n## Reusable Workflow Shape\n\nBuildchain ships `.github/workflows/.web-surface.yml` for repositories that want\nthe standard PR review and promotion flow without copying bespoke glue:\n\n```yaml\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v3\n    with:\n      build-command: npm run build\n      verify-command: npm run check\n      artifact-path: dist\n```\n\nThe reusable workflow maps GitHub events to Buildchain web-surface semantics:\n\n| Event | Buildchain behavior |\n| --- | --- |\n| `pull_request` opened / synchronized / reopened | validate, build, verify, and plan `preview` for `pr-N` |\n| `pull_request` closed | plan apply-mode cleanup for the `pr-N` preview alias and manifest |\n| `push` to `main` | validate, build, verify, plan and apply `staging` from the merged `main` SHA, then optionally open a production release PR |\n| `push` to `main` from a matching release PR merge | validate the associated release PR, plan `production`, and enter the configured GitHub Environment gate |\n| `workflow_dispatch` with `production-approved = true` | plan `production` and enter the configured GitHub Environment gate |\n\nThe optional `buildchain-ref` input is empty by default. Empty keeps the\nweb-surface run on the stable Buildchain runtime selected by the reusable\nworkflow ref, normally `@v3`. A trusted maintainer can expose a\n`workflow_dispatch` input and pass it through for one-off train validation.\nSee [`runtime-train-validation.md`](runtime-train-validation.md) for the shared\ntrain protocol and notification template:\n\n```yaml\non:\n  workflow_dispatch:\n    inputs:\n      buildchain-ref:\n        description: \"Temporary Buildchain runtime ref for trusted manual validation\"\n        required: false\n        default: \"\"\n\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v3\n    with:\n      buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n      build-command: pnpm run build\n      verify-command: pnpm run check\n      artifact-path: dist\n```\n\nOnly trusted `workflow_dispatch` runs by repository actors with write,\nmaintain, or admin permission may use a non-empty runtime override. Train refs\nsuch as `train/v3/v3.0/site-source-of-truth` are temporary validation refs, not\nstable production dependencies or pending merge targets. They may remain for a\nretention window after release as a fast-use and rollback channel, with old\ntrains handled by periodic Buildchain cleanup. The web-surface deployment\nmanifest records the resolved runtime SHA as `runtimeId` and the stable\nrollback ref as `rollbackPointer`.\n\nThe workflow deliberately plans and emits manifests by default. Live mutation is\nopt-in per channel:\n\n```yaml\npermissions:\n  contents: read\n  id-token: write\n  pull-requests: write\n\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v3\n    with:\n      build-command: pnpm run build\n      verify-command: pnpm run check\n      artifact-path: dist\n      preview-apply: true\n      preview-cleanup-apply: true\n      preview-aws-role-arn: arn:aws:iam::123456789012:role/site-preview-github-actions\n      staging-apply: true\n      staging-aws-role-arn: arn:aws:iam::123456789012:role/site-staging-github-actions\n      production-apply: false\n      production-release-on-main: false\n      production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n      production-environment: production\n      release-feedback-actor-privacy: public\n```\n\nWhen enabled, Buildchain owns the full release apply state machine:\n\n- PR preview deploys run `deploy-apply --dry-run false` with the preview role\n  and update a single idempotent PR comment.\n- Closed PR cleanup runs `cleanup-apply --dry-run false` with the preview role\n  only.\n- Pushes to `main` run staging `deploy-apply --dry-run false` with the staging\n  role, then write a staging release feedback passport artifact and comment the\n  associated merged PR with the staging URL, source SHA, artifact identity, run\n  URL, and failure context when apply did not complete.\n- When `production-release-on-main=true`, successful staging applies open or\n  update a Buildchain-owned release PR from\n  `release/<channel>-<short-sha>` to `main`, unless the current push already\n  came from a matching release PR merge. The release PR contains one empty\n  release-intent commit, carries `production-release-label`, and includes the\n  staging URLs, source SHA, artifact hash, and staging release-passport artifact\n  link in the PR body.\n- Production release PR handoff is permission-aware. Staging apply and staging\n  health remain successful even when the repository or organization has\n  GitHub Actions workflow permissions set to read-only. In that case Buildchain\n  records `release-pr-status=permission-denied`, uploads the release PR handoff\n  summary/body plus staging release passport artifacts, and writes an exact\n  manual `gh pr create` command to the step summary. Set\n  `fail-on-release-pr-error=true` only when PR creation failure should fail the\n  whole workflow.\n- Release pull requests that match the configured production gate get a\n  Buildchain review comment with the staging URL and production target, so the\n  operator can verify staging from the PR page and use merge as the approval\n  action. Consumers do not need to hand-write `gh pr create` or production\n  release-intent glue.\n- `production-apply=true` enables the production capability; it does not request\n  production for every event. Ordinary `main` pushes remain staging-only and\n  can create or update a release PR. Production runs only when the capability\n  is enabled and either:\n  - a `workflow_dispatch` passes `production-approved=true` and the triggering\n    actor currently has `write`, `maintain`, or `admin` permission; or\n  - `production-release-on-main=true` and the `main` push commit is associated\n    with exactly one same-repository, merged release pull request matching\n    `production-release-label` and `production-release-head-prefix`.\n  The production job is then gated by the configured GitHub Environment.\n- Before production artifact download, Buildchain assembles a managed sealed\n  publication capability from the exact source/runtime SHAs, production plan\n  and artifact hash, a qualifying pre-publication controller receipt, the\n  trusted manual or reviewed-release-PR decision, production Environment and\n  AWS role target, an ephemeral-runner receipt, and a fresh nonce. Production\n  revalidates that capability against the downloaded plan before it downloads\n  product bytes. The later AWS OIDC exchange remains the provider's final\n  transaction-time authorization decision and fails closed before deploy apply.\n- The `publication-*-json` inputs are an advanced external-evidence\n  compatibility path, not a prerequisite for the standard release-PR or trusted\n  manual mechanisms. External evidence must now include\n  `publication-gate-aggregate-json`; supplying only a partial set still fails\n  closed.\n- Production apply writes a production release feedback passport artifact and\n  comments the release PR with the production URL, source SHA, artifact\n  identity, run URL, rollback pointer, and failure context when apply did not\n  complete.\n\nThe feedback passport records the release responsibility chain:\n\n- human decision actor;\n- trigger actor;\n- runner/execution actor;\n- OIDC/deploy identity reference;\n- decision type and time;\n- source event, PR number, merge commit, and required gate label/head-prefix.\n\n`release-feedback-actor-privacy` controls actor values in the passport and\ncomments. `public` records GitHub actor names, `redacted` records only the actor\nrole, and `private-ref` records a stable private reference hash without exposing\nthe actor name.\n\nFor release-PR publishing, callers opt in explicitly:\n\n```yaml\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v3\n    with:\n      build-command: npm run build\n      verify-command: npm run check\n      artifact-path: dist\n      production-apply: true\n      production-release-on-main: true\n      production-release-label: buildchain-release\n      production-release-head-prefix: release/\n      production-release-branch-channel: production\n      production-release-pr-mode: auto\n      production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n      production-environment: production\n```\n\nKeep `production-apply` enabled in the caller when the repository supports\nproduction. Buildchain derives whether the current event may use that\ncapability: an ordinary `main` push plans and applies staging, a matching\nreviewed release PR merge authorizes production, and an approved trusted manual\ndispatch authorizes production. Inputs from an untrusted event cannot turn that\ndecision on.\n\n`production-release-pr-mode` controls the post-staging handoff:\n\n| Mode | Behavior |\n| --- | --- |\n| `auto` | Generate release PR facts, create/update the empty release-intent branch and PR, and label it when token permissions allow. This is the default. |\n| `summary-only` | Generate and upload release PR facts, body, passport evidence, and manual command, but do not call the GitHub PR API. |\n| `disabled` | Record a disabled handoff and skip release PR API calls. |\n\nAutomatic release PR creation normally uses the workflow `github.token`.\nConsumers that cannot enable \"GitHub Actions can create and approve pull\nrequests\" globally should prefer the first-class GitHub App path. Pass the App\nclient id as an input and the private key as a reusable workflow secret; Buildchain\ncreates an installation token inside the release PR job and uses it only for the\nrelease-intent branch, PR, and label operations:\n\n```yaml\nwith:\n  production-release-app-client-id: ${{ vars.KUNGFU_RELEASE_APP_CLIENT_ID }}\nsecrets:\n  production-release-app-private-key: ${{ secrets.KUNGFU_RELEASE_APP_PRIVATE_KEY }}\n```\n\nWhen either side of the App configuration is missing, Buildchain does not hide\nthat behind the fallback `github.token`. The handoff JSON and job summary report\n`status: \"app-token-unavailable\"` with an `appTokenStatus` such as\n`missing-client-id`, `missing-private-key`, or `create-failed`, and still include\nthe manual PR creation command. If the repository intentionally uses another\nnarrow token, pass it through `production-release-pr-token`.\n\n`production-release-app-id` remains accepted as a deprecated alias for the input\nname, but the value should be the GitHub App client id. GitHub App numeric App\nIDs and client IDs are distinct, and Buildchain passes the value to\n`actions/create-github-app-token` through its non-deprecated `client-id` input so\nnew runs do not emit the deprecated `app-id` warning.\n\nIf a repository already generates its own narrow token or PAT, it can still pass\nthat through `production-release-pr-token`:\n\n```yaml\nwith:\n  production-release-pr-token: ${{ secrets.BUILDCHAIN_RELEASE_PR_TOKEN }}\n```\n\nToken priority is: generated GitHub App installation token,\n`production-release-pr-token`, then `github.token`.\n\nThe merge button becomes the production approval only for a PR that carries the\nrelease label and comes from the configured source-branch prefix. Ordinary pull\nrequests merged into `main` deploy staging and open a release-intent PR; merging\nthat release PR triggers production. A release PR merge push does not open\nanother release PR.\n\nApply-only inputs are validated before the caller build or verification command\nruns. If the current event would run preview, staging, or production apply,\nmissing role inputs, a production apply without `production-approved=true` on\nmanual dispatch, or a manual actor without repository write authority fail\nimmediately instead of spending the build and plan jobs first.\n\nCallers must grant `id-token: write` for OIDC role assumption. Preview comments\nneed `pull-requests: write`. Automatic release PR creation also needs\n`contents: write`, `pull-requests: write`, and `issues: write` so Buildchain can\ncreate the release branch, write the empty release-intent commit, open or update\nthe PR, and apply the release label. If these permissions are unavailable,\nBuildchain degrades the release handoff instead of marking a successful staging\ndeployment as failed, unless `fail-on-release-pr-error=true`. The AWS roles remain caller-owned and\nshould be scoped by channel: preview can mutate only preview resources, staging\ncan mutate only staging resources, and production can mutate only production\nresources.\n\nApply mode fails closed when the deploy config still contains placeholder AWS\ntargets such as `pending-preview-distribution`. Planning can use placeholders\nfor dry-run-only design work, but live apply requires concrete bucket and\nCloudFront distribution identifiers.\n\n## Site Repository Shape\n\nA site repository can start with:\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[lifecycle.build]\ncommand = \"pnpm run build\"\n\n[lifecycle.verify]\ncommand = \"pnpm run check\"\n```\n\nThen add the channel, deploy, retention, and security declarations shown above.\nThe project may use pnpm, npm, yarn, Vite, Astro, Next static export, Sphinx,\nMkDocs, CMake-generated docs, or another lifecycle command source. Buildchain\nonly needs a deterministic artifact path and the manifest facts.\n\n## Signed bootstrap installer publications\n\nA web-surface artifact that contains `installer-publication.json` opts into the\n`kungfu.bootstrap-installer-publication/v1` seam. During planning, Buildchain\nfails closed unless the manifest binds:\n\n- one signed-channel payload root and exact channel-file digest;\n- one source SHA and Release Passport;\n- unique platform/architecture entries with manifest, artifact, and archive\n  digest roots; and\n- byte-identical friendly and immutable `install.sh` / `install.ps1` assets.\n\nThe resulting `kungfu-buildchain-installer-publication-evidence/v1` object and\nroot are welded into the deployment manifest. This does not make Buildchain the\nproduct installer authority: Kungfu generates the installer from its signed\nrelease channel, while the site owns only routes and presentation.\n\nThe site artifact should also declare the existing\n`kungfu-buildchain-publication-archive-policy` in its root `manifest.json`, with\nthe versioned installer directory as `immutablePath`. Buildchain then performs\npre-upload object digest checks, `--no-overwrite` upload, post-upload checks, and\nexcludes the immutable root from mutable deletion.\n\nLocal verification:\n\n```sh\nnode scripts/installer-publication.mjs \\\n  --manifest dist/installer-publication.json \\\n  --artifact-root dist\n```\n\nAfter preview, staging, or production apply, public read-back verifies exact\nbytes plus route semantics. Friendly routes require a revalidated cache policy\nwith `max-age` no greater than 300 seconds; immutable routes require at least\none year and the `immutable` directive:\n\n```sh\nnode scripts/installer-publication.mjs \\\n  --manifest dist/installer-publication.json \\\n  --public-readback\n```\n\nRedirects are not accepted as successful read-back. The evidence retains\ncontent type, cache control, ETag, object version id when exposed, size, digest,\nURL, channel root, source SHA, and Release Passport coordinates.\n\n## Boundaries\n\nBuildchain only performs live AWS mutations in explicit apply modes with\n`--dry-run false`. Production deploys must still be gated by a human-controlled\nworkflow, release, or GitHub Environment. DNS changes, staging auth\nimplementation, CloudFront distribution creation, and credential provisioning\nremain explicitly authorized infrastructure operations outside the web-surface\nartifact apply contract."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: web-surface-deployments\ndoc_type: contract\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-07-30\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-07-30\n  invisible_context_boundary: No credentials, private logs, or unpublished deployment values are included.\n---\n\n# Web-Surface Deployment Contract\n\nBuildchain supports `project.type = \"web-surface\"` for repositories that publish\nsites, docs, product pages, operator consoles, or browser apps. These projects\nneed auditable deployment semantics, but they are not package release lines and\nshould not be forced into `dev/alpha/release` version-state automation.\n\nThe release object for a web surface is:\n\n```text\nsource commit + build artifact + deploy target + channel + deployment manifest\n```\n\nThis keeps the evidence chain clear:\n\n- the source SHA explains what code was built;\n- the artifact hash explains exactly what was deployed;\n- the channel explains who can see it and whether it is promotable;\n- the deploy target and adapter explain where it would be published;\n- the deployment manifest records retention, rollback, security, and secret\n  reference metadata.\n\n## Configuration\n\n`.buildchain/buildchain.toml` is the source of truth. Web-surface projects must declare\npreview, staging, and production channels plus a deploy adapter for each.\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[channels.preview]\nurl_pattern = \"https://{alias}.preview.kungfu.tech\"\nvisibility = \"ephemeral\"\nrequires_auth = false\nnoindex = true\n\n[channels.staging]\nurl = \"https://staging.kungfu.tech\"\nvisibility = \"protected\"\naccess_control = \"managed-network\"\nedge_auth = \"none\"\nnoindex = true\npromotable = true\n\n[channels.production]\nurl = \"https://kungfu.tech\"\nvisibility = \"public\"\ncanonical = true\nnoindex = false\n\n[deploy.preview]\nadapter = \"aws-s3-cloudfront\"\nbucket = \"kungfu-tech-preview\"\ncloudfront_distribution = \"E-PREVIEW\"\nartifact_path = \"dist\"\nsecret_refs = [\"AWS_ROLE_ARN\"]\n# Optional. Defaults to \"buildchain\".\n# Use \"external\" when an existing viewer-request CloudFront Function already\n# owns preview alias, surface-prefix, and directory-index routing.\ndirectory_index_rewrite = \"buildchain\"\n# Optional. Defaults to HTTP for public channels and S3 object evidence for\n# managed-network channels. Use \"s3-object\" when CI should verify uploaded\n# objects and manifests instead of waiting for public edge convergence.\nhealth_strategy = \"http\"\n```\n\n### Multi-Surface Host Mapping\n\nSome site repositories publish more than one first-class web surface from the\nsame artifact. For example, `site-libkungfu-dev` has a hub plus separate\nhostnames for core, Buildchain, and Kung Fu Decisions. These are not just\nnavigation paths; staging, production preflight, and post-deploy health checks\nmust verify host-level behavior for each surface.\n\nDeclare named surfaces with per-channel URLs:\n\n```toml\n[surfaces.hub]\npath = \"/\"\nproduction_url = \"https://libkungfu.dev\"\nstaging_url = \"https://staging.libkungfu.dev\"\npreview_url_pattern = \"https://{alias}.preview.libkungfu.dev\"\n\n[surfaces.core]\npath = \"/core/\"\nproduction_url = \"https://core.libkungfu.dev\"\nstaging_url = \"https://core.staging.libkungfu.dev\"\npreview_url_pattern = \"https://core-{alias}.preview.libkungfu.dev\"\n\n[surfaces.buildchain]\npath = \"/buildchain/\"\nproduction_url = \"https://buildchain.libkungfu.dev\"\nstaging_url = \"https://buildchain.staging.libkungfu.dev\"\npreview_url_pattern = \"https://buildchain-{alias}.preview.libkungfu.dev\"\n\n[surfaces.kfd]\npath = \"/kfd/\"\nproduction_url = \"https://kfd.libkungfu.dev\"\nstaging_url = \"https://kfd.staging.libkungfu.dev\"\npreview_url_pattern = \"https://kfd-{alias}.preview.libkungfu.dev\"\n```\n\nBuildchain resolves every `(channel, surface)` pair. A preview alias such as\n`pr-12` becomes:\n\n```text\nhub:        https://pr-12.preview.libkungfu.dev\ncore:       https://core-pr-12.preview.libkungfu.dev\nbuildchain: https://buildchain-pr-12.preview.libkungfu.dev\nkfd:        https://kfd-pr-12.preview.libkungfu.dev\n```\n\nWhen `surfaces` is omitted, Buildchain preserves the legacy single-surface\ncontract by creating an implicit `default` surface from the channel URL. When a\nsurface is intentionally path-only, declare it explicitly:\n\n```toml\n[surfaces.docs]\npath = \"/docs/\"\npath_only = true\n```\n\n`path_only = true` is an exception, not the default. Without it, every named\nsurface must declare `preview_url_pattern`, `staging_url`, and\n`production_url`. This makes staging/production mismatches fail during\nvalidation instead of becoming invisible deploy drift.\n\nAdapter strategy remains explicit. The default `aws-s3-cloudfront` plan uses the\nchannel deploy target for every surface, and each binding records its own\nbucket, distribution id, object prefix, manifest key, source path, and URL. A\nchannel can override target details per surface:\n\n```toml\n[deploy.staging.surfaces.core]\nbucket = \"libkungfu-dev-core-staging\"\ncloudfront_distribution = \"E-CORE-STAGING\"\norigin_path = \"/core\"\n```\n\nBuildchain validates these hard constraints:\n\n- `channels.preview.url_pattern` is required and must contain the alias shape\n  used by preview deployments.\n- `channels.staging.access_control` must protect staging. Supported modes are\n  `managed-network`, `edge-basic-auth`, `oidc`, and `app-auth`.\n- `channels.staging.edge_auth` records whether the edge layer owns auth. Use\n  `edge_auth = \"none\"` when staging is protected by managed network controls\n  such as WAF/IP allowlists or VPN access.\n- `channels.staging.noindex = true` is required.\n- `channels.production.url` is required.\n- deploy adapters must be declared per channel.\n- named surfaces must declare first-class URLs for every channel unless\n  `path_only = true` is explicitly set.\n- secret material must be declared as reference names, such as\n  `secret_refs = [\"AWS_ROLE_ARN\"]`; inline secret-like deploy keys are rejected.\n\n### Floating Runtime Contract Lock\n\nWeb-surface repositories can consume the stable Buildchain workflow shell with a\nfloating ref, such as:\n\n```yaml\njobs:\n  web:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v3\n    with:\n      buildchain-contract-lock-path: .buildchain/contract-lock.json\n      buildchain-contract-compatibility-policy: major-compatible\n      buildchain-contract-drift-issue-mode: compatible-and-breaking\n      build-command: pnpm build\n      artifact-path: dist\n```\n\nThe caller repository commits `.buildchain/contract-lock.json` after reviewing an\naccepted Buildchain runtime SHA and contract digest. The reusable workflow then\nresolves the floating runtime to an immutable SHA, checks the lock before the\ncaller build command, and applies these rules:\n\n- unchanged lock: continue without feedback;\n- compatible drift: continue, write the drift summary, and open or update a\n  caller-repository issue when permissions allow;\n- breaking drift: fail closed before rendering, deployment planning, deploy\n  apply, or release publication.\n\nThe caller no longer needs to run `scripts/buildchain-contract-lock.mjs` inside\nits own build command. That check belongs to Buildchain because the actual\ncontract world is stored in the Buildchain runtime ref being used.\n\nSupported adapter names are:\n\n| Adapter | Initial use |\n| --- | --- |\n| `aws-s3-cloudfront` | Static site artifact sync plus CDN invalidation plan |\n| `aws-elastic-beanstalk` | Future dynamic app environment adapter |\n| `aws-ecs-service` | Future dynamic service adapter |\n\nThe channel ontology is independent of the adapter. A future dynamic staging\nenvironment still remains `channel = \"staging\"` with protected/noindex/security\nrequirements.\n\n## Preview Aliases\n\nPreview uses subdomains, not path prefixes:\n\n```text\nhttps://pr-123.preview.kungfu.tech\nhttps://sha-abcdef123456.preview.kungfu.tech\n```\n\nAlias semantics are explicit:\n\n| Alias | Meaning | Mutable | Retention |\n| --- | --- | --- | --- |\n| `pr-123` | Current preview for a pull request | yes | short-lived |\n| `sha-abcdef123456` | Immutable preview for one source SHA | no | longer-lived |\n\nThis allows PR comments to stay stable while preserving immutable evidence for a\nspecific source commit.\n\n## Deployment Manifest\n\nBuildchain emits a manifest with the deployment facts that matter for audit and\nrollback:\n\n```json\n{\n  \"schemaVersion\": 1,\n  \"contract\": \"kungfu-buildchain-web-surface-deployment\",\n  \"site\": \"libkungfu-dev\",\n  \"channel\": \"preview\",\n  \"alias\": \"sha-abcdef123456\",\n  \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n  \"generatedAt\": \"2026-07-01T00:00:00.000Z\",\n  \"publishedAt\": \"2026-07-01T00:00:00.000Z\",\n  \"reproducible\": true,\n  \"timestampPolicy\": \"ci-injected\",\n  \"deterministicInputs\": [\n    \"web-surface artifact content\",\n    \"buildchain.toml web-surface channels/deploy/surfaces\",\n    \"sourceSha\",\n    \"artifactHash\",\n    \"deployment channel\",\n    \"deployment alias\"\n  ],\n  \"sourceRevision\": \"...\",\n  \"timestampPolicyDetails\": {\n    \"contract\": \"kungfu-buildchain-surface-timestamp-policy\",\n    \"timestampFields\": [\"generatedAt\", \"publishedAt\", \"deployedAt\"],\n    \"timestampFieldsParticipateInArtifactDigest\": false,\n    \"artifactDigestScope\": \"web-surface artifactHash excludes deployment manifest timestamps\"\n  },\n  \"sourceSha\": \"...\",\n  \"artifactHash\": \"...\",\n  \"deployTarget\": \"libkungfu-dev-preview\",\n  \"adapter\": \"aws-s3-cloudfront\",\n  \"deployedAt\": \"2026-07-01T00:00:00.000Z\",\n  \"retentionClass\": \"preview-sha-immutable\",\n  \"expiresAt\": \"2026-09-29T00:00:00.000Z\",\n  \"accessControl\": \"none\",\n  \"edgeAuth\": \"none\",\n  \"noindex\": true,\n  \"secretRefs\": [\"AWS_ROLE_ARN\"],\n  \"surfaceBindings\": [\n    {\n      \"surface\": \"hub\",\n      \"channel\": \"preview\",\n      \"alias\": \"sha-abcdef123456\",\n      \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev\",\n      \"sourcePath\": \"/\",\n      \"artifactPathPrefix\": \"\",\n      \"viewerPathPrefix\": \"/\",\n      \"directoryIndex\": \"index.html\",\n      \"directoryIndexResolution\": true,\n      \"canonicalUrl\": \"https://libkungfu.dev\",\n      \"bucket\": \"libkungfu-dev-preview\",\n      \"distributionId\": \"E-PREVIEW\",\n      \"originPath\": \"\",\n      \"objectPrefix\": \"sha-abcdef123456\",\n      \"manifestKey\": \".buildchain/deployments/sha-abcdef123456/hub.json\",\n      \"routing\": {\n        \"contract\": \"kungfu-buildchain-web-surface-path-prefix-rewrite\",\n        \"viewerPathPrefix\": \"/\",\n        \"artifactPathPrefix\": \"\",\n        \"objectPrefix\": \"sha-abcdef123456\",\n        \"directoryIndex\": \"index.html\",\n        \"directoryIndexResolution\": true\n      },\n      \"smokeUrls\": [\n        {\n          \"kind\": \"root\",\n          \"requestPath\": \"/\",\n          \"url\": \"https://sha-abcdef123456.preview.libkungfu.dev/\",\n          \"required\": true\n        }\n      ],\n      \"noindex\": true,\n      \"accessControl\": \"none\"\n    }\n  ]\n}\n```\n\nDynamic adapters can also fill `runtimeId`, `configFingerprint`,\n`healthCheck`, `migrationState`, `rollbackPointer`, and\n`rollbackLimitations`. Buildchain records secret reference names only, never\nsecret values.\n\nThe timestamp policy is shared with package site bundles. Public deployment\nmanifests should expose real workflow generation/publication times while\nseparately declaring why the deployed artifact remains reproducible. For\nweb-surface deployment manifests, `artifactHash` is the static site artifact\ndigest and does not include deployment timestamp fields; the manifest itself\nstill records those fields for human and agent audit.\n\n## Deploy Plans\n\nDeploy planning is the default behavior. It plans the adapter steps and writes\nmanifest JSON, but it does not touch AWS, DNS, CloudFront, or deployment\ncredentials.\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-plan \\\n  --cwd fixtures/web-surface-shaped \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --alias sha-aaaaaaaaaaaa\n```\n\nFor manifest-only output:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode manifest \\\n  --cwd fixtures/web-surface-shaped \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --alias pr-123 \\\n  --output .buildchain/web-surface-manifest.json\n```\n\nThe CLI emits GitHub outputs when `GITHUB_OUTPUT` is present:\n\n- `web-surface-channel`\n- `web-surface-alias`\n- `web-surface-url`\n- `web-surface-urls-json`\n- `web-surface-artifact-hash`\n- `web-surface-manifest-json`\n\nThe reusable workflow resolves that same effective channel before running the\ncaller build or verify command. Both steps receive\n`BUILDCHAIN_WEB_SURFACE_CHANNEL` (`preview`, `staging`, or `production`) and\n`BUILDCHAIN_PREVIEW_ALIAS` for previews. Compatibility aliases\n`BUILDCHAIN_SURFACE_CHANNEL` and `BUILDCHAIN_WEB_SURFACE_ALIAS` are also\nprovided. Callers should consume these variables instead of reconstructing the\nrelease-intent state machine from raw GitHub events.\nAn unapproved manual canary resolves to `staging`; a trusted manual dispatch\nwith `production-approved=true` resolves to `production` through the same path.\n\n## Explicit Apply\n\n`deploy-apply` and `cleanup-apply` are explicit execution modes for the\n`aws-s3-cloudfront` static-site adapter. They still default to `--dry-run true`;\nlive AWS mutation requires `--dry-run false`.\n\nDeploy apply syncs the artifact, writes the deployment manifest, and invalidates\nCloudFront when a distribution id is configured:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --channel staging \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --artifact-path dist \\\n  --dry-run false \\\n  --output .buildchain/web-surface-staging-apply.json\n```\n\n### Explicit cache classes\n\nThe S3/CloudFront adapter can declare cache metadata per deploy channel or\nsurface override:\n\n```toml\n[deploy.production]\nadapter = \"aws-s3-cloudfront\"\ncache_control_default = \"public,max-age=3600\"\ncache_control_mutable = \"public,max-age=300,must-revalidate\"\ncache_control_immutable = \"public,max-age=31536000,immutable\"\n```\n\n`cache_control_default` applies to the ordinary artifact sync.\n`cache_control_mutable` is then applied to HTML, JSON, XML, generated directory\nindex aliases, and the deployment manifest. `cache_control_immutable` applies\nto append-only publication roots discovered through the archive policy below.\nMutable metadata updates exclude those append-only roots, so HTML or JSON inside\nan immutable version archive keeps the immutable class.\nThe deploy plan, surface binding, apply operations, and deployment manifest all\nrecord the effective values. Existing consumers that omit these fields retain\ntheir prior upload behavior.\n\nCache metadata complements, rather than replaces, invalidation. Every deploy\nstill records and creates the exact surface wildcard and deployment-manifest\ninvalidation paths.\n\n### Immutable publication paths\n\nWhen a surface artifact contains `manifest.json` with\n`archivePolicy.contract = \"kungfu-buildchain-publication-archive-policy\"`,\nBuildchain treats every declared `publications[].versions[].immutablePath` as\nan append-only publication boundary. This applies identically to preview,\nstaging, and production adapters.\n\nThe adapter derives the protected archive root from those declared version\npaths and applies four ordered safeguards:\n\n1. every local immutable file is checked against an existing S3 object;\n2. missing files are uploaded with `aws s3 sync --no-overwrite` and a SHA-256\n   checksum;\n3. every immutable file is checked again after upload, closing the race between\n   the first check and the no-overwrite transfer;\n4. mutable site content keeps normal `sync --delete` behavior, but every parent\n   or owning surface sync excludes the protected archive root from deletion.\n\nAn existing object with a different SHA-256 digest fails apply before mutable\ncontent is changed. Older objects without a stored S3 SHA-256 checksum are read\nand byte-hashed for compatibility. Directory-index alias writes are skipped\nunder protected roots so they cannot overwrite immutable route objects; viewer\nrequest rewriting remains the directory-index authority.\n\nThe deploy plan and manifest record `immutablePublication`,\n`mutableDeleteExcludes`, and the parent-surface coverage. Apply output records\n`immutablePreservation` plus every pre-check, no-overwrite sync, post-check, and\nmutable sync operation. Health output adds an `__immutable__` check proving that\nthe owning and parent surface syncs carried their required delete exclusions.\nThe runner must provide an AWS CLI version whose `s3 sync` supports\n`--no-overwrite`.\n\n### Qualified publication package-pin fast path\n\nA consumer may narrow one deployment to the exact paper version introduced by\na package-pin-only PR. The artifact root `manifest.json` must carry a\nconsumer-owned qualification envelope:\n\n```json\n{\n  \"publicationFastPath\": {\n    \"contract\": \"kungfu-buildchain-publication-package-pin-fast-path\",\n    \"mode\": \"package-pin-only\",\n    \"targetSurface\": \"papers\",\n    \"qualificationRoot\": \"sha256:...\",\n    \"immutablePrefixes\": [\n      \"archive/observer-declared-timelines/v0.1.0-alpha.10\"\n    ],\n    \"mutableFiles\": [\n      \"archive/index.html\",\n      \"index.html\",\n      \"manifest.json\",\n      \"observer-declared-timelines/index.html\",\n      \"observer-declared-timelines/latest/index.html\",\n      \"registry.json\"\n    ],\n    \"invalidationPaths\": [\n      \"/\",\n      \"/archive/\",\n      \"/archive/observer-declared-timelines/v0.1.0-alpha.10*\",\n      \"/observer-declared-timelines/\",\n      \"/observer-declared-timelines/latest/\",\n      \"/manifest.json\",\n      \"/registry.json\"\n    ]\n  }\n}\n```\n\nBuildchain validates that the target surface exists, every immutable prefix is\ndeclared by that surface's archive manifest, every mutable file exists outside\nthose prefixes, and the qualification root is exact. A qualified plan:\n\n- selects only `targetSurface`;\n- verifies/uploads only the declared immutable prefixes with the normal\n  no-overwrite digest safeguards;\n- copies only the declared mutable files;\n- skips full `sync --delete` and directory-index alias writes;\n- invalidates only the declared viewer paths plus the deployment manifest.\n\nAny missing, malformed, or unqualified envelope keeps the normal full-surface\nplan. The fast path narrows bytes; it does not weaken channel controls.\n`package-published`, `alpha-complete`, `staging-visible`, and\n`production-visible` remain separate facts, and a package qualification never\nauthorizes production by itself.\n\nPublication manifests may retain release history without rematerializing every\nhistorical package into the current site artifact. When at least one version\ndeclares `immutableIndex`, Buildchain treats that field as the materialization\nenvelope: all declared version prefixes remain protected from deletion, while\nonly prefixes with `immutableIndex` must exist locally and are eligible for\nupload. Manifests without the envelope retain the legacy rule that every\ndeclared prefix must exist.\n\nFor multi-surface sites, each surface host is treated as a root-relative view\nof that surface's artifact path prefix. For example, a `buildchain` surface with\n`path = \"/buildchain/\"` and preview URL\n`https://buildchain-pr-29.preview.libkungfu.dev` syncs the artifact subtree\n`dist/buildchain/` to the preview object prefix `pr-29/buildchain`. A viewer\nrequest for `https://buildchain-pr-29.preview.libkungfu.dev/docs/` therefore\nresolves against the artifact's `dist/buildchain/docs/index.html`, not\n`dist/docs/index.html` and not the hub surface root. The deployment manifest\nrecords this as `routing.contract =\n\"kungfu-buildchain-web-surface-path-prefix-rewrite\"` with\n`viewerPathPrefix = \"/\"`, `artifactPathPrefix = \"buildchain\"`, and\n`directoryIndexResolution = true`.\n\nWhen a surface uses an S3 object prefix, directory-index routing must be handled\nat the viewer-request layer. By default, `directory_index_rewrite =\n\"buildchain\"` makes Buildchain install or update one CloudFront Function per\ndistribution before uploading payloads. The function rewrites any request path\nending in `/` to the corresponding `index.html`, so\n`https://buildchain-pr-29.preview.libkungfu.dev/` resolves to\n`pr-29/buildchain/index.html` and\n`https://buildchain-pr-29.preview.libkungfu.dev/docs/` resolves to\n`pr-29/buildchain/docs/index.html`. This keeps multi-host preview roots\ncompatible with S3 REST origins, where copying alias objects such as\n`pr-29/buildchain` or `pr-29/buildchain/` is not a reliable substitute for an\nedge rewrite.\n\nIf the distribution already has a viewer-request function that owns preview\nalias routing and surface-prefix routing, set `directory_index_rewrite =\n\"external\"` on the deploy channel or surface override. In that mode Buildchain\ndoes not create, update, or attach a generic directory-index function. Instead,\nthe deployment manifest records `directoryIndexRewrite = \"external\"` and\n`directoryIndexStrategy = \"external-viewer-request-function\"`, then the normal\nhealth check still verifies every required root and nested surface URL. This is\nthe correct contract for shared preview distributions such as\n`site-libkungfu-dev`, where a generic function cannot replace the existing\nprefix router.\n\nBuildchain still writes directory-index alias objects during apply as\ncompatibility evidence, but root correctness comes from the viewer-request\nrewrite contract, not from extensionless S3 keys. If Buildchain-managed mode\nfinds a distribution with a different viewer-request function, apply fails\nclosed and records that conflict in the apply result instead of silently serving\n403s. If CloudFront rejects `UpdateDistribution` because its optimistic-lock\nETag became stale, Buildchain re-reads the distribution and retries with the\nnew ETag at most twice. A concurrent update that already attached the intended\nfunction is accepted as converged; a different viewer-request function or any\nnon-ETag AWS error still fails immediately. The reusable workflow uploads\n`buildchain-web-surface-*-diagnostics`\nartifacts containing the apply and health JSON so the failing AWS operation or\nHTTP check is visible from the consumer run.\n\nIt can also execute a previously saved deploy plan. In that mode Buildchain\nrecomputes the local artifact hash before running AWS commands and fails closed\nif the artifact no longer matches the saved plan. Before any adapter operation,\nit also checks channel-aware JSON manifests in the artifact: top-level\n`canonicalHost` and declared `pages[].host` facts must belong to the plan's\nsurface hosts. A production plan therefore rejects staging/preview host facts\nbefore AWS apply:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode deploy-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-staging-plan.json \\\n  --dry-run false \\\n  --output .buildchain/web-surface-staging-apply.json\n```\n\nCleanup apply deletes preview content, deletes the preview manifest, and\ninvalidates CloudFront:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --event pull-request-closed \\\n  --pull-number 123 \\\n  --source-sha aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa \\\n  --dry-run false \\\n  --output .buildchain/web-surface-cleanup-apply.json\n```\n\nCleanup apply can also execute a saved cleanup plan:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-apply \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-cleanup-plan.json \\\n  --dry-run false \\\n  --output .buildchain/web-surface-cleanup-apply.json\n```\n\nApply output records the channel, alias, source SHA, artifact hash, target\nbucket, object prefix, manifest key, all surface URLs, all surface bindings, CDN\ninvalidation paths, actor/run metadata, immutable preservation evidence, and\nevery adapter operation with\n`executed`, `exitCode`, `stdout`, and `stderr`. If an operation fails,\nBuildchain records the failed operation, stops subsequent adapter operations,\nand exits non-zero after writing the result JSON. Buildchain records secret\nreference names only; the runner must provide the AWS CLI and credentials\noutside Buildchain, typically through OIDC and the declared `secret_refs`.\n\n## Production Preflight And Health\n\nProduction promotion is not just `deploy-apply --channel production`. Before a\nlive production apply, the reusable workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode production-preflight \\\n  --cwd fixtures/web-surface-shaped \\\n  --plan .buildchain/web-surface-production-plan.json \\\n  --execute true \\\n  --output .buildchain/web-surface-production-preflight.json\n```\n\nThe production preflight checks that:\n\n- `channels.production` is canonical and indexable;\n- every surface has concrete production bucket and CloudFront targets;\n- every production surface URL is HTTPS;\n- the production AWS role can inspect the declared bucket and distribution;\n- CloudFront aliases cover every surface host, including product hosts such as\n  `kfd.libkungfu.dev`;\n- DNS resolves for every surface host.\n\nAfter preview, staging, and production apply, the workflow runs:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode health-check \\\n  --cwd fixtures/web-surface-shaped \\\n  --result .buildchain/web-surface-production-apply.json \\\n  --output .buildchain/web-surface-production-health.json\n```\n\nWhen the apply result includes CloudFront invalidations from the\n`aws-s3-cloudfront` adapter, health check waits for those invalidations to reach\n`Completed` before fetching public smoke URLs. This avoids reporting stale\nCloudFront 403 responses as deployment failures immediately after a successful\nS3 sync and invalidation request.\n\nAfter the invalidation wait, HTTP smoke checks also retry transient 403, 404, and\n5xx responses before recording failure. This keeps the public health signal\nstrict while absorbing short CloudFront edge propagation windows that can remain\nvisible after the invalidation waiter returns. By default, Buildchain attempts\neach HTTP smoke URL 12 times with a 10 second interval. Consumers can override\nthat window with `BUILDCHAIN_WEB_SURFACE_HEALTH_HTTP_RETRY_ATTEMPTS` and\n`BUILDCHAIN_WEB_SURFACE_HEALTH_HTTP_RETRY_INTERVAL_MS` when they need a\nsite-specific health policy.\n\nThe health check fetches every surface root URL and any nested smoke URLs\nrecorded in each surface binding. Nested smoke URLs are derived from nested HTML\nartifact files under the surface path prefix, with directory index resolution\nsuch as `dist/buildchain/docs/index.html` becoming `/docs/` on the buildchain\npreview host. If a surface has no nested HTML route, Buildchain records only\nthe root smoke URL; absence of nested HTML is not a deployment failure. When a\nnested route is present, the check fails closed if a deploy reports success but\nthat child page returns 403 or another unexpected status. Surface root checks\nexpect the apply result to have installed the directory-index rewrite, so a\nmulti-host preview root such as `https://buildchain-pr-29.preview.libkungfu.dev/`\nmust resolve to the surface `index.html`, not the bare prefix directory.\nProduction additionally fails if a response is unreachable, returns an\nunexpected status, or still sends `x-robots-tag: noindex`. The health check also\nverifies that each surface binding recorded a deployment manifest pointer. The\nproduction release passport embeds the deploy plan, apply result, production\npreflight, and health check so a reviewer or agent can audit why the production\nsite changed and whether every declared host and every existing nested route was\nactually covered.\n\nPublic channels can opt into object-level health with\n`deploy.<channel>.health_strategy = \"s3-object\"` when the deployment contract is\nalready covered by S3 manifest/object writes and public edge convergence is not\nthe right CI gate. This is useful for preview distributions whose viewer-request\nrouting is owned by an external CloudFront Function. The channel remains public;\nonly the CI health evidence changes from HTTP fetches to S3 `head-object`\nchecks.\n\nChannels declared with `access_control = \"managed-network\"` use a different\nhealth strategy by default. Buildchain does not require a GitHub-hosted runner\nto fetch a URL that is intentionally reachable only from an approved network.\nInstead, after a live apply the health check uses the deploy role to run S3\n`head-object` checks for each surface manifest and the smoke target object, such\nas the surface `index.html` or a nested `docs/index.html`. The check records\n`healthStrategy = \"s3-object\"` and skips the public HTTP fetch. Dry-run and\nplan-only checks fall back to deployment evidence: each surface must have a\nmanifest key, bucket, object prefix, `sync-static-artifact`, and\n`write-deployment-manifest` evidence, recorded as\n`healthStrategy = \"deployment-evidence\"`. If the workflow is running on a runner\nthat is allowed to reach the managed network, set\n`BUILDCHAIN_WEB_SURFACE_HEALTH_ALLOWED_RUNNER=true` or pass\n`--allowed-managed-network-runner true` to keep the normal HTTP smoke checks.\nSet `BUILDCHAIN_WEB_SURFACE_HEALTH_S3_OBJECTS=false` or pass\n`--managed-network-s3-object-verification false` only when an external channel\npolicy owns managed-network object verification.\n\n## Cleanup Plans\n\nPreview cleanup is an auditable cleanup contract. It can run as a dry-run plan,\nan apply-mode plan, or the explicit `cleanup-apply` executor with preview-only\ncredentials:\n\n```bash\nnode scripts/web-surface.mjs \\\n  --mode cleanup-plan \\\n  --cwd fixtures/web-surface-shaped \\\n  --event pull-request-closed \\\n  --pull-number 123 \\\n  --aliases pr-123,sha-abcdef123456\n```\n\nThe plan and apply result keep mutable PR aliases and immutable SHA aliases\ndistinct so a caller can expire them with different retention windows. Closed-PR\ncleanup can derive `pr-N` from `--pull-number`, records the event, source SHA,\nactor, run id, preview bucket/prefix, manifest key, and adapter steps, and is an\nauditable no-op when no aliases are requested.\n\n## Reusable Workflow Shape\n\nBuildchain ships `.github/workflows/.web-surface.yml` for repositories that want\nthe standard PR review and promotion flow without copying bespoke glue:\n\n```yaml\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v3\n    with:\n      build-command: npm run build\n      verify-command: npm run check\n      artifact-path: dist\n```\n\nThe reusable workflow maps GitHub events to Buildchain web-surface semantics:\n\n| Event | Buildchain behavior |\n| --- | --- |\n| `pull_request` opened / synchronized / reopened | validate, build, verify, and plan `preview` for `pr-N` |\n| `pull_request` closed | plan apply-mode cleanup for the `pr-N` preview alias and manifest |\n| `pull_request` closed for a matching release PR | verify the release intent and exact workflow-shell runtime, then wait for the protected `main` push; do not plan or apply production from `refs/pull/*/merge` |\n| `push` to `main` | validate, build, verify, plan and apply `staging` from the merged `main` SHA, then optionally open a production release PR |\n| `push` to `main` from a matching release PR merge | validate the associated release PR, plan `production`, and enter the configured GitHub Environment gate from the protected mainline ref |\n| `workflow_dispatch` with `production-approved = true` | plan `production` and enter the configured GitHub Environment gate |\n\nThe optional `buildchain-ref` input is empty by default. Empty keeps the\nweb-surface run on the stable Buildchain runtime selected by the reusable\nworkflow ref, normally `@v3`. A trusted maintainer can expose a\n`workflow_dispatch` input and pass it through for one-off train validation.\nSee [`runtime-train-validation.md`](runtime-train-validation.md) for the shared\ntrain protocol and notification template:\n\n```yaml\non:\n  workflow_dispatch:\n    inputs:\n      buildchain-ref:\n        description: \"Temporary Buildchain runtime ref for trusted manual validation\"\n        required: false\n        default: \"\"\n\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v3\n    with:\n      buildchain-ref: ${{ inputs.buildchain-ref || '' }}\n      build-command: pnpm run build\n      verify-command: pnpm run check\n      artifact-path: dist\n```\n\nOnly trusted `workflow_dispatch` runs by repository actors with write,\nmaintain, or admin permission may use a non-empty runtime override. Train refs\nsuch as `train/v3/v3.0/site-source-of-truth` are temporary validation refs, not\nstable production dependencies or pending merge targets. They may remain for a\nretention window after release as a fast-use and rollback channel, with old\ntrains handled by periodic Buildchain cleanup. The web-surface deployment\nmanifest records the resolved runtime SHA as `runtimeId` and the stable\nrollback ref as `rollbackPointer`.\n\nThe workflow deliberately plans and emits manifests by default. Live mutation is\nopt-in per channel:\n\n```yaml\npermissions:\n  contents: read\n  id-token: write\n  pull-requests: write\n\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v3\n    with:\n      build-command: pnpm run build\n      verify-command: pnpm run check\n      artifact-path: dist\n      preview-apply: true\n      preview-cleanup-apply: true\n      preview-aws-role-arn: arn:aws:iam::123456789012:role/site-preview-github-actions\n      staging-apply: true\n      staging-aws-role-arn: arn:aws:iam::123456789012:role/site-staging-github-actions\n      production-apply: false\n      production-release-on-main: false\n      production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n      production-environment: production\n      release-feedback-actor-privacy: public\n```\n\nWhen enabled, Buildchain owns the full release apply state machine:\n\n- PR preview deploys run `deploy-apply --dry-run false` with the preview role\n  and update a single idempotent PR comment.\n- Closed PR cleanup runs `cleanup-apply --dry-run false` with the preview role\n  only.\n- Pushes to `main` run staging `deploy-apply --dry-run false` with the staging\n  role, then write a staging release feedback passport artifact and comment the\n  associated merged PR with the staging URL, source SHA, artifact identity, run\n  URL, and failure context when apply did not complete.\n- When `production-release-on-main=true`, successful staging applies open or\n  update a Buildchain-owned release PR from\n  `release/<channel>-<short-sha>` to `main`, unless the current push already\n  came from a matching release PR merge. The release PR contains one empty\n  release-intent commit, carries `production-release-label`, and includes the\n  staging URLs, source SHA, artifact hash, and staging release-passport artifact\n  link in the PR body.\n- Production release PR handoff is permission-aware. Staging apply and staging\n  health remain successful even when the repository or organization has\n  GitHub Actions workflow permissions set to read-only. In that case Buildchain\n  records `release-pr-status=permission-denied`, uploads the release PR handoff\n  summary/body plus staging release passport artifacts, and writes an exact\n  manual `gh pr create` command to the step summary. Set\n  `fail-on-release-pr-error=true` only when PR creation failure should fail the\n  whole workflow.\n- Release pull requests that match the configured production gate get a\n  Buildchain review comment with the staging URL and production target, so the\n  operator can verify staging from the PR page and use merge as the approval\n  action. Consumers do not need to hand-write `gh pr create` or production\n  release-intent glue.\n- `production-apply=true` enables the production capability; it does not request\n  production for every event. Ordinary `main` pushes remain staging-only and\n  can create or update a release PR. Production runs only when the capability\n  is enabled and either:\n  - a `workflow_dispatch` passes `production-approved=true` and the triggering\n    actor currently has `write`, `maintain`, or `admin` permission; or\n  - `production-release-on-main=true` and the `main` push commit is associated\n    with exactly one same-repository, merged release pull request matching\n    `production-release-label` and `production-release-head-prefix`.\n  The production job is then gated by the configured GitHub Environment.\n- Before production artifact download, Buildchain assembles a managed sealed\n  publication capability from the exact source/runtime SHAs, production plan\n  and artifact hash, a qualifying pre-publication controller receipt, the\n  trusted manual or reviewed-release-PR decision, production Environment and\n  AWS role target, an ephemeral-runner receipt, and a fresh nonce. Production\n  revalidates that capability against the downloaded plan before it downloads\n  product bytes. The later AWS OIDC exchange remains the provider's final\n  transaction-time authorization decision and fails closed before deploy apply.\n- The `publication-*-json` inputs are an advanced external-evidence\n  compatibility path, not a prerequisite for the standard release-PR or trusted\n  manual mechanisms. External evidence must now include\n  `publication-gate-aggregate-json`; supplying only a partial set still fails\n  closed.\n- Production apply writes a production release feedback passport artifact and\n  comments the release PR with the production URL, source SHA, artifact\n  identity, run URL, rollback pointer, and failure context when apply did not\n  complete.\n\nThe feedback passport records the release responsibility chain:\n\n- human decision actor;\n- trigger actor;\n- runner/execution actor;\n- OIDC/deploy identity reference;\n- decision type and time;\n- source event, PR number, merge commit, and required gate label/head-prefix.\n\n`release-feedback-actor-privacy` controls actor values in the passport and\ncomments. `public` records GitHub actor names, `redacted` records only the actor\nrole, and `private-ref` records a stable private reference hash without exposing\nthe actor name.\n\nFor release-PR publishing, callers opt in explicitly:\n\n```yaml\njobs:\n  web-surface:\n    uses: kungfu-systems/buildchain/.github/workflows/.web-surface.yml@v3\n    with:\n      build-command: npm run build\n      verify-command: npm run check\n      artifact-path: dist\n      production-apply: true\n      production-release-on-main: true\n      production-release-label: buildchain-release\n      production-release-head-prefix: release/\n      production-release-branch-channel: production\n      production-release-pr-mode: auto\n      production-aws-role-arn: arn:aws:iam::123456789012:role/site-production-github-actions\n      production-environment: production\n```\n\nKeep `production-apply` enabled in the caller when the repository supports\nproduction. Buildchain derives whether the current event may use that\ncapability: an ordinary `main` push plans and applies staging, a matching\nreviewed release PR merge authorizes production, and an approved trusted manual\ndispatch authorizes production. Inputs from an untrusted event cannot turn that\ndecision on.\n\n`production-release-pr-mode` controls the post-staging handoff:\n\n| Mode | Behavior |\n| --- | --- |\n| `auto` | Generate release PR facts, create/update the empty release-intent branch and PR, and label it when token permissions allow. This is the default. |\n| `summary-only` | Generate and upload release PR facts, body, passport evidence, and manual command, but do not call the GitHub PR API. |\n| `disabled` | Record a disabled handoff and skip release PR API calls. |\n\nAutomatic release PR creation normally uses the workflow `github.token`.\nConsumers that cannot enable \"GitHub Actions can create and approve pull\nrequests\" globally should prefer the first-class GitHub App path. Pass the App\nclient id as an input and the private key as a reusable workflow secret; Buildchain\ncreates an installation token inside the release PR job and uses it only for the\nrelease-intent branch, PR, and label operations:\n\n```yaml\nwith:\n  production-release-app-client-id: ${{ vars.KUNGFU_RELEASE_APP_CLIENT_ID }}\nsecrets:\n  production-release-app-private-key: ${{ secrets.KUNGFU_RELEASE_APP_PRIVATE_KEY }}\n```\n\nWhen either side of the App configuration is missing, Buildchain does not hide\nthat behind the fallback `github.token`. The handoff JSON and job summary report\n`status: \"app-token-unavailable\"` with an `appTokenStatus` such as\n`missing-client-id`, `missing-private-key`, or `create-failed`, and still include\nthe manual PR creation command. If the repository intentionally uses another\nnarrow token, pass it through `production-release-pr-token`.\n\n`production-release-app-id` remains accepted as a deprecated alias for the input\nname, but the value should be the GitHub App client id. GitHub App numeric App\nIDs and client IDs are distinct, and Buildchain passes the value to\n`actions/create-github-app-token` through its non-deprecated `client-id` input so\nnew runs do not emit the deprecated `app-id` warning.\n\nIf a repository already generates its own narrow token or PAT, it can still pass\nthat through `production-release-pr-token`:\n\n```yaml\nwith:\n  production-release-pr-token: ${{ secrets.BUILDCHAIN_RELEASE_PR_TOKEN }}\n```\n\nToken priority is: generated GitHub App installation token,\n`production-release-pr-token`, then `github.token`.\n\nThe merge button becomes the production approval only for a PR that carries the\nrelease label and comes from the configured source-branch prefix. Ordinary pull\nrequests merged into `main` deploy staging and open a release-intent PR; merging\nthat release PR triggers production. A release PR merge push does not open\nanother release PR.\n\nApply-only inputs are validated before the caller build or verification command\nruns. If the current event would run preview, staging, or production apply,\nmissing role inputs, a production apply without `production-approved=true` on\nmanual dispatch, or a manual actor without repository write authority fail\nimmediately instead of spending the build and plan jobs first.\n\nCallers must grant `id-token: write` for OIDC role assumption. Preview comments\nneed `pull-requests: write`. Automatic release PR creation also needs\n`contents: write`, `pull-requests: write`, and `issues: write` so Buildchain can\ncreate the release branch, write the empty release-intent commit, open or update\nthe PR, and apply the release label. If these permissions are unavailable,\nBuildchain degrades the release handoff instead of marking a successful staging\ndeployment as failed, unless `fail-on-release-pr-error=true`. The AWS roles remain caller-owned and\nshould be scoped by channel: preview can mutate only preview resources, staging\ncan mutate only staging resources, and production can mutate only production\nresources.\n\nApply mode fails closed when the deploy config still contains placeholder AWS\ntargets such as `pending-preview-distribution`. Planning can use placeholders\nfor dry-run-only design work, but live apply requires concrete bucket and\nCloudFront distribution identifiers.\n\n## Site Repository Shape\n\nA site repository can start with:\n\n```toml\nschema = 1\n\n[project]\ntype = \"web-surface\"\nname = \"site-kungfu-tech\"\nsite = \"kungfu-tech\"\n\n[lifecycle.build]\ncommand = \"pnpm run build\"\n\n[lifecycle.verify]\ncommand = \"pnpm run check\"\n```\n\nThen add the channel, deploy, retention, and security declarations shown above.\nThe project may use pnpm, npm, yarn, Vite, Astro, Next static export, Sphinx,\nMkDocs, CMake-generated docs, or another lifecycle command source. Buildchain\nonly needs a deterministic artifact path and the manifest facts.\n\n## Signed bootstrap installer publications\n\nA web-surface artifact that contains `installer-publication.json` opts into the\n`kungfu.bootstrap-installer-publication/v1` seam. During planning, Buildchain\nfails closed unless the manifest binds:\n\n- one signed-channel payload root and exact channel-file digest;\n- one source SHA and Release Passport;\n- unique platform/architecture entries with manifest, artifact, and archive\n  digest roots; and\n- byte-identical friendly and immutable `install.sh` / `install.ps1` assets.\n\nThe resulting `kungfu-buildchain-installer-publication-evidence/v1` object and\nroot are welded into the deployment manifest. This does not make Buildchain the\nproduct installer authority: Kungfu generates the installer from its signed\nrelease channel, while the site owns only routes and presentation.\n\nThe site artifact should also declare the existing\n`kungfu-buildchain-publication-archive-policy` in its root `manifest.json`, with\nthe versioned installer directory as `immutablePath`. Buildchain then performs\npre-upload object digest checks, `--no-overwrite` upload, post-upload checks, and\nexcludes the immutable root from mutable deletion.\n\nLocal verification:\n\n```sh\nnode scripts/installer-publication.mjs \\\n  --manifest dist/installer-publication.json \\\n  --artifact-root dist\n```\n\nAfter preview, staging, or production apply, public read-back verifies exact\nbytes plus route semantics. Friendly routes require a revalidated cache policy\nwith `max-age` no greater than 300 seconds; immutable routes require at least\none year and the `immutable` directive:\n\n```sh\nnode scripts/installer-publication.mjs \\\n  --manifest dist/installer-publication.json \\\n  --public-readback\n```\n\nRedirects are not accepted as successful read-back. The evidence retains\ncontent type, cache control, ETag, object version id when exposed, size, digest,\nURL, channel root, source SHA, and Release Passport coordinates.\n\n## Boundaries\n\nBuildchain only performs live AWS mutations in explicit apply modes with\n`--dry-run false`. Production deploys must still be gated by a human-controlled\nworkflow, release, or GitHub Environment. DNS changes, staging auth\nimplementation, CloudFront distribution creation, and credential provisioning\nremain explicitly authorized infrastructure operations outside the web-surface\nartifact apply contract."
     },
     {
       "id": "fixture:infra-contract-aws-cdk-shaped",
@@ -2730,7 +2821,7 @@
   "pageRegistry": {
     "path": "page-registry.json",
     "contract": "kungfu-buildchain-site-page-registry",
-    "pageCount": 59,
+    "pageCount": 60,
     "categories": [
       "action",
       "api",
@@ -2768,7 +2859,7 @@
         "homepagePriority": 20,
         "defaultPresentation": "workflow-surface-list",
         "includeInFirstScreen": true,
-        "markdown": "Bootstrap a repository:\n\n```bash\nnpx @kungfu-tech/buildchain init --type package --package-manager pnpm\nnpx @kungfu-tech/buildchain validate --require-version-state\nnpx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v3/v3.0\n```\n\nBuildchain supports package and non-package projects through\n`.buildchain/buildchain.toml`. Legacy root `buildchain.toml` files remain\nreadable, but new consumers should keep Buildchain-owned files under\n`.buildchain/`:\n\n```text\n.buildchain/buildchain.toml\n.buildchain/contract-lock.json\n.buildchain/kfd/kfd-3/surfaces.json\n.buildchain/release-passport/buildchain.release.json\n```\n\nLifecycle commands can call pnpm, npm, yarn, pip, Conan, CMake, Make, custom\nscripts, or any other command that can run in the repository checkout.\n\nThe KFD entrypoint is `buildchain kfd`. Buildchain provides concrete KFD-1\ncontract-world, KFD-2 trust-claim, and KFD-3 collaboration-surface workflows,\nplus fail-closed product-evidence gates for KFD-4, KFD-5, and KFD-7. These\ngates preserve product-owned qualification and support decisions; they do not\nturn a schema-valid record into certification or shipped support.\n\nBuildchain's active GitHub Action surface is deliberately small:\n\n- `actions/validate-config`\n- `actions/run-lifecycle`\n- `actions/promote-buildchain-ref`\n- `actions/report-buildchain-issue`\n\nThe active reusable workflow surfaces are:\n\n- `.github/workflows/.gate-profile.yml` for project-neutral Shifu Gate profile\n  planning, capability-aware runner dispatch, receipt validation, and one\n  stable aggregate check;\n- `.github/workflows/.auditable-demo.yml` for exact-artifact demo\n  qualification, transcript-bound renderer smoke, optional media rendering\n  from the exact passing Gate bundle, and opt-in content-addressed web-delivery\n  profiles with independently verified rendition roles;\n- `.github/workflows/.build.yml` for deterministic multi-platform build and\n  artifact contracts;\n- `.github/workflows/build.yml` for the single-config channel router that uses\n  `vN-alpha` during development/prerelease work and `vN` for stable releases;\n- `.github/workflows/release-candidate-promote.yml` for post-merge\n  promote-only publication from a PR-stage release candidate, without a second\n  heavy build;\n- `.github/workflows/.web-surface.yml` for preview, staging, production, and\n  cleanup plans for site/app repositories;\n- `.github/workflows/buildchain-ref-promotion.yml` for protected release\n  promotion and version-state transactions;\n- `.github/workflows/binary-distribution.yml` for Buildchain's own release\n  passport proof case.\n\nStable consumers should reference actions and workflows through floating major\nrefs after reviewing the exact release passport:\n\n```yaml\nuses: kungfu-systems/buildchain/actions/validate-config@v3\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/build.yml@v3\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v3\n```"
+        "markdown": "Bootstrap a repository:\n\n```bash\nnpx @kungfu-tech/buildchain init --type package --package-manager pnpm\nnpx @kungfu-tech/buildchain validate --require-version-state\nnpx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v3/v3.0\n```\n\nBootstrap and inspect a governed paper repository through one interface:\n\n```bash\nnpx @kungfu-tech/buildchain paper scaffold \\\n  --package @kungfu-tech/paper-example \\\n  --repository kungfu-systems/paper-example\nnpx @kungfu-tech/buildchain paper preflight --offline\nnpx @kungfu-tech/buildchain paper status\n```\n\nThe paper surface is dry-run first. Add `--write` only to create missing\nscaffold files; external mutations such as npm bootstrap, Alpha PR creation,\nand release resumption require `--execute`. See\n[`docs/publication-artifacts.md`](docs/publication-artifacts.md) for the\nevidence-state model and operator flow.\n\nBuildchain supports package and non-package projects through\n`.buildchain/buildchain.toml`. Legacy root `buildchain.toml` files remain\nreadable, but new consumers should keep Buildchain-owned files under\n`.buildchain/`:\n\n```text\n.buildchain/buildchain.toml\n.buildchain/contract-lock.json\n.buildchain/kfd/kfd-3/surfaces.json\n.buildchain/release-passport/buildchain.release.json\n```\n\nLifecycle commands can call pnpm, npm, yarn, pip, Conan, CMake, Make, custom\nscripts, or any other command that can run in the repository checkout.\n\nThe KFD entrypoint is `buildchain kfd`. Buildchain provides concrete KFD-1\ncontract-world, KFD-2 trust-claim, and KFD-3 collaboration-surface workflows,\nplus fail-closed product-evidence gates for KFD-4, KFD-5, and KFD-7. These\ngates preserve product-owned qualification and support decisions; they do not\nturn a schema-valid record into certification or shipped support.\n\nBuildchain's action registry currently contains six active entries. Four are\ndirect consumer integration actions:\n\n- `actions/validate-config`\n- `actions/run-lifecycle`\n- `actions/promote-buildchain-ref`\n- `actions/report-buildchain-issue`\n\nTwo additional release-authority components are also registered and versioned:\n\n- `actions/github-artifact-attestation`\n- `actions/macos-credential-island`\n\n`dist/site/workflow-registry.json#actions` is the machine-readable inventory;\nthis split keeps the older four-action consumer list from being mistaken for\nthe complete current registry.\n\nThe active reusable workflow surfaces are:\n\n- `.github/workflows/.gate-profile.yml` for project-neutral Shifu Gate profile\n  planning, capability-aware runner dispatch, receipt validation, and one\n  stable aggregate check;\n- `.github/workflows/.auditable-demo.yml` for exact-artifact demo\n  qualification, transcript-bound renderer smoke, optional media rendering\n  from the exact passing Gate bundle, and opt-in content-addressed web-delivery\n  profiles with independently verified rendition roles;\n- `.github/workflows/.build.yml` for deterministic multi-platform build and\n  artifact contracts;\n- `.github/workflows/build.yml` for the single-config channel router that uses\n  `vN-alpha` during development/prerelease work and `vN` for stable releases;\n- `.github/workflows/release-candidate-promote.yml` for post-merge\n  promote-only publication from a PR-stage release candidate, without a second\n  heavy build;\n- `.github/workflows/.web-surface.yml` for preview, staging, production, and\n  cleanup plans for site/app repositories;\n- `.github/workflows/buildchain-ref-promotion.yml` for protected release\n  promotion and version-state transactions;\n- `.github/workflows/binary-distribution.yml` for Buildchain's own release\n  passport proof case.\n\nStable consumers should reference actions and workflows through floating major\nrefs after reviewing the exact release passport:\n\n```yaml\nuses: kungfu-systems/buildchain/actions/validate-config@v3\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/build.yml@v3\n```\n\n```yaml\nuses: kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@v3\n```"
       },
       {
         "id": "release-model",
@@ -2849,7 +2940,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:cc32692e8d04816e8de94f208e43c2d5c5c7a8425cec8b32edc73ab78591fbbf"
+      "digest": "sha256:430eed733bfcbebd853da9c60a687822dab73689d7fb9ad2e9a760af279415e5"
     },
     {
       "id": "auditable-demo",
@@ -2857,7 +2948,7 @@
       "path": "docs/auditable-demo.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:0e8cf2162c2e1f83cfe3a6171e3055f494cab5f03fdcbec3854e1793678e6908"
+      "digest": "sha256:4b3e529060ba54a439a86159a4dc0fc7fb43c8456a90e4b32579c86b20bc6bab"
     },
     {
       "id": "install",
@@ -2873,7 +2964,7 @@
       "path": "docs/release-passport.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:d698078075700e60bafb9677bc4c35d49970136b98caaecfc51d38344285cdd5"
+      "digest": "sha256:e1ca1d470de4faeb9f7f0a57228aebbc166d0c96d03a5603fc576ad955c497a4"
     },
     {
       "id": "github-artifact-attestation",
@@ -2897,7 +2988,7 @@
       "path": "docs/publication-authority.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:118dc751fa3c37b4b20f4b909534458148c0f42c2c9d69f13e2fa5373dbfe244"
+      "digest": "sha256:6c91ee89d1ed5c0c570806684738916876556b2f1bcbf4be4f73f30ff89e98a4"
     },
     {
       "id": "github-governance-authority",
@@ -2905,7 +2996,7 @@
       "path": "docs/github-governance-authority.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:b8c3d9ad53c2509bbd95804ccc31f6aa89989c3aadf3a2b75d9c73aef168b7e8"
+      "digest": "sha256:197ae7a949817f60f46b67b060731df14d0343d9daecd7d6eacfae9a526b6a12"
     },
     {
       "id": "release-candidate",
@@ -2913,7 +3004,7 @@
       "path": "docs/release-candidate.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:887bc3c041c3231d8e6dd403964d04d28a9eb13081bc4154dc2a6ebd56697ecd"
+      "digest": "sha256:fbcffddf1e2c50502186b7ba557e29f96be59a1da6d438aabd4d1f9ce32b5915"
     },
     {
       "id": "release-propagation",
@@ -2921,7 +3012,7 @@
       "path": "docs/release-propagation.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:b7d2deef7d50fc412aa21c7ef1019c4c2bd8b0392b9b323356b1c0b1fc2596b6"
+      "digest": "sha256:aea013d923a8d419fc76e99a81765f281640dd95141d32ae415b8572604e9d32"
     },
     {
       "id": "readme-badges",
@@ -2953,7 +3044,7 @@
       "path": "docs/consumer-issue-reporting.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:96804310360c02f408fee9d540385d875a40d09bef046c3df369228d311a1cdd"
+      "digest": "sha256:324342b10e69ca5ce6d04a267fb5fc2a6b52e674f6252eec2121557c5542f729"
     },
     {
       "id": "infra-contract",
@@ -2969,7 +3060,7 @@
       "path": "docs/toolkit-observability.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:d7f4179c3912d7bbc5940bfba69e674fb03d020a740063c0b877a171bd5789e3"
+      "digest": "sha256:1a08331cdca2b48e622ecbb799a7465a59cc4a779dd73d36f559f9bc1b98578c"
     },
     {
       "id": "site-bundle-contract",
@@ -2985,7 +3076,7 @@
       "path": "docs/migration-inventory.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:bb73731a3b747d02b9453537109754f194c58dba92c260ac84c632b0d58607af"
+      "digest": "sha256:25d896711f4efebffa9a8960b7eb97438d9fd4892aa08bef0339026e83a53bdf"
     },
     {
       "id": "ownership",
@@ -2993,7 +3084,7 @@
       "path": "docs/ownership.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:a9f54f211b55da6464d890b0ebfe046dbf564aabdfee3aadf457723f9aae398a"
+      "digest": "sha256:91a1b59f0f71067c58ffd685a23b29e14a4d6fe33c1a44f8708b7d0512e4baa5"
     },
     {
       "id": "product-mechanism",
@@ -3009,7 +3100,7 @@
       "path": "docs/cli.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:49da688f9f8b726a9169a3e4b246cb6ef07c6c626ea15c22f0b26ba1a37a58b4"
+      "digest": "sha256:60c6b00e0dbf60f0b7ba8c3c549027925d94a6bdf8a2af3f8e35d24ef1dd50ba"
     },
     {
       "id": "build-facts",
@@ -3041,7 +3132,7 @@
       "path": "docs/lifecycle-protocol.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:55425241363da6105a6b36a46bf8c9d7edd5b0e0f9dbcebe1452327642eb2af9"
+      "digest": "sha256:4b7a8efe1d22751ded069f46a23490db70cda9e9e14641acab600ab781245b19"
     },
     {
       "id": "reusable-build-surface",
@@ -3049,7 +3140,7 @@
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:ea36ec722f811f5156735aa7471ed080cdc7e87d71c20c300243b226e233e675"
+      "digest": "sha256:8908e1f1589537ac8ef82ee1dacdd24072ca871e3e245825669e7cfbdebd2e3d"
     },
     {
       "id": "publish-transaction",
@@ -3057,7 +3148,7 @@
       "path": "docs/publish-transaction.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:cde5256d5f6443a6d32b47783900a0677e973855266af5a360db8d4d112bb677"
+      "digest": "sha256:9b830727e5b0d2192c937f19106c11ea5064dde77e30d290825f343df47f291b"
     },
     {
       "id": "release-governance",
@@ -3065,7 +3156,7 @@
       "path": "docs/release-governance.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:42a45f51db7ea11658431718835e1a430959db2a5cc80fc4651681502fe6fb7c"
+      "digest": "sha256:60ec90d3294818d3c53e403312801a8ab47be7c0f34810002676fbfcdbceaa60"
     },
     {
       "id": "release-flow",
@@ -3073,7 +3164,7 @@
       "path": "docs/release-flow.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:fc6495a7b5124c17c880777e16fc98e60ed7766ec9a958abfca3030bdc2c321e"
+      "digest": "sha256:bac959565c36cf39c3cd30dfce00dbbb59b73ed21b852a8f24a6cae281cb5f05"
     },
     {
       "id": "runtime-train-validation",
@@ -3081,7 +3172,7 @@
       "path": "docs/runtime-train-validation.md",
       "plane": "verify",
       "exists": true,
-      "digest": "sha256:c9ebf451294f92a2be3aa2ac4b2ec7afb3cc17bbeae2ece7879b800c0f274a40"
+      "digest": "sha256:1a4ce3fc2c150f88bc4d32123a108478ba5d73d0d69b8a95bf0d6670e32618a0"
     },
     {
       "id": "versioning",
@@ -3089,7 +3180,7 @@
       "path": "docs/versioning.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:4b40cb8675c111b7588297102a61cb241630f2b707a67a0384a6df7527b2c64c"
+      "digest": "sha256:5dd27f3c4a412a23093e5d33746a5d5d40353625c8ffe89a961978fc5de9c03e"
     },
     {
       "id": "web-surface-deployments",
@@ -3097,7 +3188,7 @@
       "path": "docs/web-surface-deployments.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:ed4ff02dcb6f66118a29084784f25d8008ca472f59005b2e014133524706a9c5"
+      "digest": "sha256:484e896746d2f4cca4f9f18d29c14784ec20143c12affc3dbb9ccfbf8f221b55"
     }
   ],
   "releaseModel": {