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

package/docs/reusable-build-surface.md

@@ -8,17 +8,17 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-07-27
+last_reviewed: 2026-07-31
 ai_provenance:
   model_family: GPT-5
   product: Codex
-  generated_at: 2026-07-27
+  generated_at: 2026-07-30
   invisible_context: not asserted
 ---
 
 # Reusable Build Surface
 
-Buildchain v2 provides a reusable build workflow for repositories that need
+Buildchain v3 provides a reusable build workflow for repositories that need
 Buildchain's release semantics but cannot be described as a simple Node package.
 The first target shape is `libnode`: expensive native builds, multiple operating
 systems, self-hosted runner labels, and release artifacts that must be auditable.
@@ -31,9 +31,8 @@ only signs and verifies immutable data. See
 
 ## Automatic Channel Router
 
-The preferred consumer surface is one reusable workflow call. After v2.12
-reaches the stable major ref, consumers keep this configuration for both alpha
-development and stable release work:
+The preferred consumer surface is one reusable workflow call. Consumers keep
+this configuration for both alpha development and stable release work:
 
 ```yaml
 jobs:
@@ -79,10 +78,10 @@ with:
   buildchain-channel: stable
 ```
 
-During the v2.12 prerelease evaluation window, canaries use
-`build.yml@v3-alpha`. The same router then selects `v3-alpha` or stable `v2` as
-the runtime. Production consumers should adopt `build.yml@v3` after the router
-has reached stable; this keeps the routing shell itself on a stable ref.
+During v3 prerelease evaluation windows, canaries use `build.yml@v3-alpha`.
+The same router then selects `v3-alpha` or stable `v3` as the runtime.
+Production consumers use `build.yml@v3`; this keeps the routing shell itself on
+a stable ref.
 
 The router is generated from `.build.yml`'s input/output surface. Run
 `node scripts/generate-channel-build-workflow.mjs` after changing the advanced
@@ -116,12 +115,33 @@ jobs:
 
 `runner-preset` is the stable first-class surface for known runner fleets:
 
-| Preset                  | Platforms                                                                |
-| ----------------------- | ------------------------------------------------------------------------ |
-| `github-hosted`         | `ubuntu-24.04`, `macos-latest`, `windows-2022`                                                              |
-| `kungfu-v4-self-hosted` | Kungfu Linux x64, macOS ARM64, and Windows x64 self-hosted runner labels                                    |
+| Preset                  | Platforms                                                                                                      |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `github-hosted`         | `ubuntu-24.04`, `macos-latest`, `windows-2022`                                                                 |
+| `kungfu-v4-self-hosted` | Kungfu Linux x64, macOS ARM64, and Windows x64 self-hosted runner labels                                       |
 | `kungfu-v4-native`      | Kungfu Linux x64, Linux ARM64, macOS ARM64, and Windows x64; Linux ARM64 uses GitHub-hosted `ubuntu-24.04-arm` |
-| `custom`                | Requires `platforms-json`                                                                                   |
+| `custom`                | Requires `platforms-json`                                                                                      |
+
+Set `self-hosted-offline-fallback: true` to inspect every exact-label
+self-hosted lane from the trusted Buildchain workflow shell before the matrix
+starts. A lane with no matching online runner is replaced independently by its
+supported GitHub-hosted runner: Kungfu Linux x64 uses `ubuntu-24.04`, macOS ARM64
+uses `macos-15`, and Windows x64 uses `windows-2022`. Online-but-busy runners
+remain online and keep their declared self-hosted route. Organization-owned
+repositories inspect organization runner inventory so selected-repository runner
+groups are not mistaken for an empty repository runner inventory. If the
+inventory token, permission, or API is unavailable, Buildchain preserves the
+original matrix instead of guessing that the fleet is offline. The public
+workflow output `runner-routing-json` records only de-identified counts,
+inventory scope, and routing decisions.
+
+```yaml
+with:
+  runner-preset: kungfu-v4-native
+  self-hosted-offline-fallback: true
+secrets:
+  BUILDCHAIN_PROMOTION_TOKEN: ${{ secrets.KUNGFU_GITHUB_TOKEN }}
+```
 
 Callers can still provide a custom matrix with `platforms-json`. Each platform
 object has:
