@kungfu-tech/buildchain 3.0.9-alpha.9 → 4.0.0-alpha.0

package/docs/release-flow.md

@@ -18,7 +18,7 @@ ai_provenance:
 
 # Release Flow Diagrams
 
-This document describes the Buildchain v3 branch, tag, and version-state flow.
+This document describes the Buildchain v4 branch, tag, and version-state flow.
 See [Release governance](release-governance.md) for the design rationale.
 
 ## Architecture
@@ -64,16 +64,16 @@ for the versioned policy and evidence contract.
 
 | Ref kind | Example | Mutability | Purpose |
 | --- | --- | --- | --- |
-| Development branch | `dev/v3/v3.0` | moves | next source state for a minor line |
-| Alpha branch | `alpha/v3/v3.0` | moves | latest test state for a minor line |
-| Release branch | `release/v3/v3.0` | moves | latest production state for a minor line |
+| Development branch | `dev/v4/v4.0` | moves | next source state for a minor line |
+| Alpha branch | `alpha/v4/v4.0` | moves | latest test state for a minor line |
+| Release branch | `release/v4/v4.0` | moves | latest production state for a minor line |
 | Major gate branch | `publish-gate/major` | moves | reviewed administrator gate for publishing the next major |
-| Exact alpha tag | `v3.0.3-alpha.0` | immutable | audit ref for one tested prerelease |
-| Exact release tag | `v3.0.2` | immutable | audit ref for one production release |
-| Floating alpha tag | `v3.0-alpha` | moves | latest test channel for a minor line |
-| Floating major alpha tag | `v3-alpha` | moves | latest test channel on the highest published alpha minor for a major line |
-| Floating minor tag | `v3.0` | moves | latest production patch on a minor line |
-| Floating major tag | `v3` | moves | selected stable major entrypoint |
+| Exact alpha tag | `v4.0.3-alpha.0` | immutable | audit ref for one tested prerelease |
+| Exact release tag | `v4.0.2` | immutable | audit ref for one production release |
+| Floating alpha tag | `v4.0-alpha` | moves | latest test channel for a minor line |
+| Floating major alpha tag | `v4-alpha` | moves | latest test channel on the highest published alpha minor for a major line |
+| Floating minor tag | `v4.0` | moves | latest production patch on a minor line |
+| Floating major tag | `v4` | moves | selected stable major entrypoint |
 
 ## Ref Protection Contract
 
@@ -87,20 +87,20 @@ refs/tags/v*.*.*
 ```
 
 Do not apply immutable-tag rulesets to every `refs/tags/v*` ref. Buildchain
-must be able to update floating channel tags such as `v3`, `v3.0`, `v3.0-alpha`,
-and `v3-alpha` after the exact tag and publish evidence are valid. A ruleset that
+must be able to update floating channel tags such as `v4`, `v4.0`, `v4.0-alpha`,
+and `v4-alpha` after the exact tag and publish evidence are valid. A ruleset that
 matches all `v*` tags also matches floating tags, so release finalization can
 fail with GitHub protected-ref errors even though the exact release tag and
 published artifacts are already durable.
 
 The intended governance split is:
 
-- exact tags such as `v3.0.2` and `v3.0.3-alpha.0` are immutable audit refs;
+- exact tags such as `v4.0.2` and `v4.0.3-alpha.0` are immutable audit refs;
 - for publish transactions, the exact tag points to the transaction
   `source_sha`, matching package-registry source metadata such as npm
   `gitHead`; generated version-state commits remain on protected branches and
   floating channel refs;
-- floating tags such as `v3`, `v3.0`, `v3.0-alpha`, and `v3-alpha` are mutable channel refs
+- floating tags such as `v4`, `v4.0`, `v4.0-alpha`, and `v4-alpha` are mutable channel refs
   owned by the Buildchain promotion token;
 - protected branches still require reviewed channel PRs before Buildchain can
   move any exact or floating release refs.
@@ -116,17 +116,17 @@ The workflow is backed by the CLI command:
 
 ```bash
 buildchain release line open \
-  --major 3 \
+  --major 4 \
   --minor 1 \
