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

package/docs/dev-delivery-warrant.md

@@ -1,5 +1,5 @@
 ---
-status: accepted
+status: draft
 period: ongoing
 theme: dev-delivery-warrant
 doc_type: technical-reference
@@ -7,7 +7,7 @@ source_level: local-files
 confidence: high
 sensitivity: public
 evidence_grade: A
-review_state: self-reviewed
+review_state: unreviewed
 last_reviewed: 2026-08-11
 ai_provenance:
   model_family: GPT-5
@@ -38,17 +38,10 @@ and retained enqueue time.
 
 Selection is deterministic FIFO plus aging with bounded priority. Priority may
 reorder queued work, but it cannot preempt the active Warrant. Exactly one
-candidate receives a `provisional` leased Warrant containing a fencing token,
-lease generation, expected-old state root, expiry, and the complete exact
-source binding. It reserves the next protected-dev landing before expensive
-native shards start, but it is not GitHub Merge Queue admission authority.
-Heartbeat extends only that generation. Native proof success atomically
-upgrades the same token and generation to `qualified`; only then may enqueue
-begin. Expiry fences further mutations by the old token, but it does not prove
-that the old native process stopped. The active Warrant therefore remains in
-place until bounded termination is proven by rooted terminal evidence. Only
-that exact fenced settlement may clear the holder and permit successor
-selection.
+candidate receives a leased Warrant containing a fencing token, lease
+generation, expected-old state root, expiry, and the complete exact source
+binding. Heartbeat extends only that generation. Expiry recovery rejects the
+old token, retains queue age, and returns the candidate to selection.
 
 A terminal event may cancel a candidate before selection without minting a
 Warrant. This transition is limited to an exact non-active queued candidate and
@@ -58,12 +51,7 @@ An active candidate still requires its current fencing token and lease
 generation. Exact duplicate cancellation evidence is a visible no-op; identity,
 state, event, or evidence drift fails closed.
 
-The reusable terminal controller classifies authoritative completion,
-cancellation, supersession, native failure, and transient dequeue separately.
-`dequeued` alone never clears an active Warrant: a fresh holder continues with
-the same generation and token, while an expired holder waits for proof that its
-fenced worker stopped. Queued work may still settle as dequeued because it never
-started native execution. The controller uses one `settle` operation for active,
+The reusable terminal controller uses one `settle` operation for active,
 queued, already-terminal, and never-admitted pull requests. An active Warrant
 still requires its exact fence and evidence. A matching queued cancellation is
 persisted normally. A duplicate terminal event or a pull request that never
@@ -85,37 +73,23 @@ That lane outranks not-yet-leased ordinary work, but never preempts or rewrites
 an active Warrant; unrelated, conflicted, mismatched, or fabricated claims fail
 closed before selection.
 
-## Three proof authorities
+## Split proof authority
 
-Source Qualification Proof is created from the cheap source-acceptance gate. It
-binds the semantic source, exact source head and patch/tree intent, plan,
-affected closure, dependencies, toolchain, covered paths, and exact acceptance
-evidence. Ready state and approval are established before provisional
-selection.
+Source Qualification Proof is independent of the moving dev base. It binds the
+semantic source, exact source head and patch/tree intent, plan, affected
+closure, dependencies, toolchain, covered paths, and shard evidence.
 
-Native Qualification Proof is separate. It binds semantic source and patch,
-plan, affected closure, dependency graph, toolchain, the exact execution
-environment contract, covered paths, native shard evidence, and the exact dev
-base used by the native composition. Before reuse, the consumer roots the
-complete attributed Dev delta, including both sides of every rename, then
-classifies it:
+Before reuse, the consumer classifies the dev delta:
 
-- unchanged semantic roots plus an unrelated fully attributed base delta reuse
-  native qualification and run only a cheap Project Cut replay. GitHub's `behind`
+- unchanged roots plus an unrelated attributed delta reuse source
+  qualification and run only a cheap Project Cut replay. GitHub's `behind`
   state is accepted only when a rooted replay proof binds the exact current
   protected base, unchanged PR head and source patch, replay tree, required
   context roots, and a qualified `project.cut.merge-queue-admission/v1`
   receipt;