@@ -268,23 +288,30 @@ jobs:
 
 Allowed override refs are deliberately narrow:
 
-| Ref form | Meaning |
-| --- | --- |
-| `train/v3/v3.0/<capability>` | Temporary capability train under the active minor line |
-| `refs/heads/train/v3/v3.0/<capability>` | Explicit branch ref for the same train |
-| `<40-character SHA>` | Exact immutable Buildchain runtime commit |
+| Ref form                                | Meaning                                                |
+| --------------------------------------- | ------------------------------------------------------ |
+| `train/v3/v3.0/<capability>`            | Temporary capability train under the active minor line |
+| `refs/heads/train/v3/v3.0/<capability>` | Explicit branch ref for the same train                 |
+| `<40-character SHA>`                    | Exact immutable Buildchain runtime commit              |
 
 Override requests fail closed unless the event is `workflow_dispatch` and the
-actor has write, maintain, or admin permission on the caller repository.
+actor has write, maintain, or admin permission on the caller repository. One
+non-override exact-pin case is also admitted: when the reusable workflow itself
+is invoked from an exact Buildchain SHA and `buildchain-ref` names that identical
+SHA, the run records `pinned-self`. The input cannot select code other than the
+already-running workflow shell, so protected push and pull-request publication
+jobs can retain one immutable runtime root. Different SHA and train requests
+still fail closed outside trusted manual dispatch.
+
 Pull requests, including same-repository pull requests and fork-originated pull
-requests, cannot use `buildchain-ref` override. This keeps automated PR builds on
-the stable runtime surface.
+requests, cannot select an independent `buildchain-ref` override. This keeps
+automated PR builds on the stable or exact pinned-self runtime surface.
 
 Every run resolves the runtime ref to an immutable SHA before checkout. The job
 summary and aggregate build summary record the workflow shell ref, requested
 runtime ref, resolved runtime ref, runtime SHA, stability class, trust decision,
 and rollback ref. Train refs are development validation refs: they do not move
-`v2`, `vX.Y`, `vX.Y-alpha`, npm dist-tags, or production release refs, and they
+`v3`, `vX.Y`, `vX.Y-alpha`, npm dist-tags, or production release refs, and they
 must not be pinned as long-term production dependencies.
 
 Runtime override validates Buildchain runtime scripts, CLI code, local actions,
@@ -304,13 +331,13 @@ major line, and compatibility policy they reviewed.
 
 The reusable build trust gate checks this lock before any heavy matrix job:
 
-1. resolve the Buildchain runtime ref, for example `v2`, to an immutable SHA;
+1. resolve the Buildchain runtime ref, for example `v3`, to an immutable SHA;
 2. read `dist/site/buildchain-contract.json` from that checked-out Buildchain
    ref;
 3. read the consumer's `.buildchain/contract-lock.json`;
 4. compare the accepted contract with the current contract.
 
-SHA drift alone is not a failure. `v2` is expected to advance. Buildchain only
+SHA drift alone is not a failure. `v3` is expected to advance. Buildchain only
 fails fast when the accepted contract is no longer compatible, for example a
 required input is removed, a required output disappears, a protected behavior
 promise changes, or the major line changes. Additive changes such as optional
@@ -416,11 +443,11 @@ jobs:
 
 `checkout-cache-mode` accepts:
 
-| Mode | Behavior |
-| --- | --- |
-| `off` | Default. Buildchain fetches the locked commit from GitHub. |
-| `auto` | Try the trusted cache first; on miss, record the miss and fall back according to `checkout-cache-fallback`. |
-| `require` | Require the cache to provide the locked commit and fail before lifecycle work if unavailable. |
+| Mode      | Behavior                                                                                                    |
+| --------- | ----------------------------------------------------------------------------------------------------------- |
+| `off`     | Default. Buildchain fetches the locked commit from GitHub.                                                  |
+| `auto`    | Try the trusted cache first; on miss, record the miss and fall back according to `checkout-cache-fallback`. |
+| `require` | Require the cache to provide the locked commit and fail before lifecycle work if unavailable.               |
 
 The cache can be a local/LAN mirror URL template or a runner-local bare
 reference repository template. Templates support `{owner}`, `{repo}`,