-  --source-ref release/v3/v3.0 \
+  --source-ref release/v4/v4.0 \
   --json
 ```
 
 When the workflow is run with `apply=true`, Buildchain:
 
-- writes the initial version-state commit, such as `3.1.0-alpha.0`;
-- creates `dev/v3/v3.1` from that commit;
-- creates `alpha/v3/v3.1` and `release/v3/v3.1` from the selected source ref;
+- writes the initial version-state commit, such as `4.1.0-alpha.0`;
+- creates `dev/v4/v4.1` from that commit;
+- creates `alpha/v4/v4.1` and `release/v4/v4.1` from the selected source ref;
 - applies branch protection with one approving review and the configured
   required status check; dev starts strict, while alpha and release also require
   the pair-specific `verify` aggregate without a source-up-to-date ancestry loop;
@@ -134,7 +134,7 @@ When the workflow is run with `apply=true`, Buildchain:
   the exact queue parameters and bypass actors from the current default dev
   branch when the policy is `inherit` or absent;
 - switches the repository default branch to the new dev line when requested;
-- opens the first `dev/v3/v3.1 -> alpha/v3/v3.1` channel PR when requested.
+- opens the first `dev/v4/v4.1 -> alpha/v4/v4.1` channel PR when requested.
 
 This makes minor-line creation a single audited operation. The channel PR still
 goes through the normal verify/review/promotion path before an alpha is
@@ -251,26 +251,26 @@ The same minor line can loop through this state machine many times.
 
 ## Version Examples
 
-Assume `v3.0.2-alpha.1` has been tested and a maintainer merges
-`alpha/v3/v3.0 -> release/v3/v3.0`.
+Assume `v4.0.2-alpha.1` has been tested and a maintainer merges
+`alpha/v4/v4.0 -> release/v4/v4.0`.
 
 Buildchain should produce:
 
 ```text
-v3.0.2                  exact production tag
-v3.0                    floating minor tag
-v3                      floating major tag when v3.0 is the selected major line
-release/v3/v3.0         production channel branch
+v4.0.2                  exact production tag
+v4.0                    floating minor tag
+v4                      floating major tag when v4.0 is the selected major line
+release/v4/v4.0         production channel branch
 ```
 
 It should also prepare:
 
 ```text