-- an overlapping delta reruns affected native shards or the full native plan;
-- an unknown or truncated graph, ambiguous rename, missing attribution, or
-  changed source, plan, closure, dependency, toolchain, or environment root
-  fails closed to full native qualification.
-
-The reuse decision binds the exact old and current Dev heads, normalized changed
-paths and rename pairs in `baseDeltaRoot`. This makes local and hosted replay of
-the same inputs byte-deterministic. Generated outputs that participate in the
-affected closure must be listed in `affected-paths-json`; a delta touching one
-of those surfaces is overlap, not a documentation-only advance.
+- an overlapping delta reruns the affected source shards;
+- an unknown graph or changed source, plan, closure, dependency, or toolchain
+  root fails closed to full source qualification.
 
 Integration Delivery Proof is separate and cannot be cached across candidates.
 It binds the exact current dev base, replay tree, GitHub `merge_group` head and
@@ -139,19 +113,6 @@ buildchain dev warrant submit --repository owner/repository \
 buildchain dev warrant select --repository owner/repository \
   --branch dev/v4/v4.0 --execute
 
-buildchain dev proof native --branch dev/v4/v4.0 \
-  --qualified-base <sha> --environment-root <root> \
-  --affected-paths-json '["packages/native"]' ...
-
-buildchain dev proof classify-native --source-proof native-proof.json \
-  --current-base <sha> --graph-known true --attribution-complete true \
-  --changed-paths-json '[]' --renames-json '[]' ...
-
-buildchain dev warrant qualify --repository owner/repository \
-  --branch dev/v4/v4.0 --fencing-token <root> --lease-generation 1 \
-  --native-proof native-proof.json \
-  --native-reuse-decision native-reuse-decision.json --execute
-
 buildchain dev warrant cancel-queued --repository owner/repository \
   --branch dev/v4/v4.0 --candidate-id <root> --pull-request 123 \
   --expected-source-head <queued-sha> --observed-source-head <event-sha> \
@@ -159,16 +120,16 @@ buildchain dev warrant cancel-queued --repository owner/repository \
   --evidence-root <terminal-event-root> --execute
 ```
 
-`heartbeat`, `qualify`, `recover`, `close`, `settle`, `cancel-queued`, and `observe` use the same durable authority.
+`heartbeat`, `recover`, `close`, `settle`, `cancel-queued`, and `observe` use the same durable authority.
 Warrant-scoped mutations require the exact fencing token and lease generation.
 `close` also requires a rooted terminal evidence object.
 
-Expensive native commands must run through `dev-delivery-native-run.mjs` (or an
-equivalent exact consumer). It performs an exact fenced heartbeat before spawn,
-renews throughout the complete child lifetime, performs a final renewal before
-accepting success, and terminates the process group on heartbeat or fencing
-failure. Missing, stale, expired, or mismatched Warrant state therefore blocks
-native spawn instead of becoming qualification evidence.
+On the v4 preview line, `observe` alone has an explicit `--read-mode v4`
+candidate. It requires a retained exact semantic-diff qualification and source
+binding, invokes an effect-disabled Rust state projection, retains parity
+evidence, and returns the existing v3 observation shape. The default and
+rollback mode is `v3`; mutation commands ignore the read switch. See
+[`v4-delivery-warrant-read-candidate.md`](v4-delivery-warrant-read-candidate.md).
 
 Proof commands create, verify, classify, and compose the two proof layers:
 
@@ -181,134 +142,15 @@ buildchain dev proof replay-proof \
 buildchain dev proof integration --warrant-result warrant.json ...
 ```
 
