@kungfu-tech/buildchain 4.0.9 → 4.0.10-alpha.0

package/architecture/agent-change-map.md

@@ -202,6 +202,7 @@ Safe change route: Reduce one owned responsibility behind the stable facade, run
 - `scripts/generate-channel-promotion-workflow.mjs`
 - `.github/workflows/v4-stage-capsule-canary.yml`
 - `packages/core/release-tail-provider-plane.js`
+- `packages/core/buildchain-publication-authority.js`
 
 ## cli-command-registry
 

package/architecture/build-environments.json

@@ -66,6 +66,23 @@
       "runners": {
         "preset": "kungfu-v4-self-hosted"
       }
+    },
+    "kungfu-hosted": {
+      "runners": {
+        "preset": "custom",
+        "platforms_json": "[{\"id\":\"linux-x64\",\"name\":\"Linux x64\",\"platform\":\"linux\",\"runner\":\"[\\\"ubuntu-24.04\\\"]\",\"capabilities\":[\"node\",\"native-toolchain\",\"product-artifacts\",\"rust\"],\"environment\":{\"CC\":\"gcc-14\",\"CXX\":\"g++-14\"}},{\"id\":\"linux-arm64\",\"name\":\"Linux ARM64\",\"platform\":\"linux\",\"runner\":\"[\\\"ubuntu-24.04-arm\\\"]\",\"capabilities\":[\"node\",\"native-toolchain\",\"product-artifacts\",\"rust\"]},{\"id\":\"macos-arm64\",\"name\":\"macOS ARM64\",\"platform\":\"macos\",\"runner\":\"[\\\"macos-15\\\"]\",\"capabilities\":[\"node\",\"native-toolchain\",\"product-artifacts\",\"rust\"]},{\"id\":\"windows-x64\",\"name\":\"Windows x64\",\"platform\":\"windows\",\"runner\":\"[\\\"windows-2022\\\"]\",\"capabilities\":[\"node\",\"native-toolchain\",\"product-artifacts\",\"rust\"]}]"
+      },
+      "checkout": {
+        "history_mode": "full",
+        "github_timeout_seconds": 1200
+      },
+      "cache": {
+        "profile_ref": "docs/shifu/windows-alpha-sccache.cache-profile.json",
+        "profile_digest": "sha256:581c430b959c0b45272031cad85a3fae740a6398abf7c1051d1d43b098ee0adb",
+        "provider": "sccache",
+        "platforms_json": "[\"windows-x64\"]",
+        "required": true
+      }
     }
   }
 }

package/architecture/maintainability-debt.json

@@ -3087,7 +3087,8 @@
     "scripts/dev-delivery-warrant.mjs",
     "scripts/generate-channel-promotion-workflow.mjs",
     ".github/workflows/v4-stage-capsule-canary.yml",
-    "packages/core/release-tail-provider-plane.js"
+    "packages/core/release-tail-provider-plane.js",
+    "packages/core/buildchain-publication-authority.js"
   ],
   "burnDownSlices": [
     {

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "4.0.9",
+    "version": "4.0.10-alpha.0",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v4",
@@ -2230,7 +2230,7 @@
         "manual entries carry source file digests so downstream sites and agents can detect stale hand-written documentation"
       ],
       "breakingDigest": "sha256:7d0d2819e3a3e72989d9c57b5efe9d0bc0a79bc0f2c82a0c7b9d6c5a211a91f2",
-      "auditDigest": "sha256:5a826b4665d21e46ebaace02497512ea6ddc7d629194d926dd9b755e2d2207b0"
+      "auditDigest": "sha256:870a8ad5cd203150207664bee152665e38ff12d410a23234322468ca5b61c45f"
     },
     {
       "contractVersion": 1,
@@ -4354,5 +4354,5 @@
   "compatibilityFactCutRoot": "sha256:f61b975d4a96c921cc4bd37fb3ed9a0596b47004fe34dc7219979d697e3707f9",
   "compatibilityProofRegistryRoot": "sha256:b7194b811e4d3af2df4390bc4d1731e16a86215bd64ee18cb630dd5492f4fb63",
   "compatibilityDigest": "sha256:e398528e54509c05569630ffcc98a04d41e831479ab921df65943b49bf077719",
-  "contractDigest": "sha256:8fcc598c161f44a5e12cc277f59df709d611863c92e6abf26f8c7a36bf0a38dd"
+  "contractDigest": "sha256:f6d82d2ee65427a7fb6f1bac41b20e273e6f662131d4b95773e4c6fca998ae9f"
 }

package/dist/site/buildchain-site.json