-v3.0.3-alpha.0          exact next alpha tag
-v3.0-alpha              floating alpha tag
-v3-alpha                floating major alpha tag when v3.0 is the highest published alpha minor
-alpha/v3/v3.0           alpha channel branch
-dev/v3/v3.0             development channel branch
+v4.0.3-alpha.0          exact next alpha tag
+v4.0-alpha              floating alpha tag
+v4-alpha                floating major alpha tag when v4.0 is the highest published alpha minor
+alpha/v4/v4.0           alpha channel branch
+dev/v4/v4.0             development channel branch
 ```
 
 This is expected behavior. A production release closes one patch and opens the

package/docs/release-governance.md

@@ -263,11 +263,9 @@ semantics and fail-closed verification requirements.
 The authority verifies the complete result set on GitHub-hosted infrastructure
 before delivery. The consumer controller also performs final result verification,
 exact-byte import, manifest recomputation, and deterministic-artifact replacement
-on a GitHub-hosted lane. macOS results finalize on a GitHub-hosted macOS runner so
-the consumer lifecycle can perform native post-sign checks before publication;
-other platforms retain the GitHub-hosted Ubuntu control lane. Self-hosted build
-runners do not download authority result payloads, and aggregate/release evidence
-fails closed until this finalization succeeds.
+on a GitHub-hosted lane. Self-hosted build runners do not download authority
+result payloads, and aggregate/release evidence fails closed until this
+finalization succeeds.
 
 The central `buildchain-artifact-signing` environment reuses the established
 macOS Credential Island names (`BUILDCHAIN_MACOS_CERTIFICATE_*`,
@@ -493,11 +491,10 @@ GitHub Merge Queue does not by itself decide which candidate may spend a long
 native proof before enqueue. Repositories with that workload use the
 [Dev Delivery Warrant Queue](dev-delivery-warrant.md) as the durable,
 FIFO-aging scheduling and fencing authority before native queue admission. A
-provisional Warrant reserves the landing order before native shards, while only
-its atomic qualified upgrade can authorize enqueue. Later candidates remain
-visibly queued and continue source/CI work; GitHub still owns the exact
-`merge_group` proof and final ref mutation. Workflow concurrency remains only a
-process critical section and is not fairness or ownership authority.
+selected Warrant owns one complete delivery attempt and later candidates remain
+visibly queued; GitHub still owns the exact `merge_group` proof and final ref
+mutation. Workflow concurrency remains only a process critical section and is
+not fairness or ownership authority.
 
 Every required workflow must handle both `pull_request` and `merge_group`
 before the queue is enabled. Queue runs do not provide
@@ -613,12 +610,6 @@ The reusable caller supports `off`, read-only `shadow`, and fail-closed
 `required` rollout modes. GitHub Merge Queue remains the final protected-ref
 authority in every mode.
 
-Bounded-concurrency experiments use the separate effect-disabled Warrant
-shadow planner. It may evaluate at most two fully bound lanes from one exact
-observation, but it cannot mint a second production Warrant or mutate GitHub.
-Its aggregate threshold decision is qualification evidence for a later rollout
-change, not authority to change the live single-flight policy.
-
 The canonical consumer required check context is `check / check`, matching the
 reusable workflow call plus its `check` job. Buildchain's own `Verify` workflow
 emits the repository-local context `check`, so Buildchain self-promotion,
@@ -726,13 +717,13 @@ status to failure, while the merge group must still produce its own final check.
 that want a stable day-to-day operations contract, Buildchain also exposes a
 patrol workflow family:
 
-| Workflow                                         | Intended cadence                   | Default intent                                                                             |
-| ------------------------------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------ |
-| `.github/workflows/patrol-daily.yml`             | daily                              | lightweight inspection plus ready dev PR maintenance                                       |
-| `.github/workflows/patrol-weekly.yml`            | weekly                             | release-state, passport, gate, and stale-state health checks as they are added             |
-| `.github/workflows/patrol-monthly.yml`           | monthly                            | governance, permission, branch-protection, and workflow drift checks as they are added     |
-| `.github/workflows/patrol-observed-evidence.yml` | caller-selected schedule           | validated immutable observation plus atomic last-known-good publication; no per-refresh PR |
-| `.github/workflows/stable-candidate-patrol.yml`  | repository-selected release window | qualify immutable alpha candidates and open the exact source-lock stable PR                |
+| Workflow | Intended cadence | Default intent |
+| --- | --- | --- |
+| `.github/workflows/patrol-daily.yml` | daily | lightweight inspection plus ready dev PR maintenance |
+| `.github/workflows/patrol-weekly.yml` | weekly | release-state, passport, gate, and stale-state health checks as they are added |
+| `.github/workflows/patrol-monthly.yml` | monthly | governance, permission, branch-protection, and workflow drift checks as they are added |
+| `.github/workflows/patrol-observed-evidence.yml` | caller-selected schedule | validated immutable observation plus atomic last-known-good publication; no per-refresh PR |
+| `.github/workflows/stable-candidate-patrol.yml` | repository-selected release window | qualify immutable alpha candidates and open the exact source-lock stable PR |
 
 The cadence names describe patrol intensity, not release cadence:
 
@@ -834,11 +825,8 @@ declare version-state files and lifecycle commands without pretending every
 project is a Node workspace. Supported version files include JSON, TOML, and
 regex-based files such as `CMakeLists.txt` or `conanfile.py`.
 
-The promotion action consumes `version.files`, optional
-`version.derived_files`, and `lifecycle.verify`. Semver and anchored/manual
-repositories may both declare lifecycle-regenerated tracked outputs as derived
-files; anchored/manual repositories additionally bind them into their committed
-version witnesses.
+The promotion action consumes `version.files`, optional anchored/manual
+`version.derived_files`, and `lifecycle.verify`.
 The verify stage runs after generated version-state changes are applied locally
 and before any release refs move. If `verification-command` is passed directly
 to the action, that explicit command overrides `lifecycle.verify`.

package/docs/release-passport.md

@@ -313,13 +313,6 @@ fails closed if any claim is missing source bindings, machine evidence, hashes,
 artifact coordinates, verification result, audit boundary, responsibility, or
 residual risk.
 
-The same self-promotion boundary extends the Buildchain-owned KFD witness
-generator against the transaction's exact source SHA. It produces the standard
-full-cut adopter manifest, the non-qualifying KFD-4/5/7 product gates, and the
-one-way legacy projection before the final passport is collected. An explicitly
-supplied adopter manifest still takes precedence; an omitted self-release
-manifest no longer silently produces a KFD-1/2/3-only passport.
-
 ### KFD-3 collaboration-interface release gate
 
 KFD-3 asks a different release question than KFD-1. KFD-1 proves that named
@@ -410,14 +403,8 @@ Pass the standard full-cut declaration with `--kfd-adopter-manifest-json`
 together with three `--kfd-product-gate-json` arguments for KFD-4, KFD-5, and
 KFD-7. The collector invokes the verifier from the exact installed
 `@kungfu-tech/kfd` package, binds the package artifact, registry and verifier
-roots, the collector's exact product repository and source, the
-manifest/report/bundle witness roots, and the existing product-gate roots. A
-non-Buildchain adopter is accepted only when its manifest identity, artifact
-coordinate, and all three product-gate repositories match the collector's
-`--repository` value. The lower-level Node API exposes the same boundary as
-`expectedAdopterId`, `expectedSourceRepository`, and `expectedSourceSha`, while
-omitted identity/repository values retain the Buildchain self-release default.
-It emits `kfd-adopter-manifest.json`,
+roots, the exact Buildchain source, the manifest/report/bundle witness roots,
+and the existing product-gate roots. It emits `kfd-adopter-manifest.json`,
 `kfd-adopter-manifest-gate.json`, and a legacy `kfd-support.json` projection.
 The release passport and `artifact-evidence.json` carry the same rooted
 `kfdAdopter` binding.

package/docs/release-tail-contract.md

@@ -7,21 +7,21 @@ source_level: local-files
 confidence: high
 sensitivity: public
 evidence_grade: A
-review_state: unreviewed
-last_reviewed: 2026-08-07
+review_state: self-reviewed
+last_reviewed: 2026-08-13
 ai_provenance:
   model_family: GPT-5
   product: Codex
   generated_at: 2026-08-07
-  visible_context: Buildchain dev/v3/v3.0 release workflows, promotion Action, transaction and activation code, local exact-head managed-consumer callers, and the Kungfu alpha release-tail implementation.
+  visible_context: Buildchain dev/v3/v3.0 release workflows, the v4 capability manifest and architecture constitution, promotion Action, transaction and activation code, local exact-head managed-consumer callers, and the Kungfu alpha release-tail implementation.
   invisible_context_boundary: Did not read credentials, private logs, signed URLs, provider state, or unpublished release assets.
 ---
 
 # Declarative release-tail contract
 
-Buildchain v3 currently lets a consumer repository provide shell commands at
-several points around publication. Those hooks made early adoption possible,
-but they also let a consumer redefine the final release transaction. The
+Buildchain's v3 compatibility line lets a consumer repository provide shell
+commands at several points around publication. Those hooks made early adoption
+possible, but they also let a consumer redefine the final release transaction. The
 machine authority for the current inventory is
 [`architecture/release-tail-contract-inventory.json`](../architecture/release-tail-contract-inventory.json).
 The declaration schema is
@@ -33,6 +33,13 @@ implementation is documented in
 provider plane does not itself cut over a consumer, run a release, or
 reinterpret an already published release.
 
+The v4 line carries this contract as its production release-tail boundary. The
+v4 capability manifest names `typescript-v4` as the sole writer and marks the
+legacy v3 writer retired. Deterministic v4 journal, activation, stable-fence,
+recovery, provider readback, rollback, and N-1 qualification contracts gate
+every provider mutation; the retained v3 release ref is rollback evidence, not
+an active fallback writer.
+
 ## Current executable surfaces
 
 The reverse scan classifies 27 workflow, Action, config, and CLI coordinates

package/docs/release-tail-provider-plane.md

@@ -28,15 +28,15 @@ The frozen boundary and migration inventory remain in
 ## Public entry points
 
 - Node: `@kungfu-tech/buildchain/release-tail-provider-plane`,
-  `release-tail-provider-adapters`, `release-tail-compatibility`, and
-  `publication-rehearsal-runtime`.
-- CLI: `buildchain release-tail plan|init|status|verify|compat|rehearse`.
+  `release-tail-provider-adapters`, and `release-tail-compatibility`.
+- CLI: `buildchain release-tail plan|init|status|verify|compat`.
 - Action: `kungfu-systems/buildchain/actions/release-tail@<exact-ref>`.
 - reusable workflow: `kungfu-systems/buildchain/.github/workflows/release-tail.yml@<exact-ref>`.
 
-The CLI and Action both invoke the public publication rehearsal runtime over
-the same core transaction implementation. The Action is a thin provider
-transport wrapper; callers cannot inject an execution command or runner state.
+The Action is the provider-executing entry point. The CLI compiles, initializes,
+inspects, verifies, and diagnoses bounded v3 compatibility using the same core
+transaction format. The reusable workflow checks out an exact Buildchain ref
+and invokes the packaged Action; callers cannot inject an execution command.
 
 ## Inputs and secrets
 
@@ -82,12 +82,9 @@ buildchain release-tail init --declaration release-tail.json --state .buildchain
 buildchain release-tail verify --state .buildchain/release-tail/state.json
 ```
 