-## Bounded-concurrency shadow qualification
-
-The default production queue remains single-flight. A separate effect-disabled shadow
-planner can replay the same deterministic candidate order with a bound of one
-or two lanes. It does not issue, renew, supersede, close, or persist a Warrant;
-it cannot enqueue a pull request; and its output explicitly carries no
-production or rollout authority.
-
-Each lane binds the exact queue root and generation, protected-base head,
-source head, projected-base root, Project Cut, approval, required checks,
-status, and lease evidence. An active production candidate must additionally
-match its current fencing token and lease generation. A queued shadow lane must
-not carry either. Stale evidence, an occupied native queue, cross-lane evidence
-aliasing, shared conflict keys, or an incompatible projected base fails closed.
-A failure in one lane remains visible without converting or concealing the
-other lane's result.
-
-The planner and aggregate qualification command consume immutable JSON files:
-
-```sh
-buildchain dev warrant shadow-plan --input observation.json \
-  --max-concurrency 2 --output shadow-plan.json
-
-buildchain dev warrant shadow-qualify --input qualification-input.json \
-  --output shadow-qualification.json
-```
-
-Both commands reject `--execute`. Qualification reports compare explicit
-thresholds for sample count, eligible overlap, projected queue-wait benefit,
-additional runner cost, ambiguity, and false positives. A `proceed` result is
-only evidence for a separate reviewed rollout decision; it never changes the
-live Warrant schema, queue state, merge-queue policy, or protected branch.
-
-## Opt-in bounded qualification and exclusive landing
-
-Buildchain also defines an explicit production opt-in that turns successful
-shadow evidence into a separate v2 authority state. It does not widen or
-reinterpret the v1 Warrant queue. The accepted
-[`Qualification Lease and Landing Warrant ADR`](dev-delivery-qualification-landing-adr.md)
-and `contracts/dev-delivery-authority-v2.schema.json` are authoritative.
-
-In `bounded-qualification-landing` mode, a configured number of exact
-Qualification Leases may coexist. Each lease carries
-`authority = qualification-only` and `mergeGroupAdmission = false`. Completing
-qualification records evidence and releases that lease. Qualified candidates
-then wait for the one `Landing Warrant`, which alone carries
-`authority = merge-group-admission` and may be checked for `merge_group`
-admission.
-
-Concurrency is granted only across disjoint rooted `qualificationDomains`.
-Overlap and unknown domains are held behind the active safety boundary with an
-explicit content-rooted reason. `maxLandingOvertakes` prevents a slow older
-candidate from being bypassed indefinitely, while `maxQualificationAttempts`
-turns repeated heartbeat loss into a rooted terminal failure. Every release
-returns a deterministic rooted wake instruction; an exact duplicate release or
-recovery is a state-root-preserving no-op.
-
-The public command family is explicit:
-
-```sh
-buildchain dev authority migrate --repository owner/repository \
-  --branch dev/v3/v3.0 --legacy-state v1-queue.json --execute --json
-buildchain dev authority lease-qualification --repository owner/repository \
-  --branch dev/v4/v4.0 --execute
-buildchain dev authority heartbeat-qualification --repository owner/repository \
-  --branch dev/v4/v4.0 --candidate-id <root> \
-  --authority-token <root> --authority-generation 1 --execute
-buildchain dev authority complete-qualification --repository owner/repository \
-  --branch dev/v4/v4.0 --candidate-id <root> \
-  --authority-token <root> --authority-generation 1 \
-  --evidence-root <qualification-root> --execute
-buildchain dev authority lease-landing --repository owner/repository \
-  --branch dev/v4/v4.0 --execute
-buildchain dev authority heartbeat-landing --repository owner/repository \
-  --branch dev/v4/v4.0 --candidate-id <root> \
-  --authority-token <root> --authority-generation 1 --execute
-buildchain dev authority recover --repository owner/repository \
-  --branch dev/v4/v4.0 --execute
-buildchain dev authority admit-merge-group --repository owner/repository \
-  --branch dev/v4/v4.0 --candidate-id <root> \
-  --authority-token <root> --authority-generation 1 \
-  --merge-group-head <sha>
-```
-
-Terminal settlement releases either authority immediately from exact evidence;
-it does not wait for TTL. Exact duplicate settlement is a state-root-preserving
-no-op. The default `buildchain dev warrant` commands, v1 state bytes, and
-single-flight behavior do not change while this mode is off.
-
 ## Workflow rollout and rollback
 
 The reusable `dev-pr-auto-merge.yml` supports three explicit rollout modes:
 
 - `off` preserves the previous exact-head admission controller;
 - `shadow` qualifies the source and emits a read-only queue submission plan;