@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "c951b90a6dc6cffa8e62a75218194019ad47679f",
+  "sourceRevision": "626d32c65639db26e308ac1e25d6a8062f5df6f8",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.9",
+    "version": "4.0.10-alpha.0",
     "versionSource": "package.json#version"
   },
   "source": {
@@ -4506,7 +4506,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/reusable-build-surface.md",
-      "digest": "sha256:bc609cad079a44afb8c2cf2b4459d44612bfd5ff09ed3064f85a2a3f02a5ec1e",
+      "digest": "sha256:58b91e75fc345ecd24377cf99a26ba344bc107016ef426ac5d99bb1c71d713b0",
       "headings": [
         {
           "level": 1,
@@ -4544,7 +4544,7 @@
           "anchor": "maintaining-the-contract"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-reusable-build\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-08\nai_provenance:\n  model_family: GPT-6\n  product: Codex\n  generated_at: 2026-09-08\n  invisible_context_boundary: No private credentials or unrelated repositories inspected.\n---\n\n# Reusable Build Surface\n\nA project declares its build in `buildchain.toml`. The reusable workflow owns\njob sequencing, admission, runner boundaries and evidence aggregation. Ordinary\nsingle-project calls have no inputs:\n\n```yaml\npermissions:\n  actions: read\n  contents: read\n  issues: write\n  id-token: write\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v4\n```\n\nUse `@v4-alpha` to select the alpha runtime. The exact called workflow SHA is\nthe runtime SHA; a second runtime selector cannot override it. Both the public\n`build.yml` and the `.build.yml` backbone expose exactly one optional input:\n`config-path`. Neither accepts command overrides, runtime refs, arbitrary JSON\nconfiguration or legacy aliases.\n\n## Project discovery\n\nAt the repository root, exactly one of `.buildchain/buildchain.toml` and\n`buildchain.toml` must exist. Missing or ambiguous configurations fail before\nmatrix scheduling. A nested project is selected with its configuration location:\n\n```yaml\njobs:\n  native:\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v4-alpha\n    with:\n      config-path: packages/native/.buildchain/buildchain.toml\n```\n\nThe config location determines the project working directory. Planning and\nlifecycle execution discover the same file. Absolute paths, parent traversal,\nsymlink escape, malformed TOML and unknown `[build]` keys fail closed. A\nconfiguration locator cannot carry a profile override or execution authority.\n\n## Project configuration\n\n```toml\nschema = 1\n\n[lifecycle.install]\ncommand = \"corepack pnpm install --frozen-lockfile\"\n\n[lifecycle.build]\ncommand = \"corepack pnpm build\"\n\n[lifecycle.verify]\ncommand = \"corepack pnpm test\"\n\n[build]\nenvironment = \"github-hosted\"\ntimeout_minutes = 120\nfail_fast = false\n\n[build.tools]\nnode = \"24\"\nrust = \"stable\"\ngo = \"1.25.x\" # optional; omitted toolchains are not installed\n\n[build.artifacts]\nname = \"my-library\"\npaths = [\"dist\"]\nrequired_paths = [\"dist/library.js\"]\nmin_files = 1\nrelease_candidate = true\nretention_days = 14\ncompression_level = 0\n```\n\nCommands remain exclusively in `[lifecycle]`. The backbone explicitly invokes\ninstall, build and verify in that order on each platform. Build is required;\ninstall and verify are required when declared. Unneeded stages require no\nadditional boolean setting. Per-stage lifecycle timeout declarations retain\nprecedence over the build timeout fallback.\n\nArtifact paths and required file paths are relative to the selected project.\nPlatform artifact names derive from the configured base name,\nplatform and source SHA; callers do not supply naming templates. The final\nmanifest checks `min_files`, `max_files`, `min_total_bytes` and `required_paths`.\n\nOther optional project sections are:\n\n| TOML section | Responsibility |\n| --- | --- |\n| `build.diagnostics` | Process sampling and expected parallelism |\n| `build.verification` | Consumer-produced verify substage evidence location |\n| `build.finalization` | Verification of final signed bytes and platform placement |\n| `build.transport_smoke` | Transport simulation scenario and artifact root |\n| `build.attestation` | Subject path and attested platform |\n| `build.macos_signing` | App path and sealed-input platform |\n| `build.contract` | Compatibility and drift reporting policies |\n| `build.evidence` | Repository files containing gate and candidate-family evidence |\n\nDeclarative signing targets continue to belong to `[signing.artifacts]`.\nThe formal signing authority remains `authority/v3/v3.0/artifact-signing`\nwith the protected `buildchain-artifact-signing` environment.\nCredentials, authority profiles and signer identities cannot be supplied through\nthat declaration. See [Release Candidate](release-candidate.md)\nand [GitHub Artifact Attestation](github-artifact-attestation.md).\n\n## Governed environments\n\n`build.environment` selects a profile in\n[`architecture/build-environments.json`](../architecture/build-environments.json)\nfrom the exact Buildchain runtime. Infrastructure owners maintain runner\npresets/platforms, Linux container images, mirrors, cache transport, artifact\nrelay settings and credential-island environments there. Adding a runner label\nor provider role requires reviewing that profile; project TOML cannot redefine\nit. Secrets still cross explicit workflow secret/environment boundaries.\n\nThe initial profiles are `github-hosted`, `github-hosted-container`,\n`kungfu-v4-native` and `kungfu-v4-self-hosted`. The container profile uses the\nexisting digest-pinned `kungfu-verify` image. Native and container jobs remain\nseparate because GitHub selects `runs-on` and `container` before executing\nsteps. Their shared behavior is owned by these composite actions:\n\n| Action | Owner responsibility |\n| --- | --- |\n| `build-lifecycle-stage` | Lifecycle manifests, sampling and diagnostics |\n| `build-signing-request` | Unsigned requests and detached signing control inputs |\n| `build-verification-evidence` | Independent substage verification and failure evidence |\n| `build-attestation-policy` | Source-bound artifact attestation policy |\n| `build-agent-hub-evidence` | Agent Hub conformance evidence |\n| `build-artifact-transfer` | GitHub and S3 transport plus payload manifests |\n\nThe backbone still owns install → build → verify order, job dependencies,\npermissions, signing control, credential-island placement and final aggregation.\nA composite's internal receipt inputs transport already resolved facts; they\nare not additional reusable-workflow configuration inputs.\n\n## Identity and admission\n\nThe configuration resolver reads the exact consumer source without executing\nconsumer commands. It emits a deterministic plan/root binding configuration\nbytes, source SHA, called-workflow SHA, selected environment, toolchain and\ncache roots. Trust checks run before project execution or privileged runners.\n\nTracked consumer workflows use `@v4` or `@v4-alpha` and commit both\n`.buildchain/contract-lock.json` and `.buildchain/alpha-contract-lock.json`.\nThe called channel selects its matching lock. Source-persisted train/SHA\nselectors and mismatched locks remain forbidden. Ordinary builds have no\nruntime-override path; specialized release/recovery entry points keep their\nseparate, bounded admission contracts.\n\nBootstrap owns its admitted release and recovery capabilities. It is not an\nalternate parameter envelope for ordinary builds and is not injected into the\nbuild backbone. Release promotion consumes an already sealed candidate and\nmust verify the source, artifacts and receipts independently.\n\n## Evidence and failure behavior\n\nThe workflow retains runtime/source identity, build and diagnostics summaries,\nRelease Candidate Passport, signing/finalization and controller receipt outputs.\nThe public facade forwards those outputs from the single backbone execution.\nPlatform manifests include deterministic payload hashes; transport preserves\nhidden artifacts and provenance. Substage failure evidence is collected even\nwhen verify fails. Untrusted events cannot reach build runners.\n\nSigning authority and credential-island jobs remain separate from ordinary\nbuild execution. Imported signed bytes undergo consumer verification before\nmanifests are recomputed. Release builds produce candidates; registry publishing\nbelongs to the protected release path.\n\n## Maintaining the contract\n\nUpdate the TOML parser and plan resolver, owner contracts, affected consumers\nand tests together. Run `node scripts/generate-channel-build-workflow.mjs`,\n`pnpm run generate:workflows`, generated reference/site checks and the full\n`pnpm run check`. Breaking input removal is intentional: migrate old `with`\nsettings to TOML and remove them from calls; no compatibility forwarding exists.\n\nThe Buildchain fixture at `fixtures/libnode-shaped/buildchain.toml` exercises\nnative macOS/Windows and Linux-container builds through this public contract."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-reusable-build\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-09\nai_provenance:\n  model_family: GPT-6\n  product: Codex\n  generated_at: 2026-09-09\n  invisible_context_boundary: No private credentials or unrelated repositories inspected.\n---\n\n# Reusable Build Surface\n\nA project declares its build in `buildchain.toml`. The reusable workflow owns\njob sequencing, admission, runner boundaries and evidence aggregation. Ordinary\nsingle-project calls have no inputs:\n\n```yaml\npermissions:\n  actions: read\n  contents: read\n  issues: write\n  id-token: write\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v4\n```\n\nUse `@v4-alpha` to select the alpha runtime. The exact called workflow SHA is\nthe runtime SHA; a second runtime selector cannot override it. Both the public\n`build.yml` and the `.build.yml` backbone expose exactly one optional input:\n`config-path`. Neither accepts command overrides, runtime refs, arbitrary JSON\nconfiguration or legacy aliases.\n\n## Project discovery\n\nAt the repository root, exactly one of `.buildchain/buildchain.toml` and\n`buildchain.toml` must exist. Missing or ambiguous configurations fail before\nmatrix scheduling. A nested project is selected with its configuration location:\n\n```yaml\njobs:\n  native:\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v4-alpha\n    with:\n      config-path: packages/native/.buildchain/buildchain.toml\n```\n\nThe config location determines the project working directory. Planning and\nlifecycle execution discover the same file. Absolute paths, parent traversal,\nsymlink escape, malformed TOML and unknown `[build]` keys fail closed. A\nconfiguration locator cannot carry a profile override or execution authority.\n\n## Project configuration\n\n```toml\nschema = 1\n\n[lifecycle.install]\ncommand = \"corepack pnpm install --frozen-lockfile\"\n\n[lifecycle.build]\ncommand = \"corepack pnpm build\"\n\n[lifecycle.verify]\ncommand = \"corepack pnpm test\"\n\n[build]\nenvironment = \"github-hosted\"\ntimeout_minutes = 120\nfail_fast = false\n\n[build.tools]\nnode = \"24\"\nrust = \"stable\"\ngo = \"1.25.x\" # optional; omitted toolchains are not installed\n\n[build.artifacts]\nname = \"my-library\"\npaths = [\"dist\"]\nrequired_paths = [\"dist/library.js\"]\nmin_files = 1\nrelease_candidate = true\nretention_days = 14\ncompression_level = 0\n```\n\nCommands remain exclusively in `[lifecycle]`. The backbone explicitly invokes\ninstall, build and verify in that order on each platform. Build is required;\ninstall and verify are required when declared. Unneeded stages require no\nadditional boolean setting. Per-stage lifecycle timeout declarations retain\nprecedence over the build timeout fallback.\n\nArtifact paths and required file paths are relative to the selected project.\nPlatform artifact names derive from the configured base name,\nplatform and source SHA; callers do not supply naming templates. The final\nmanifest checks `min_files`, `max_files`, `min_total_bytes` and `required_paths`.\n\nOther optional project sections are:\n\n| TOML section | Responsibility |\n| --- | --- |\n| `build.diagnostics` | Process sampling and expected parallelism |\n| `build.verification` | Consumer-produced verify substage evidence location |\n| `build.finalization` | Verification of final signed bytes and platform placement |\n| `build.transport_smoke` | Transport simulation scenario and artifact root |\n| `build.attestation` | Subject path and attested platform |\n| `build.macos_signing` | App path and sealed-input platform |\n| `build.contract` | Compatibility and drift reporting policies |\n| `build.evidence` | Repository files containing gate and candidate-family evidence |\n\nDeclarative signing targets continue to belong to `[signing.artifacts]`.\nThe formal signing authority remains `authority/v3/v3.0/artifact-signing`\nwith the protected `buildchain-artifact-signing` environment.\nCredentials, authority profiles and signer identities cannot be supplied through\nthat declaration. See [Release Candidate](release-candidate.md)\nand [GitHub Artifact Attestation](github-artifact-attestation.md).\n\n## Governed environments\n\n`build.environment` selects a profile in\n[`architecture/build-environments.json`](../architecture/build-environments.json)\nfrom the exact Buildchain runtime. Infrastructure owners maintain runner\npresets/platforms, Linux container images, mirrors, cache transport, artifact\nrelay settings and credential-island environments there. Adding a runner label\nor provider role requires reviewing that profile; project TOML cannot redefine\nit. Secrets still cross explicit workflow secret/environment boundaries.\n\nThe profiles are `github-hosted`, `github-hosted-container`, `kungfu-hosted`,\n`kungfu-v4-native` and `kungfu-v4-self-hosted`. `kungfu-hosted` preserves the\nKungfu release matrix on GitHub-hosted Ubuntu 24.04 x64 and ARM64, macOS 15\nARM64 and Windows 2022 x64. It selects GCC 14 for Linux x64, full Git history\nand the required Windows sccache profile at\n`docs/shifu/windows-alpha-sccache.cache-profile.json`, bound to its reviewed\ndigest in the environment registry. All four lanes transfer artifacts directly\nthrough GitHub; the profile adds no provider roles or signing authority.\nExisting profiles retain their runner and cache policies. The container profile\nuses the existing digest-pinned `kungfu-verify` image. Native and container jobs remain\nseparate because GitHub selects `runs-on` and `container` before executing\nsteps. Their shared behavior is owned by these composite actions:\n\n| Action | Owner responsibility |\n| --- | --- |\n| `build-lifecycle-stage` | Lifecycle manifests, sampling and diagnostics |\n| `build-signing-request` | Unsigned requests and detached signing control inputs |\n| `build-verification-evidence` | Independent substage verification and failure evidence |\n| `build-attestation-policy` | Source-bound artifact attestation policy |\n| `build-agent-hub-evidence` | Agent Hub conformance evidence |\n| `build-artifact-transfer` | GitHub and S3 transport plus payload manifests |\n\nThe backbone still owns install → build → verify order, job dependencies,\npermissions, signing control, credential-island placement and final aggregation.\nA composite's internal receipt inputs transport already resolved facts; they\nare not additional reusable-workflow configuration inputs.\n\n## Identity and admission\n\nThe configuration resolver reads the exact consumer source without executing\nconsumer commands. It emits a deterministic plan/root binding configuration\nbytes, source SHA, called-workflow SHA, selected environment, toolchain and\ncache roots. Trust checks run before project execution or privileged runners.\n\nTracked consumer workflows use `@v4` or `@v4-alpha` and commit both\n`.buildchain/contract-lock.json` and `.buildchain/alpha-contract-lock.json`.\nThe called channel selects its matching lock. Source-persisted train/SHA\nselectors and mismatched locks remain forbidden. Ordinary builds have no\nruntime-override path; specialized release/recovery entry points keep their\nseparate, bounded admission contracts.\n\nBootstrap owns its admitted release and recovery capabilities. It is not an\nalternate parameter envelope for ordinary builds and is not injected into the\nbuild backbone. Release promotion consumes an already sealed candidate and\nmust verify the source, artifacts and receipts independently.\n\n## Evidence and failure behavior\n\nThe workflow retains runtime/source identity, build and diagnostics summaries,\nRelease Candidate Passport, signing/finalization and controller receipt outputs.\nThe public facade forwards those outputs from the single backbone execution.\nPlatform manifests include deterministic payload hashes; transport preserves\nhidden artifacts and provenance. Substage failure evidence is collected even\nwhen verify fails. Untrusted events cannot reach build runners.\n\nSigning authority and credential-island jobs remain separate from ordinary\nbuild execution. Imported signed bytes undergo consumer verification before\nmanifests are recomputed. Release builds produce candidates; registry publishing\nbelongs to the protected release path.\n\n## Maintaining the contract\n\nUpdate the TOML parser and plan resolver, owner contracts, affected consumers\nand tests together. Run `node scripts/generate-channel-build-workflow.mjs`,\n`pnpm run generate:workflows`, generated reference/site checks and the full\n`pnpm run check`. Breaking input removal is intentional: migrate old `with`\nsettings to TOML and remove them from calls; no compatibility forwarding exists.\n\nThe Buildchain fixture at `fixtures/libnode-shaped/buildchain.toml` exercises\nnative macOS/Windows and Linux-container builds through this public contract."
     },
     {
       "id": "manual:runtime-train-validation",
@@ -5023,7 +5023,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/v4-production-release.md",
-      "digest": "sha256:078404ecd65922736de17039c43d160f6e3da971921a39c3fab10f437573e3ea",
+      "digest": "sha256:66c9c191777a2ea914f103d73f6b25ca894b114155c09ce46d926bcf55eb2298",
       "headings": [
         {
           "level": 1,
@@ -5061,7 +5061,7 @@
           "anchor": "automatic-next-development-review"
         }
       ],
-      "markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-v4-production-release\ndoc_type: runbook\nsource_level: repository-contracts + protected-provider-readback\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-09-08\nai_provenance:\n  model_family: GPT-6\n  product: Codex\n  generated_at: 2026-09-08\n  invisible_context: Provider credentials and private provider state were not read.\n---\n\n# Buildchain v4 production release\n\nBuildchain v4 is the production release authority for the `v4.0` line. The\nprotected source path is:\n\n```text\ndev/v4/v4.0 -> alpha/v4/v4.0 -> release/v4/v4.0\n```\n\nPublic consumers use `v4-alpha` for the current prerelease channel and `v4`\nfor stable, with matching stable and alpha contract locks. Exact commits and\nimmutable release tags identify retained evidence and explicitly admitted runtime\ninputs; tracked v4 reusable-workflow selectors remain `@v4` or `@v4-alpha`.\n\nBefore qualifying a new release, run `node scripts/check-universal-workflow-bootstrap.mjs`.\nThe required repository check rejects an expired or not-yet-valid candidate admission\npolicy before publication. Renew the bounded validity window through protected review;\nkeep its capability, permission, reviewer and exact-source requirements unchanged.\nHistorical publication receipts remain immutable when a later admission window expires.\n\nThe release transaction is fail-closed. The v4 provider-operation journal,\nactivation plan, stable publication fence, and partial-mutation recovery plan\nbind the exact source, qualification, policy, provider readback, protected\nancestry, and target roots. Confirmed operations are never replayed; uncertain\noperations require provider readback before retry; stable publication requires\nan N-1 or independently sealed qualification.\n\n## Public build qualification\n\nAfter a successful Alpha Self-Dogfood run, Stable Candidate Qualification reads\nits exact `buildchain-summary-<source SHA>` artifact. Protected default-branch\ncode verifies the source run, published alpha runtime, all three platform\nartifacts and install/build/verify evidence before writing\n`buildchain-canary/buildchain-zero-input` on that runtime commit. Manual replay\naccepts only the source run ID. This observation remains Buildchain-owned; it\nneither dispatches another repository nor grants stable publication authority.\n\n## Provider readback\n\nA stable release is complete only when all of these coordinates agree:\n\n- `release/v4/v4.0`, `v4`, `v4.0`, and the exact `v4.0.x` tag;\n- the GitHub Release tag and attached Release Passport evidence;\n- npm `@kungfu-tech/buildchain@4.0.x`, its `gitHead`, and the `latest` tag;\n- the protected source and release transaction roots.\n\nThe alpha channel applies the same rule to `alpha/v4/v4.0`, `v4-alpha`, the\nexact alpha tag, and npm's `alpha` tag.\n\n## Non-destructive rollback\n\nRollback never rewrites an exact tag, release, package version, Passport, or\nprovider journal. Stop forward promotion and select the last verified exact\nv4 runtime through an admitted, non-persistent recovery input; keep tracked v4\nworkflow selectors on their locked floating channel. Use `release/v3/v3.0`\ncoordinate only as an explicit compatibility rollback reference. Restoring v3\nas production authority requires a new reviewed cutover; it is not an implicit\nfallback.\n\nBefore any retry, compare the current provider state with the retained\ntransaction and operation roots. Resume only missing eligible operations.\nConflicting state remains `repair-required` or terminal and must not be\nconverted into success by moving a floating ref.\n\n## Publication settlement and binary recovery\n\nPublication, next-development advancement, and binary distribution have separate\nresults. A completed native ReleaseReceipt remains publication evidence when the\nlater generated Dev PR is still pending or its enqueue call fails. SETTLE verifies\nthe immutable invocation, transaction, both provider states, receipt and Passport\nroots even when APPLY fails after publication. It has no provider write permission.\n\nAPPLY retains that exact chain before waiting for next-development in the existing GitHub Release as\n`buildchain-publication-settlement.json`; it reads the exact tag and original\n`buildchain.release.json` before adding the packet. The APPLY artifact also retains\n`delivery-summary.json`, which reports publication and next-development separately.\nA green workflow label cannot substitute for this receipt verification.\n\nRecovery verifies both its current execution chain and any already published\nsettlement against the exact tag, source and original Passport. It preserves\nthe existing settlement bytes and uses that original receipt for development\nadvancement. A corrected runtime may produce different recovery observations;\nthey do not authorize replacing the completed publication packet. Ambiguous,\ntampered or mismatched retained evidence still blocks recovery.\n\nBinary Distribution reads this settlement and the original publication Passport.\nTag creation can precede settlement, so it waits at most 160 observations, 15 seconds\napart, for missing evidence. A mismatched source, tag, Passport or receipt fails\nimmediately. It no longer requires a legacy `buildchain/release-state/*` ref for v4.\n\nThe sealed binary publisher retains the publication Passport and writes its own\nPassport as `buildchain.binary.release.json`. All v4 asset collisions are checked\nbefore uploads: identical bytes are preserved, absent assets are added, and\nconflicting bytes are rejected. Each publication authorization is retained as\n`buildchain.binary.capability-<sha256>.json`, so a fresh recovery capability does\nnot overwrite an earlier grant. Existing assets are never clobbered. Recovery uses\nthe same exact successful Binary Distribution evidence run through\n`self-release-binary-assets.yml`; it does not rebuild already admitted archives or\ncreate another npm version. Read back all three platform archives, checksums,\nboth Passports and the settlement packet before declaring distribution complete.\n\nThe native publication receipt authorizes no stable promotion and makes no claim\nthat a pending next-development PR has merged. Inspect the exact PR head, protected\nbase and merge result independently. A retry of the publication phase must first\nread retained provider facts and resume only missing operations.\n\n## Protected stable finalization\n\nA successful protected `Verify` on the release branch starts the same floating\nalpha publisher used for prereleases. The publisher creates the stable version\nPR and waits within the original transaction for protected merge and the exact\nmerged commit's successful `Verify`, before moving floating tags and completing\nthe publication receipt. Generated finalization heads are classified from their\nrooted product state and exact source tag, so their checks do not publish again.\n\nThe independent version reviewer also handles generated stable finalization PRs.\nIt requires the exact protected source parent, the rooted version-state parent,\nthe matching immutable stable tag, and byte-for-byte regeneration of the complete\ndeclared version delta. Verification uses protected source code without approval\ncredentials. A separate step approves only the verified head and enables normal\nprotected auto-merge. Changed source/base, modified PR contents, requested changes,\nfailed final checks, and timeout remain failures. Recover an interrupted run using\nthe original source and retained provider evidence; never rewrite published bytes.\n\n## Automatic next-development review\n\nAfter stable completion, the producer generates the next patch at `alpha.0`\nfrom an isolated Git checkout of the exact current protected Dev commit. The\ncheckout explicitly fetches the exact Dev commit into its own object database;\nshallow local clones alone may omit commits fetched only into `FETCH_HEAD`.\nIt retains its own index so version verification can inspect the actual\ngenerated delta, and uses the admitted runtime dependency bridge. A source\narchive without Git metadata cannot perform that verification. The publication\nreceipt remains complete if development preparation fails; recover the original\ntransaction with corrected, reviewed tooling before publishing the next version.\n\n`self-release-next-development.yml` observes a successful exact `Verify` PR run\nfor a same-repository `chore/next-development/*` branch. It executes only the\nprotected default branch runtime. The PR must have one parent equal to the\ncurrent protected Dev head. The protected generator reconstructs every tracked\nbyte, permits only the declared immediate alpha version increment, and verifies\nthe completed alpha settlement against the exact tag and original Passport.\nThe published source tree must equal the protected development base tree.\n\nThe verification step receives no approval credential and never executes PR\ncode. A separate step uses `BUILDCHAIN_APPROVAL_TOKEN`, verifies that its identity\nis the independent `kungfu-origin` CODEOWNER, rereads the exact PR/run/base, and\napproves only that commit. Existing requests for changes stop automation.\nThe exact approval is read back before queue admission with the separate\n`BUILDCHAIN_PROMOTION_TOKEN`. Required checks, CODEOWNER protection and native\nmerge-group verification remain enforced. Missing credentials or evidence,\nforks, source changes and base/head drift fail closed.\n\nThe producer waits for pending independent review and required checks with a\nbounded retry budget. Publication evidence is already durable during this wait,\nso binaries can proceed independently. The reviewer also enqueues the verified\nhead idempotently, allowing a producer interruption to leave a recoverable PR.\nAn interrupted producer run remains failed; a successful later release is needed\nto establish an uninterrupted end-to-end publication."
+      "markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-v4-production-release\ndoc_type: runbook\nsource_level: repository-contracts + protected-provider-readback\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-09-08\nai_provenance:\n  model_family: GPT-6\n  product: Codex\n  generated_at: 2026-09-08\n  invisible_context: Provider credentials and private provider state were not read.\n---\n\n# Buildchain v4 production release\n\nBuildchain v4 is the production release authority for the `v4.0` line. The\nprotected source path is:\n\n```text\ndev/v4/v4.0 -> alpha/v4/v4.0 -> release/v4/v4.0\n```\n\nPublic consumers use `v4-alpha` for the current prerelease channel and `v4`\nfor stable, with matching stable and alpha contract locks. Exact commits and\nimmutable release tags identify retained evidence and explicitly admitted runtime\ninputs; tracked v4 reusable-workflow selectors remain `@v4` or `@v4-alpha`.\n\nWhen generated stable version commits make a direct alpha-to-release merge\nconflict, use the supported `publish-gate/release/v4/v4.0/<exact-alpha-version>`\nsource-lock PR. Its reconciliation commit preserves the exact published alpha\ntree and admits the current release head as a parent. Verify both parents and\ntree equality before review. This ancestry preparation does not grant publication\nqualification; the protected PR checks and native stable fence still apply.\n\nBefore qualifying a new release, run `node scripts/check-universal-workflow-bootstrap.mjs`.\nThe required repository check rejects an expired or not-yet-valid candidate admission\npolicy before publication. Renew the bounded validity window through protected review;\nkeep its capability, permission, reviewer and exact-source requirements unchanged.\nHistorical publication receipts remain immutable when a later admission window expires.\n\nThe release transaction is fail-closed. The v4 provider-operation journal,\nactivation plan, stable publication fence, and partial-mutation recovery plan\nbind the exact source, qualification, policy, provider readback, protected\nancestry, and target roots. Confirmed operations are never replayed; uncertain\noperations require provider readback before retry; stable publication requires\nan N-1 or independently sealed qualification.\n\n## Public build qualification\n\nAfter a successful Alpha Self-Dogfood run, Stable Candidate Qualification reads\nits exact `buildchain-summary-<source SHA>` artifact. Protected default-branch\ncode verifies the source run, published alpha runtime, all three platform\nartifacts and install/build/verify evidence before writing\n`buildchain-canary/buildchain-zero-input` on that runtime commit. Manual replay\naccepts only the source run ID. This observation remains Buildchain-owned; it\nneither dispatches another repository nor grants stable publication authority.\n\n## Provider readback\n\nA stable release is complete only when all of these coordinates agree:\n\n- `release/v4/v4.0`, `v4`, `v4.0`, and the exact `v4.0.x` tag;\n- the GitHub Release tag and attached Release Passport evidence;\n- npm `@kungfu-tech/buildchain@4.0.x`, its sealed package integrity, and the `latest` tag;\n- the protected source and release transaction roots.\n\nThe immutable version tag identifies the publication source. Stable finalization\ncan place the release branch and floating runtime tags on a later generated\nversion commit. Verify their rooted version delta and ancestry rather than\nrequiring those distinct commits to be identical. Registry `gitHead`, when\npresent, is additional source evidence; publishing a sealed tarball can omit it.\nThe original payload manifest, published package digest and Passport retain the\nrequired source binding.\n\nThe alpha channel applies the same rule to `alpha/v4/v4.0`, `v4-alpha`, the\nexact alpha tag, and npm's `alpha` tag.\n\n## Non-destructive rollback\n\nRollback never rewrites an exact tag, release, package version, Passport, or\nprovider journal. Stop forward promotion and select the last verified exact\nv4 runtime through an admitted, non-persistent recovery input; keep tracked v4\nworkflow selectors on their locked floating channel. Use `release/v3/v3.0`\ncoordinate only as an explicit compatibility rollback reference. Restoring v3\nas production authority requires a new reviewed cutover; it is not an implicit\nfallback.\n\nBefore any retry, compare the current provider state with the retained\ntransaction and operation roots. Resume only missing eligible operations.\nConflicting state remains `repair-required` or terminal and must not be\nconverted into success by moving a floating ref.\n\n## Publication settlement and binary recovery\n\nPublication, next-development advancement, and binary distribution have separate\nresults. A completed native ReleaseReceipt remains publication evidence when the\nlater generated Dev PR is still pending or its enqueue call fails. SETTLE verifies\nthe immutable invocation, transaction, both provider states, receipt and Passport\nroots even when APPLY fails after publication. It has no provider write permission.\n\nAPPLY retains that exact chain before waiting for next-development in the existing GitHub Release as\n`buildchain-publication-settlement.json`; it reads the exact tag and original\n`buildchain.release.json` before adding the packet. The APPLY artifact also retains\n`delivery-summary.json`, which reports publication and next-development separately.\nA green workflow label cannot substitute for this receipt verification.\n\nRecovery verifies both its current execution chain and any already published\nsettlement against the exact tag, source and original Passport. It preserves\nthe existing settlement bytes and uses that original receipt for development\nadvancement. A corrected runtime may produce different recovery observations;\nthey do not authorize replacing the completed publication packet. Ambiguous,\ntampered or mismatched retained evidence still blocks recovery.\n\nBinary Distribution reads this settlement and the original publication Passport.\nTag creation can precede settlement, so it waits at most 160 observations, 15 seconds\napart, for missing evidence. A mismatched source, tag, Passport or receipt fails\nimmediately. It no longer requires a legacy `buildchain/release-state/*` ref for v4.\n\nThe sealed binary publisher retains the publication Passport and writes its own\nPassport as `buildchain.binary.release.json`. All v4 asset collisions are checked\nbefore uploads: identical bytes are preserved, absent assets are added, and\nconflicting bytes are rejected. Each publication authorization is retained as\n`buildchain.binary.capability-<sha256>.json`, so a fresh recovery capability does\nnot overwrite an earlier grant. Existing assets are never clobbered. Recovery uses\nthe same exact successful Binary Distribution evidence run through\n`self-release-binary-assets.yml`; it does not rebuild already admitted archives or\ncreate another npm version. Read back all three platform archives, checksums,\nboth Passports and the settlement packet before declaring distribution complete.\n\nThe native publication receipt authorizes no stable promotion and makes no claim\nthat a pending next-development PR has merged. Inspect the exact PR head, protected\nbase and merge result independently. A retry of the publication phase must first\nread retained provider facts and resume only missing operations.\n\n## Protected stable finalization\n\nA successful protected `Verify` on the release branch starts the same floating\nalpha publisher used for prereleases. The publisher creates the stable version\nPR and waits within the original transaction for protected merge and the exact\nmerged commit's successful `Verify`, before moving floating tags and completing\nthe publication receipt. Generated finalization heads are classified from their\nrooted product state and exact source tag, so their checks do not publish again.\n\nThe independent version reviewer also handles generated stable finalization PRs.\nIt requires the exact protected source parent, the rooted version-state parent,\nthe matching immutable stable tag, and byte-for-byte regeneration of the complete\ndeclared version delta. Verification uses protected source code without approval\ncredentials. A separate step approves only the verified head and enables normal\nprotected auto-merge. Changed source/base, modified PR contents, requested changes,\nfailed final checks, and timeout remain failures. Recover an interrupted run using\nthe original source and retained provider evidence; never rewrite published bytes.\n\n## Automatic next-development review\n\nAfter stable completion, the producer generates the next patch at `alpha.0`\nfrom an isolated Git checkout of the exact current protected Dev commit. The\ncheckout explicitly fetches the exact Dev commit into its own object database;\nshallow local clones alone may omit commits fetched only into `FETCH_HEAD`.\nIt retains its own index so version verification can inspect the actual\ngenerated delta, and uses the admitted runtime dependency bridge. A source\narchive without Git metadata cannot perform that verification. The publication\nreceipt remains complete if development preparation fails; recover the original\ntransaction with corrected, reviewed tooling before publishing the next version.\n\n`self-release-next-development.yml` observes a successful exact `Verify` PR run\nfor a same-repository `chore/next-development/*` branch. It executes only the\nprotected default branch runtime. The PR must have one parent equal to the\ncurrent protected Dev head. The protected generator reconstructs every tracked\nbyte, permits only the declared immediate alpha version increment, and verifies\nthe completed alpha settlement against the exact tag and original Passport.\nThe published source tree must equal the protected development base tree.\n\nThe verification step receives no approval credential and never executes PR\ncode. A separate step uses `BUILDCHAIN_APPROVAL_TOKEN`, verifies that its identity\nis the independent `kungfu-origin` CODEOWNER, rereads the exact PR/run/base, and\napproves only that commit. Existing requests for changes stop automation.\nThe exact approval is read back before queue admission with the separate\n`BUILDCHAIN_PROMOTION_TOKEN`. Required checks, CODEOWNER protection and native\nmerge-group verification remain enforced. Missing credentials or evidence,\nforks, source changes and base/head drift fail closed.\n\nThe producer waits for pending independent review and required checks with a\nbounded retry budget. Publication evidence is already durable during this wait,\nso binaries can proceed independently. The reviewer also enqueues the verified\nhead idempotently, allowing a producer interruption to leave a recoverable PR.\nAn interrupted producer run remains failed; a successful later release is needed\nto establish an uninterrupted end-to-end publication."
     },
     {
       "id": "manual:v4-publication-rehearsal",
@@ -6146,7 +6146,7 @@
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:bc609cad079a44afb8c2cf2b4459d44612bfd5ff09ed3064f85a2a3f02a5ec1e"
+      "digest": "sha256:58b91e75fc345ecd24377cf99a26ba344bc107016ef426ac5d99bb1c71d713b0"
     },
     {
       "id": "v4-adopter-delivery",

package/dist/site/kfd-claims.json

@@ -21,7 +21,7 @@
     "contract": "kungfu-buildchain-public-surface-reverse-audit",
     "path": "dist/site/public-surface-audit.json",
     "status": "passed",
-    "sha256": "3c5aab59b1a568e40cbe40061873013c742c01d6cae08b5f88048482f5d20053",
+    "sha256": "861ceb5042a6454b4fc530cafb04c4d633b32e058b9d8a1cd59d6cb916ca0fd0",
     "summary": {
       "cliCommandCount": 117,
       "workflowCount": 116,
@@ -246,7 +246,7 @@
       "contract": "kungfu-buildchain-public-surface-reverse-audit",
       "path": "dist/site/public-surface-audit.json",
       "status": "passed",
-      "sha256": "3c5aab59b1a568e40cbe40061873013c742c01d6cae08b5f88048482f5d20053",
+      "sha256": "861ceb5042a6454b4fc530cafb04c4d633b32e058b9d8a1cd59d6cb916ca0fd0",
       "summary": {
         "cliCommandCount": 117,
         "workflowCount": 116,

package/dist/site/kfd-upstream-aggregate.json

@@ -4,7 +4,7 @@
   "product": {
     "id": "kungfu-tech-buildchain",
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.9",
+    "version": "4.0.10-alpha.0",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "source": {

package/dist/site/manual-registry.json

@@ -433,7 +433,7 @@
       "title": "Reusable build surface",
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
-      "digest": "sha256:bc609cad079a44afb8c2cf2b4459d44612bfd5ff09ed3064f85a2a3f02a5ec1e",
+      "digest": "sha256:58b91e75fc345ecd24377cf99a26ba344bc107016ef426ac5d99bb1c71d713b0",
       "capabilityGroup": "reusable-build",
       "audience": [
         "consumer",

package/dist/site/page-registry.json

@@ -4440,7 +4440,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/reusable-build-surface.md",
-      "digest": "sha256:bc609cad079a44afb8c2cf2b4459d44612bfd5ff09ed3064f85a2a3f02a5ec1e",
+      "digest": "sha256:58b91e75fc345ecd24377cf99a26ba344bc107016ef426ac5d99bb1c71d713b0",
       "headings": [
         {
           "level": 1,
@@ -4478,7 +4478,7 @@
           "anchor": "maintaining-the-contract"
         }
       ],
-      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-reusable-build\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-08\nai_provenance:\n  model_family: GPT-6\n  product: Codex\n  generated_at: 2026-09-08\n  invisible_context_boundary: No private credentials or unrelated repositories inspected.\n---\n\n# Reusable Build Surface\n\nA project declares its build in `buildchain.toml`. The reusable workflow owns\njob sequencing, admission, runner boundaries and evidence aggregation. Ordinary\nsingle-project calls have no inputs:\n\n```yaml\npermissions:\n  actions: read\n  contents: read\n  issues: write\n  id-token: write\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v4\n```\n\nUse `@v4-alpha` to select the alpha runtime. The exact called workflow SHA is\nthe runtime SHA; a second runtime selector cannot override it. Both the public\n`build.yml` and the `.build.yml` backbone expose exactly one optional input:\n`config-path`. Neither accepts command overrides, runtime refs, arbitrary JSON\nconfiguration or legacy aliases.\n\n## Project discovery\n\nAt the repository root, exactly one of `.buildchain/buildchain.toml` and\n`buildchain.toml` must exist. Missing or ambiguous configurations fail before\nmatrix scheduling. A nested project is selected with its configuration location:\n\n```yaml\njobs:\n  native:\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v4-alpha\n    with:\n      config-path: packages/native/.buildchain/buildchain.toml\n```\n\nThe config location determines the project working directory. Planning and\nlifecycle execution discover the same file. Absolute paths, parent traversal,\nsymlink escape, malformed TOML and unknown `[build]` keys fail closed. A\nconfiguration locator cannot carry a profile override or execution authority.\n\n## Project configuration\n\n```toml\nschema = 1\n\n[lifecycle.install]\ncommand = \"corepack pnpm install --frozen-lockfile\"\n\n[lifecycle.build]\ncommand = \"corepack pnpm build\"\n\n[lifecycle.verify]\ncommand = \"corepack pnpm test\"\n\n[build]\nenvironment = \"github-hosted\"\ntimeout_minutes = 120\nfail_fast = false\n\n[build.tools]\nnode = \"24\"\nrust = \"stable\"\ngo = \"1.25.x\" # optional; omitted toolchains are not installed\n\n[build.artifacts]\nname = \"my-library\"\npaths = [\"dist\"]\nrequired_paths = [\"dist/library.js\"]\nmin_files = 1\nrelease_candidate = true\nretention_days = 14\ncompression_level = 0\n```\n\nCommands remain exclusively in `[lifecycle]`. The backbone explicitly invokes\ninstall, build and verify in that order on each platform. Build is required;\ninstall and verify are required when declared. Unneeded stages require no\nadditional boolean setting. Per-stage lifecycle timeout declarations retain\nprecedence over the build timeout fallback.\n\nArtifact paths and required file paths are relative to the selected project.\nPlatform artifact names derive from the configured base name,\nplatform and source SHA; callers do not supply naming templates. The final\nmanifest checks `min_files`, `max_files`, `min_total_bytes` and `required_paths`.\n\nOther optional project sections are:\n\n| TOML section | Responsibility |\n| --- | --- |\n| `build.diagnostics` | Process sampling and expected parallelism |\n| `build.verification` | Consumer-produced verify substage evidence location |\n| `build.finalization` | Verification of final signed bytes and platform placement |\n| `build.transport_smoke` | Transport simulation scenario and artifact root |\n| `build.attestation` | Subject path and attested platform |\n| `build.macos_signing` | App path and sealed-input platform |\n| `build.contract` | Compatibility and drift reporting policies |\n| `build.evidence` | Repository files containing gate and candidate-family evidence |\n\nDeclarative signing targets continue to belong to `[signing.artifacts]`.\nThe formal signing authority remains `authority/v3/v3.0/artifact-signing`\nwith the protected `buildchain-artifact-signing` environment.\nCredentials, authority profiles and signer identities cannot be supplied through\nthat declaration. See [Release Candidate](release-candidate.md)\nand [GitHub Artifact Attestation](github-artifact-attestation.md).\n\n## Governed environments\n\n`build.environment` selects a profile in\n[`architecture/build-environments.json`](../architecture/build-environments.json)\nfrom the exact Buildchain runtime. Infrastructure owners maintain runner\npresets/platforms, Linux container images, mirrors, cache transport, artifact\nrelay settings and credential-island environments there. Adding a runner label\nor provider role requires reviewing that profile; project TOML cannot redefine\nit. Secrets still cross explicit workflow secret/environment boundaries.\n\nThe initial profiles are `github-hosted`, `github-hosted-container`,\n`kungfu-v4-native` and `kungfu-v4-self-hosted`. The container profile uses the\nexisting digest-pinned `kungfu-verify` image. Native and container jobs remain\nseparate because GitHub selects `runs-on` and `container` before executing\nsteps. Their shared behavior is owned by these composite actions:\n\n| Action | Owner responsibility |\n| --- | --- |\n| `build-lifecycle-stage` | Lifecycle manifests, sampling and diagnostics |\n| `build-signing-request` | Unsigned requests and detached signing control inputs |\n| `build-verification-evidence` | Independent substage verification and failure evidence |\n| `build-attestation-policy` | Source-bound artifact attestation policy |\n| `build-agent-hub-evidence` | Agent Hub conformance evidence |\n| `build-artifact-transfer` | GitHub and S3 transport plus payload manifests |\n\nThe backbone still owns install → build → verify order, job dependencies,\npermissions, signing control, credential-island placement and final aggregation.\nA composite's internal receipt inputs transport already resolved facts; they\nare not additional reusable-workflow configuration inputs.\n\n## Identity and admission\n\nThe configuration resolver reads the exact consumer source without executing\nconsumer commands. It emits a deterministic plan/root binding configuration\nbytes, source SHA, called-workflow SHA, selected environment, toolchain and\ncache roots. Trust checks run before project execution or privileged runners.\n\nTracked consumer workflows use `@v4` or `@v4-alpha` and commit both\n`.buildchain/contract-lock.json` and `.buildchain/alpha-contract-lock.json`.\nThe called channel selects its matching lock. Source-persisted train/SHA\nselectors and mismatched locks remain forbidden. Ordinary builds have no\nruntime-override path; specialized release/recovery entry points keep their\nseparate, bounded admission contracts.\n\nBootstrap owns its admitted release and recovery capabilities. It is not an\nalternate parameter envelope for ordinary builds and is not injected into the\nbuild backbone. Release promotion consumes an already sealed candidate and\nmust verify the source, artifacts and receipts independently.\n\n## Evidence and failure behavior\n\nThe workflow retains runtime/source identity, build and diagnostics summaries,\nRelease Candidate Passport, signing/finalization and controller receipt outputs.\nThe public facade forwards those outputs from the single backbone execution.\nPlatform manifests include deterministic payload hashes; transport preserves\nhidden artifacts and provenance. Substage failure evidence is collected even\nwhen verify fails. Untrusted events cannot reach build runners.\n\nSigning authority and credential-island jobs remain separate from ordinary\nbuild execution. Imported signed bytes undergo consumer verification before\nmanifests are recomputed. Release builds produce candidates; registry publishing\nbelongs to the protected release path.\n\n## Maintaining the contract\n\nUpdate the TOML parser and plan resolver, owner contracts, affected consumers\nand tests together. Run `node scripts/generate-channel-build-workflow.mjs`,\n`pnpm run generate:workflows`, generated reference/site checks and the full\n`pnpm run check`. Breaking input removal is intentional: migrate old `with`\nsettings to TOML and remove them from calls; no compatibility forwarding exists.\n\nThe Buildchain fixture at `fixtures/libnode-shaped/buildchain.toml` exercises\nnative macOS/Windows and Linux-container builds through this public contract."
+      "markdown": "---\nstatus: draft\nperiod: ongoing\ntheme: buildchain-reusable-build\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: B\nreview_state: unreviewed\nlast_reviewed: 2026-09-09\nai_provenance:\n  model_family: GPT-6\n  product: Codex\n  generated_at: 2026-09-09\n  invisible_context_boundary: No private credentials or unrelated repositories inspected.\n---\n\n# Reusable Build Surface\n\nA project declares its build in `buildchain.toml`. The reusable workflow owns\njob sequencing, admission, runner boundaries and evidence aggregation. Ordinary\nsingle-project calls have no inputs:\n\n```yaml\npermissions:\n  actions: read\n  contents: read\n  issues: write\n  id-token: write\njobs:\n  build:\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v4\n```\n\nUse `@v4-alpha` to select the alpha runtime. The exact called workflow SHA is\nthe runtime SHA; a second runtime selector cannot override it. Both the public\n`build.yml` and the `.build.yml` backbone expose exactly one optional input:\n`config-path`. Neither accepts command overrides, runtime refs, arbitrary JSON\nconfiguration or legacy aliases.\n\n## Project discovery\n\nAt the repository root, exactly one of `.buildchain/buildchain.toml` and\n`buildchain.toml` must exist. Missing or ambiguous configurations fail before\nmatrix scheduling. A nested project is selected with its configuration location:\n\n```yaml\njobs:\n  native:\n    uses: kungfu-systems/buildchain/.github/workflows/build.yml@v4-alpha\n    with:\n      config-path: packages/native/.buildchain/buildchain.toml\n```\n\nThe config location determines the project working directory. Planning and\nlifecycle execution discover the same file. Absolute paths, parent traversal,\nsymlink escape, malformed TOML and unknown `[build]` keys fail closed. A\nconfiguration locator cannot carry a profile override or execution authority.\n\n## Project configuration\n\n```toml\nschema = 1\n\n[lifecycle.install]\ncommand = \"corepack pnpm install --frozen-lockfile\"\n\n[lifecycle.build]\ncommand = \"corepack pnpm build\"\n\n[lifecycle.verify]\ncommand = \"corepack pnpm test\"\n\n[build]\nenvironment = \"github-hosted\"\ntimeout_minutes = 120\nfail_fast = false\n\n[build.tools]\nnode = \"24\"\nrust = \"stable\"\ngo = \"1.25.x\" # optional; omitted toolchains are not installed\n\n[build.artifacts]\nname = \"my-library\"\npaths = [\"dist\"]\nrequired_paths = [\"dist/library.js\"]\nmin_files = 1\nrelease_candidate = true\nretention_days = 14\ncompression_level = 0\n```\n\nCommands remain exclusively in `[lifecycle]`. The backbone explicitly invokes\ninstall, build and verify in that order on each platform. Build is required;\ninstall and verify are required when declared. Unneeded stages require no\nadditional boolean setting. Per-stage lifecycle timeout declarations retain\nprecedence over the build timeout fallback.\n\nArtifact paths and required file paths are relative to the selected project.\nPlatform artifact names derive from the configured base name,\nplatform and source SHA; callers do not supply naming templates. The final\nmanifest checks `min_files`, `max_files`, `min_total_bytes` and `required_paths`.\n\nOther optional project sections are:\n\n| TOML section | Responsibility |\n| --- | --- |\n| `build.diagnostics` | Process sampling and expected parallelism |\n| `build.verification` | Consumer-produced verify substage evidence location |\n| `build.finalization` | Verification of final signed bytes and platform placement |\n| `build.transport_smoke` | Transport simulation scenario and artifact root |\n| `build.attestation` | Subject path and attested platform |\n| `build.macos_signing` | App path and sealed-input platform |\n| `build.contract` | Compatibility and drift reporting policies |\n| `build.evidence` | Repository files containing gate and candidate-family evidence |\n\nDeclarative signing targets continue to belong to `[signing.artifacts]`.\nThe formal signing authority remains `authority/v3/v3.0/artifact-signing`\nwith the protected `buildchain-artifact-signing` environment.\nCredentials, authority profiles and signer identities cannot be supplied through\nthat declaration. See [Release Candidate](release-candidate.md)\nand [GitHub Artifact Attestation](github-artifact-attestation.md).\n\n## Governed environments\n\n`build.environment` selects a profile in\n[`architecture/build-environments.json`](../architecture/build-environments.json)\nfrom the exact Buildchain runtime. Infrastructure owners maintain runner\npresets/platforms, Linux container images, mirrors, cache transport, artifact\nrelay settings and credential-island environments there. Adding a runner label\nor provider role requires reviewing that profile; project TOML cannot redefine\nit. Secrets still cross explicit workflow secret/environment boundaries.\n\nThe profiles are `github-hosted`, `github-hosted-container`, `kungfu-hosted`,\n`kungfu-v4-native` and `kungfu-v4-self-hosted`. `kungfu-hosted` preserves the\nKungfu release matrix on GitHub-hosted Ubuntu 24.04 x64 and ARM64, macOS 15\nARM64 and Windows 2022 x64. It selects GCC 14 for Linux x64, full Git history\nand the required Windows sccache profile at\n`docs/shifu/windows-alpha-sccache.cache-profile.json`, bound to its reviewed\ndigest in the environment registry. All four lanes transfer artifacts directly\nthrough GitHub; the profile adds no provider roles or signing authority.\nExisting profiles retain their runner and cache policies. The container profile\nuses the existing digest-pinned `kungfu-verify` image. Native and container jobs remain\nseparate because GitHub selects `runs-on` and `container` before executing\nsteps. Their shared behavior is owned by these composite actions:\n\n| Action | Owner responsibility |\n| --- | --- |\n| `build-lifecycle-stage` | Lifecycle manifests, sampling and diagnostics |\n| `build-signing-request` | Unsigned requests and detached signing control inputs |\n| `build-verification-evidence` | Independent substage verification and failure evidence |\n| `build-attestation-policy` | Source-bound artifact attestation policy |\n| `build-agent-hub-evidence` | Agent Hub conformance evidence |\n| `build-artifact-transfer` | GitHub and S3 transport plus payload manifests |\n\nThe backbone still owns install → build → verify order, job dependencies,\npermissions, signing control, credential-island placement and final aggregation.\nA composite's internal receipt inputs transport already resolved facts; they\nare not additional reusable-workflow configuration inputs.\n\n## Identity and admission\n\nThe configuration resolver reads the exact consumer source without executing\nconsumer commands. It emits a deterministic plan/root binding configuration\nbytes, source SHA, called-workflow SHA, selected environment, toolchain and\ncache roots. Trust checks run before project execution or privileged runners.\n\nTracked consumer workflows use `@v4` or `@v4-alpha` and commit both\n`.buildchain/contract-lock.json` and `.buildchain/alpha-contract-lock.json`.\nThe called channel selects its matching lock. Source-persisted train/SHA\nselectors and mismatched locks remain forbidden. Ordinary builds have no\nruntime-override path; specialized release/recovery entry points keep their\nseparate, bounded admission contracts.\n\nBootstrap owns its admitted release and recovery capabilities. It is not an\nalternate parameter envelope for ordinary builds and is not injected into the\nbuild backbone. Release promotion consumes an already sealed candidate and\nmust verify the source, artifacts and receipts independently.\n\n## Evidence and failure behavior\n\nThe workflow retains runtime/source identity, build and diagnostics summaries,\nRelease Candidate Passport, signing/finalization and controller receipt outputs.\nThe public facade forwards those outputs from the single backbone execution.\nPlatform manifests include deterministic payload hashes; transport preserves\nhidden artifacts and provenance. Substage failure evidence is collected even\nwhen verify fails. Untrusted events cannot reach build runners.\n\nSigning authority and credential-island jobs remain separate from ordinary\nbuild execution. Imported signed bytes undergo consumer verification before\nmanifests are recomputed. Release builds produce candidates; registry publishing\nbelongs to the protected release path.\n\n## Maintaining the contract\n\nUpdate the TOML parser and plan resolver, owner contracts, affected consumers\nand tests together. Run `node scripts/generate-channel-build-workflow.mjs`,\n`pnpm run generate:workflows`, generated reference/site checks and the full\n`pnpm run check`. Breaking input removal is intentional: migrate old `with`\nsettings to TOML and remove them from calls; no compatibility forwarding exists.\n\nThe Buildchain fixture at `fixtures/libnode-shaped/buildchain.toml` exercises\nnative macOS/Windows and Linux-container builds through this public contract."
     },
     {
       "id": "manual:runtime-train-validation",
@@ -4957,7 +4957,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/v4-production-release.md",
-      "digest": "sha256:078404ecd65922736de17039c43d160f6e3da971921a39c3fab10f437573e3ea",
+      "digest": "sha256:66c9c191777a2ea914f103d73f6b25ca894b114155c09ce46d926bcf55eb2298",
       "headings": [
         {
           "level": 1,
@@ -4995,7 +4995,7 @@
           "anchor": "automatic-next-development-review"
         }
       ],
-      "markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-v4-production-release\ndoc_type: runbook\nsource_level: repository-contracts + protected-provider-readback\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-09-08\nai_provenance:\n  model_family: GPT-6\n  product: Codex\n  generated_at: 2026-09-08\n  invisible_context: Provider credentials and private provider state were not read.\n---\n\n# Buildchain v4 production release\n\nBuildchain v4 is the production release authority for the `v4.0` line. The\nprotected source path is:\n\n```text\ndev/v4/v4.0 -> alpha/v4/v4.0 -> release/v4/v4.0\n```\n\nPublic consumers use `v4-alpha` for the current prerelease channel and `v4`\nfor stable, with matching stable and alpha contract locks. Exact commits and\nimmutable release tags identify retained evidence and explicitly admitted runtime\ninputs; tracked v4 reusable-workflow selectors remain `@v4` or `@v4-alpha`.\n\nBefore qualifying a new release, run `node scripts/check-universal-workflow-bootstrap.mjs`.\nThe required repository check rejects an expired or not-yet-valid candidate admission\npolicy before publication. Renew the bounded validity window through protected review;\nkeep its capability, permission, reviewer and exact-source requirements unchanged.\nHistorical publication receipts remain immutable when a later admission window expires.\n\nThe release transaction is fail-closed. The v4 provider-operation journal,\nactivation plan, stable publication fence, and partial-mutation recovery plan\nbind the exact source, qualification, policy, provider readback, protected\nancestry, and target roots. Confirmed operations are never replayed; uncertain\noperations require provider readback before retry; stable publication requires\nan N-1 or independently sealed qualification.\n\n## Public build qualification\n\nAfter a successful Alpha Self-Dogfood run, Stable Candidate Qualification reads\nits exact `buildchain-summary-<source SHA>` artifact. Protected default-branch\ncode verifies the source run, published alpha runtime, all three platform\nartifacts and install/build/verify evidence before writing\n`buildchain-canary/buildchain-zero-input` on that runtime commit. Manual replay\naccepts only the source run ID. This observation remains Buildchain-owned; it\nneither dispatches another repository nor grants stable publication authority.\n\n## Provider readback\n\nA stable release is complete only when all of these coordinates agree:\n\n- `release/v4/v4.0`, `v4`, `v4.0`, and the exact `v4.0.x` tag;\n- the GitHub Release tag and attached Release Passport evidence;\n- npm `@kungfu-tech/buildchain@4.0.x`, its `gitHead`, and the `latest` tag;\n- the protected source and release transaction roots.\n\nThe alpha channel applies the same rule to `alpha/v4/v4.0`, `v4-alpha`, the\nexact alpha tag, and npm's `alpha` tag.\n\n## Non-destructive rollback\n\nRollback never rewrites an exact tag, release, package version, Passport, or\nprovider journal. Stop forward promotion and select the last verified exact\nv4 runtime through an admitted, non-persistent recovery input; keep tracked v4\nworkflow selectors on their locked floating channel. Use `release/v3/v3.0`\ncoordinate only as an explicit compatibility rollback reference. Restoring v3\nas production authority requires a new reviewed cutover; it is not an implicit\nfallback.\n\nBefore any retry, compare the current provider state with the retained\ntransaction and operation roots. Resume only missing eligible operations.\nConflicting state remains `repair-required` or terminal and must not be\nconverted into success by moving a floating ref.\n\n## Publication settlement and binary recovery\n\nPublication, next-development advancement, and binary distribution have separate\nresults. A completed native ReleaseReceipt remains publication evidence when the\nlater generated Dev PR is still pending or its enqueue call fails. SETTLE verifies\nthe immutable invocation, transaction, both provider states, receipt and Passport\nroots even when APPLY fails after publication. It has no provider write permission.\n\nAPPLY retains that exact chain before waiting for next-development in the existing GitHub Release as\n`buildchain-publication-settlement.json`; it reads the exact tag and original\n`buildchain.release.json` before adding the packet. The APPLY artifact also retains\n`delivery-summary.json`, which reports publication and next-development separately.\nA green workflow label cannot substitute for this receipt verification.\n\nRecovery verifies both its current execution chain and any already published\nsettlement against the exact tag, source and original Passport. It preserves\nthe existing settlement bytes and uses that original receipt for development\nadvancement. A corrected runtime may produce different recovery observations;\nthey do not authorize replacing the completed publication packet. Ambiguous,\ntampered or mismatched retained evidence still blocks recovery.\n\nBinary Distribution reads this settlement and the original publication Passport.\nTag creation can precede settlement, so it waits at most 160 observations, 15 seconds\napart, for missing evidence. A mismatched source, tag, Passport or receipt fails\nimmediately. It no longer requires a legacy `buildchain/release-state/*` ref for v4.\n\nThe sealed binary publisher retains the publication Passport and writes its own\nPassport as `buildchain.binary.release.json`. All v4 asset collisions are checked\nbefore uploads: identical bytes are preserved, absent assets are added, and\nconflicting bytes are rejected. Each publication authorization is retained as\n`buildchain.binary.capability-<sha256>.json`, so a fresh recovery capability does\nnot overwrite an earlier grant. Existing assets are never clobbered. Recovery uses\nthe same exact successful Binary Distribution evidence run through\n`self-release-binary-assets.yml`; it does not rebuild already admitted archives or\ncreate another npm version. Read back all three platform archives, checksums,\nboth Passports and the settlement packet before declaring distribution complete.\n\nThe native publication receipt authorizes no stable promotion and makes no claim\nthat a pending next-development PR has merged. Inspect the exact PR head, protected\nbase and merge result independently. A retry of the publication phase must first\nread retained provider facts and resume only missing operations.\n\n## Protected stable finalization\n\nA successful protected `Verify` on the release branch starts the same floating\nalpha publisher used for prereleases. The publisher creates the stable version\nPR and waits within the original transaction for protected merge and the exact\nmerged commit's successful `Verify`, before moving floating tags and completing\nthe publication receipt. Generated finalization heads are classified from their\nrooted product state and exact source tag, so their checks do not publish again.\n\nThe independent version reviewer also handles generated stable finalization PRs.\nIt requires the exact protected source parent, the rooted version-state parent,\nthe matching immutable stable tag, and byte-for-byte regeneration of the complete\ndeclared version delta. Verification uses protected source code without approval\ncredentials. A separate step approves only the verified head and enables normal\nprotected auto-merge. Changed source/base, modified PR contents, requested changes,\nfailed final checks, and timeout remain failures. Recover an interrupted run using\nthe original source and retained provider evidence; never rewrite published bytes.\n\n## Automatic next-development review\n\nAfter stable completion, the producer generates the next patch at `alpha.0`\nfrom an isolated Git checkout of the exact current protected Dev commit. The\ncheckout explicitly fetches the exact Dev commit into its own object database;\nshallow local clones alone may omit commits fetched only into `FETCH_HEAD`.\nIt retains its own index so version verification can inspect the actual\ngenerated delta, and uses the admitted runtime dependency bridge. A source\narchive without Git metadata cannot perform that verification. The publication\nreceipt remains complete if development preparation fails; recover the original\ntransaction with corrected, reviewed tooling before publishing the next version.\n\n`self-release-next-development.yml` observes a successful exact `Verify` PR run\nfor a same-repository `chore/next-development/*` branch. It executes only the\nprotected default branch runtime. The PR must have one parent equal to the\ncurrent protected Dev head. The protected generator reconstructs every tracked\nbyte, permits only the declared immediate alpha version increment, and verifies\nthe completed alpha settlement against the exact tag and original Passport.\nThe published source tree must equal the protected development base tree.\n\nThe verification step receives no approval credential and never executes PR\ncode. A separate step uses `BUILDCHAIN_APPROVAL_TOKEN`, verifies that its identity\nis the independent `kungfu-origin` CODEOWNER, rereads the exact PR/run/base, and\napproves only that commit. Existing requests for changes stop automation.\nThe exact approval is read back before queue admission with the separate\n`BUILDCHAIN_PROMOTION_TOKEN`. Required checks, CODEOWNER protection and native\nmerge-group verification remain enforced. Missing credentials or evidence,\nforks, source changes and base/head drift fail closed.\n\nThe producer waits for pending independent review and required checks with a\nbounded retry budget. Publication evidence is already durable during this wait,\nso binaries can proceed independently. The reviewer also enqueues the verified\nhead idempotently, allowing a producer interruption to leave a recoverable PR.\nAn interrupted producer run remains failed; a successful later release is needed\nto establish an uninterrupted end-to-end publication."
+      "markdown": "---\nstatus: active\nperiod: ongoing\ntheme: buildchain-v4-production-release\ndoc_type: runbook\nsource_level: repository-contracts + protected-provider-readback\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: unreviewed\nlast_reviewed: 2026-09-08\nai_provenance:\n  model_family: GPT-6\n  product: Codex\n  generated_at: 2026-09-08\n  invisible_context: Provider credentials and private provider state were not read.\n---\n\n# Buildchain v4 production release\n\nBuildchain v4 is the production release authority for the `v4.0` line. The\nprotected source path is:\n\n```text\ndev/v4/v4.0 -> alpha/v4/v4.0 -> release/v4/v4.0\n```\n\nPublic consumers use `v4-alpha` for the current prerelease channel and `v4`\nfor stable, with matching stable and alpha contract locks. Exact commits and\nimmutable release tags identify retained evidence and explicitly admitted runtime\ninputs; tracked v4 reusable-workflow selectors remain `@v4` or `@v4-alpha`.\n\nWhen generated stable version commits make a direct alpha-to-release merge\nconflict, use the supported `publish-gate/release/v4/v4.0/<exact-alpha-version>`\nsource-lock PR. Its reconciliation commit preserves the exact published alpha\ntree and admits the current release head as a parent. Verify both parents and\ntree equality before review. This ancestry preparation does not grant publication\nqualification; the protected PR checks and native stable fence still apply.\n\nBefore qualifying a new release, run `node scripts/check-universal-workflow-bootstrap.mjs`.\nThe required repository check rejects an expired or not-yet-valid candidate admission\npolicy before publication. Renew the bounded validity window through protected review;\nkeep its capability, permission, reviewer and exact-source requirements unchanged.\nHistorical publication receipts remain immutable when a later admission window expires.\n\nThe release transaction is fail-closed. The v4 provider-operation journal,\nactivation plan, stable publication fence, and partial-mutation recovery plan\nbind the exact source, qualification, policy, provider readback, protected\nancestry, and target roots. Confirmed operations are never replayed; uncertain\noperations require provider readback before retry; stable publication requires\nan N-1 or independently sealed qualification.\n\n## Public build qualification\n\nAfter a successful Alpha Self-Dogfood run, Stable Candidate Qualification reads\nits exact `buildchain-summary-<source SHA>` artifact. Protected default-branch\ncode verifies the source run, published alpha runtime, all three platform\nartifacts and install/build/verify evidence before writing\n`buildchain-canary/buildchain-zero-input` on that runtime commit. Manual replay\naccepts only the source run ID. This observation remains Buildchain-owned; it\nneither dispatches another repository nor grants stable publication authority.\n\n## Provider readback\n\nA stable release is complete only when all of these coordinates agree:\n\n- `release/v4/v4.0`, `v4`, `v4.0`, and the exact `v4.0.x` tag;\n- the GitHub Release tag and attached Release Passport evidence;\n- npm `@kungfu-tech/buildchain@4.0.x`, its sealed package integrity, and the `latest` tag;\n- the protected source and release transaction roots.\n\nThe immutable version tag identifies the publication source. Stable finalization\ncan place the release branch and floating runtime tags on a later generated\nversion commit. Verify their rooted version delta and ancestry rather than\nrequiring those distinct commits to be identical. Registry `gitHead`, when\npresent, is additional source evidence; publishing a sealed tarball can omit it.\nThe original payload manifest, published package digest and Passport retain the\nrequired source binding.\n\nThe alpha channel applies the same rule to `alpha/v4/v4.0`, `v4-alpha`, the\nexact alpha tag, and npm's `alpha` tag.\n\n## Non-destructive rollback\n\nRollback never rewrites an exact tag, release, package version, Passport, or\nprovider journal. Stop forward promotion and select the last verified exact\nv4 runtime through an admitted, non-persistent recovery input; keep tracked v4\nworkflow selectors on their locked floating channel. Use `release/v3/v3.0`\ncoordinate only as an explicit compatibility rollback reference. Restoring v3\nas production authority requires a new reviewed cutover; it is not an implicit\nfallback.\n\nBefore any retry, compare the current provider state with the retained\ntransaction and operation roots. Resume only missing eligible operations.\nConflicting state remains `repair-required` or terminal and must not be\nconverted into success by moving a floating ref.\n\n## Publication settlement and binary recovery\n\nPublication, next-development advancement, and binary distribution have separate\nresults. A completed native ReleaseReceipt remains publication evidence when the\nlater generated Dev PR is still pending or its enqueue call fails. SETTLE verifies\nthe immutable invocation, transaction, both provider states, receipt and Passport\nroots even when APPLY fails after publication. It has no provider write permission.\n\nAPPLY retains that exact chain before waiting for next-development in the existing GitHub Release as\n`buildchain-publication-settlement.json`; it reads the exact tag and original\n`buildchain.release.json` before adding the packet. The APPLY artifact also retains\n`delivery-summary.json`, which reports publication and next-development separately.\nA green workflow label cannot substitute for this receipt verification.\n\nRecovery verifies both its current execution chain and any already published\nsettlement against the exact tag, source and original Passport. It preserves\nthe existing settlement bytes and uses that original receipt for development\nadvancement. A corrected runtime may produce different recovery observations;\nthey do not authorize replacing the completed publication packet. Ambiguous,\ntampered or mismatched retained evidence still blocks recovery.\n\nBinary Distribution reads this settlement and the original publication Passport.\nTag creation can precede settlement, so it waits at most 160 observations, 15 seconds\napart, for missing evidence. A mismatched source, tag, Passport or receipt fails\nimmediately. It no longer requires a legacy `buildchain/release-state/*` ref for v4.\n\nThe sealed binary publisher retains the publication Passport and writes its own\nPassport as `buildchain.binary.release.json`. All v4 asset collisions are checked\nbefore uploads: identical bytes are preserved, absent assets are added, and\nconflicting bytes are rejected. Each publication authorization is retained as\n`buildchain.binary.capability-<sha256>.json`, so a fresh recovery capability does\nnot overwrite an earlier grant. Existing assets are never clobbered. Recovery uses\nthe same exact successful Binary Distribution evidence run through\n`self-release-binary-assets.yml`; it does not rebuild already admitted archives or\ncreate another npm version. Read back all three platform archives, checksums,\nboth Passports and the settlement packet before declaring distribution complete.\n\nThe native publication receipt authorizes no stable promotion and makes no claim\nthat a pending next-development PR has merged. Inspect the exact PR head, protected\nbase and merge result independently. A retry of the publication phase must first\nread retained provider facts and resume only missing operations.\n\n## Protected stable finalization\n\nA successful protected `Verify` on the release branch starts the same floating\nalpha publisher used for prereleases. The publisher creates the stable version\nPR and waits within the original transaction for protected merge and the exact\nmerged commit's successful `Verify`, before moving floating tags and completing\nthe publication receipt. Generated finalization heads are classified from their\nrooted product state and exact source tag, so their checks do not publish again.\n\nThe independent version reviewer also handles generated stable finalization PRs.\nIt requires the exact protected source parent, the rooted version-state parent,\nthe matching immutable stable tag, and byte-for-byte regeneration of the complete\ndeclared version delta. Verification uses protected source code without approval\ncredentials. A separate step approves only the verified head and enables normal\nprotected auto-merge. Changed source/base, modified PR contents, requested changes,\nfailed final checks, and timeout remain failures. Recover an interrupted run using\nthe original source and retained provider evidence; never rewrite published bytes.\n\n## Automatic next-development review\n\nAfter stable completion, the producer generates the next patch at `alpha.0`\nfrom an isolated Git checkout of the exact current protected Dev commit. The\ncheckout explicitly fetches the exact Dev commit into its own object database;\nshallow local clones alone may omit commits fetched only into `FETCH_HEAD`.\nIt retains its own index so version verification can inspect the actual\ngenerated delta, and uses the admitted runtime dependency bridge. A source\narchive without Git metadata cannot perform that verification. The publication\nreceipt remains complete if development preparation fails; recover the original\ntransaction with corrected, reviewed tooling before publishing the next version.\n\n`self-release-next-development.yml` observes a successful exact `Verify` PR run\nfor a same-repository `chore/next-development/*` branch. It executes only the\nprotected default branch runtime. The PR must have one parent equal to the\ncurrent protected Dev head. The protected generator reconstructs every tracked\nbyte, permits only the declared immediate alpha version increment, and verifies\nthe completed alpha settlement against the exact tag and original Passport.\nThe published source tree must equal the protected development base tree.\n\nThe verification step receives no approval credential and never executes PR\ncode. A separate step uses `BUILDCHAIN_APPROVAL_TOKEN`, verifies that its identity\nis the independent `kungfu-origin` CODEOWNER, rereads the exact PR/run/base, and\napproves only that commit. Existing requests for changes stop automation.\nThe exact approval is read back before queue admission with the separate\n`BUILDCHAIN_PROMOTION_TOKEN`. Required checks, CODEOWNER protection and native\nmerge-group verification remain enforced. Missing credentials or evidence,\nforks, source changes and base/head drift fail closed.\n\nThe producer waits for pending independent review and required checks with a\nbounded retry budget. Publication evidence is already durable during this wait,\nso binaries can proceed independently. The reviewer also enqueues the verified\nhead idempotently, allowing a producer interruption to leave a recoverable PR.\nAn interrupted producer run remains failed; a successful later release is needed\nto establish an uninterrupted end-to-end publication."
     },
     {
       "id": "manual:v4-publication-rehearsal",

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

@@ -10639,8 +10639,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "547dde42a349a047f2aadcfc3ee9e3e31b6a7f6bfc75b7d37e5dcff7abd15308",
-    "workflowRegistryDigest": "fc2a924e1005b40e9d725cc9eaaffa499f96dcc42581ff419b9f254c3f33b5be",
-    "pageRegistryDigest": "09db5cdb5969b1c411bb23297b1943f35e6150b1f878582b43bd11f897884c10"
+    "workflowRegistryDigest": "5c2a53c099e5e5164bd7dcf33a0020af3f46d1037b697b7ea2195f8c8c333b37",
+    "pageRegistryDigest": "4e167e415d89756e862dd2cd01c808d1861918fccc87f721a43ff4c5dd348cbd"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "c951b90a6dc6cffa8e62a75218194019ad47679f",
+  "sourceRevision": "626d32c65639db26e308ac1e25d6a8062f5df6f8",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.9",
+    "version": "4.0.10-alpha.0",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/site-manifest.json

@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "c951b90a6dc6cffa8e62a75218194019ad47679f",
+  "sourceRevision": "626d32c65639db26e308ac1e25d6a8062f5df6f8",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.9",
+    "version": "4.0.10-alpha.0",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -293,7 +293,7 @@
       "path": "docs/reusable-build-surface.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:bc609cad079a44afb8c2cf2b4459d44612bfd5ff09ed3064f85a2a3f02a5ec1e"
+      "digest": "sha256:58b91e75fc345ecd24377cf99a26ba344bc107016ef426ac5d99bb1c71d713b0"
     },
     {
       "id": "v4-adopter-delivery",

package/dist/site/workflow-registry.json

@@ -2464,7 +2464,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.9",
+      "introducedVersion": "4.0.10-alpha.0",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -3565,7 +3565,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.9",
+      "introducedVersion": "4.0.10-alpha.0",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -5656,7 +5656,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.9",
+      "introducedVersion": "4.0.10-alpha.0",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -5687,7 +5687,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.9",
+      "introducedVersion": "4.0.10-alpha.0",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -5718,7 +5718,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.9",
+      "introducedVersion": "4.0.10-alpha.0",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",

package/docs/reusable-build-surface.md

@@ -8,11 +8,11 @@ confidence: high
 sensitivity: public
 evidence_grade: B
 review_state: unreviewed
-last_reviewed: 2026-09-08
+last_reviewed: 2026-09-09
 ai_provenance:
   model_family: GPT-6
   product: Codex
-  generated_at: 2026-09-08
+  generated_at: 2026-09-09
   invisible_context_boundary: No private credentials or unrelated repositories inspected.
 ---
 
@@ -133,9 +133,16 @@ relay settings and credential-island environments there. Adding a runner label
 or provider role requires reviewing that profile; project TOML cannot redefine
 it. Secrets still cross explicit workflow secret/environment boundaries.
 
-The initial profiles are `github-hosted`, `github-hosted-container`,
-`kungfu-v4-native` and `kungfu-v4-self-hosted`. The container profile uses the
-existing digest-pinned `kungfu-verify` image. Native and container jobs remain
+The profiles are `github-hosted`, `github-hosted-container`, `kungfu-hosted`,
+`kungfu-v4-native` and `kungfu-v4-self-hosted`. `kungfu-hosted` preserves the
+Kungfu release matrix on GitHub-hosted Ubuntu 24.04 x64 and ARM64, macOS 15
+ARM64 and Windows 2022 x64. It selects GCC 14 for Linux x64, full Git history
+and the required Windows sccache profile at
+`docs/shifu/windows-alpha-sccache.cache-profile.json`, bound to its reviewed
+digest in the environment registry. All four lanes transfer artifacts directly
+through GitHub; the profile adds no provider roles or signing authority.
+Existing profiles retain their runner and cache policies. The container profile
+uses the existing digest-pinned `kungfu-verify` image. Native and container jobs remain
 separate because GitHub selects `runs-on` and `container` before executing
 steps. Their shared behavior is owned by these composite actions:
 

package/docs/v4-production-release.md

@@ -30,6 +30,13 @@ for stable, with matching stable and alpha contract locks. Exact commits and
 immutable release tags identify retained evidence and explicitly admitted runtime
 inputs; tracked v4 reusable-workflow selectors remain `@v4` or `@v4-alpha`.
 
+When generated stable version commits make a direct alpha-to-release merge
+conflict, use the supported `publish-gate/release/v4/v4.0/<exact-alpha-version>`
+source-lock PR. Its reconciliation commit preserves the exact published alpha
+tree and admits the current release head as a parent. Verify both parents and
+tree equality before review. This ancestry preparation does not grant publication
+qualification; the protected PR checks and native stable fence still apply.
+
 Before qualifying a new release, run `node scripts/check-universal-workflow-bootstrap.mjs`.
 The required repository check rejects an expired or not-yet-valid candidate admission
 policy before publication. Renew the bounded validity window through protected review;
@@ -59,9 +66,17 @@ A stable release is complete only when all of these coordinates agree:
 
 - `release/v4/v4.0`, `v4`, `v4.0`, and the exact `v4.0.x` tag;
 - the GitHub Release tag and attached Release Passport evidence;
-- npm `@kungfu-tech/buildchain@4.0.x`, its `gitHead`, and the `latest` tag;
+- npm `@kungfu-tech/buildchain@4.0.x`, its sealed package integrity, and the `latest` tag;
 - the protected source and release transaction roots.
 
+The immutable version tag identifies the publication source. Stable finalization
+can place the release branch and floating runtime tags on a later generated
+version commit. Verify their rooted version delta and ancestry rather than
+requiring those distinct commits to be identical. Registry `gitHead`, when
+present, is additional source evidence; publishing a sealed tarball can omit it.
+The original payload manifest, published package digest and Passport retain the
+required source binding.
+
 The alpha channel applies the same rule to `alpha/v4/v4.0`, `v4-alpha`, the
 exact alpha tag, and npm's `alpha` tag.
 

package/package.json

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