-For complete local release semantics, use the exact capsule command in
-[`publication-rehearsal.md`](publication-rehearsal.md). Simulation and replay
-exercise planning, validation, transaction, retry, and evidence without
-claiming external provider truth. Provider execution belongs in the Action or
-reusable workflow so token handling and transport capabilities remain explicit.
-Retain the state and rehearsal evidence artifacts.
+Provider execution belongs in the Action or reusable workflow so token handling
+and provider permissions remain explicit. Retain the state artifact: it is the
+resume boundary and evidence source, not a disposable log.
 
 ## Buildchain self-dogfood route
 
@@ -95,15 +92,12 @@ Buildchain self-release calls the same public reusable workflow coordinate as a
 consumer:
 
 ```text
-kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@769b221bad7a6b9104afad4c2628d9dca396ab0f
+kungfu-systems/buildchain/.github/workflows/release-candidate-promote.yml@train/v3/v3.0/consumer-equivalent-self-dogfood
 ```
 
-The caller pins the public router and runtime to the same exact implementation
-SHA. Its internal alpha shell remains on the named train, so automatic
-`workflow_run` publication uses the immutable-router path without a manual
-runtime override. For alpha self-release, the promotion Action materializes the
-sealed GitHub Release asset declaration, executes it through this provider
-plane, and retains the
+The public router resolves the workflow shell and runtime to exact SHAs. For
+alpha self-release, the promotion Action materializes the sealed GitHub Release
+asset declaration, executes it through this provider plane, and retains the
 declaration root, transaction root, state root, receipt roots, controller
 receipt, and route-parity evidence. The legacy GitHub Release helper is not a
 fallback when `declarative-release-tail` is enabled; a provider or readback