@@ -466,6 +493,33 @@ Runtime checkout evidence is uploaded separately as `runtime-checkout.json`,
 including cache transport, fallback attempts, and exact runtime `HEAD`
 verification, even when a later lifecycle step fails.
 
+## Auditable Compiler Cache
+
+Consumers can prepare `sccache` on selected platforms after the install
+lifecycle and before compilation:
+
+```yaml
+with:
+  compiler-cache-provider: sccache
+  compiler-cache-platforms-json: '["windows-x64"]'
+  compiler-cache-required: true
+```
+
+The consumer remains responsible for installing and pinning the tool before
+the preparation step. Buildchain probes its version, runs `sccache
+--zero-stats`, and writes
+`compiler-cache-preparation.json`. The receipt binds the source commit/tree,
+Buildchain runtime, platform, cache profile, and any declared dependency,
+toolchain, or policy roots. It resets counters only; it does not delete cached
+compiler outputs.
+
+Final diagnostics admit sccache hit/miss outcomes as current-run evidence only
+when that preparation receipt is present and valid. A bare `sccache
+--show-stats` result without the reset receipt remains cumulative and is
+reported as unavailable for the current run. The preparation receipt is copied
+into the small diagnostics artifact and sealed by
+`diagnostics-manifest.json`.
+
 When a Buildchain maintainer asks for downstream validation, the expected
 request is:
 
@@ -484,38 +538,38 @@ separate periodic cleanup task.
 
 The reusable workflow exposes the resolved contract:
 