-- `required` persists the submission, selects a provisional Warrant, runs or
-  reuses semantic native proof under heartbeat, atomically qualifies the same
-  fence, and refuses GitHub enqueue unless the immutable queue commit, state root, active Warrant, and
-  selected candidate all pass exact readback validation. Immediately before
-  enqueue, the controller also rereads the current protected state ref and
-  verifies the active candidate, fencing token, generation, pull request, and
-  exact head. A previously valid result is not authority after terminal
-  closeout. Re-running qualification for the same selected head may regenerate
-  timestamped proof bytes, but it retains the immutable active Warrant and its
-  originally selected proof instead of rewriting or rejecting that attempt.
-  Each candidate also retains the exact successful source workflow run. If a
-  controller discovers that another candidate owns the active Warrant, a
-  configured consumer workflow is dispatched immediately for that exact PR,
-  head, and source run; the candidate is not left waiting for a patrol cron.
-
-The controller persists a completed native proof before its final base
-reclassification. A later exact retry can supply that proof and avoid the
-expensive native command when the rooted delta still proves reuse safe. A
-duplicate dispatch against the same already-qualified Warrant returns the same
-proof and reuse roots without another queue mutation. Both result forms carry
-`landingAuthority: false`: only the live qualified Warrant plus exact-head
-GitHub merge-queue admission can authorize landing.
-
-The required controller checks the protected base again after native work. A
-disjoint attributed delta reuses the proof. Overlap or unknown attribution
-triggers one automatic revalidation on the latest base; continued overlap,
-native failure, cancellation, semantic head movement, or an unrecoverable merge
-conflict closes the exact fence. The next queued candidate is notified through
-the `buildchain-dev-delivery-wake` repository event. Its complete semantic
-candidate is carried under the single `client_payload.candidate` envelope so
-GitHub's ten-property top-level limit cannot discard proof bindings. If
-cancellation prevents cleanup, lease expiry recovers retained queue age and
-mints a new fence.
+- `required` persists the submission, selects the Warrant, and refuses GitHub
+  enqueue unless the immutable queue commit, state root, active Warrant, and
+  selected candidate all pass exact readback validation.
 
 Consumers should deploy `shadow` first, inspect receipts, then change their
 protected caller to `required`. Rollback is a reviewed caller change back to
@@ -318,22 +160,15 @@ merged candidate (or accepts explicit evidence for another terminal outcome),
 then closes only the current fencing generation. The separate queued
 cancellation reusable workflow cannot close an active generation; it advances
 the state ref only when the caller's complete terminal binding and expected-old
-root still match. A delayed `dequeued` event is ignored when GitHub readback
-shows the same exact PR head is already queued again, so an earlier queue event
-cannot close a newer active Warrant generation.
+root still match.
 
 Buildchain uses the same contract for its own protected dev line through
 `buildchain-dev-delivery.yml`. The manual caller requires the exact PR head and
-semantic source roots, accepts an optional reusable native proof, pins the runtime to the caller commit, selects
+all native/source proof roots, pins the runtime to the caller commit, selects
 `delivery-warrant-mode: required`, and targets GitHub Merge Queue. It does not
 offer an `off` switch: rollback is a reviewed change to this caller, not an
 operator-time weakening of a specific delivery attempt.
 
-`buildchain init --type native` generates the corresponding protected-dev
-consumer workflow. It supports both explicit dispatch and the bounded wake
-event, uses the same reusable controller, and keeps the native command in the
-consumer repository rather than inventing provider-specific shards.
-
 This mechanism schedules protected delivery only. It does not serialize local
 development, source-only checks, unrelated channels, release publication, or
 runner provisioning. It never grants authority to enable cloud runner

package/docs/engineering-housekeeper.md

@@ -29,9 +29,17 @@ their heads are already ancestors of a mainline.
 The reusable entrypoint is:
 
 ```yaml
-uses: kungfu-systems/buildchain/.github/workflows/engineering-housekeeper.yml@v3
+uses: kungfu-systems/buildchain/.github/workflows/engineering-housekeeper.yml@v4
 ```
 
+The v4 surface is a traceable forward-port of protected v3 merge
+`c9d53c69e90393b2178ad7cdbf00f17e403e17f9` and exact source
+`518990c4118a12562eb9847cb2e1b704983909a0`. It preserves the same `v1`
+contract, temporary-family allowlist, provider adapter, mutation fences, and
+evidence roots. The v4 manifest records that TypeScript remains the sole
+legacy-authoritative writer; the forward-port does not create another contract
+or provider authority. Existing v3 callers retain their original interface.
+
 ## Report mode
 
 `report` is the default. The caller grants only read permissions and receives
@@ -40,7 +48,7 @@ separate plan, Markdown report, and dry-run receipt artifacts:
 ```yaml
 jobs:
   housekeeper:
-    uses: kungfu-systems/buildchain/.github/workflows/engineering-housekeeper.yml@v3
+    uses: kungfu-systems/buildchain/.github/workflows/engineering-housekeeper.yml@v4
     permissions:
       contents: read
       pull-requests: read
@@ -81,7 +89,7 @@ An unattended scheduled caller can set both values in committed policy.
 ```yaml
 jobs:
   housekeeper:
-    uses: kungfu-systems/buildchain/.github/workflows/engineering-housekeeper.yml@v3
+    uses: kungfu-systems/buildchain/.github/workflows/engineering-housekeeper.yml@v4
     permissions:
       contents: write
       pull-requests: write