package/docs/release-train.md

@@ -13,13 +13,13 @@ ai_provenance:
   model_family: GPT-5
   product: Codex
   generated_at: 2026-08-11
-  visible_context: Buildchain v3 release candidate, recovery, Dev to Alpha Candidate Patrol, rooted blocker repair, Warrant, publication transaction, and release governance sources.
+  visible_context: Buildchain v4 parity of the v3 release candidate, recovery, Dev to Alpha Candidate Patrol, rooted blocker repair, Warrant, publication transaction, and release governance sources.
   invisible_context_boundary: Live provider state and credentials were not read.
 ---
 
 # Release Train and Release Cut
 
-Buildchain v3 exposes a pure, provider-neutral Release Train contract for
+Buildchain v4 exposes the same pure, provider-neutral Release Train contract proven on v3 for
 retaining one authorized Alpha candidate while the development branch keeps
 moving. The contract does not select a candidate, write a Git ref, open a pull
 request, publish a package, or replace any existing provider gate. Controllers
@@ -92,7 +92,7 @@ and records a Dev landing with the same patch root. A landed but different Dev
 patch produces a rooted `cut-dev-patch-root-mismatch` gate rather than
 publication authority.
 
-Buildchain v3 Candidate Patrol resolves the open managed candidate's persisted
+Buildchain v4 Candidate Patrol resolves the open managed candidate's persisted
 train before it considers a new qualified development head. It reads back the
 candidate ref and tree, Alpha base, and exact Buildchain runtime. Matching
 coordinates resume the frozen candidate; a newer development head becomes a
@@ -102,7 +102,7 @@ enumerated `superseded` transition is reported as superseded.
 
 ## Buildchain self-dogfood campaign
 
-Buildchain qualifies the complete v3 mechanism with
+Buildchain qualifies the complete v4 parity mechanism with
 `scripts/release-train-self-dogfood.mjs`. The campaign composes one frozen
 Release Cut, moving-dev observation, deterministic failed build, successor
 repair, cut/dev patch-root settlement, publication gate, and bounded Delivery

package/docs/reusable-build-surface.md

@@ -354,8 +354,7 @@ ref is not blind trust. Each released Buildchain ref carries a package-owned
 runtime contract world in `dist/site/buildchain-contract.json`. Consumers may
 keep a small lock file, `.buildchain/contract-lock.json`, recording the
 Buildchain ref, resolved SHA, contract digest, compatibility digest, accepted
-major line, compatibility proof registry root, per-surface proof roots, and the
-compatibility policy they reviewed.
+major line, and compatibility policy they reviewed.
 
 The reusable build trust gate checks this lock before any heavy matrix job:
 