-| Output                            | Meaning                                                                         |
-| --------------------------------- | ------------------------------------------------------------------------------- |
-| `runner-preset`                   | Resolved preset, or `custom` when `platforms-json` was provided                 |
-| `platforms-json`                  | Exact matrix JSON used by the build job                                         |
-| `platform-count`                  | Number of matrix platforms                                                      |
-| `linux-container-enabled`         | `true` when Linux platforms are routed through a job container                  |
-| `linux-container-image`           | Resolved digest-pinned Linux job container image                                |
-| `build-summary-artifact`          | Uploaded aggregate summary artifact name                                        |
-| `build-diagnostics-summary-artifact` | Uploaded aggregate diagnostics summary artifact name                         |
-| `release-candidate-passport-artifact` | Uploaded PR-stage release-candidate passport artifact name when `release-candidate` is enabled |
-| `release-candidate-passport-json` | Compact release-candidate passport JSON when `release-candidate` is enabled     |
-| `build-summary-json`              | Compact aggregate JSON with platform count, file count, and byte total          |
-| `build-diagnostics-summary-json`  | Compact aggregate diagnostics JSON with platform, lifecycle warning/error, diagnostics contract warning, and sidecar manifest warning totals |
-| `trusted-event`                   | `true` when the event is trusted enough to reach build runners                  |
-| `buildchain-runtime-ref`          | Runtime ref selected after applying the empty-default or override policy        |
-| `buildchain-runtime-sha`          | Immutable Buildchain runtime commit used by all runtime checkouts               |
-| `buildchain-runtime-class`        | `stable`, `alpha`, `authority`, `train`, `exact-sha`, or `development`          |
-| `buildchain-runtime-override`     | `true` when an authority, train, or exact-SHA `buildchain-ref` override was accepted |
-| `buildchain-runtime-trust-decision` | Runtime override trust decision                                               |
-| `buildchain-contract-lock-status` | `unchanged`, `compatible-drift`, `breaking-drift`, `missing-lock`, `non-floating-runtime`, or first-release `runtime-contract-unavailable` |
-| `buildchain-contract-lock-drift`  | `true` when the floating runtime SHA or contract digest changed                 |
-| `buildchain-contract-digest`      | Current Buildchain runtime contract digest                                      |
-| `publish-channel`                 | Resolved publish channel requested by the caller                                |
-| `publish-allowed`                 | `true` only when this event/ref may publish after verification                  |
-| `publish-reason`                  | Human-readable reason for the publish gate decision                             |
-| `publish-source-ref`              | Gate source ref that was resolved before checkout                               |
-| `publish-source-sha`              | Exact source commit used by checkout, build, verify, and artifacts              |
-| `publish-source-locked`           | `true` when a `publish-gate/*` source ref was explicitly locked                 |
-| `publish-source-channel`          | `alpha`, `release`, `anchor`, or `major` parsed from the source ref             |
-| `publish-source-line`             | Product line parsed from source refs such as `v22/v22.22`                       |
-| `publish-source-consumer-version` | Consumer package version parsed from source refs                                |
-| `release-manifest-json`           | Resolved release manifest including source lock, version state, and anchor data |
+| Output                                | Meaning                                                                                                                                      |
+| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `runner-preset`                       | Resolved preset, or `custom` when `platforms-json` was provided                                                                              |
+| `platforms-json`                      | Exact matrix JSON used by the build job                                                                                                      |
+| `platform-count`                      | Number of matrix platforms                                                                                                                   |
+| `linux-container-enabled`             | `true` when Linux platforms are routed through a job container                                                                               |
+| `linux-container-image`               | Resolved digest-pinned Linux job container image                                                                                             |
+| `build-summary-artifact`              | Uploaded aggregate summary artifact name                                                                                                     |
+| `build-diagnostics-summary-artifact`  | Uploaded aggregate diagnostics summary artifact name                                                                                         |
+| `release-candidate-passport-artifact` | Uploaded PR-stage release-candidate passport artifact name when `release-candidate` is enabled                                               |
+| `release-candidate-passport-json`     | Compact release-candidate passport JSON when `release-candidate` is enabled                                                                  |
+| `build-summary-json`                  | Compact aggregate JSON with platform count, file count, and byte total                                                                       |
+| `build-diagnostics-summary-json`      | Compact aggregate diagnostics JSON with platform, lifecycle warning/error, diagnostics contract warning, and sidecar manifest warning totals |
+| `trusted-event`                       | `true` when the event is trusted enough to reach build runners                                                                               |
+| `buildchain-runtime-ref`              | Runtime ref selected after applying the empty-default or override policy                                                                     |
+| `buildchain-runtime-sha`              | Immutable Buildchain runtime commit used by all runtime checkouts                                                                            |
+| `buildchain-runtime-class`            | `stable`, `alpha`, `authority`, `train`, `exact-sha`, or `development`                                                                       |
+| `buildchain-runtime-override`         | `true` when an authority, train, or exact-SHA `buildchain-ref` override was accepted                                                         |
+| `buildchain-runtime-trust-decision`   | Runtime override trust decision                                                                                                              |
+| `buildchain-contract-lock-status`     | `unchanged`, `compatible-drift`, `breaking-drift`, `missing-lock`, `non-floating-runtime`, or first-release `runtime-contract-unavailable`   |
+| `buildchain-contract-lock-drift`      | `true` when the floating runtime SHA or contract digest changed                                                                              |
+| `buildchain-contract-digest`          | Current Buildchain runtime contract digest                                                                                                   |
+| `publish-channel`                     | Resolved publish channel requested by the caller                                                                                             |
+| `publish-allowed`                     | `true` only when this event/ref may publish after verification                                                                               |
+| `publish-reason`                      | Human-readable reason for the publish gate decision                                                                                          |
+| `publish-source-ref`                  | Gate source ref that was resolved before checkout                                                                                            |
+| `publish-source-sha`                  | Exact source commit used by checkout, build, verify, and artifacts                                                                           |
+| `publish-source-locked`               | `true` when a `publish-gate/*` source ref was explicitly locked                                                                              |
+| `publish-source-channel`              | `alpha`, `release`, `anchor`, or `major` parsed from the source ref                                                                          |
+| `publish-source-line`                 | Product line parsed from source refs such as `v22/v22.22`                                                                                    |
+| `publish-source-consumer-version`     | Consumer package version parsed from source refs                                                                                             |
+| `release-manifest-json`               | Resolved release manifest including source lock, version state, and anchor data                                                              |
 
 The aggregate summaries are intentionally artifacts as well as outputs. GitHub
 Actions matrix outputs are not a reliable place to carry every platform's full