@@ -120,7 +128,7 @@ continue.
 | `max-actions`               | number  | `20`                        | Positive global apply limit.                                                      |
 | `artifact-retention-days`   | number  | `30`                        | Retention for plan, report, and receipts.                                         |
 | `buildchain-repository`     | string  | `kungfu-systems/buildchain` | Runtime source repository.                                                        |
-| `buildchain-ref`            | string  | `v3`                        | Runtime ref; trusted manual qualification may pass a train or exact SHA.          |
+| `buildchain-ref`            | string  | `v4`                        | Runtime ref; trusted qualification may pass a train or exact SHA.                 |
 
 Stable outputs are `plan-root`, `report-receipt-root`, optional
 `branch-receipt-root` and `pull-request-receipt-root`, `action-count`,

package/docs/getting-started.md

@@ -83,7 +83,7 @@ The generated caller should contain one reusable `uses:` edge and a manual
 ```bash
 rg -n 'uses:|buildchain-ref:' .github/workflows/build.yml
 pnpm exec buildchain release --dry-run \
-  --target-ref alpha/v3/v3.0 \
+  --target-ref alpha/v4/v4.0 \
   --json
 ```
 

package/docs/install.md

@@ -6,8 +6,8 @@ adopting a new version.
 
 ## Standalone Binary
 
-Buildchain v3.0.0 does not publish standalone platform archives. This section
-documents the verified legacy binary release contract; v3 consumers should use
+Buildchain v4.0.0 does not publish standalone platform archives. This section
+documents the verified legacy binary release contract; v4 consumers should use
 the npm package or repository workflow surface below.
 
 Use the archive that matches the platform:
@@ -64,7 +64,7 @@ Stable consumers should pin the exact Buildchain version they have validated,
 for example:
 
 ```bash
-pnpm add -D @kungfu-tech/buildchain@3.0.0
+pnpm add -D @kungfu-tech/buildchain@4.0.0
 ```
 
 If a repository dogfoods a just-published Buildchain version and pnpm's release
@@ -74,7 +74,7 @@ all packages:
 
 ```yaml
 minimumReleaseAgeExclude:
-  - '@kungfu-tech/buildchain@3.0.0'
+  - '@kungfu-tech/buildchain@4.0.0'
 ```
 
 Remove that entry after the package is old enough for the repository's normal
@@ -89,7 +89,7 @@ packages.
 ```bash
 npx @kungfu-tech/buildchain init --type package --package-manager pnpm
 npx @kungfu-tech/buildchain validate --require-version-state
-npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v3/v3.0
+npx @kungfu-tech/buildchain release --dry-run --target-ref alpha/v4/v4.0
 ```
 
 Use `.buildchain/buildchain.toml` to declare lifecycle commands. The commands may use Node

package/docs/kfd-support.md

@@ -77,13 +77,8 @@ KFD records and evidence by SHA-256. The result uses
 `buildchain kfd support project` derives a compatibility projection from the
 standard adopter manifest and its exact passing gate. The adopter manifest is
 the sole KFD-1..13 declaration authority; the command rejects stale package,
-source, witness, registry, verifier-set, and KFD-4/5/7 gate roots. Gate creation
-accepts an explicit `expectedAdopterId`, `expectedSourceRepository`, and
-`expectedSourceSha`; omitting the first two preserves the Buildchain
-self-release default. The gate, every product-gate projection, the legacy
-matrix, Release Passport, and artifact evidence all retain that exact
-adopter/repository/source closure. The emitted matrix is not an independent
-declaration and cannot widen adopter claims.
+source, witness, registry, verifier-set, and KFD-4/5/7 gate roots. The emitted
+matrix is not an independent declaration and cannot widen adopter claims.
 
 ## KFD-1
 

package/docs/lifecycle-protocol.md

@@ -301,10 +301,8 @@ and optionally `lifecycle.publish`.
 The verify stage runs after Buildchain has applied the generated version-state
 changes to the local checkout, and before it creates release commits or moves
 refs. After the command finishes, Buildchain checks that only declared
-`version.files` and `version.derived_files` changed. The latter declares tracked
-outputs regenerated by `lifecycle.version-state` that do not directly contain a
-version field. This prevents verification from quietly adding extra source
-changes to the release commit while keeping generated evidence explicit.
+version-state files changed. This prevents verification from quietly adding
+extra source changes to the release commit.
 
 Buildchain-owned untracked runtime evidence is excluded only through an exact
 internal allowlist. This includes contract-drift issue material under