@@ -372,14 +371,6 @@ promise changes, or the major line changes. Additive changes such as optional
 inputs, optional outputs, diagnostics, or documentation updates continue under
 the default `major-compatible` policy.
 
-A changed breaking digest is never accepted because it appears in a handwritten
-allowlist. Each historical digest must resolve to exactly one immutable,
-directed compatibility proof for the current surface digest. The proof binds
-the operation scope, protected authority, exact Git cut, and protected-merge
-evidence. The legacy `compatibleBreakingDigests` arrays remain in the site
-contract only as deterministic, parity-checked projections of those proofs;
-an orphan digest or ambiguous proof fails source acceptance.
-
 ```yaml
 jobs:
   build:
@@ -396,12 +387,11 @@ jobs:
 
 When compatible drift is detected, the build continues and Buildchain opens or
 updates a low-priority issue in the consumer repository. The issue records the
-old SHA/digest, new SHA/digest, compatibility result, workflow run, exact proof
-root, direction, scope, evidence, authority, cut, and rooted verification
-receipt. When breaking drift is detected, the same issue path is used, but the
-trust gate fails before matrix build or publish work starts. If the workflow
-token cannot write issues, Buildchain writes a copyable issue body into the job
-summary.
+old SHA/digest, new SHA/digest, compatibility result, workflow run, and the next
+action: review the Buildchain release notes and update the lock. When breaking
+drift is detected, the same issue path is used, but the trust gate fails before
+matrix build or publish work starts. If the workflow token cannot write issues,
+Buildchain writes a copyable issue body into the job summary.
 
 The lock is intentionally small. It does not copy the full contract. The full
 contract remains in the Buildchain ref and package; the consumer records only
@@ -709,17 +699,6 @@ 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.
-Archives whose executable hosts a JIT runtime can additionally request the
-Buildchain-owned `entitlements_profile = "jit-executable-v1"` and exact paths,
-for example `entitlements_paths = ["product/runtime/python/bin/python3"]`.
-Paths are relative to the extracted archive root. The authority
-then attaches only `com.apple.security.cs.allow-jit` to the exact executable
-Mach-O files sealed in `entitlements_paths`, leaves every other executable and
-library without exception entitlements, and records the profile, paths, and
-entitled executable count in provider evidence. Consumer-provided entitlement
-files and wildcard target paths are unsupported. The profile is valid only for
-Apple `archive` requests and fails closed on an unsafe, missing,
-non-executable, duplicate, or unsealed target path.
 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,
@@ -1408,6 +1387,14 @@ with:
 `self-hosted`; a self-hosted control plane must not be exposed to untrusted fork
 events or arbitrary caller-controlled workflow code.
 
+Consumers that must verify platform-native properties of the final bytes can
+set `artifact-finalization-command` and `artifact-finalization-on-platform:
+true`. Buildchain then imports any signed result (or preserves the declared
+unsigned artifact), runs the command on the matching GitHub-hosted platform,
+and reseals the manifest before publishing the final deterministic artifact.
+Platform-native finalization fails closed for self-hosted runners so signing
+authority credentials and final bytes stay inside the trusted hosted boundary.
+
 `require-trusted-event` controls access to build runners. It does not override
 the publish gate: pull requests remain non-publishing events.
 

package/docs/site-bundle-contract.md

@@ -54,11 +54,7 @@ overview, and fixture guides.
 `buildchain-contract.json` is the machine-readable Buildchain runtime contract
 world used by floating-ref contract locks. It records public workflow/action/CLI
 surfaces, compatibility digests, and audit digests for the files that implement
-those surfaces. Its immutable compatibility proofs bind historical breaking
-digests to exact target surfaces, operation scopes, protected authority,
-evidence, and Git cuts. `compatibleBreakingDigests` and per-surface proof-root
-lists are generated projections; site consumers must not edit or reinterpret
-them as independent authority.
+those surfaces.
 `manual-registry.json` enumerates the packaged Markdown manuals with source
 digests so an agent can find complete operating documentation from the npm
 artifact. `node-api-registry.json` enumerates public Node import surfaces from

package/docs/stable-candidate-patrol.md

@@ -125,7 +125,7 @@ permissions:
 
 jobs:
   stable:
-    uses: kungfu-systems/buildchain/.github/workflows/stable-candidate-patrol.yml@v3
+    uses: kungfu-systems/buildchain/.github/workflows/stable-candidate-patrol.yml@v4
     with:
       release-now: ${{ inputs.release-now }}
       dry-run: false
@@ -165,15 +165,15 @@ returned a GraphQL error in the response body.
 
 ## Exact-source stable promotion
 
-For a selected `3.0.2-alpha.4`, Patrol creates the immutable source branch:
+For a selected `4.0.2-alpha.4`, Patrol creates the immutable source branch:
 
 ```text