@@ -562,11 +616,46 @@ lifecycle and before verification. Buildchain binds the exact artifact bytes or
 the caller repository, source commit, source tree, immutable runtime, platform,
 and requested signature semantics, then publishes a deterministic
 `<artifact>-signing-request-<platform>-<source-sha>` request. No consumer
-workflow step is required.
+workflow step is required. The lifecycle runner automatically adds declarations
+selected for the current platform to the `build` manifest scan, including
+subjects outside the caller's ordinary `artifact-paths`; this extends the
+evidence preimage without silently adding those subjects to the ordinary
+artifact upload.
+
+The request root is a Buildchain-owned generated output. After the declaration,
+lifecycle manifest, and source paths pass validation, sealing replaces that root
+before materializing the current request set. This keeps repeated jobs on a
+self-hosted runner idempotent and prevents stale requests from an earlier run
+from entering the uploaded request artifact. An output root that contains the
+workspace, working directory, lifecycle manifest, or any declared subject is
+rejected before cleanup.
+
+Self-hosted runners whose network requires different routes for Artifact upload
+and download can scope an upload-only proxy bypass to the sealed signing request:
+
+```yaml
+with:
+  artifact-signing-request-upload-no-proxy: ".blob.core.windows.net"
+```
+
+The caller repository variable
+`BUILDCHAIN_ARTIFACT_SIGNING_REQUEST_UPLOAD_NO_PROXY` provides the same value
+without changing a consumer workflow; an explicit workflow input takes
+precedence. When neither is set, Buildchain preserves the runner's existing
+`NO_PROXY` and `no_proxy` values. The resolved value applies only to the
+Buildchain-owned signing-request upload. Authority dispatch and immutable
+signed-result download keep the runner's original proxy route. This is a
+transport control only: it does not change request bytes, signing authority,
+artifact identity, or verification policy.
 
 `profile = "auto"` resolves signable Apple artifacts such as Mach-O files,
-`.dylib`, `.framework`, `.app`, `.xpc`, `.plugin`, `.pkg`, and `.dmg` to the
-native `apple-developer-id` provider. Windows `pe` and `binary` artifacts
+`.dylib`, `.framework`, `.app`, `.xpc`, `.plugin`, `.pkg`, `.dmg`, and macOS
+archives containing native code to the native `apple-developer-id` provider.
+For a declared macOS `archive`, the authority safely extracts the sealed
+container, signs and verifies every Mach-O payload, signs Mach-O payloads inside
+embedded Python wheels, rebuilds each affected wheel's PEP 427 `RECORD`, and
+recreates the original zip or tar.gz before returning the exact final bytes.
+Windows `pe` and `binary` artifacts
 resolve to timestamped native `windows-authenticode`; Windows PE never falls
 back to a detached signature. Linux and other non-native binary files,
 archives, blobs, and directories resolve to `detached-signature-v1`. Buildchain records that as a
@@ -582,9 +671,40 @@ evidence. Consumer repositories neither receive nor duplicate credential-island
 material. The reusable workflow dispatches the sealed request to the
 Buildchain repository, waits for its protected authority workflow, verifies the
 immutable result, replaces only the declared artifact with the returned final