-publish-gate/release/v3/v3.0/3.0.2-alpha.4
+publish-gate/release/v4/v4.0/4.0.2-alpha.4
 ```
 
-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,
+and opens it against `release/v4/v4.0`. This is an existing strict Buildchain
+governance path. The PR freezes the qualified candidate even if `v4.0-alpha`
+or `alpha/v4/v4.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.
 
@@ -206,7 +206,7 @@ step; the durable authority record remains the candidate ledger entry and PR.
 The default ledger ref is derived from the release line, for example:
 
 ```text
-buildchain/candidate-ledger/v3/v3.0
+buildchain/candidate-ledger/v4/v4.0
 ```
 
 It stores `.buildchain/stable-candidate-ledger.json`. Patrol runs are serialized

package/docs/v4-canonical-contracts.md

@@ -0,0 +1,92 @@
+---
+status: draft
+period: 2026-08-07
+theme: buildchain-v4-canonical-contracts
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-08-07
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-07
+  visible_context: Protected Buildchain v4 architecture, canonical contract implementations, schemas, and cross-language fixtures.
+  invisible_context_boundary: Did not inspect credentials, private logs, hidden model state, or unobserved production behavior.
+---
+
+# Buildchain v4 canonical contracts
+
+Buildchain v4 uses one provider-free contract layer for deterministic state-machine bytes and roots. TypeScript v3 remains the sole production writer. These contracts introduce no Git ref writer, network or filesystem effect, daemon, database, credential owner, or ambient clock.
+
+## Canonical JSON v1
+
+`buildchain-canonical-json/v1` accepts only JSON values. Object keys must be non-empty printable ASCII and are ordered by ascending ASCII code point. Arrays retain input order. Numbers are base-10 integers in the inclusive JavaScript-safe range `-9007199254740991..9007199254740991`; fractions, negative zero, non-finite numbers, and wider integers are rejected. Strings use JSON escaping and UTF-8. The exact output ends with one LF byte.
+
+Content roots hash these exact bytes with an explicit domain separator:
+
+```text
+sha256(ASCII(domain) + NUL + canonical-json-bytes)
+```
+
+The only v1 domains are `queue-state`, `candidate-identity`, `fencing-token`, `transition-receipt`, `observation`, `semantic-diff`, and `bootstrap-evidence`. A queue-state root is computed from a value that omits its own `stateRoot` field.
+
+## Explicit clocks and closed envelopes
+
+Pure contract code accepts time only as `YYYY-MM-DDTHH:mm:ss.SSSZ`. An adapter samples once and passes the value as data. Missing clocks, offsets, invalid calendar instants, or other precision are rejected.
+
+Event, receipt, and typed-fault objects use closed versioned shapes in [`contracts/v4-canonical-contracts-v1.schema.json`](../contracts/v4-canonical-contracts-v1.schema.json). Unknown fields fail. Only a rejected receipt carries a typed fault; accepted and no-op receipts carry `null`.
+
+## Implementations and proof
+
+- JavaScript: [`packages/core/v4-canonical-contracts.js`](../packages/core/v4-canonical-contracts.js)
+- Rust: [`crates/buildchain-v4-contracts`](../crates/buildchain-v4-contracts)
+- Shared golden and adversarial cases: [`architecture/v4-canonical-contract-fixtures.json`](../architecture/v4-canonical-contract-fixtures.json)
+
+Run the focused proof with:
+
+```sh
+pnpm run check:v4-contracts
+```
+
+The check validates both implementations, compares exact UTF-8 bytes and SHA-256 roots, exercises invalid numbers, keys, clocks, domains, and envelope shapes, and scans the pure libraries for ambient clock or provider imports. Delivery Warrant decide/fold, shadow invocation, provider effects, and production authority remain outside this contract slice.
+
+## Shared Delivery Warrant fixture runner
+
+The versioned trace contract in [`contracts/v4-delivery-warrant-trace-v1.schema.json`](../contracts/v4-delivery-warrant-trace-v1.schema.json) is the language-neutral boundary for retained Delivery Warrant fixtures. The JavaScript runner in [`packages/core/v4-delivery-warrant-fixture-runner.js`](../packages/core/v4-delivery-warrant-fixture-runner.js) and the Rust runner in [`crates/buildchain-v4-contracts`](../crates/buildchain-v4-contracts) consume the same UTF-8 fixture bytes and emit the same deterministic semantic projection.
+
+Each trace is closed and ordered. It binds the exact prior root, event, action or typed fault, canonical successor bytes and root, generation, fencing counter, ordered declarative effects, provider-neutral observations, and rooted receipt. The runner verifies the full root chain before returning a projection. Malformed JSON, missing or unknown fields, reordered sequences, stale roots, and unsupported contract versions fail closed.
+
+The retained public-safe fixtures are:
+
+- [`golden.json`](../contracts/fixtures/v4-delivery-warrant-trace-v1/golden.json) for accepted submit/select transitions and ordered effects;
+- [`replay.json`](../contracts/fixtures/v4-delivery-warrant-trace-v1/replay.json) for a stale-fence typed fault and response-loss readback.
+
+The runner is not a state-machine implementation and does not sample time, execute effects, access Git/GitHub, or move production authority. TypeScript v3 remains the sole production writer. Later Rust decide/fold and TypeScript shadow adapters supply or consume this contract instead of defining another projection shape.
+
+## TypeScript shadow adapter
+
+The adapter in [`packages/core/v4-delivery-warrant-shadow-adapter.js`](../packages/core/v4-delivery-warrant-shadow-adapter.js) runs the existing TypeScript v3 fixture projection first and preserves that exact result as the only authoritative output. When explicitly enabled, it sends the same canonical input bytes to the replaceable Rust host command, requires the effect-disabled host capability, and captures the returned semantic projection only as a non-authoritative observation. Rust never receives effect authority, and success, failure, timeout, cancellation, malformed output, or an unsupported host cannot change the v3 result.
+
+Shadow retention accepts only checked-in fixtures or captured replays explicitly marked public-safe. Each returned observation binds the input root, exact TypeScript and Rust source revisions, validator version, capture time, fixed retention deadline, both projections, and sanitized diagnostics. It contains no comparison verdict or cutover signal. The adapter is disabled unless the caller opts in or sets `BUILDCHAIN_V4_WARRANT_SHADOW=enabled`; even then, invalid source bindings or an unsafe retention class skip Rust invocation.
+
+## Pure Rust Delivery Warrant domain
+
+The `warrant` module in [`crates/buildchain-v4-contracts`](../crates/buildchain-v4-contracts) implements the protected Delivery Warrant manifest as provider-free typed state, seven event decisions, and a separate fold. It freezes all nine candidate states and all nine primitives from the shadow bootstrap plan. Every decision binds the event's exact `subjectRoot`, takes time only from the validated event envelope, and returns a typed action or fault. Fold produces a canonical successor; the combined transition produces only ordered `persist-successor` and `request-admission` intents plus a rooted receipt. It never executes either intent.
+
+Duplicate submission deliberately retains the legacy generation/root mutation for shadow comparability. Manifest aliases remain explicit, waiting and blocked remain valid states without invented public transitions, and response-loss reconciliation is symmetric for every declarative effect. Stale expected-old roots and fences, lease expiry, terminal duplicates, cancellation, response loss, provider conflict, and retry exhaustion are closed typed outcomes. The retry policy permits at most one reread/redecision and then stops.
+
+The domain consumes the same retained golden and replay bytes as the shared runner. Focused tests cover deterministic replay, bounded property sequences, duplicate behavior, stale compare-and-set and fencing, lease recovery/reselection, settlement and cancellation idempotence, response loss, provider conflict, and calendar-boundary clock arithmetic. Repository-level architecture tests reject provider and I/O imports, ambient clocks, process execution, hidden writers, and unbounded retry loops. The manifest still names `typescript-v3` as the sole authoritative writer with a zero second-writer budget; this slice adds no shadow routing, effect adapter, read/write cutover, or production authority.
+
+## Read-only state projection
+
+The Rust host also accepts `delivery-warrant.state-project` with the dedicated
+`delivery-warrant-state-projection-v1` capability. It decodes and validates the
+closed v4 state, then returns the same state and its canonical `queue-state`
+root. The command has no effect adapter, provider import, store access, or write
+authority. The TypeScript read-candidate adapter binds this projection to a
+previously qualified semantic-diff report and retains parity evidence before
+returning the unchanged v3 observation schema. See
+[`v4-delivery-warrant-read-candidate.md`](v4-delivery-warrant-read-candidate.md).