-bytes, and then runs the consumer's normal verification. Platform manifests,
-KFD evidence, checksums, and Release Passport inputs therefore observe the
-final signed artifact rather than the pre-signing build output.
+bytes. The ordinary platform lane completes the consumer's functional
+verification before delegation. A GitHub-hosted finalization lane then verifies
+the authority result against the sealed request, imports the exact signed bytes,
+and recomputes the final manifest before replacing the deterministic artifact.
+The signing result is never downloaded back to a self-hosted native runner.
+Platform manifests, KFD evidence, checksums, and Release Passport inputs
+therefore observe the final signed artifact rather than the pre-signing build
+output.
+
+For a standalone Mach-O request, the authority requires strict Developer ID
+verification, the declared Team ID, hardened runtime, and an `Accepted`
+`notarytool` result for the exact submission. Apple creates the notarization
+ticket for that binary and publishes it online, but
+[standalone binaries do not support stapling](https://developer.apple.com/documentation/security/customizing-the-notarization-workflow).
+Buildchain therefore records
+`standalone-notary-ticket-online` and does not misapply app-bundle
+`spctl --assess --type execute` semantics to the raw executable.
+
+For a compound archive request, the authority notarizes the complete extracted
+signed product tree and records `compound-notary-ticket-online`. A generic
+archive container cannot carry a stapled ticket and is not itself a Gatekeeper
+execution target; Gatekeeper evaluates the extracted signed code. Archive path
+and symlink validation fail closed before any payload is signed.
+
+For a declared `app-bundle`, the same protected authority extracts the sealed
+application, derives and verifies its bundle identity, signs nested native code,
+submits both the application and disk image for notarization, staples and
+Gatekeeper-assesses both deliverables, and returns a ZIP, DMG, evidence document,
+and source-bound manifest. The reusable workflow verifies those returned bytes
+on GitHub-hosted infrastructure, adds them to the normal macOS platform payload,
+and publishes a separate `<artifact>-macos-credential-<source-sha>` projection
+for release pipelines that consume the credential-island evidence contract.
+Consumers declare the `.app` under `[[signing.artifacts]]`; they do not configure
+an environment, certificate, notary credential, or authority workflow.
 
 The durable v3 authority runtime is
 `authority/v3/v3.0/artifact-signing`. It is channel-neutral: alpha and stable
@@ -606,8 +726,17 @@ to GitHub artifacts:
 ```yaml
 with:
   artifact-transfer-mode: github-artifacts
+  artifact-compression-level: 0
 ```
 
+Direct GitHub Artifact payloads default to compression level `0`. Buildchain
+artifacts are commonly already-compressed archives; storing them without a
+second compression pass shortens the upload window while preserving the same
+artifact name, run/id/digest binding, retention, and no-overwrite behavior.
+Callers may select `1` through `9` for payloads that materially benefit from
+compression. Manifests and diagnostics retain their existing small-artifact
+behavior.
+
 Large self-hosted native builds can opt into the first-class S3 relay path:
 
 ```yaml
@@ -643,15 +772,15 @@ The relay configuration is intentionally generic. Buildchain does not hard-code
 organization buckets, regions, or role ARNs. Callers may pass explicit inputs,
 or set repository/organization variables and secrets using these names:
 
-| Variable or secret | Meaning |
-| --- | --- |
-| `BUILDCHAIN_ARTIFACT_RELAY_S3_BUCKET` | Relay bucket name |
-| `BUILDCHAIN_ARTIFACT_RELAY_S3_REGION` | Relay bucket region |
-| `BUILDCHAIN_ARTIFACT_RELAY_S3_PREFIX` | Relay object prefix; defaults to `buildchain-artifacts` |
-| `BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN` | Shared OIDC role ARN for upload and download |
-| `BUILDCHAIN_ARTIFACT_RELAY_S3_UPLOAD_ROLE_ARN` | Upload OIDC role ARN for self-hosted build jobs |
-| `BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN` | Download OIDC role ARN for the GitHub-hosted relay job |
-| `BUILDCHAIN_ARTIFACT_RELAY_S3_OIDC_AUDIENCE` | Optional OIDC audience override |
+| Variable or secret                               | Meaning                                                 |
+| ------------------------------------------------ | ------------------------------------------------------- |
+| `BUILDCHAIN_ARTIFACT_RELAY_S3_BUCKET`            | Relay bucket name                                       |
+| `BUILDCHAIN_ARTIFACT_RELAY_S3_REGION`            | Relay bucket region                                     |
+| `BUILDCHAIN_ARTIFACT_RELAY_S3_PREFIX`            | Relay object prefix; defaults to `buildchain-artifacts` |
+| `BUILDCHAIN_ARTIFACT_RELAY_S3_ROLE_ARN`          | Shared OIDC role ARN for upload and download            |
+| `BUILDCHAIN_ARTIFACT_RELAY_S3_UPLOAD_ROLE_ARN`   | Upload OIDC role ARN for self-hosted build jobs         |
+| `BUILDCHAIN_ARTIFACT_RELAY_S3_DOWNLOAD_ROLE_ARN` | Download OIDC role ARN for the GitHub-hosted relay job  |
+| `BUILDCHAIN_ARTIFACT_RELAY_S3_OIDC_AUDIENCE`     | Optional OIDC audience override                         |
 
 For AWS China regions, Buildchain defaults the OIDC audience to
 `sts.amazonaws.com.cn`; other regions default to `sts.amazonaws.com`. The caller
@@ -842,15 +971,14 @@ promotion starts:
   `vN`, and `buildchain-stable-contract-lock-path`.
 
 The generated router also owns the stable-shell layout transition through
-`.buildchain/promotion-shell-routing.json`. Stable `v2.14.13` contains the hidden
-advanced workflow, so the stable lane calls that workflow at the exact immutable
-SHA behind the released `v2` state and forwards the complete internal promotion
-identity surface. The logical shell identity remains `vN`, and the router
-retains it in the public audit outputs. The internal advanced-shell call receives
-the exact call ref selected by the routing configuration, so its called-workflow
-ref check and checkout SHA both bind to the same immutable identity. Updating the
-routing pin after a stable release does not require any consumer declaration
-change.
+`.buildchain/promotion-shell-routing.json`. The v3 stable and alpha lanes call
+the hidden advanced workflow at the exact immutable SHA behind their selected
+v3 channel state and forward the complete internal promotion identity surface.
+The logical shell identity remains `vN`, and the router retains it in the public
+audit outputs. The internal advanced-shell call receives the exact call ref
+selected by the routing configuration, so its called-workflow ref check and
+checkout SHA both bind to the same immutable identity. Updating a routing pin
+after a release does not require any consumer declaration change.
 
 The router resolves immutable SHAs and the selected lock digest before candidate
 download. The advanced shell verifies the same router, shell, runtime, lock,
@@ -922,7 +1050,7 @@ main`, marks the rest as `role: platform`, and passes the generated
 side effect. Downloaded platform manifests are still passed into the release
 passport unless `release-passport-platform-manifest-paths` is set explicitly.
 The same Buildchain contract lock check runs before release-candidate
-resolution and before publish. A compatible `v2` drift leaves an issue in the
+resolution and before publish. A compatible `v3` drift leaves an issue in the
 consumer repository but does not trigger a second heavy build; an incompatible
 drift fails before publish side effects.
 
@@ -965,7 +1093,7 @@ publish side effect:
   with:
     sha: ${{ needs.build.outputs.publish-source-sha }}
     target-ref: release/v22/v22.22
-    require-publish-source-lock: 'true'
+    require-publish-source-lock: "true"
     publish-source-ref: ${{ needs.build.outputs.publish-source-ref }}
     publish-source-sha: ${{ needs.build.outputs.publish-source-sha }}
     publish-source-locked: ${{ needs.build.outputs.publish-source-locked }}
@@ -1087,7 +1215,7 @@ Supported placeholders are `{artifact}`, `{artifactName}`, `{platform}`,
 `{platformId}`, `{platformName}`, `{sha}`, `{shortSha}`, `{ref}`, `{runId}`,
 and `{runAttempt}`. Invalid GitHub artifact name characters are normalized to
 `-`, so `{ref}` remains deterministic even for refs such as
-`refs/heads/dev/v2/v2.0`.
+`refs/heads/dev/v3/v3.0`.
 
 Each platform also writes and uploads:
 

package/docs/runtime-train-validation.md

@@ -1,3 +1,21 @@
+---
+status: active
+period: ongoing
+theme: buildchain-runtime-train-validation
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-31
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-31
+  invisible_context: not asserted
+---
+
 # Runtime Train Validation
 
 Buildchain consumers should keep stable workflow refs such as `@v3` in
@@ -23,7 +41,7 @@ train/v3/v3.0/<capability>
 
 It is a validation pointer, not a release channel:
 
-- it does not move `v2`, `vX.Y`, `vX.Y-alpha`, exact tags, npm dist-tags, or
+- it does not move `v3`, `vX.Y`, `vX.Y-alpha`, exact tags, npm dist-tags, or
   production refs;
 - it must not be pinned as a long-term production dependency;
 - it should point at the Buildchain commit that downstream maintainers are
@@ -140,7 +158,7 @@ summary. The evidence should include:
 
 ## Trust and limitation
 
-Official floating channel refs such as `v2` and `v3-alpha` may be selected on
+Official floating channel refs such as `v3` and `v3-alpha` may be selected on
 pull requests and pushes. Train refs and arbitrary exact-SHA overrides still
 fail closed unless the event is `workflow_dispatch` and the actor has write,
 maintain, or admin permission on the caller repository. Pull requests,

package/docs/shifu-gate-profiles.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: B
 review_state: self-reviewed
-last_reviewed: 2026-07-13
+last_reviewed: 2026-07-29
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -54,6 +54,12 @@ matrix and aggregate. Matrix entries retain the Shifu plan digest, ordered gate
 groups, required/advisory modes, action ids, definition digests, skips, and
 unsupported selections.
 
+Each matrix job timeout reserves the sum of the selected Gate action budgets
+plus 30 minutes for Buildchain-owned checkout, toolchain setup, plan download,
+receipt validation, and artifact upload. The total remains capped at GitHub's
+six-hour job limit. This control-plane allowance does not enlarge any Shifu
+Gate's own declared action budget or change its definition digest.
+
 `github-hosted` declares only the inherent `node` capability. Projects that
 need a native compiler, product artifacts, devices, or other facilities must
 use a suitable preset or declare a custom matrix. Capabilities are scheduling

package/docs/stable-candidate-patrol.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: self-reviewed
-last_reviewed: 2026-07-11
+last_reviewed: 2026-07-31
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -162,15 +162,15 @@ returned a GraphQL error in the response body.
 
 ## Exact-source stable promotion
 
-For a selected `2.12.0-alpha.4`, Patrol creates the immutable source branch:
+For a selected `3.0.2-alpha.4`, Patrol creates the immutable source branch:
 
 ```text
-publish-gate/release/v2/v2.12/2.12.0-alpha.4
+publish-gate/release/v3/v3.0/3.0.2-alpha.4
 ```
 
-and opens it against `release/v2/v2.12`. This is an existing strict Buildchain
-governance path. The PR freezes the qualified candidate even if `v2.12-alpha`
-or `alpha/v2/v2.12` has already moved to alpha.5. Normal Verify,
+and opens it against `release/v3/v3.0`. This is an existing strict Buildchain
+governance path. The PR freezes the qualified candidate even if `v3.0-alpha`
+or `alpha/v3/v3.0` has already moved to alpha.5. Normal Verify,
 release-candidate resolution, source-tree equivalence, publish transaction,
 passport, registry, tag, and floating-ref checks still run.
 

package/docs/toolkit-observability.md

@@ -1,3 +1,21 @@
+---
+status: draft
+period: ongoing
+theme: buildchain-observability
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-07-31
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-07-31
+  invisible_context: not asserted
+---
+
 # Toolkit Observability
 
 Buildchain ships a small logging toolkit for repository workflows and project
@@ -232,6 +250,10 @@ are recorded as unavailable instead of failing the diagnostics artifact. Call
 compiler cache data. Native diagnostics also expose `compilerCaches` and
 `nativeCacheDirs` as top-level fields in each diagnostics artifact and aggregate
 summary, so reviewers do not have to dig through nested cache sections first.
+For reusable builds, sccache outcomes enter structured current-run evidence only
+when a sibling `compiler-cache-preparation.json` proves the counters were reset
+after install and before build; cumulative stats without that receipt remain
+explicitly unavailable.
 
 Process samples are intentionally summarized before they become long-lived
 artifacts. The summary records requested parallelism, the source of that value