@kungfu-tech/buildchain 4.0.1 → 4.0.2-alpha.0

package/architecture/agent-change-map.md

@@ -894,6 +894,7 @@ Owner: Buildchain protected delivery maintainers
 - `packages/core/dev-delivery-warrant.js`
 - `packages/core/dev-delivery-warrant-state.js`
 - `packages/core/dev-delivery-warrant-qualification.js`
+- `packages/core/dev-delivery-warrant-legacy-recovery.js`
 - `packages/core/dev-delivery-native-proof.js`
 - `packages/core/dev-delivery-native-execution.js`
 - `packages/core/dev-delivery-execution-failure.js`
@@ -940,6 +941,7 @@ Owner: Buildchain protected delivery maintainers
 
 - `tests/dev-delivery-warrant.test.mjs`
 - `tests/dev-delivery-warrant-command.test.mjs`
+- `tests/dev-delivery-warrant-legacy-recovery.test.mjs`
 - `tests/dev-delivery-two-phase.test.mjs`
 - `tests/dev-delivery-two-phase-run.test.mjs`
 - `tests/dev-delivery-native-run.test.mjs`
@@ -956,7 +958,7 @@ Owner: Buildchain protected delivery maintainers
 
 ### Minimal validation
 
-- `node --test tests/dev-delivery-warrant.test.mjs tests/dev-delivery-warrant-command.test.mjs tests/dev-delivery-two-phase.test.mjs tests/dev-delivery-two-phase-run.test.mjs tests/dev-delivery-native-run.test.mjs tests/dev-delivery-process-boundary.test.mjs tests/dev-delivery-process-boundary-negative.test.mjs tests/dev-delivery-provider-heartbeat.test.mjs tests/dev-delivery-authority.test.mjs tests/build-surface.test.mjs tests/v4-delivery-authority-parity.test.mjs`
+- `node --test tests/dev-delivery-warrant.test.mjs tests/dev-delivery-warrant-command.test.mjs tests/dev-delivery-warrant-legacy-recovery.test.mjs tests/dev-delivery-two-phase.test.mjs tests/dev-delivery-two-phase-run.test.mjs tests/dev-delivery-native-run.test.mjs tests/dev-delivery-process-boundary.test.mjs tests/dev-delivery-process-boundary-negative.test.mjs tests/dev-delivery-provider-heartbeat.test.mjs tests/dev-delivery-authority.test.mjs tests/build-surface.test.mjs tests/v4-delivery-authority-parity.test.mjs`
 
 ## v4-publication-rehearsal
 

package/architecture/internal-capabilities.json

@@ -76,6 +76,7 @@
     "packages/core/dev-delivery-warrant.js",
     "packages/core/dev-delivery-warrant-state.js",
     "packages/core/dev-delivery-warrant-qualification.js",
+    "packages/core/dev-delivery-warrant-legacy-recovery.js",
     "packages/core/dev-delivery-native-proof.js",
     "packages/core/dev-delivery-native-execution.js",
     "packages/core/dev-delivery-execution-failure.js",
@@ -591,6 +592,7 @@
         "packages/core/dev-delivery-warrant.js",
         "packages/core/dev-delivery-warrant-state.js",
         "packages/core/dev-delivery-warrant-qualification.js",
+        "packages/core/dev-delivery-warrant-legacy-recovery.js",
         "packages/core/dev-delivery-native-proof.js",
         "packages/core/dev-delivery-native-execution.js",
         "packages/core/dev-delivery-execution-failure.js",
@@ -624,6 +626,7 @@
       "tests": [
         "tests/dev-delivery-warrant.test.mjs",
         "tests/dev-delivery-warrant-command.test.mjs",
+        "tests/dev-delivery-warrant-legacy-recovery.test.mjs",
         "tests/dev-delivery-two-phase.test.mjs",
         "tests/dev-delivery-two-phase-run.test.mjs",
         "tests/dev-delivery-native-run.test.mjs",
@@ -649,7 +652,7 @@
         "dist/site/schemas/dev-delivery-authority-v2.schema.json"
       ],
       "validationCommands": [
-        "node --test tests/dev-delivery-warrant.test.mjs tests/dev-delivery-warrant-command.test.mjs tests/dev-delivery-two-phase.test.mjs tests/dev-delivery-two-phase-run.test.mjs tests/dev-delivery-native-run.test.mjs tests/dev-delivery-process-boundary.test.mjs tests/dev-delivery-process-boundary-negative.test.mjs tests/dev-delivery-provider-heartbeat.test.mjs tests/dev-delivery-authority.test.mjs tests/build-surface.test.mjs tests/v4-delivery-authority-parity.test.mjs"
+        "node --test tests/dev-delivery-warrant.test.mjs tests/dev-delivery-warrant-command.test.mjs tests/dev-delivery-warrant-legacy-recovery.test.mjs tests/dev-delivery-two-phase.test.mjs tests/dev-delivery-two-phase-run.test.mjs tests/dev-delivery-native-run.test.mjs tests/dev-delivery-process-boundary.test.mjs tests/dev-delivery-process-boundary-negative.test.mjs tests/dev-delivery-provider-heartbeat.test.mjs tests/dev-delivery-authority.test.mjs tests/build-surface.test.mjs tests/v4-delivery-authority-parity.test.mjs"
       ]
     },
     {

package/architecture/maintainability-debt.json

@@ -7,8 +7,8 @@
   },
   "totalExcessLedger": {
     "metric": "calibrated-full-dimensional-excess-v1",
-    "measuredExcess": 67962,
-    "current": 59901
+    "measuredExcess": 67948,
+    "current": 59887
   },
   "defaults": {
     "owner": "Buildchain architecture maintainers",
@@ -1398,21 +1398,21 @@
       "scripts/dev-delivery-warrant-options.mjs": {
         "baseline": {
           "functions": {
-            "devDeliveryCliOptions@36": {
+            "devDeliveryCliOptions@61": {
               "lines": 247
             }
           }
         },
         "current": {
           "functions": {
-            "devDeliveryCliOptions@36": {
-              "lines": 247
+            "devDeliveryCliOptions@61": {
+              "lines": 233
             }
           }
         },
         "target": {
           "functions": {
-            "devDeliveryCliOptions@36": {
+            "devDeliveryCliOptions@61": {
               "lines": 180
             }
           }

package/architecture/maintainability-policy.json

@@ -26,12 +26,12 @@
   },
   "repositoryBudgets": {
     "baselineRevision": "858dbe00b6206a8f356b4a12d2659bee7a72e71b",
-    "maxHandMaintainedSourceFiles": 443,
-    "maxHandMaintainedSourceLines": 164457,
+    "maxHandMaintainedSourceFiles": 444,
+    "maxHandMaintainedSourceLines": 164728,
     "maxWorkflowFiles": 77,
     "maxWorkflowLines": 26791,
-    "latestTransition": "Compatibility Facts verification is split into bounded validation stages.",
-    "latestTransitionRationale": "Bundle indexing and reference validation, query planning, relation-state checks, authority-proof selection, and path orchestration now have explicit private boundaries. load_bundle complexity falls from 38 to 12 and verify_path_inner falls from 216 lines and complexity 68 to 23 lines and complexity 7; every resulting function is within the default Rust budgets, verifier.rs falls from 553 to 551 lines, and no public receipt, fault, serialization, or authority contract changes.",
+    "latestTransition": "Legacy provisional Warrant recovery is isolated behind one terminal-only authority boundary.",
+    "latestTransitionRationale": "One bounded source module admits only a complete exact set of failed hosted legacy runs, requires every provider job to be terminal, and performs one expected-old transition into the current strict state contract. The CLI parser extracts state-coordinate options from its oversized compatibility mapping, reducing devDeliveryCliOptions from 247 to 233 lines; dedicated recovery tests remain below the default test-file budget.",
     "rationale": "Bounded modules separate candidate, evidence, native proof and execution, canonical failure verification, closed-set execution transfer, process-boundary verification, Warrant state and qualification, authority state, qualification, Landing acquisition, verified-attempt admission, Landing settlement and fence validation, provider attempt and heartbeat readback, sealed terminal evidence, hosted heartbeat, resume, store, options, command-specific adapters, and CLI orchestration responsibilities. The protected delivery workflow gives candidate and seal jobs no provider write credential, recursively rejects transfer drift, scopes every transfer artifact to the exact provider run attempt, chains every durable heartbeat state and receipt root on a distinct hosted runner domain, and permits qualification or exact failure settlement only after the finalizer verifies live jobs and the latest durable authority state. Public Landing admission and heartbeat always perform non-injectable fresh exact-attempt provider readback, tolerate only a not-yet-materialized seal job while retaining exact native and duplicate-job rejection, and heartbeat-loss coordination never invokes GitHub's run-scoped cancellation API where a successor rerun could race. The hosted process boundary anchors trust in the kernel-resolved versioned Runner.Worker path while accepting an equivalent argv-zero spelling with the same basename; its public boundary marker is allowed only at the one exact non-secret value, so a forged value under the same credential-like name still fails closed. The credentialless transfer seal validates the rooted native reuse decision against the Warrant-bound source, closure, dependency, toolchain, environment and command inputs; qualifiedBase stays in the proof and decision where it is rooted and later independently rechecked, rather than being assumed on the Warrant schema. V2 mutation cannot initialize a second empty authority beside a legacy ref: migration reads and roots the canonical live v1 ref, rechecks it, applies the explicit configured v2 policy, and atomically replaces its bytes through one expected-old non-force update, so old v1 controllers fail closed while the prior commit remains immutable history. Candidate ancestry classifies the GitHub artifact runtime token as credential authority. Every Landing settlement, including an unexpired fence, requires product-owned terminal readback. Terminal cleanup reads the immutable historical attempt, derives workflow and hosted Landing job identity from live run data, reads the exact protected ref head and compares containment against that immutable SHA, and seals merged only when the admitted merge-group head is contained by that protected base; a later different-head merge settles the old attempt as dequeued. Terminal normalization preserves transfer, finalizer boundary, native and seal job, admitted provider attempt, protected-base head, containment result, and terminal readback coordinates. The public reusable workflow truthfully retains its single-flight v1 authority without advertising v2 migration, while bounded v2 remains a separate opt-in CLI, Node API, and schema contract; the tracked self-caller stays on public v4-alpha with matching stable and alpha locks, and transient train selection is dispatch-only. Next-development parity adds one versioned transition authority, one durable controller, one bounded reservation adapter, and pure public-contract recovery evidence while retaining the existing thin floating-channel callers byte-for-byte. The floating-consumer gate reuses the existing contract-world evaluator so SHA drift passes only under the selected lock's compatibility policy, breaking surface drift still fails closed, and external certification reconstructs the receipt from the observed workflow SHA rather than the lock's historical evidence SHA. Tail reseal adds no Stage Capsule effect or general rebuild authority: it verifies the exact retained four-platform bytes, admits one known macOS tail failure through live provider readback, fences signing and finalization to explicit credentials and Warrant identity, and requires standard candidate Passport plus provider and protected readback. Compatibility Facts parity isolates canonical encoding, temporal verification, lifecycle validation, fixture projection, public authority projection, and CLI adaptation into bounded modules; legacy digest and proof arrays are derived only from exact current Fact lineage. Publication Rehearsal adds no production release authority: the content-addressed capsule contract binds source, candidate, manifest, config, canonical data-only provider bindings, provider policy, observations and core version separately from filesystem, runtime and rehearsal-only provider authority; simulate, replay and explicitly authorized provider rehearsal all reuse the release-tail planner, while same-commit local dogfood resolves the new reusable contract and exact current runtime before external callers remain on floating v4-alpha. Cross-runtime candidate recovery preserves original runtime and provider roots and creates resume lineage only after exact public ref, tag, ancestry, npm version and integrity readback. Adopter Delivery restores the reviewed public v3 gate, drivers, Passport binding, N-1 bootstrap and exact archive loader through one public v4 surface while keeping provider and release authority explicit non-claims. Floating Alpha bootstrap uses only the existing exact resolver and protected Alpha private shell to move an otherwise stale floating shell, retains public v4 stable promotion, and removes itself after protected readback. CI lane change-budget enforcement adds a bounded parser, evaluator, guard, and tests without creating another merge authority.",
     "governance": "legacy-debt-sunset-2026q4"
   },

package/architecture/v3-core-mechanism-inventory.json

@@ -293,6 +293,7 @@
       "sourcePaths": [
         "packages/core/dev-delivery-proof.js",
         "packages/core/dev-delivery-warrant-cancellation.js",
+        "packages/core/dev-delivery-warrant-legacy-recovery.js",
         "packages/core/dev-delivery-warrant-qualification.js",
         "packages/core/dev-delivery-warrant-settlement.js",
         "packages/core/dev-delivery-warrant-state.js",
@@ -306,6 +307,7 @@
       "testPaths": [
         "tests/dev-delivery-warrant.test.mjs",
         "tests/dev-delivery-warrant-command.test.mjs",
+        "tests/dev-delivery-warrant-legacy-recovery.test.mjs",
         "tests/release-blocker-priority.test.mjs"
       ],
       "migrationDisposition": "rebuild-in-rust-with-compatibility-projection",

package/dist/site/buildchain-contract.json

@@ -4,7 +4,7 @@
   "product": {
     "name": "Buildchain",
     "package": "@kungfu-tech/buildchain",
-    "version": "4.0.1",
+    "version": "4.0.2-alpha.0",
     "repository": "https://github.com/kungfu-systems/buildchain"
   },
   "majorLine": "v4",
@@ -1646,7 +1646,7 @@
         "resume-from-candidate-run is fail-closed and uses a fresh caller event instead of rerunning a frozen startup graph"
       ],
       "breakingDigest": "sha256:9db8dd07152855d03ff30f9c571438593c689d3e8139fa45431d000f548242f5",
-      "auditDigest": "sha256:1b505fd44a452b01e0516c9da45994cf7edb33c7f4c3bc01b2f3155ed3d3feb0",
+      "auditDigest": "sha256:1b77b563669a70c8e0a7c6d335f2ddcef9a95178d08e742ecf4aaf66652e7b4f",
       "compatibleBreakingDigests": [
         "sha256:aa30f22e3af0a89841310bdbdc900844dd95a66974db173fa140a71bbd7e82c0"
       ],
@@ -5173,7 +5173,7 @@
         "missing receipts are non-qualifying and must not be represented as a successful controller run"
       ],
       "breakingDigest": "sha256:015d8de793adbd4c539416be7d7512e18cc92097e629b0203fa06d2c183e98bd",
-      "auditDigest": "sha256:1b505fd44a452b01e0516c9da45994cf7edb33c7f4c3bc01b2f3155ed3d3feb0"
+      "auditDigest": "sha256:1b77b563669a70c8e0a7c6d335f2ddcef9a95178d08e742ecf4aaf66652e7b4f"
     },
     {
       "contractVersion": 1,
@@ -5399,5 +5399,5 @@
   "compatibilityFactCutRoot": "sha256:f61b975d4a96c921cc4bd37fb3ed9a0596b47004fe34dc7219979d697e3707f9",
   "compatibilityProofRegistryRoot": "sha256:b7194b811e4d3af2df4390bc4d1731e16a86215bd64ee18cb630dd5492f4fb63",
   "compatibilityDigest": "sha256:20411029d83211dff426fb6535a608902129844a5ccb4788db77d3f81becb839",
-  "contractDigest": "sha256:766fa56a71450d75897ca1040098b5acce8851cb3f1ab76dadc7abc2364bd763"
+  "contractDigest": "sha256:9b8272580aaff37c2ee2772f9a72ca9de83160994f8e7c12156cc3c60fbee5f5"
 }

package/dist/site/buildchain-site.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-bundle",
-  "generatedAt": "2026-08-28T20:22:42.731Z",
-  "publishedAt": "2026-08-28T20:22:42.731Z",
+  "generatedAt": "2026-08-28T20:30:35.956Z",
+  "publishedAt": "2026-08-28T20:30:35.956Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "9df599a42bebd6595ed92a598a569c40651d8c12",
+  "sourceRevision": "3881f9dea6fa750ce5e561fc86419a163ca19b90",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.1",
+    "version": "4.0.2-alpha.0",
     "versionSource": "package.json#version"
   },
   "source": {
@@ -2279,7 +2279,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/dev-delivery-warrant.md",
-      "digest": "sha256:c1124dfae8c771750b127f8c3b85a22cee4b564093bd8d8225e51e11e8146894",
+      "digest": "sha256:5feb5f64f19446f31023ceb1af830cd98383141aeacf689c89e980d7ce9f88ab",
       "headings": [
         {
           "level": 1,
@@ -2317,7 +2317,7 @@
           "anchor": "workflow-rollout-and-rollback"
         }
       ],
-      "markdown": "---\nstatus: accepted\nperiod: ongoing\ntheme: dev-delivery-warrant\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-08-17\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-08-11\n  invisible_context: not asserted\n---\n\n# Dev Delivery Warrant Queue\n\nBuildchain's Dev Delivery Warrant Queue gives a qualified slow pull request a\ndurable, non-preemptive delivery turn without replacing GitHub Merge Queue as\nthe final protected-ref authority.\n\nThe queue is stored on a dedicated Git ref below\n`buildchain/dev-delivery-warrant/`. Every update creates a child Git commit and\nadvances the ref without force. The transition receipt binds the expected old\nstate root; a competing controller receives a visible non-fast-forward failure\ninstead of a second authority claim.\n\n## Contract\n\nA submission binds the repository, protected dev line, pull request, semantic\nsource identity, exact source head, native Assignment and Initiative roots,\nsource patch or tree intent, reusable Source Qualification Proof, plan,\naffected closure, dependencies, toolchain, delivery class, priority, attempts,\nand retained enqueue time.\n\nSelection is deterministic FIFO plus aging with bounded priority. Priority may\nreorder queued work, but it cannot preempt the active Warrant. Exactly one\ncandidate receives a `provisional` leased Warrant containing a fencing token,\nlease generation, expected-old state root, expiry, and the complete exact\nsource binding. It reserves the next protected-dev landing before expensive\nnative shards start, but it is not GitHub Merge Queue admission authority.\nHeartbeat extends only that generation. Native proof success atomically\nupgrades the same token and generation to `qualified`; only then may enqueue\nbegin. Expiry fences further mutations by the old token, but it does not prove\nthat the old native process stopped. The active Warrant therefore remains in\nplace until bounded termination is proven by rooted terminal evidence. Only\nthat exact fenced settlement may clear the holder and permit successor\nselection.\n\nA terminal event may cancel a candidate before selection without minting a\nWarrant. This transition is limited to an exact non-active queued candidate and\nbinds its candidate root, pull request, recorded source head, event-observed\nsource head, terminal event action, evidence root, and expected-old queue root.\nAn active candidate still requires its current fencing token and lease\ngeneration. Exact duplicate cancellation evidence is a visible no-op; identity,\nstate, event, or evidence drift fails closed.\n\nThe reusable terminal controller classifies authoritative completion,\ncancellation, supersession, native failure, and transient dequeue separately.\n`dequeued` retains only a provisional Warrant whose native worker may still be\nrunning: a fresh holder continues with the same generation and token, while an\nexpired holder waits for proof that its fenced worker stopped. A qualified or\nhistorical phase-less holder has no unproven native worker to fence, so its exact\ndequeue closes atomically and persists the rooted queued-successor wake. Queued\nwork may also settle as dequeued because it never started native execution. The\ncontroller uses one `settle` operation for active, queued, already-terminal,\nand never-admitted pull requests. An active Warrant still requires its exact\nfence and evidence. A matching queued cancellation is persisted normally. A\nduplicate terminal event replays the persisted wake, while a pull request that\nnever entered Warrant authority returns a rooted explicit no-op instead of\nfailing the workflow or inventing queue state.\n\nThe supported priority classes are `ordinary`, `expedited`, and `emergency`.\nThe queue does not infer an emergency: callers must choose it explicitly under\ntheir reviewed policy. Delivery classes are `non-native-fast`,\n`native-proof-required`, `cross-platform`, and `release`.\n\n## CI lane change budget\n\n`architecture/ci-lane-change-budget.json` pins the exact protected-Dev cut\nthat predates lane-budget enforcement. `scripts/check-ci-lane-change-budget.mjs`\ncompares the current workflow job set with that cut on every repository check.\nLegacy jobs remain readable without invented metadata, while every newly added\njob fails closed until its exact `<workflow>#<job>` lane declares:\n\n- merge or non-merge authority class;\n- trigger class;\n- concurrency scope and `cancel-in-progress` behavior;\n- expected runner-minutes per run;\n- cancellation/settlement behavior; and\n- merge-critical SLO impact, expected contribution, metric, and rationale.\n\nThe guard is repository policy only. It does not become another required\nGitHub status, acquire merge-queue authority, or relax Delivery Warrant,\nexact-head, approval, required-check, and protected-ref enforcement. A removed\nlane must also remove its declaration, so stale budget records cannot conceal\nworkflow drift.\n\nA release-blocker candidate may additionally carry a rooted priority claim\ncreated from a settled Release Train dual landing. The claim binds the exact\nAssignment, Initiative, repair, prior and successor cuts, candidate generation,\ncut candidate, Dev head, semantic patch, both landing evidence roots, and\npublication gate. Only a claim whose repository, protected base, Work roots,\nhead, patch, and claim root match the queued candidate enters the blocker lane.\nThat lane outranks not-yet-leased ordinary work, but never preempts or rewrites\nan active Warrant; unrelated, conflicted, mismatched, or fabricated claims fail\nclosed before selection.\n\n## Three proof authorities\n\nSource Qualification Proof is created from the cheap source-acceptance gate. It\nbinds the semantic source, exact source head and patch/tree intent, plan,\naffected closure, dependencies, toolchain, covered paths, and exact acceptance\nevidence. Ready state and approval are established before provisional\nselection.\n\nNative Qualification Proof is separate. Its v4 form binds semantic source and patch,\nplan, affected closure, dependency graph, toolchain, the exact execution\nenvironment contract, covered paths, native shard evidence, the exact dev\nbase used by the native composition, and the v3 native heartbeat-run receipt.\nThat receipt exposes and roots the exact repository, protected base, source\nhead, qualified base, toolchain, and environment binding established before\nprocess spawn. The proof carries the exact receipt bytes as well as repeating\nthe binding and receipt roots in its shard evidence. Public verification\nrecomputes those bytes and requires a successful outcome, positive heartbeat\ncount, exact command root, ordered start/completion/qualification timestamps,\nand the complete execution binding; caller-computed roots without the receipt\nbytes are not a v4 proof. Before reuse, the consumer roots the\ncomplete attributed Dev delta, including both sides of every rename, then\nclassifies it:\n\n- unchanged semantic roots plus an unrelated fully attributed base delta reuse\n  native qualification and run only a cheap Project Cut replay. GitHub's `behind`\n  state is accepted only when a rooted replay proof binds the exact current\n  protected base, unchanged PR head and source patch, replay tree, required\n  context roots, and a qualified `project.cut.merge-queue-admission/v1`\n  receipt;\n- an overlapping delta reruns affected native shards or the full native plan;\n- an unknown or truncated graph, ambiguous rename, missing attribution, or\n  changed source, plan, closure, dependency, toolchain, or environment root\n  fails closed to full native qualification.\n\nHistorical Native Qualification Proof v1, v2, and v3 values remain readable,\nbut they cannot be reused because they do not carry the current v4 exact native\nexecution evidence. They fail closed to explicit native revalidation and\nproduce a v4 proof.\n\nThe reuse decision binds the exact old and current Dev heads, normalized changed\npaths and rename pairs in `baseDeltaRoot`. This makes local and hosted replay of\nthe same inputs byte-deterministic. Generated outputs that participate in the\naffected closure must be listed in `affected-paths-json`; a delta touching one\nof those surfaces is overlap, not a documentation-only advance.\n\nIntegration Delivery Proof is separate and cannot be cached across candidates.\nIt binds the exact current dev base, replay tree, GitHub `merge_group` head and\ntree, active Warrant fencing generation, Source Qualification Proof root, and\nfinal required-context roots. GitHub's exact merge-group checks remain the\nfinal integration authority.\n\n## CLI\n\nQueue commands are dry-run by default:\n\n```sh\nbuildchain dev warrant submit --repository owner/repository \\\n  --branch dev/v4/v4.0 --pull-request 123 --source-head <sha> \\\n  --assignment-root <root> --initiative-root <root> \\\n  --source-identity-root <root> --source-patch-root <root> \\\n  --source-proof-root <root> --plan-root <root> --closure-root <root> \\\n  --dependency-root <root> --toolchain-root <root> \\\n  --environment-root <root> \\\n  --delivery-class native-proof-required\n\nbuildchain dev warrant select --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\n\nbuildchain dev proof native --branch dev/v4/v4.0 \\\n  --source-head <sha> --qualified-base <sha> \\\n  --environment-root <root> \\\n  --native-execution-receipt native-heartbeat-run.json \\\n  --affected-paths-json '[\"packages/native\"]' ...\n\nbuildchain dev proof classify-native --source-proof native-proof.json \\\n  --current-base <sha> --graph-known true --attribution-complete true \\\n  --changed-paths-json '[]' --renames-json '[]' ...\n\nbuildchain dev warrant qualify --repository owner/repository \\\n  --branch dev/v4/v4.0 --fencing-token <root> --lease-generation 1 \\\n  --native-proof native-proof.json \\\n  --native-reuse-decision native-reuse-decision.json --execute\n\nbuildchain dev warrant cancel-queued --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> --pull-request 123 \\\n  --expected-source-head <queued-sha> --observed-source-head <event-sha> \\\n  --expected-old <queue-root> --event-action closed --outcome cancelled \\\n  --evidence-root <terminal-event-root> --execute\n```\n\n`heartbeat`, `qualify`, `recover`, `close`, `settle`, `cancel-queued`, and `observe` use the same durable authority.\nWarrant-scoped mutations require the exact fencing token and lease generation.\n`close` also requires a rooted terminal evidence object.\n\nOn the v4 line, `observe` also has an explicit `--read-mode v4` candidate. It requires retained exact semantic-diff qualification and source binding, invokes the effect-disabled Rust projection, retains parity evidence, and returns the existing observation shape. The default and rollback mode remains `v3`; mutation commands ignore the read switch. See [`v4-delivery-warrant-read-candidate.md`](v4-delivery-warrant-read-candidate.md).\n\nExpensive native commands must run through `dev-delivery-native-run.mjs` (or an\nequivalent exact consumer). Before spawn it validates the environment and\nexecution roots and traverses the complete Linux `/proc` ancestry. An unreadable\nprocess environment or status is a failure, as is any variable name containing a\ngeneric auth, credential, key, password, secret, or token segment. The child\nstill receives only the fixed process-basics allowlist. The command root,\nexact execution binding and root, successful outcome, child start and completion\ntimes, and heartbeat count are included in the native receipt. The controller\nkeeps retained-fence heartbeats across the direct child lifetime and requires a\nfinal successful heartbeat after child exit; process-group termination on fence\nloss remains fail-closed runtime behavior rather than a claimed receipt field.\n\nThe reusable workflow does not run that controller in a credentialed job. A\nGitHub-hosted `native-execution` job has read-only checkout permission, no\nprovider write credential in the candidate step or its ancestry, and cannot\nqualify, settle, enqueue, or renew provider state. It copies only rooted proof\nand Warrant bytes into a dedicated staging directory and uploads that closed set.\nThe success artifact contains exactly its transfer manifest, Warrant, native\nresult, native proof, and reuse decision; the failed-native artifact contains\nexactly its transfer manifest, Warrant, canonical rooted failure, and\nprovider-settlement binding. Recursive verification rejects missing or extra\nentries, duplicate or case-colliding paths, traversal, symlinks, directories,\nother non-regular entries, non-canonical failure or manifest JSON bytes, byte\ndrift, and mutation between the first and second recursive membership\nsnapshots. A\ndependent GitHub-hosted finalizer downloads those bytes and uses live\nActions job readback to prove different positive job ids, different runner\nidentities, a matching run attempt, and strict native-completion-before-finalizer\nordering. It recomputes the canonical failure root and binds that exact root,\ntransfer root, native job, Warrant state and fence into the live provider\nboundary. Failure settlement consumes those verified coordinates directly; it\ndoes not synthesize a second failure. The boundary also roots a live open-PR\nhead and protected-ref readback. The trusted finalizer uses its provider credential only for\nthose GET readbacks until the byte transfer, runner boundary, and semantic native\nproof have passed independent verification. It then rereads the live PR head,\nprotected base, and Warrant fence before qualifying or settling. A missing or\ncorrupt artifact, unreadable `/proc`, same job or runner, invalid timestamp,\nself-hosted label, stale PR/base/fence, or readback mismatch fails closed. Native\nexit zero is only evidence input.\n\nProof commands create, verify, classify, and compose the two proof layers:\n\n```sh\nbuildchain dev proof source ...\nbuildchain dev proof classify --source-proof source-proof.json ...\nbuildchain dev proof replay ...\nbuildchain dev proof replay-proof \\\n  --qualification-receipt project-cut-admission.json ...\nbuildchain dev proof integration --warrant-result warrant.json ...\n```\n\n## Opt-in bounded qualification and exclusive landing\n\nBuildchain also defines an explicit production opt-in that turns successful\nshadow evidence into a separate v2 authority state. It does not widen or\nreinterpret the v1 Warrant queue. The accepted\n[`Qualification Lease and Landing Warrant ADR`](dev-delivery-qualification-landing-adr.md)\nand `contracts/dev-delivery-authority-v2.schema.json` are authoritative.\n\nIn `bounded-qualification-landing` mode, a configured number of exact\nQualification Leases may coexist. Each lease carries\n`authority = qualification-only` and `mergeGroupAdmission = false`. Completing\nqualification records evidence and releases that lease. Qualified candidates\nthen wait for the one `Landing Warrant`, which alone carries\n`authority = merge-group-admission` and may be checked for `merge_group`\nadmission.\n\nConcurrency is granted only across disjoint rooted `qualificationDomains`.\nOverlap and unknown domains are held behind the active safety boundary with an\nexplicit content-rooted reason. `maxLandingOvertakes` prevents a slow older\ncandidate from being bypassed indefinitely, while `maxQualificationAttempts`\nturns repeated heartbeat loss into a rooted terminal failure. Every release\nreturns a deterministic rooted wake instruction; an exact duplicate release or\nrecovery is a state-root-preserving no-op.\n\nAn expired qualification-only lease may release its bounded compute slot. An\nexpired Landing Warrant does not release exclusive provider authority by time\nalone: recovery retains it and requires exact provider-stop or terminal\nsettlement evidence for the same token and generation before another landing\ncandidate can be selected. Expired cleanup invokes a separate independent\nprovider terminal verifier after candidate exit. Its rooted readback must match\nthe exact repository, protected base, authority state root, candidate, pull\nrequest, source head, Landing token and generation, provider run and job, and a\nfresh observation for that Warrant. Caller assertions, forged roots, wrong\nbindings, nonterminal states, and stale observations cannot release the slot.\nThe verifier reads the immutable historical run-attempt endpoint. A later rerun\nor synchronized PR head cannot rewrite the admitted attempt or prevent its\nterminal settlement; current PR identity and protected base still must match.\nThe reader rejects an empty run conclusion, nonterminal run or job state,\nunsupported job conclusion, or pull-request state outside `open|closed` before\nit can seal product-owned cleanup evidence.\n\nThe public two-phase workflow keeps heartbeat authority in a fourth,\nGitHub-hosted job on a runner domain distinct from admission, native execution,\nevidence sealing, and finalization. Each successful heartbeat records the exact\nexpected-old and next authority state roots plus its receipt root. The\ncredentialless native job holds only its immutable admission binding; the\nhosted coordinator alone renews durable state. After heartbeat loss it records\nthe exact current attempt but never invokes GitHub's run-scoped cancellation\nAPI, so a successor rerun cannot be cancelled through a stale coordinate. All boundary jobs must prove the exact\n`GitHub Actions` hosted runner group and reject `self-hosted`. The finalizer\nrereads the provider job set and live authority state, rejects missing\nor reordered receipt continuity, and requires the live state root to equal the\nreceipt's latest root before it can qualify, settle, or land.\n\nA terminal native failure retains the complete provider chain through every\nwrite-normalize-observe-remutate cycle: `transferRoot`,\n`finalizerBoundaryRoot`, `nativeJobId`, `sealJobId`, the exact admitted\n`providerAttempt`, and, when expiry cleanup was required, the independent\n`providerTerminalReadbackRoot`.\n\nBuildchain's tracked self-delivery caller invokes\n`kungfu-systems/buildchain/.github/workflows/dev-pr-auto-merge.yml@v4-alpha`.\nThe durable selector remains the floating alpha channel, the repository keeps\nmatching `.buildchain/contract-lock.json` (`v4`) and\n`.buildchain/alpha-contract-lock.json` (`v4-alpha`), and a train runtime may be\nselected only through the trusted, non-persistent `workflow_dispatch` input.\nNo candidate SHA or train ref is persisted in the caller.\n\nOnly complete `verified-native-qualification` evidence can mint a new Landing\nWarrant. Migrated `legacy-compatibility-only` evidence may preserve an exact\nalready-active historical Landing fence, but it cannot create a successor\nLanding or acquire native proof authority.\n\nThe public command family is explicit:\n\n```sh\nbuildchain dev authority migrate --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute --json\nbuildchain dev authority submit --repository owner/repository \\\n  --branch dev/v4/v4.0 --environment-root <root> \\\n  --qualification-domains '[\"<root>\"]' ... --execute\nbuildchain dev authority lease-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority heartbeat-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 --execute\nbuildchain dev authority complete-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 \\\n  --evidence-root <qualification-root> --execute\nbuildchain dev authority lease-landing --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority heartbeat-landing --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 \\\n  --provider-attempt admitted-provider-attempt.json --execute\nbuildchain dev authority recover --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority admit-merge-group --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 \\\n  --merge-group-head <sha>\n```\n\nTerminal settlement releases either authority immediately from exact evidence;\nit does not wait for TTL. Exact duplicate settlement is a state-root-preserving\nno-op. The default `buildchain dev warrant` commands, v1 state bytes, and\nsingle-flight behavior do not change while this mode is off.\n\nMigration also accepts the historical non-native v1 form whose active Warrant\npredates the `phase` field. It preserves that exact fence as Landing authority\nand records a schema-safe `legacy-compatibility-only` qualification carrying the\nexact legacy state root, token, generation, source proof, and phase. Fields that\nv1 never established remain explicitly null, including the phase-less\nqualification time and every native proof field. A migrated qualified v1\nWarrant retains its historical proof roots as compatibility facts, but\n`nativeProofAuthority` remains false because migration cannot reconstruct the\nv2 execution binding or qualification contract. Neither form can claim new\nnative proof or reuse authority. Phase-less native candidates remain invalid.\n\n## Workflow rollout and rollback\n\nThe reusable `dev-pr-auto-merge.yml` supports three explicit rollout modes:\n\n- `off` preserves the previous exact-head admission controller;\n- `shadow` qualifies the source and emits a read-only queue submission plan;\n- `required` persists the submission, selects a provisional Warrant, runs or\n  reuses semantic native proof under heartbeat, atomically qualifies the same\n  fence, and refuses GitHub enqueue unless the immutable queue commit, state root, active Warrant, and\n  selected candidate all pass exact readback validation. Immediately before\n  enqueue, the controller writes and then reads back both the exact-head queue\n  admission status and active lease status. Only after those statuses are\n  visible at their required states does it reread the pull request head,\n  protected base, native merge queue, and current protected Warrant state. The\n  final rooted admission transaction binds the frozen base, source head,\n  candidate, fencing token, generation, native proof roots, Project Cut proof,\n  and both status contexts. Status propagation is retried before enqueue;\n  base, head, queue-predecessor, lease, or Warrant drift revokes both statuses\n  without attempting enqueue. A previously valid result is not authority after terminal\n  closeout. Re-running qualification for the same selected head may regenerate\n  timestamped proof bytes, but it retains the immutable active Warrant and its\n  originally selected proof instead of rewriting or rejecting that attempt.\n  Each candidate also retains the exact successful source workflow run. If a\n  controller discovers that another candidate owns the active Warrant, a\n  configured consumer workflow is dispatched immediately for that exact PR,\n  head, source run, Assignment and Initiative, source identity and patch,\n  plan, closure, dependency, toolchain, environment, affected paths, delivery\n  class, and priority; the candidate is not left waiting for a patrol cron.\n  The shipped Buildchain caller and native template configure this handoff path\n  and accept the same complete input contract. A historical phase-less owner\n  uses the distinct `legacy-phase-less-active-owner` command path. That path\n  carries the exact queue state root observed before its duplicate submission,\n  fencing token, generation, PR, head, and source-run binding. The submission\n  receipt proves that pre-transition root even though the queue transition\n  advances the current state root. The path omits `environment-root`, `native-command`, and\n  `native-command-root`, and rejects readback drift. It therefore resumes the\n  historical non-native authority without inventing a native command contract\n  or upgrading the owner to native proof authority.\n\n  The PR-controlled native candidate runs in a distinct GitHub-hosted job with\n  no provider write credential in the step or process ancestry. The dependent\n  credentialed finalizer runs on another live-readback-proven GitHub-hosted job\n  and runner, verifies the content-addressed transfer, then independently rereads\n  the PR, protected base, and provider fence before qualification or settlement.\n  Detached descendants, including descendants that unset runner tracking, remain\n  in the native runner authority domain and cannot enter the fresh finalizer\n  domain. Exit zero alone is never treated as provider mutation authority,\n  Landing authority, or completed delivery.\n\n  Persistent self-hosted runners are intentionally outside this contract. A\n  `needs` edge alone does not prove process cleanup or a new authority domain, so\n  the finalizer rejects a self-hosted label. Supporting self-hosted execution\n  would require separately attested one-job runner destruction and a provider\n  readback contract at least as strong as the GitHub-hosted boundary.\n\n  Required-mode admission also performs a latest-base Project Cut immediately\n  before enqueue. If the protected base advanced, the controller reclassifies\n  the exact attributed delta against the rooted native proof. Only a disjoint,\n  fully attributed move may reuse that proof; overlap, unknown attribution,\n  missing composition, or merge conflict fails with a stable pre-enqueue reason.\n  The rooted Project Cut receipt binds the frozen and admitted base SHAs,\n  GitHub's exact synthetic merge commit and replay tree, and the unchanged PR\n  head. A final base/head/queue/Warrant compare-and-swap readback must still\n  match that receipt before the enqueue mutation is attempted.\n\n  The protected branch ref is the base authority for that compare-and-swap.\n  A pull request's `base.sha` may remain an older composition snapshot while\n  GitHub reports the pull request as behind, so it is diagnostic rather than a\n  substitute for the separately read protected ref and rooted Project Cut.\n\nFor a required native delivery class, the reusable controller rejects a\nmissing or malformed environment root before runtime checkout, candidate\nsubmission, Warrant selection, or native execution. The input remains\nconditionally optional so `off`, `shadow`, and `non-native-fast` callers keep\ntheir documented behavior.\n\nThe controller persists a completed native proof before its final base\nreclassification. A later exact retry can supply that proof and avoid the\nexpensive native command when the rooted delta still proves reuse safe. A\nduplicate dispatch against the same already-qualified Warrant returns the same\nproof and reuse roots plus a rooted qualification replay output without another\nqueue mutation. Both result forms carry\n`landingAuthority: false`: only the live qualified Warrant plus exact-head\nGitHub merge-queue admission can authorize landing.\n\nThe required controller checks the protected base again after native work. A\ndisjoint attributed delta reuses the proof. Overlap or unknown attribution\ntriggers one automatic revalidation on the latest base; continued overlap,\nnative failure, cancellation, semantic head movement, or an unrecoverable merge\nconflict closes the exact fence. The next queued candidate is notified through\nthe `buildchain-dev-delivery-wake` repository event. Its complete semantic\ncandidate is carried under the single `client_payload.candidate` envelope so\nGitHub's ten-property top-level limit cannot discard proof bindings. If\ncancellation prevents cleanup, lease expiry recovers retained queue age and\nmints a new fence.\n\nConsumers should deploy `shadow` first, inspect receipts, then change their\nprotected caller to `required`. Rollback is a reviewed caller change back to\n`off`; it does not delete queue history or reinterpret old receipts. The\nterminal reusable workflow creates the exact Integration Delivery Proof for a\nmerged candidate (or accepts explicit evidence for another terminal outcome),\nthen closes only the current fencing generation. The separate queued\ncancellation reusable workflow cannot close an active generation; it advances\nthe state ref only when the caller's complete terminal binding and expected-old\nroot still match. A delayed `dequeued` event is ignored when GitHub readback\nshows the same exact PR head is already queued again, so an earlier queue event\ncannot close a newer active Warrant generation.\n\nBuildchain uses the same contract for its own protected dev line through\n`buildchain-dev-delivery.yml`. The manual caller requires the exact PR head and\nsemantic source roots, accepts an optional reusable native proof, keeps both\nthe durable public selector and explicit runtime input on `v4-alpha`, selects\n`delivery-warrant-mode: required`, and targets GitHub Merge Queue. It does not\noffer an `off` switch: rollback is a reviewed change to this caller, not an\noperator-time weakening of a specific delivery attempt.\n\n`templates/native-dev-delivery.yml` provides the corresponding protected-dev\nconsumer workflow. It supports both explicit dispatch and the bounded wake\nevent, calls the allowed floating `@v4-alpha` selector, explicitly passes the v4\nruntime ref that locks every delivery job to the same checkout, and keeps the\nnative command in the consumer repository rather than inventing\nprovider-specific shards. Both callers explicitly bind the queue-admission\nand active-lease status contexts so write/readback fencing uses the same exact\nnames. The reusable workflow defaults the explicit runtime input to\n`v4-alpha`; an empty input or any v3 selector fails before the first runtime\ncheckout.\n\nThis mechanism schedules protected delivery only. It does not serialize local\ndevelopment, source-only checks, unrelated channels, release publication, or\nrunner provisioning. It never grants authority to enable cloud runner\ncampaigns."
+      "markdown": "---\nstatus: accepted\nperiod: ongoing\ntheme: dev-delivery-warrant\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-08-17\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-08-11\n  invisible_context: not asserted\n---\n\n# Dev Delivery Warrant Queue\n\nBuildchain's Dev Delivery Warrant Queue gives a qualified slow pull request a\ndurable, non-preemptive delivery turn without replacing GitHub Merge Queue as\nthe final protected-ref authority.\n\nThe queue is stored on a dedicated Git ref below\n`buildchain/dev-delivery-warrant/`. Every update creates a child Git commit and\nadvances the ref without force. The transition receipt binds the expected old\nstate root; a competing controller receives a visible non-fast-forward failure\ninstead of a second authority claim.\n\n## Contract\n\nA submission binds the repository, protected dev line, pull request, semantic\nsource identity, exact source head, native Assignment and Initiative roots,\nsource patch or tree intent, reusable Source Qualification Proof, plan,\naffected closure, dependencies, toolchain, delivery class, priority, attempts,\nand retained enqueue time.\n\nSelection is deterministic FIFO plus aging with bounded priority. Priority may\nreorder queued work, but it cannot preempt the active Warrant. Exactly one\ncandidate receives a `provisional` leased Warrant containing a fencing token,\nlease generation, expected-old state root, expiry, and the complete exact\nsource binding. It reserves the next protected-dev landing before expensive\nnative shards start, but it is not GitHub Merge Queue admission authority.\nHeartbeat extends only that generation. Native proof success atomically\nupgrades the same token and generation to `qualified`; only then may enqueue\nbegin. Expiry fences further mutations by the old token, but it does not prove\nthat the old native process stopped. The active Warrant therefore remains in\nplace until bounded termination is proven by rooted terminal evidence. Only\nthat exact fenced settlement may clear the holder and permit successor\nselection.\n\nA terminal event may cancel a candidate before selection without minting a\nWarrant. This transition is limited to an exact non-active queued candidate and\nbinds its candidate root, pull request, recorded source head, event-observed\nsource head, terminal event action, evidence root, and expected-old queue root.\nAn active candidate still requires its current fencing token and lease\ngeneration. Exact duplicate cancellation evidence is a visible no-op; identity,\nstate, event, or evidence drift fails closed.\n\nThe reusable terminal controller classifies authoritative completion,\ncancellation, supersession, native failure, and transient dequeue separately.\n`dequeued` retains only a provisional Warrant whose native worker may still be\nrunning: a fresh holder continues with the same generation and token, while an\nexpired holder waits for proof that its fenced worker stopped. A qualified or\nhistorical phase-less holder has no unproven native worker to fence, so its exact\ndequeue closes atomically and persists the rooted queued-successor wake. Queued\nwork may also settle as dequeued because it never started native execution. The\ncontroller uses one `settle` operation for active, queued, already-terminal,\nand never-admitted pull requests. An active Warrant still requires its exact\nfence and evidence. A matching queued cancellation is persisted normally. A\nduplicate terminal event replays the persisted wake, while a pull request that\nnever entered Warrant authority returns a rooted explicit no-op instead of\nfailing the workflow or inventing queue state.\n\nThe supported priority classes are `ordinary`, `expedited`, and `emergency`.\nThe queue does not infer an emergency: callers must choose it explicitly under\ntheir reviewed policy. Delivery classes are `non-native-fast`,\n`native-proof-required`, `cross-platform`, and `release`.\n\n## CI lane change budget\n\n`architecture/ci-lane-change-budget.json` pins the exact protected-Dev cut\nthat predates lane-budget enforcement. `scripts/check-ci-lane-change-budget.mjs`\ncompares the current workflow job set with that cut on every repository check.\nLegacy jobs remain readable without invented metadata, while every newly added\njob fails closed until its exact `<workflow>#<job>` lane declares:\n\n- merge or non-merge authority class;\n- trigger class;\n- concurrency scope and `cancel-in-progress` behavior;\n- expected runner-minutes per run;\n- cancellation/settlement behavior; and\n- merge-critical SLO impact, expected contribution, metric, and rationale.\n\nThe guard is repository policy only. It does not become another required\nGitHub status, acquire merge-queue authority, or relax Delivery Warrant,\nexact-head, approval, required-check, and protected-ref enforcement. A removed\nlane must also remove its declaration, so stale budget records cannot conceal\nworkflow drift.\n\nA release-blocker candidate may additionally carry a rooted priority claim\ncreated from a settled Release Train dual landing. The claim binds the exact\nAssignment, Initiative, repair, prior and successor cuts, candidate generation,\ncut candidate, Dev head, semantic patch, both landing evidence roots, and\npublication gate. Only a claim whose repository, protected base, Work roots,\nhead, patch, and claim root match the queued candidate enters the blocker lane.\nThat lane outranks not-yet-leased ordinary work, but never preempts or rewrites\nan active Warrant; unrelated, conflicted, mismatched, or fabricated claims fail\nclosed before selection.\n\n## Three proof authorities\n\nSource Qualification Proof is created from the cheap source-acceptance gate. It\nbinds the semantic source, exact source head and patch/tree intent, plan,\naffected closure, dependencies, toolchain, covered paths, and exact acceptance\nevidence. Ready state and approval are established before provisional\nselection.\n\nNative Qualification Proof is separate. Its v4 form binds semantic source and patch,\nplan, affected closure, dependency graph, toolchain, the exact execution\nenvironment contract, covered paths, native shard evidence, the exact dev\nbase used by the native composition, and the v3 native heartbeat-run receipt.\nThat receipt exposes and roots the exact repository, protected base, source\nhead, qualified base, toolchain, and environment binding established before\nprocess spawn. The proof carries the exact receipt bytes as well as repeating\nthe binding and receipt roots in its shard evidence. Public verification\nrecomputes those bytes and requires a successful outcome, positive heartbeat\ncount, exact command root, ordered start/completion/qualification timestamps,\nand the complete execution binding; caller-computed roots without the receipt\nbytes are not a v4 proof. Before reuse, the consumer roots the\ncomplete attributed Dev delta, including both sides of every rename, then\nclassifies it:\n\n- unchanged semantic roots plus an unrelated fully attributed base delta reuse\n  native qualification and run only a cheap Project Cut replay. GitHub's `behind`\n  state is accepted only when a rooted replay proof binds the exact current\n  protected base, unchanged PR head and source patch, replay tree, required\n  context roots, and a qualified `project.cut.merge-queue-admission/v1`\n  receipt;\n- an overlapping delta reruns affected native shards or the full native plan;\n- an unknown or truncated graph, ambiguous rename, missing attribution, or\n  changed source, plan, closure, dependency, toolchain, or environment root\n  fails closed to full native qualification.\n\nHistorical Native Qualification Proof v1, v2, and v3 values remain readable,\nbut they cannot be reused because they do not carry the current v4 exact native\nexecution evidence. They fail closed to explicit native revalidation and\nproduce a v4 proof.\n\nThe reuse decision binds the exact old and current Dev heads, normalized changed\npaths and rename pairs in `baseDeltaRoot`. This makes local and hosted replay of\nthe same inputs byte-deterministic. Generated outputs that participate in the\naffected closure must be listed in `affected-paths-json`; a delta touching one\nof those surfaces is overlap, not a documentation-only advance.\n\nIntegration Delivery Proof is separate and cannot be cached across candidates.\nIt binds the exact current dev base, replay tree, GitHub `merge_group` head and\ntree, active Warrant fencing generation, Source Qualification Proof root, and\nfinal required-context roots. GitHub's exact merge-group checks remain the\nfinal integration authority.\n\n## CLI\n\nQueue commands are dry-run by default:\n\n```sh\nbuildchain dev warrant submit --repository owner/repository \\\n  --branch dev/v4/v4.0 --pull-request 123 --source-head <sha> \\\n  --assignment-root <root> --initiative-root <root> \\\n  --source-identity-root <root> --source-patch-root <root> \\\n  --source-proof-root <root> --plan-root <root> --closure-root <root> \\\n  --dependency-root <root> --toolchain-root <root> \\\n  --environment-root <root> \\\n  --delivery-class native-proof-required\n\nbuildchain dev warrant select --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\n\nbuildchain dev proof native --branch dev/v4/v4.0 \\\n  --source-head <sha> --qualified-base <sha> \\\n  --environment-root <root> \\\n  --native-execution-receipt native-heartbeat-run.json \\\n  --affected-paths-json '[\"packages/native\"]' ...\n\nbuildchain dev proof classify-native --source-proof native-proof.json \\\n  --current-base <sha> --graph-known true --attribution-complete true \\\n  --changed-paths-json '[]' --renames-json '[]' ...\n\nbuildchain dev warrant qualify --repository owner/repository \\\n  --branch dev/v4/v4.0 --fencing-token <root> --lease-generation 1 \\\n  --native-proof native-proof.json \\\n  --native-reuse-decision native-reuse-decision.json --execute\n\nbuildchain dev warrant cancel-queued --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> --pull-request 123 \\\n  --expected-source-head <queued-sha> --observed-source-head <event-sha> \\\n  --expected-old <queue-root> --event-action closed --outcome cancelled \\\n  --evidence-root <terminal-event-root> --execute\n```\n\n`heartbeat`, `qualify`, `recover`, `close`, `settle`, `cancel-queued`, and `observe` use the same durable authority.\nWarrant-scoped mutations require the exact fencing token and lease generation.\n`close` also requires a rooted terminal evidence object.\n\nLegacy v3 queues that predate the native command contract can be observed but\ncannot enter ordinary mutation paths. If every live legacy candidate has an\nexact completed failed hosted run with zero nonterminal jobs, an operator may\natomically terminalize that complete live set:\n\n```sh\nbuildchain dev warrant recover-legacy-terminal \\\n  --repository owner/repository --branch dev/v4/v4.0 \\\n  --expected-old sha256:<current-state-root> \\\n  --legacy-terminal-recovery legacy-terminal-recovery.json --execute\n```\n\nThe request must cover every live legacy native candidate exactly once and\nbind each stored candidate, source workflow run, terminal provider result, and\ncontent-addressed evidence object. Each evidence object carries the exact\nprovider job identities, attempts, conclusions, and completion timestamps; all\njobs must be terminal and at least one must have failed. The transition writes\none expected-old state update and requires the resulting queue to pass the\ncurrent strict native-proof contract. The recovery cannot qualify, merge,\nrequeue, or partially advance a legacy authority state.\n\nOn the v4 line, `observe` also has an explicit `--read-mode v4` candidate. It requires retained exact semantic-diff qualification and source binding, invokes the effect-disabled Rust projection, retains parity evidence, and returns the existing observation shape. The default and rollback mode remains `v3`; mutation commands ignore the read switch. See [`v4-delivery-warrant-read-candidate.md`](v4-delivery-warrant-read-candidate.md).\n\nExpensive native commands must run through `dev-delivery-native-run.mjs` (or an\nequivalent exact consumer). Before spawn it validates the environment and\nexecution roots and traverses the complete Linux `/proc` ancestry. An unreadable\nprocess environment or status is a failure, as is any variable name containing a\ngeneric auth, credential, key, password, secret, or token segment. The child\nstill receives only the fixed process-basics allowlist. The command root,\nexact execution binding and root, successful outcome, child start and completion\ntimes, and heartbeat count are included in the native receipt. The controller\nkeeps retained-fence heartbeats across the direct child lifetime and requires a\nfinal successful heartbeat after child exit; process-group termination on fence\nloss remains fail-closed runtime behavior rather than a claimed receipt field.\n\nThe reusable workflow does not run that controller in a credentialed job. A\nGitHub-hosted `native-execution` job has read-only checkout permission, no\nprovider write credential in the candidate step or its ancestry, and cannot\nqualify, settle, enqueue, or renew provider state. It copies only rooted proof\nand Warrant bytes into a dedicated staging directory and uploads that closed set.\nThe success artifact contains exactly its transfer manifest, Warrant, native\nresult, native proof, and reuse decision; the failed-native artifact contains\nexactly its transfer manifest, Warrant, canonical rooted failure, and\nprovider-settlement binding. Recursive verification rejects missing or extra\nentries, duplicate or case-colliding paths, traversal, symlinks, directories,\nother non-regular entries, non-canonical failure or manifest JSON bytes, byte\ndrift, and mutation between the first and second recursive membership\nsnapshots. A\ndependent GitHub-hosted finalizer downloads those bytes and uses live\nActions job readback to prove different positive job ids, different runner\nidentities, a matching run attempt, and strict native-completion-before-finalizer\nordering. It recomputes the canonical failure root and binds that exact root,\ntransfer root, native job, Warrant state and fence into the live provider\nboundary. Failure settlement consumes those verified coordinates directly; it\ndoes not synthesize a second failure. The boundary also roots a live open-PR\nhead and protected-ref readback. The trusted finalizer uses its provider credential only for\nthose GET readbacks until the byte transfer, runner boundary, and semantic native\nproof have passed independent verification. It then rereads the live PR head,\nprotected base, and Warrant fence before qualifying or settling. A missing or\ncorrupt artifact, unreadable `/proc`, same job or runner, invalid timestamp,\nself-hosted label, stale PR/base/fence, or readback mismatch fails closed. Native\nexit zero is only evidence input.\n\nProof commands create, verify, classify, and compose the two proof layers:\n\n```sh\nbuildchain dev proof source ...\nbuildchain dev proof classify --source-proof source-proof.json ...\nbuildchain dev proof replay ...\nbuildchain dev proof replay-proof \\\n  --qualification-receipt project-cut-admission.json ...\nbuildchain dev proof integration --warrant-result warrant.json ...\n```\n\n## Opt-in bounded qualification and exclusive landing\n\nBuildchain also defines an explicit production opt-in that turns successful\nshadow evidence into a separate v2 authority state. It does not widen or\nreinterpret the v1 Warrant queue. The accepted\n[`Qualification Lease and Landing Warrant ADR`](dev-delivery-qualification-landing-adr.md)\nand `contracts/dev-delivery-authority-v2.schema.json` are authoritative.\n\nIn `bounded-qualification-landing` mode, a configured number of exact\nQualification Leases may coexist. Each lease carries\n`authority = qualification-only` and `mergeGroupAdmission = false`. Completing\nqualification records evidence and releases that lease. Qualified candidates\nthen wait for the one `Landing Warrant`, which alone carries\n`authority = merge-group-admission` and may be checked for `merge_group`\nadmission.\n\nConcurrency is granted only across disjoint rooted `qualificationDomains`.\nOverlap and unknown domains are held behind the active safety boundary with an\nexplicit content-rooted reason. `maxLandingOvertakes` prevents a slow older\ncandidate from being bypassed indefinitely, while `maxQualificationAttempts`\nturns repeated heartbeat loss into a rooted terminal failure. Every release\nreturns a deterministic rooted wake instruction; an exact duplicate release or\nrecovery is a state-root-preserving no-op.\n\nAn expired qualification-only lease may release its bounded compute slot. An\nexpired Landing Warrant does not release exclusive provider authority by time\nalone: recovery retains it and requires exact provider-stop or terminal\nsettlement evidence for the same token and generation before another landing\ncandidate can be selected. Expired cleanup invokes a separate independent\nprovider terminal verifier after candidate exit. Its rooted readback must match\nthe exact repository, protected base, authority state root, candidate, pull\nrequest, source head, Landing token and generation, provider run and job, and a\nfresh observation for that Warrant. Caller assertions, forged roots, wrong\nbindings, nonterminal states, and stale observations cannot release the slot.\nThe verifier reads the immutable historical run-attempt endpoint. A later rerun\nor synchronized PR head cannot rewrite the admitted attempt or prevent its\nterminal settlement; current PR identity and protected base still must match.\nThe reader rejects an empty run conclusion, nonterminal run or job state,\nunsupported job conclusion, or pull-request state outside `open|closed` before\nit can seal product-owned cleanup evidence.\n\nThe public two-phase workflow keeps heartbeat authority in a fourth,\nGitHub-hosted job on a runner domain distinct from admission, native execution,\nevidence sealing, and finalization. Each successful heartbeat records the exact\nexpected-old and next authority state roots plus its receipt root. The\ncredentialless native job holds only its immutable admission binding; the\nhosted coordinator alone renews durable state. After heartbeat loss it records\nthe exact current attempt but never invokes GitHub's run-scoped cancellation\nAPI, so a successor rerun cannot be cancelled through a stale coordinate. All boundary jobs must prove the exact\n`GitHub Actions` hosted runner group and reject `self-hosted`. The finalizer\nrereads the provider job set and live authority state, rejects missing\nor reordered receipt continuity, and requires the live state root to equal the\nreceipt's latest root before it can qualify, settle, or land.\n\nA terminal native failure retains the complete provider chain through every\nwrite-normalize-observe-remutate cycle: `transferRoot`,\n`finalizerBoundaryRoot`, `nativeJobId`, `sealJobId`, the exact admitted\n`providerAttempt`, and, when expiry cleanup was required, the independent\n`providerTerminalReadbackRoot`.\n\nBuildchain's tracked self-delivery caller invokes\n`kungfu-systems/buildchain/.github/workflows/dev-pr-auto-merge.yml@v4-alpha`.\nThe durable selector remains the floating alpha channel, the repository keeps\nmatching `.buildchain/contract-lock.json` (`v4`) and\n`.buildchain/alpha-contract-lock.json` (`v4-alpha`), and a train runtime may be\nselected only through the trusted, non-persistent `workflow_dispatch` input.\nNo candidate SHA or train ref is persisted in the caller.\n\nOnly complete `verified-native-qualification` evidence can mint a new Landing\nWarrant. Migrated `legacy-compatibility-only` evidence may preserve an exact\nalready-active historical Landing fence, but it cannot create a successor\nLanding or acquire native proof authority.\n\nThe public command family is explicit:\n\n```sh\nbuildchain dev authority migrate --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute --json\nbuildchain dev authority submit --repository owner/repository \\\n  --branch dev/v4/v4.0 --environment-root <root> \\\n  --qualification-domains '[\"<root>\"]' ... --execute\nbuildchain dev authority lease-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority heartbeat-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 --execute\nbuildchain dev authority complete-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 \\\n  --evidence-root <qualification-root> --execute\nbuildchain dev authority lease-landing --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority heartbeat-landing --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 \\\n  --provider-attempt admitted-provider-attempt.json --execute\nbuildchain dev authority recover --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority admit-merge-group --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 \\\n  --merge-group-head <sha>\n```\n\nTerminal settlement releases either authority immediately from exact evidence;\nit does not wait for TTL. Exact duplicate settlement is a state-root-preserving\nno-op. The default `buildchain dev warrant` commands, v1 state bytes, and\nsingle-flight behavior do not change while this mode is off.\n\nMigration also accepts the historical non-native v1 form whose active Warrant\npredates the `phase` field. It preserves that exact fence as Landing authority\nand records a schema-safe `legacy-compatibility-only` qualification carrying the\nexact legacy state root, token, generation, source proof, and phase. Fields that\nv1 never established remain explicitly null, including the phase-less\nqualification time and every native proof field. A migrated qualified v1\nWarrant retains its historical proof roots as compatibility facts, but\n`nativeProofAuthority` remains false because migration cannot reconstruct the\nv2 execution binding or qualification contract. Neither form can claim new\nnative proof or reuse authority. Phase-less native candidates remain invalid.\n\n## Workflow rollout and rollback\n\nThe reusable `dev-pr-auto-merge.yml` supports three explicit rollout modes:\n\n- `off` preserves the previous exact-head admission controller;\n- `shadow` qualifies the source and emits a read-only queue submission plan;\n- `required` persists the submission, selects a provisional Warrant, runs or\n  reuses semantic native proof under heartbeat, atomically qualifies the same\n  fence, and refuses GitHub enqueue unless the immutable queue commit, state root, active Warrant, and\n  selected candidate all pass exact readback validation. Immediately before\n  enqueue, the controller writes and then reads back both the exact-head queue\n  admission status and active lease status. Only after those statuses are\n  visible at their required states does it reread the pull request head,\n  protected base, native merge queue, and current protected Warrant state. The\n  final rooted admission transaction binds the frozen base, source head,\n  candidate, fencing token, generation, native proof roots, Project Cut proof,\n  and both status contexts. Status propagation is retried before enqueue;\n  base, head, queue-predecessor, lease, or Warrant drift revokes both statuses\n  without attempting enqueue. A previously valid result is not authority after terminal\n  closeout. Re-running qualification for the same selected head may regenerate\n  timestamped proof bytes, but it retains the immutable active Warrant and its\n  originally selected proof instead of rewriting or rejecting that attempt.\n  Each candidate also retains the exact successful source workflow run. If a\n  controller discovers that another candidate owns the active Warrant, a\n  configured consumer workflow is dispatched immediately for that exact PR,\n  head, source run, Assignment and Initiative, source identity and patch,\n  plan, closure, dependency, toolchain, environment, affected paths, delivery\n  class, and priority; the candidate is not left waiting for a patrol cron.\n  The shipped Buildchain caller and native template configure this handoff path\n  and accept the same complete input contract. A historical phase-less owner\n  uses the distinct `legacy-phase-less-active-owner` command path. That path\n  carries the exact queue state root observed before its duplicate submission,\n  fencing token, generation, PR, head, and source-run binding. The submission\n  receipt proves that pre-transition root even though the queue transition\n  advances the current state root. The path omits `environment-root`, `native-command`, and\n  `native-command-root`, and rejects readback drift. It therefore resumes the\n  historical non-native authority without inventing a native command contract\n  or upgrading the owner to native proof authority.\n\n  The PR-controlled native candidate runs in a distinct GitHub-hosted job with\n  no provider write credential in the step or process ancestry. The dependent\n  credentialed finalizer runs on another live-readback-proven GitHub-hosted job\n  and runner, verifies the content-addressed transfer, then independently rereads\n  the PR, protected base, and provider fence before qualification or settlement.\n  Detached descendants, including descendants that unset runner tracking, remain\n  in the native runner authority domain and cannot enter the fresh finalizer\n  domain. Exit zero alone is never treated as provider mutation authority,\n  Landing authority, or completed delivery.\n\n  Persistent self-hosted runners are intentionally outside this contract. A\n  `needs` edge alone does not prove process cleanup or a new authority domain, so\n  the finalizer rejects a self-hosted label. Supporting self-hosted execution\n  would require separately attested one-job runner destruction and a provider\n  readback contract at least as strong as the GitHub-hosted boundary.\n\n  Required-mode admission also performs a latest-base Project Cut immediately\n  before enqueue. If the protected base advanced, the controller reclassifies\n  the exact attributed delta against the rooted native proof. Only a disjoint,\n  fully attributed move may reuse that proof; overlap, unknown attribution,\n  missing composition, or merge conflict fails with a stable pre-enqueue reason.\n  The rooted Project Cut receipt binds the frozen and admitted base SHAs,\n  GitHub's exact synthetic merge commit and replay tree, and the unchanged PR\n  head. A final base/head/queue/Warrant compare-and-swap readback must still\n  match that receipt before the enqueue mutation is attempted.\n\n  The protected branch ref is the base authority for that compare-and-swap.\n  A pull request's `base.sha` may remain an older composition snapshot while\n  GitHub reports the pull request as behind, so it is diagnostic rather than a\n  substitute for the separately read protected ref and rooted Project Cut.\n\nFor a required native delivery class, the reusable controller rejects a\nmissing or malformed environment root before runtime checkout, candidate\nsubmission, Warrant selection, or native execution. The input remains\nconditionally optional so `off`, `shadow`, and `non-native-fast` callers keep\ntheir documented behavior.\n\nThe controller persists a completed native proof before its final base\nreclassification. A later exact retry can supply that proof and avoid the\nexpensive native command when the rooted delta still proves reuse safe. A\nduplicate dispatch against the same already-qualified Warrant returns the same\nproof and reuse roots plus a rooted qualification replay output without another\nqueue mutation. Both result forms carry\n`landingAuthority: false`: only the live qualified Warrant plus exact-head\nGitHub merge-queue admission can authorize landing.\n\nThe required controller checks the protected base again after native work. A\ndisjoint attributed delta reuses the proof. Overlap or unknown attribution\ntriggers one automatic revalidation on the latest base; continued overlap,\nnative failure, cancellation, semantic head movement, or an unrecoverable merge\nconflict closes the exact fence. The next queued candidate is notified through\nthe `buildchain-dev-delivery-wake` repository event. Its complete semantic\ncandidate is carried under the single `client_payload.candidate` envelope so\nGitHub's ten-property top-level limit cannot discard proof bindings. If\ncancellation prevents cleanup, lease expiry recovers retained queue age and\nmints a new fence.\n\nConsumers should deploy `shadow` first, inspect receipts, then change their\nprotected caller to `required`. Rollback is a reviewed caller change back to\n`off`; it does not delete queue history or reinterpret old receipts. The\nterminal reusable workflow creates the exact Integration Delivery Proof for a\nmerged candidate (or accepts explicit evidence for another terminal outcome),\nthen closes only the current fencing generation. The separate queued\ncancellation reusable workflow cannot close an active generation; it advances\nthe state ref only when the caller's complete terminal binding and expected-old\nroot still match. A delayed `dequeued` event is ignored when GitHub readback\nshows the same exact PR head is already queued again, so an earlier queue event\ncannot close a newer active Warrant generation.\n\nBuildchain uses the same contract for its own protected dev line through\n`buildchain-dev-delivery.yml`. The manual caller requires the exact PR head and\nsemantic source roots, accepts an optional reusable native proof, keeps both\nthe durable public selector and explicit runtime input on `v4-alpha`, selects\n`delivery-warrant-mode: required`, and targets GitHub Merge Queue. It does not\noffer an `off` switch: rollback is a reviewed change to this caller, not an\noperator-time weakening of a specific delivery attempt.\n\n`templates/native-dev-delivery.yml` provides the corresponding protected-dev\nconsumer workflow. It supports both explicit dispatch and the bounded wake\nevent, calls the allowed floating `@v4-alpha` selector, explicitly passes the v4\nruntime ref that locks every delivery job to the same checkout, and keeps the\nnative command in the consumer repository rather than inventing\nprovider-specific shards. Both callers explicitly bind the queue-admission\nand active-lease status contexts so write/readback fencing uses the same exact\nnames. The reusable workflow defaults the explicit runtime input to\n`v4-alpha`; an empty input or any v3 selector fails before the first runtime\ncheckout.\n\nThis mechanism schedules protected delivery only. It does not serialize local\ndevelopment, source-only checks, unrelated channels, release publication, or\nrunner provisioning. It never grants authority to enable cloud runner\ncampaigns."
     },
     {
       "id": "manual:dev-qualification-patrol",

package/dist/site/kfd-claims.json

@@ -21,13 +21,13 @@
     "contract": "kungfu-buildchain-public-surface-reverse-audit",
     "path": "dist/site/public-surface-audit.json",
     "status": "passed",
-    "sha256": "ac7fa1c43d79b817090fa6ebfe2344d6ccd980bc5ec71547e53a0856b5db066b",
+    "sha256": "3ba4e7c9bdccd207be8b168f85704ee0fe0403c64fa06deb27ecf6910407646e",
     "summary": {
       "cliCommandCount": 117,
       "workflowCount": 77,
       "actionCount": 8,
       "sitePageCount": 84,
-      "docCommandRefCount": 1049,
+      "docCommandRefCount": 1050,
       "failureCount": 0
     },
     "auditBoundary": {
@@ -246,13 +246,13 @@
       "contract": "kungfu-buildchain-public-surface-reverse-audit",
       "path": "dist/site/public-surface-audit.json",
       "status": "passed",
-      "sha256": "ac7fa1c43d79b817090fa6ebfe2344d6ccd980bc5ec71547e53a0856b5db066b",
+      "sha256": "3ba4e7c9bdccd207be8b168f85704ee0fe0403c64fa06deb27ecf6910407646e",
       "summary": {
         "cliCommandCount": 117,
         "workflowCount": 77,
         "actionCount": 8,
         "sitePageCount": 84,
-        "docCommandRefCount": 1049,
+        "docCommandRefCount": 1050,
         "failureCount": 0
       },
       "auditBoundary": {

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

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

package/dist/site/page-registry.json

@@ -2213,7 +2213,7 @@
       ],
       "maturity": "stable",
       "sourcePath": "docs/dev-delivery-warrant.md",
-      "digest": "sha256:c1124dfae8c771750b127f8c3b85a22cee4b564093bd8d8225e51e11e8146894",
+      "digest": "sha256:5feb5f64f19446f31023ceb1af830cd98383141aeacf689c89e980d7ce9f88ab",
       "headings": [
         {
           "level": 1,
@@ -2251,7 +2251,7 @@
           "anchor": "workflow-rollout-and-rollback"
         }
       ],
-      "markdown": "---\nstatus: accepted\nperiod: ongoing\ntheme: dev-delivery-warrant\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-08-17\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-08-11\n  invisible_context: not asserted\n---\n\n# Dev Delivery Warrant Queue\n\nBuildchain's Dev Delivery Warrant Queue gives a qualified slow pull request a\ndurable, non-preemptive delivery turn without replacing GitHub Merge Queue as\nthe final protected-ref authority.\n\nThe queue is stored on a dedicated Git ref below\n`buildchain/dev-delivery-warrant/`. Every update creates a child Git commit and\nadvances the ref without force. The transition receipt binds the expected old\nstate root; a competing controller receives a visible non-fast-forward failure\ninstead of a second authority claim.\n\n## Contract\n\nA submission binds the repository, protected dev line, pull request, semantic\nsource identity, exact source head, native Assignment and Initiative roots,\nsource patch or tree intent, reusable Source Qualification Proof, plan,\naffected closure, dependencies, toolchain, delivery class, priority, attempts,\nand retained enqueue time.\n\nSelection is deterministic FIFO plus aging with bounded priority. Priority may\nreorder queued work, but it cannot preempt the active Warrant. Exactly one\ncandidate receives a `provisional` leased Warrant containing a fencing token,\nlease generation, expected-old state root, expiry, and the complete exact\nsource binding. It reserves the next protected-dev landing before expensive\nnative shards start, but it is not GitHub Merge Queue admission authority.\nHeartbeat extends only that generation. Native proof success atomically\nupgrades the same token and generation to `qualified`; only then may enqueue\nbegin. Expiry fences further mutations by the old token, but it does not prove\nthat the old native process stopped. The active Warrant therefore remains in\nplace until bounded termination is proven by rooted terminal evidence. Only\nthat exact fenced settlement may clear the holder and permit successor\nselection.\n\nA terminal event may cancel a candidate before selection without minting a\nWarrant. This transition is limited to an exact non-active queued candidate and\nbinds its candidate root, pull request, recorded source head, event-observed\nsource head, terminal event action, evidence root, and expected-old queue root.\nAn active candidate still requires its current fencing token and lease\ngeneration. Exact duplicate cancellation evidence is a visible no-op; identity,\nstate, event, or evidence drift fails closed.\n\nThe reusable terminal controller classifies authoritative completion,\ncancellation, supersession, native failure, and transient dequeue separately.\n`dequeued` retains only a provisional Warrant whose native worker may still be\nrunning: a fresh holder continues with the same generation and token, while an\nexpired holder waits for proof that its fenced worker stopped. A qualified or\nhistorical phase-less holder has no unproven native worker to fence, so its exact\ndequeue closes atomically and persists the rooted queued-successor wake. Queued\nwork may also settle as dequeued because it never started native execution. The\ncontroller uses one `settle` operation for active, queued, already-terminal,\nand never-admitted pull requests. An active Warrant still requires its exact\nfence and evidence. A matching queued cancellation is persisted normally. A\nduplicate terminal event replays the persisted wake, while a pull request that\nnever entered Warrant authority returns a rooted explicit no-op instead of\nfailing the workflow or inventing queue state.\n\nThe supported priority classes are `ordinary`, `expedited`, and `emergency`.\nThe queue does not infer an emergency: callers must choose it explicitly under\ntheir reviewed policy. Delivery classes are `non-native-fast`,\n`native-proof-required`, `cross-platform`, and `release`.\n\n## CI lane change budget\n\n`architecture/ci-lane-change-budget.json` pins the exact protected-Dev cut\nthat predates lane-budget enforcement. `scripts/check-ci-lane-change-budget.mjs`\ncompares the current workflow job set with that cut on every repository check.\nLegacy jobs remain readable without invented metadata, while every newly added\njob fails closed until its exact `<workflow>#<job>` lane declares:\n\n- merge or non-merge authority class;\n- trigger class;\n- concurrency scope and `cancel-in-progress` behavior;\n- expected runner-minutes per run;\n- cancellation/settlement behavior; and\n- merge-critical SLO impact, expected contribution, metric, and rationale.\n\nThe guard is repository policy only. It does not become another required\nGitHub status, acquire merge-queue authority, or relax Delivery Warrant,\nexact-head, approval, required-check, and protected-ref enforcement. A removed\nlane must also remove its declaration, so stale budget records cannot conceal\nworkflow drift.\n\nA release-blocker candidate may additionally carry a rooted priority claim\ncreated from a settled Release Train dual landing. The claim binds the exact\nAssignment, Initiative, repair, prior and successor cuts, candidate generation,\ncut candidate, Dev head, semantic patch, both landing evidence roots, and\npublication gate. Only a claim whose repository, protected base, Work roots,\nhead, patch, and claim root match the queued candidate enters the blocker lane.\nThat lane outranks not-yet-leased ordinary work, but never preempts or rewrites\nan active Warrant; unrelated, conflicted, mismatched, or fabricated claims fail\nclosed before selection.\n\n## Three proof authorities\n\nSource Qualification Proof is created from the cheap source-acceptance gate. It\nbinds the semantic source, exact source head and patch/tree intent, plan,\naffected closure, dependencies, toolchain, covered paths, and exact acceptance\nevidence. Ready state and approval are established before provisional\nselection.\n\nNative Qualification Proof is separate. Its v4 form binds semantic source and patch,\nplan, affected closure, dependency graph, toolchain, the exact execution\nenvironment contract, covered paths, native shard evidence, the exact dev\nbase used by the native composition, and the v3 native heartbeat-run receipt.\nThat receipt exposes and roots the exact repository, protected base, source\nhead, qualified base, toolchain, and environment binding established before\nprocess spawn. The proof carries the exact receipt bytes as well as repeating\nthe binding and receipt roots in its shard evidence. Public verification\nrecomputes those bytes and requires a successful outcome, positive heartbeat\ncount, exact command root, ordered start/completion/qualification timestamps,\nand the complete execution binding; caller-computed roots without the receipt\nbytes are not a v4 proof. Before reuse, the consumer roots the\ncomplete attributed Dev delta, including both sides of every rename, then\nclassifies it:\n\n- unchanged semantic roots plus an unrelated fully attributed base delta reuse\n  native qualification and run only a cheap Project Cut replay. GitHub's `behind`\n  state is accepted only when a rooted replay proof binds the exact current\n  protected base, unchanged PR head and source patch, replay tree, required\n  context roots, and a qualified `project.cut.merge-queue-admission/v1`\n  receipt;\n- an overlapping delta reruns affected native shards or the full native plan;\n- an unknown or truncated graph, ambiguous rename, missing attribution, or\n  changed source, plan, closure, dependency, toolchain, or environment root\n  fails closed to full native qualification.\n\nHistorical Native Qualification Proof v1, v2, and v3 values remain readable,\nbut they cannot be reused because they do not carry the current v4 exact native\nexecution evidence. They fail closed to explicit native revalidation and\nproduce a v4 proof.\n\nThe reuse decision binds the exact old and current Dev heads, normalized changed\npaths and rename pairs in `baseDeltaRoot`. This makes local and hosted replay of\nthe same inputs byte-deterministic. Generated outputs that participate in the\naffected closure must be listed in `affected-paths-json`; a delta touching one\nof those surfaces is overlap, not a documentation-only advance.\n\nIntegration Delivery Proof is separate and cannot be cached across candidates.\nIt binds the exact current dev base, replay tree, GitHub `merge_group` head and\ntree, active Warrant fencing generation, Source Qualification Proof root, and\nfinal required-context roots. GitHub's exact merge-group checks remain the\nfinal integration authority.\n\n## CLI\n\nQueue commands are dry-run by default:\n\n```sh\nbuildchain dev warrant submit --repository owner/repository \\\n  --branch dev/v4/v4.0 --pull-request 123 --source-head <sha> \\\n  --assignment-root <root> --initiative-root <root> \\\n  --source-identity-root <root> --source-patch-root <root> \\\n  --source-proof-root <root> --plan-root <root> --closure-root <root> \\\n  --dependency-root <root> --toolchain-root <root> \\\n  --environment-root <root> \\\n  --delivery-class native-proof-required\n\nbuildchain dev warrant select --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\n\nbuildchain dev proof native --branch dev/v4/v4.0 \\\n  --source-head <sha> --qualified-base <sha> \\\n  --environment-root <root> \\\n  --native-execution-receipt native-heartbeat-run.json \\\n  --affected-paths-json '[\"packages/native\"]' ...\n\nbuildchain dev proof classify-native --source-proof native-proof.json \\\n  --current-base <sha> --graph-known true --attribution-complete true \\\n  --changed-paths-json '[]' --renames-json '[]' ...\n\nbuildchain dev warrant qualify --repository owner/repository \\\n  --branch dev/v4/v4.0 --fencing-token <root> --lease-generation 1 \\\n  --native-proof native-proof.json \\\n  --native-reuse-decision native-reuse-decision.json --execute\n\nbuildchain dev warrant cancel-queued --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> --pull-request 123 \\\n  --expected-source-head <queued-sha> --observed-source-head <event-sha> \\\n  --expected-old <queue-root> --event-action closed --outcome cancelled \\\n  --evidence-root <terminal-event-root> --execute\n```\n\n`heartbeat`, `qualify`, `recover`, `close`, `settle`, `cancel-queued`, and `observe` use the same durable authority.\nWarrant-scoped mutations require the exact fencing token and lease generation.\n`close` also requires a rooted terminal evidence object.\n\nOn the v4 line, `observe` also has an explicit `--read-mode v4` candidate. It requires retained exact semantic-diff qualification and source binding, invokes the effect-disabled Rust projection, retains parity evidence, and returns the existing observation shape. The default and rollback mode remains `v3`; mutation commands ignore the read switch. See [`v4-delivery-warrant-read-candidate.md`](v4-delivery-warrant-read-candidate.md).\n\nExpensive native commands must run through `dev-delivery-native-run.mjs` (or an\nequivalent exact consumer). Before spawn it validates the environment and\nexecution roots and traverses the complete Linux `/proc` ancestry. An unreadable\nprocess environment or status is a failure, as is any variable name containing a\ngeneric auth, credential, key, password, secret, or token segment. The child\nstill receives only the fixed process-basics allowlist. The command root,\nexact execution binding and root, successful outcome, child start and completion\ntimes, and heartbeat count are included in the native receipt. The controller\nkeeps retained-fence heartbeats across the direct child lifetime and requires a\nfinal successful heartbeat after child exit; process-group termination on fence\nloss remains fail-closed runtime behavior rather than a claimed receipt field.\n\nThe reusable workflow does not run that controller in a credentialed job. A\nGitHub-hosted `native-execution` job has read-only checkout permission, no\nprovider write credential in the candidate step or its ancestry, and cannot\nqualify, settle, enqueue, or renew provider state. It copies only rooted proof\nand Warrant bytes into a dedicated staging directory and uploads that closed set.\nThe success artifact contains exactly its transfer manifest, Warrant, native\nresult, native proof, and reuse decision; the failed-native artifact contains\nexactly its transfer manifest, Warrant, canonical rooted failure, and\nprovider-settlement binding. Recursive verification rejects missing or extra\nentries, duplicate or case-colliding paths, traversal, symlinks, directories,\nother non-regular entries, non-canonical failure or manifest JSON bytes, byte\ndrift, and mutation between the first and second recursive membership\nsnapshots. A\ndependent GitHub-hosted finalizer downloads those bytes and uses live\nActions job readback to prove different positive job ids, different runner\nidentities, a matching run attempt, and strict native-completion-before-finalizer\nordering. It recomputes the canonical failure root and binds that exact root,\ntransfer root, native job, Warrant state and fence into the live provider\nboundary. Failure settlement consumes those verified coordinates directly; it\ndoes not synthesize a second failure. The boundary also roots a live open-PR\nhead and protected-ref readback. The trusted finalizer uses its provider credential only for\nthose GET readbacks until the byte transfer, runner boundary, and semantic native\nproof have passed independent verification. It then rereads the live PR head,\nprotected base, and Warrant fence before qualifying or settling. A missing or\ncorrupt artifact, unreadable `/proc`, same job or runner, invalid timestamp,\nself-hosted label, stale PR/base/fence, or readback mismatch fails closed. Native\nexit zero is only evidence input.\n\nProof commands create, verify, classify, and compose the two proof layers:\n\n```sh\nbuildchain dev proof source ...\nbuildchain dev proof classify --source-proof source-proof.json ...\nbuildchain dev proof replay ...\nbuildchain dev proof replay-proof \\\n  --qualification-receipt project-cut-admission.json ...\nbuildchain dev proof integration --warrant-result warrant.json ...\n```\n\n## Opt-in bounded qualification and exclusive landing\n\nBuildchain also defines an explicit production opt-in that turns successful\nshadow evidence into a separate v2 authority state. It does not widen or\nreinterpret the v1 Warrant queue. The accepted\n[`Qualification Lease and Landing Warrant ADR`](dev-delivery-qualification-landing-adr.md)\nand `contracts/dev-delivery-authority-v2.schema.json` are authoritative.\n\nIn `bounded-qualification-landing` mode, a configured number of exact\nQualification Leases may coexist. Each lease carries\n`authority = qualification-only` and `mergeGroupAdmission = false`. Completing\nqualification records evidence and releases that lease. Qualified candidates\nthen wait for the one `Landing Warrant`, which alone carries\n`authority = merge-group-admission` and may be checked for `merge_group`\nadmission.\n\nConcurrency is granted only across disjoint rooted `qualificationDomains`.\nOverlap and unknown domains are held behind the active safety boundary with an\nexplicit content-rooted reason. `maxLandingOvertakes` prevents a slow older\ncandidate from being bypassed indefinitely, while `maxQualificationAttempts`\nturns repeated heartbeat loss into a rooted terminal failure. Every release\nreturns a deterministic rooted wake instruction; an exact duplicate release or\nrecovery is a state-root-preserving no-op.\n\nAn expired qualification-only lease may release its bounded compute slot. An\nexpired Landing Warrant does not release exclusive provider authority by time\nalone: recovery retains it and requires exact provider-stop or terminal\nsettlement evidence for the same token and generation before another landing\ncandidate can be selected. Expired cleanup invokes a separate independent\nprovider terminal verifier after candidate exit. Its rooted readback must match\nthe exact repository, protected base, authority state root, candidate, pull\nrequest, source head, Landing token and generation, provider run and job, and a\nfresh observation for that Warrant. Caller assertions, forged roots, wrong\nbindings, nonterminal states, and stale observations cannot release the slot.\nThe verifier reads the immutable historical run-attempt endpoint. A later rerun\nor synchronized PR head cannot rewrite the admitted attempt or prevent its\nterminal settlement; current PR identity and protected base still must match.\nThe reader rejects an empty run conclusion, nonterminal run or job state,\nunsupported job conclusion, or pull-request state outside `open|closed` before\nit can seal product-owned cleanup evidence.\n\nThe public two-phase workflow keeps heartbeat authority in a fourth,\nGitHub-hosted job on a runner domain distinct from admission, native execution,\nevidence sealing, and finalization. Each successful heartbeat records the exact\nexpected-old and next authority state roots plus its receipt root. The\ncredentialless native job holds only its immutable admission binding; the\nhosted coordinator alone renews durable state. After heartbeat loss it records\nthe exact current attempt but never invokes GitHub's run-scoped cancellation\nAPI, so a successor rerun cannot be cancelled through a stale coordinate. All boundary jobs must prove the exact\n`GitHub Actions` hosted runner group and reject `self-hosted`. The finalizer\nrereads the provider job set and live authority state, rejects missing\nor reordered receipt continuity, and requires the live state root to equal the\nreceipt's latest root before it can qualify, settle, or land.\n\nA terminal native failure retains the complete provider chain through every\nwrite-normalize-observe-remutate cycle: `transferRoot`,\n`finalizerBoundaryRoot`, `nativeJobId`, `sealJobId`, the exact admitted\n`providerAttempt`, and, when expiry cleanup was required, the independent\n`providerTerminalReadbackRoot`.\n\nBuildchain's tracked self-delivery caller invokes\n`kungfu-systems/buildchain/.github/workflows/dev-pr-auto-merge.yml@v4-alpha`.\nThe durable selector remains the floating alpha channel, the repository keeps\nmatching `.buildchain/contract-lock.json` (`v4`) and\n`.buildchain/alpha-contract-lock.json` (`v4-alpha`), and a train runtime may be\nselected only through the trusted, non-persistent `workflow_dispatch` input.\nNo candidate SHA or train ref is persisted in the caller.\n\nOnly complete `verified-native-qualification` evidence can mint a new Landing\nWarrant. Migrated `legacy-compatibility-only` evidence may preserve an exact\nalready-active historical Landing fence, but it cannot create a successor\nLanding or acquire native proof authority.\n\nThe public command family is explicit:\n\n```sh\nbuildchain dev authority migrate --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute --json\nbuildchain dev authority submit --repository owner/repository \\\n  --branch dev/v4/v4.0 --environment-root <root> \\\n  --qualification-domains '[\"<root>\"]' ... --execute\nbuildchain dev authority lease-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority heartbeat-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 --execute\nbuildchain dev authority complete-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 \\\n  --evidence-root <qualification-root> --execute\nbuildchain dev authority lease-landing --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority heartbeat-landing --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 \\\n  --provider-attempt admitted-provider-attempt.json --execute\nbuildchain dev authority recover --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority admit-merge-group --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 \\\n  --merge-group-head <sha>\n```\n\nTerminal settlement releases either authority immediately from exact evidence;\nit does not wait for TTL. Exact duplicate settlement is a state-root-preserving\nno-op. The default `buildchain dev warrant` commands, v1 state bytes, and\nsingle-flight behavior do not change while this mode is off.\n\nMigration also accepts the historical non-native v1 form whose active Warrant\npredates the `phase` field. It preserves that exact fence as Landing authority\nand records a schema-safe `legacy-compatibility-only` qualification carrying the\nexact legacy state root, token, generation, source proof, and phase. Fields that\nv1 never established remain explicitly null, including the phase-less\nqualification time and every native proof field. A migrated qualified v1\nWarrant retains its historical proof roots as compatibility facts, but\n`nativeProofAuthority` remains false because migration cannot reconstruct the\nv2 execution binding or qualification contract. Neither form can claim new\nnative proof or reuse authority. Phase-less native candidates remain invalid.\n\n## Workflow rollout and rollback\n\nThe reusable `dev-pr-auto-merge.yml` supports three explicit rollout modes:\n\n- `off` preserves the previous exact-head admission controller;\n- `shadow` qualifies the source and emits a read-only queue submission plan;\n- `required` persists the submission, selects a provisional Warrant, runs or\n  reuses semantic native proof under heartbeat, atomically qualifies the same\n  fence, and refuses GitHub enqueue unless the immutable queue commit, state root, active Warrant, and\n  selected candidate all pass exact readback validation. Immediately before\n  enqueue, the controller writes and then reads back both the exact-head queue\n  admission status and active lease status. Only after those statuses are\n  visible at their required states does it reread the pull request head,\n  protected base, native merge queue, and current protected Warrant state. The\n  final rooted admission transaction binds the frozen base, source head,\n  candidate, fencing token, generation, native proof roots, Project Cut proof,\n  and both status contexts. Status propagation is retried before enqueue;\n  base, head, queue-predecessor, lease, or Warrant drift revokes both statuses\n  without attempting enqueue. A previously valid result is not authority after terminal\n  closeout. Re-running qualification for the same selected head may regenerate\n  timestamped proof bytes, but it retains the immutable active Warrant and its\n  originally selected proof instead of rewriting or rejecting that attempt.\n  Each candidate also retains the exact successful source workflow run. If a\n  controller discovers that another candidate owns the active Warrant, a\n  configured consumer workflow is dispatched immediately for that exact PR,\n  head, source run, Assignment and Initiative, source identity and patch,\n  plan, closure, dependency, toolchain, environment, affected paths, delivery\n  class, and priority; the candidate is not left waiting for a patrol cron.\n  The shipped Buildchain caller and native template configure this handoff path\n  and accept the same complete input contract. A historical phase-less owner\n  uses the distinct `legacy-phase-less-active-owner` command path. That path\n  carries the exact queue state root observed before its duplicate submission,\n  fencing token, generation, PR, head, and source-run binding. The submission\n  receipt proves that pre-transition root even though the queue transition\n  advances the current state root. The path omits `environment-root`, `native-command`, and\n  `native-command-root`, and rejects readback drift. It therefore resumes the\n  historical non-native authority without inventing a native command contract\n  or upgrading the owner to native proof authority.\n\n  The PR-controlled native candidate runs in a distinct GitHub-hosted job with\n  no provider write credential in the step or process ancestry. The dependent\n  credentialed finalizer runs on another live-readback-proven GitHub-hosted job\n  and runner, verifies the content-addressed transfer, then independently rereads\n  the PR, protected base, and provider fence before qualification or settlement.\n  Detached descendants, including descendants that unset runner tracking, remain\n  in the native runner authority domain and cannot enter the fresh finalizer\n  domain. Exit zero alone is never treated as provider mutation authority,\n  Landing authority, or completed delivery.\n\n  Persistent self-hosted runners are intentionally outside this contract. A\n  `needs` edge alone does not prove process cleanup or a new authority domain, so\n  the finalizer rejects a self-hosted label. Supporting self-hosted execution\n  would require separately attested one-job runner destruction and a provider\n  readback contract at least as strong as the GitHub-hosted boundary.\n\n  Required-mode admission also performs a latest-base Project Cut immediately\n  before enqueue. If the protected base advanced, the controller reclassifies\n  the exact attributed delta against the rooted native proof. Only a disjoint,\n  fully attributed move may reuse that proof; overlap, unknown attribution,\n  missing composition, or merge conflict fails with a stable pre-enqueue reason.\n  The rooted Project Cut receipt binds the frozen and admitted base SHAs,\n  GitHub's exact synthetic merge commit and replay tree, and the unchanged PR\n  head. A final base/head/queue/Warrant compare-and-swap readback must still\n  match that receipt before the enqueue mutation is attempted.\n\n  The protected branch ref is the base authority for that compare-and-swap.\n  A pull request's `base.sha` may remain an older composition snapshot while\n  GitHub reports the pull request as behind, so it is diagnostic rather than a\n  substitute for the separately read protected ref and rooted Project Cut.\n\nFor a required native delivery class, the reusable controller rejects a\nmissing or malformed environment root before runtime checkout, candidate\nsubmission, Warrant selection, or native execution. The input remains\nconditionally optional so `off`, `shadow`, and `non-native-fast` callers keep\ntheir documented behavior.\n\nThe controller persists a completed native proof before its final base\nreclassification. A later exact retry can supply that proof and avoid the\nexpensive native command when the rooted delta still proves reuse safe. A\nduplicate dispatch against the same already-qualified Warrant returns the same\nproof and reuse roots plus a rooted qualification replay output without another\nqueue mutation. Both result forms carry\n`landingAuthority: false`: only the live qualified Warrant plus exact-head\nGitHub merge-queue admission can authorize landing.\n\nThe required controller checks the protected base again after native work. A\ndisjoint attributed delta reuses the proof. Overlap or unknown attribution\ntriggers one automatic revalidation on the latest base; continued overlap,\nnative failure, cancellation, semantic head movement, or an unrecoverable merge\nconflict closes the exact fence. The next queued candidate is notified through\nthe `buildchain-dev-delivery-wake` repository event. Its complete semantic\ncandidate is carried under the single `client_payload.candidate` envelope so\nGitHub's ten-property top-level limit cannot discard proof bindings. If\ncancellation prevents cleanup, lease expiry recovers retained queue age and\nmints a new fence.\n\nConsumers should deploy `shadow` first, inspect receipts, then change their\nprotected caller to `required`. Rollback is a reviewed caller change back to\n`off`; it does not delete queue history or reinterpret old receipts. The\nterminal reusable workflow creates the exact Integration Delivery Proof for a\nmerged candidate (or accepts explicit evidence for another terminal outcome),\nthen closes only the current fencing generation. The separate queued\ncancellation reusable workflow cannot close an active generation; it advances\nthe state ref only when the caller's complete terminal binding and expected-old\nroot still match. A delayed `dequeued` event is ignored when GitHub readback\nshows the same exact PR head is already queued again, so an earlier queue event\ncannot close a newer active Warrant generation.\n\nBuildchain uses the same contract for its own protected dev line through\n`buildchain-dev-delivery.yml`. The manual caller requires the exact PR head and\nsemantic source roots, accepts an optional reusable native proof, keeps both\nthe durable public selector and explicit runtime input on `v4-alpha`, selects\n`delivery-warrant-mode: required`, and targets GitHub Merge Queue. It does not\noffer an `off` switch: rollback is a reviewed change to this caller, not an\noperator-time weakening of a specific delivery attempt.\n\n`templates/native-dev-delivery.yml` provides the corresponding protected-dev\nconsumer workflow. It supports both explicit dispatch and the bounded wake\nevent, calls the allowed floating `@v4-alpha` selector, explicitly passes the v4\nruntime ref that locks every delivery job to the same checkout, and keeps the\nnative command in the consumer repository rather than inventing\nprovider-specific shards. Both callers explicitly bind the queue-admission\nand active-lease status contexts so write/readback fencing uses the same exact\nnames. The reusable workflow defaults the explicit runtime input to\n`v4-alpha`; an empty input or any v3 selector fails before the first runtime\ncheckout.\n\nThis mechanism schedules protected delivery only. It does not serialize local\ndevelopment, source-only checks, unrelated channels, release publication, or\nrunner provisioning. It never grants authority to enable cloud runner\ncampaigns."
+      "markdown": "---\nstatus: accepted\nperiod: ongoing\ntheme: dev-delivery-warrant\ndoc_type: technical-reference\nsource_level: local-files\nconfidence: high\nsensitivity: public\nevidence_grade: A\nreview_state: self-reviewed\nlast_reviewed: 2026-08-17\nai_provenance:\n  model_family: GPT-5\n  product: Codex\n  generated_at: 2026-08-11\n  invisible_context: not asserted\n---\n\n# Dev Delivery Warrant Queue\n\nBuildchain's Dev Delivery Warrant Queue gives a qualified slow pull request a\ndurable, non-preemptive delivery turn without replacing GitHub Merge Queue as\nthe final protected-ref authority.\n\nThe queue is stored on a dedicated Git ref below\n`buildchain/dev-delivery-warrant/`. Every update creates a child Git commit and\nadvances the ref without force. The transition receipt binds the expected old\nstate root; a competing controller receives a visible non-fast-forward failure\ninstead of a second authority claim.\n\n## Contract\n\nA submission binds the repository, protected dev line, pull request, semantic\nsource identity, exact source head, native Assignment and Initiative roots,\nsource patch or tree intent, reusable Source Qualification Proof, plan,\naffected closure, dependencies, toolchain, delivery class, priority, attempts,\nand retained enqueue time.\n\nSelection is deterministic FIFO plus aging with bounded priority. Priority may\nreorder queued work, but it cannot preempt the active Warrant. Exactly one\ncandidate receives a `provisional` leased Warrant containing a fencing token,\nlease generation, expected-old state root, expiry, and the complete exact\nsource binding. It reserves the next protected-dev landing before expensive\nnative shards start, but it is not GitHub Merge Queue admission authority.\nHeartbeat extends only that generation. Native proof success atomically\nupgrades the same token and generation to `qualified`; only then may enqueue\nbegin. Expiry fences further mutations by the old token, but it does not prove\nthat the old native process stopped. The active Warrant therefore remains in\nplace until bounded termination is proven by rooted terminal evidence. Only\nthat exact fenced settlement may clear the holder and permit successor\nselection.\n\nA terminal event may cancel a candidate before selection without minting a\nWarrant. This transition is limited to an exact non-active queued candidate and\nbinds its candidate root, pull request, recorded source head, event-observed\nsource head, terminal event action, evidence root, and expected-old queue root.\nAn active candidate still requires its current fencing token and lease\ngeneration. Exact duplicate cancellation evidence is a visible no-op; identity,\nstate, event, or evidence drift fails closed.\n\nThe reusable terminal controller classifies authoritative completion,\ncancellation, supersession, native failure, and transient dequeue separately.\n`dequeued` retains only a provisional Warrant whose native worker may still be\nrunning: a fresh holder continues with the same generation and token, while an\nexpired holder waits for proof that its fenced worker stopped. A qualified or\nhistorical phase-less holder has no unproven native worker to fence, so its exact\ndequeue closes atomically and persists the rooted queued-successor wake. Queued\nwork may also settle as dequeued because it never started native execution. The\ncontroller uses one `settle` operation for active, queued, already-terminal,\nand never-admitted pull requests. An active Warrant still requires its exact\nfence and evidence. A matching queued cancellation is persisted normally. A\nduplicate terminal event replays the persisted wake, while a pull request that\nnever entered Warrant authority returns a rooted explicit no-op instead of\nfailing the workflow or inventing queue state.\n\nThe supported priority classes are `ordinary`, `expedited`, and `emergency`.\nThe queue does not infer an emergency: callers must choose it explicitly under\ntheir reviewed policy. Delivery classes are `non-native-fast`,\n`native-proof-required`, `cross-platform`, and `release`.\n\n## CI lane change budget\n\n`architecture/ci-lane-change-budget.json` pins the exact protected-Dev cut\nthat predates lane-budget enforcement. `scripts/check-ci-lane-change-budget.mjs`\ncompares the current workflow job set with that cut on every repository check.\nLegacy jobs remain readable without invented metadata, while every newly added\njob fails closed until its exact `<workflow>#<job>` lane declares:\n\n- merge or non-merge authority class;\n- trigger class;\n- concurrency scope and `cancel-in-progress` behavior;\n- expected runner-minutes per run;\n- cancellation/settlement behavior; and\n- merge-critical SLO impact, expected contribution, metric, and rationale.\n\nThe guard is repository policy only. It does not become another required\nGitHub status, acquire merge-queue authority, or relax Delivery Warrant,\nexact-head, approval, required-check, and protected-ref enforcement. A removed\nlane must also remove its declaration, so stale budget records cannot conceal\nworkflow drift.\n\nA release-blocker candidate may additionally carry a rooted priority claim\ncreated from a settled Release Train dual landing. The claim binds the exact\nAssignment, Initiative, repair, prior and successor cuts, candidate generation,\ncut candidate, Dev head, semantic patch, both landing evidence roots, and\npublication gate. Only a claim whose repository, protected base, Work roots,\nhead, patch, and claim root match the queued candidate enters the blocker lane.\nThat lane outranks not-yet-leased ordinary work, but never preempts or rewrites\nan active Warrant; unrelated, conflicted, mismatched, or fabricated claims fail\nclosed before selection.\n\n## Three proof authorities\n\nSource Qualification Proof is created from the cheap source-acceptance gate. It\nbinds the semantic source, exact source head and patch/tree intent, plan,\naffected closure, dependencies, toolchain, covered paths, and exact acceptance\nevidence. Ready state and approval are established before provisional\nselection.\n\nNative Qualification Proof is separate. Its v4 form binds semantic source and patch,\nplan, affected closure, dependency graph, toolchain, the exact execution\nenvironment contract, covered paths, native shard evidence, the exact dev\nbase used by the native composition, and the v3 native heartbeat-run receipt.\nThat receipt exposes and roots the exact repository, protected base, source\nhead, qualified base, toolchain, and environment binding established before\nprocess spawn. The proof carries the exact receipt bytes as well as repeating\nthe binding and receipt roots in its shard evidence. Public verification\nrecomputes those bytes and requires a successful outcome, positive heartbeat\ncount, exact command root, ordered start/completion/qualification timestamps,\nand the complete execution binding; caller-computed roots without the receipt\nbytes are not a v4 proof. Before reuse, the consumer roots the\ncomplete attributed Dev delta, including both sides of every rename, then\nclassifies it:\n\n- unchanged semantic roots plus an unrelated fully attributed base delta reuse\n  native qualification and run only a cheap Project Cut replay. GitHub's `behind`\n  state is accepted only when a rooted replay proof binds the exact current\n  protected base, unchanged PR head and source patch, replay tree, required\n  context roots, and a qualified `project.cut.merge-queue-admission/v1`\n  receipt;\n- an overlapping delta reruns affected native shards or the full native plan;\n- an unknown or truncated graph, ambiguous rename, missing attribution, or\n  changed source, plan, closure, dependency, toolchain, or environment root\n  fails closed to full native qualification.\n\nHistorical Native Qualification Proof v1, v2, and v3 values remain readable,\nbut they cannot be reused because they do not carry the current v4 exact native\nexecution evidence. They fail closed to explicit native revalidation and\nproduce a v4 proof.\n\nThe reuse decision binds the exact old and current Dev heads, normalized changed\npaths and rename pairs in `baseDeltaRoot`. This makes local and hosted replay of\nthe same inputs byte-deterministic. Generated outputs that participate in the\naffected closure must be listed in `affected-paths-json`; a delta touching one\nof those surfaces is overlap, not a documentation-only advance.\n\nIntegration Delivery Proof is separate and cannot be cached across candidates.\nIt binds the exact current dev base, replay tree, GitHub `merge_group` head and\ntree, active Warrant fencing generation, Source Qualification Proof root, and\nfinal required-context roots. GitHub's exact merge-group checks remain the\nfinal integration authority.\n\n## CLI\n\nQueue commands are dry-run by default:\n\n```sh\nbuildchain dev warrant submit --repository owner/repository \\\n  --branch dev/v4/v4.0 --pull-request 123 --source-head <sha> \\\n  --assignment-root <root> --initiative-root <root> \\\n  --source-identity-root <root> --source-patch-root <root> \\\n  --source-proof-root <root> --plan-root <root> --closure-root <root> \\\n  --dependency-root <root> --toolchain-root <root> \\\n  --environment-root <root> \\\n  --delivery-class native-proof-required\n\nbuildchain dev warrant select --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\n\nbuildchain dev proof native --branch dev/v4/v4.0 \\\n  --source-head <sha> --qualified-base <sha> \\\n  --environment-root <root> \\\n  --native-execution-receipt native-heartbeat-run.json \\\n  --affected-paths-json '[\"packages/native\"]' ...\n\nbuildchain dev proof classify-native --source-proof native-proof.json \\\n  --current-base <sha> --graph-known true --attribution-complete true \\\n  --changed-paths-json '[]' --renames-json '[]' ...\n\nbuildchain dev warrant qualify --repository owner/repository \\\n  --branch dev/v4/v4.0 --fencing-token <root> --lease-generation 1 \\\n  --native-proof native-proof.json \\\n  --native-reuse-decision native-reuse-decision.json --execute\n\nbuildchain dev warrant cancel-queued --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> --pull-request 123 \\\n  --expected-source-head <queued-sha> --observed-source-head <event-sha> \\\n  --expected-old <queue-root> --event-action closed --outcome cancelled \\\n  --evidence-root <terminal-event-root> --execute\n```\n\n`heartbeat`, `qualify`, `recover`, `close`, `settle`, `cancel-queued`, and `observe` use the same durable authority.\nWarrant-scoped mutations require the exact fencing token and lease generation.\n`close` also requires a rooted terminal evidence object.\n\nLegacy v3 queues that predate the native command contract can be observed but\ncannot enter ordinary mutation paths. If every live legacy candidate has an\nexact completed failed hosted run with zero nonterminal jobs, an operator may\natomically terminalize that complete live set:\n\n```sh\nbuildchain dev warrant recover-legacy-terminal \\\n  --repository owner/repository --branch dev/v4/v4.0 \\\n  --expected-old sha256:<current-state-root> \\\n  --legacy-terminal-recovery legacy-terminal-recovery.json --execute\n```\n\nThe request must cover every live legacy native candidate exactly once and\nbind each stored candidate, source workflow run, terminal provider result, and\ncontent-addressed evidence object. Each evidence object carries the exact\nprovider job identities, attempts, conclusions, and completion timestamps; all\njobs must be terminal and at least one must have failed. The transition writes\none expected-old state update and requires the resulting queue to pass the\ncurrent strict native-proof contract. The recovery cannot qualify, merge,\nrequeue, or partially advance a legacy authority state.\n\nOn the v4 line, `observe` also has an explicit `--read-mode v4` candidate. It requires retained exact semantic-diff qualification and source binding, invokes the effect-disabled Rust projection, retains parity evidence, and returns the existing observation shape. The default and rollback mode remains `v3`; mutation commands ignore the read switch. See [`v4-delivery-warrant-read-candidate.md`](v4-delivery-warrant-read-candidate.md).\n\nExpensive native commands must run through `dev-delivery-native-run.mjs` (or an\nequivalent exact consumer). Before spawn it validates the environment and\nexecution roots and traverses the complete Linux `/proc` ancestry. An unreadable\nprocess environment or status is a failure, as is any variable name containing a\ngeneric auth, credential, key, password, secret, or token segment. The child\nstill receives only the fixed process-basics allowlist. The command root,\nexact execution binding and root, successful outcome, child start and completion\ntimes, and heartbeat count are included in the native receipt. The controller\nkeeps retained-fence heartbeats across the direct child lifetime and requires a\nfinal successful heartbeat after child exit; process-group termination on fence\nloss remains fail-closed runtime behavior rather than a claimed receipt field.\n\nThe reusable workflow does not run that controller in a credentialed job. A\nGitHub-hosted `native-execution` job has read-only checkout permission, no\nprovider write credential in the candidate step or its ancestry, and cannot\nqualify, settle, enqueue, or renew provider state. It copies only rooted proof\nand Warrant bytes into a dedicated staging directory and uploads that closed set.\nThe success artifact contains exactly its transfer manifest, Warrant, native\nresult, native proof, and reuse decision; the failed-native artifact contains\nexactly its transfer manifest, Warrant, canonical rooted failure, and\nprovider-settlement binding. Recursive verification rejects missing or extra\nentries, duplicate or case-colliding paths, traversal, symlinks, directories,\nother non-regular entries, non-canonical failure or manifest JSON bytes, byte\ndrift, and mutation between the first and second recursive membership\nsnapshots. A\ndependent GitHub-hosted finalizer downloads those bytes and uses live\nActions job readback to prove different positive job ids, different runner\nidentities, a matching run attempt, and strict native-completion-before-finalizer\nordering. It recomputes the canonical failure root and binds that exact root,\ntransfer root, native job, Warrant state and fence into the live provider\nboundary. Failure settlement consumes those verified coordinates directly; it\ndoes not synthesize a second failure. The boundary also roots a live open-PR\nhead and protected-ref readback. The trusted finalizer uses its provider credential only for\nthose GET readbacks until the byte transfer, runner boundary, and semantic native\nproof have passed independent verification. It then rereads the live PR head,\nprotected base, and Warrant fence before qualifying or settling. A missing or\ncorrupt artifact, unreadable `/proc`, same job or runner, invalid timestamp,\nself-hosted label, stale PR/base/fence, or readback mismatch fails closed. Native\nexit zero is only evidence input.\n\nProof commands create, verify, classify, and compose the two proof layers:\n\n```sh\nbuildchain dev proof source ...\nbuildchain dev proof classify --source-proof source-proof.json ...\nbuildchain dev proof replay ...\nbuildchain dev proof replay-proof \\\n  --qualification-receipt project-cut-admission.json ...\nbuildchain dev proof integration --warrant-result warrant.json ...\n```\n\n## Opt-in bounded qualification and exclusive landing\n\nBuildchain also defines an explicit production opt-in that turns successful\nshadow evidence into a separate v2 authority state. It does not widen or\nreinterpret the v1 Warrant queue. The accepted\n[`Qualification Lease and Landing Warrant ADR`](dev-delivery-qualification-landing-adr.md)\nand `contracts/dev-delivery-authority-v2.schema.json` are authoritative.\n\nIn `bounded-qualification-landing` mode, a configured number of exact\nQualification Leases may coexist. Each lease carries\n`authority = qualification-only` and `mergeGroupAdmission = false`. Completing\nqualification records evidence and releases that lease. Qualified candidates\nthen wait for the one `Landing Warrant`, which alone carries\n`authority = merge-group-admission` and may be checked for `merge_group`\nadmission.\n\nConcurrency is granted only across disjoint rooted `qualificationDomains`.\nOverlap and unknown domains are held behind the active safety boundary with an\nexplicit content-rooted reason. `maxLandingOvertakes` prevents a slow older\ncandidate from being bypassed indefinitely, while `maxQualificationAttempts`\nturns repeated heartbeat loss into a rooted terminal failure. Every release\nreturns a deterministic rooted wake instruction; an exact duplicate release or\nrecovery is a state-root-preserving no-op.\n\nAn expired qualification-only lease may release its bounded compute slot. An\nexpired Landing Warrant does not release exclusive provider authority by time\nalone: recovery retains it and requires exact provider-stop or terminal\nsettlement evidence for the same token and generation before another landing\ncandidate can be selected. Expired cleanup invokes a separate independent\nprovider terminal verifier after candidate exit. Its rooted readback must match\nthe exact repository, protected base, authority state root, candidate, pull\nrequest, source head, Landing token and generation, provider run and job, and a\nfresh observation for that Warrant. Caller assertions, forged roots, wrong\nbindings, nonterminal states, and stale observations cannot release the slot.\nThe verifier reads the immutable historical run-attempt endpoint. A later rerun\nor synchronized PR head cannot rewrite the admitted attempt or prevent its\nterminal settlement; current PR identity and protected base still must match.\nThe reader rejects an empty run conclusion, nonterminal run or job state,\nunsupported job conclusion, or pull-request state outside `open|closed` before\nit can seal product-owned cleanup evidence.\n\nThe public two-phase workflow keeps heartbeat authority in a fourth,\nGitHub-hosted job on a runner domain distinct from admission, native execution,\nevidence sealing, and finalization. Each successful heartbeat records the exact\nexpected-old and next authority state roots plus its receipt root. The\ncredentialless native job holds only its immutable admission binding; the\nhosted coordinator alone renews durable state. After heartbeat loss it records\nthe exact current attempt but never invokes GitHub's run-scoped cancellation\nAPI, so a successor rerun cannot be cancelled through a stale coordinate. All boundary jobs must prove the exact\n`GitHub Actions` hosted runner group and reject `self-hosted`. The finalizer\nrereads the provider job set and live authority state, rejects missing\nor reordered receipt continuity, and requires the live state root to equal the\nreceipt's latest root before it can qualify, settle, or land.\n\nA terminal native failure retains the complete provider chain through every\nwrite-normalize-observe-remutate cycle: `transferRoot`,\n`finalizerBoundaryRoot`, `nativeJobId`, `sealJobId`, the exact admitted\n`providerAttempt`, and, when expiry cleanup was required, the independent\n`providerTerminalReadbackRoot`.\n\nBuildchain's tracked self-delivery caller invokes\n`kungfu-systems/buildchain/.github/workflows/dev-pr-auto-merge.yml@v4-alpha`.\nThe durable selector remains the floating alpha channel, the repository keeps\nmatching `.buildchain/contract-lock.json` (`v4`) and\n`.buildchain/alpha-contract-lock.json` (`v4-alpha`), and a train runtime may be\nselected only through the trusted, non-persistent `workflow_dispatch` input.\nNo candidate SHA or train ref is persisted in the caller.\n\nOnly complete `verified-native-qualification` evidence can mint a new Landing\nWarrant. Migrated `legacy-compatibility-only` evidence may preserve an exact\nalready-active historical Landing fence, but it cannot create a successor\nLanding or acquire native proof authority.\n\nThe public command family is explicit:\n\n```sh\nbuildchain dev authority migrate --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute --json\nbuildchain dev authority submit --repository owner/repository \\\n  --branch dev/v4/v4.0 --environment-root <root> \\\n  --qualification-domains '[\"<root>\"]' ... --execute\nbuildchain dev authority lease-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority heartbeat-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 --execute\nbuildchain dev authority complete-qualification --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 \\\n  --evidence-root <qualification-root> --execute\nbuildchain dev authority lease-landing --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority heartbeat-landing --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 \\\n  --provider-attempt admitted-provider-attempt.json --execute\nbuildchain dev authority recover --repository owner/repository \\\n  --branch dev/v4/v4.0 --execute\nbuildchain dev authority admit-merge-group --repository owner/repository \\\n  --branch dev/v4/v4.0 --candidate-id <root> \\\n  --authority-token <root> --authority-generation 1 \\\n  --merge-group-head <sha>\n```\n\nTerminal settlement releases either authority immediately from exact evidence;\nit does not wait for TTL. Exact duplicate settlement is a state-root-preserving\nno-op. The default `buildchain dev warrant` commands, v1 state bytes, and\nsingle-flight behavior do not change while this mode is off.\n\nMigration also accepts the historical non-native v1 form whose active Warrant\npredates the `phase` field. It preserves that exact fence as Landing authority\nand records a schema-safe `legacy-compatibility-only` qualification carrying the\nexact legacy state root, token, generation, source proof, and phase. Fields that\nv1 never established remain explicitly null, including the phase-less\nqualification time and every native proof field. A migrated qualified v1\nWarrant retains its historical proof roots as compatibility facts, but\n`nativeProofAuthority` remains false because migration cannot reconstruct the\nv2 execution binding or qualification contract. Neither form can claim new\nnative proof or reuse authority. Phase-less native candidates remain invalid.\n\n## Workflow rollout and rollback\n\nThe reusable `dev-pr-auto-merge.yml` supports three explicit rollout modes:\n\n- `off` preserves the previous exact-head admission controller;\n- `shadow` qualifies the source and emits a read-only queue submission plan;\n- `required` persists the submission, selects a provisional Warrant, runs or\n  reuses semantic native proof under heartbeat, atomically qualifies the same\n  fence, and refuses GitHub enqueue unless the immutable queue commit, state root, active Warrant, and\n  selected candidate all pass exact readback validation. Immediately before\n  enqueue, the controller writes and then reads back both the exact-head queue\n  admission status and active lease status. Only after those statuses are\n  visible at their required states does it reread the pull request head,\n  protected base, native merge queue, and current protected Warrant state. The\n  final rooted admission transaction binds the frozen base, source head,\n  candidate, fencing token, generation, native proof roots, Project Cut proof,\n  and both status contexts. Status propagation is retried before enqueue;\n  base, head, queue-predecessor, lease, or Warrant drift revokes both statuses\n  without attempting enqueue. A previously valid result is not authority after terminal\n  closeout. Re-running qualification for the same selected head may regenerate\n  timestamped proof bytes, but it retains the immutable active Warrant and its\n  originally selected proof instead of rewriting or rejecting that attempt.\n  Each candidate also retains the exact successful source workflow run. If a\n  controller discovers that another candidate owns the active Warrant, a\n  configured consumer workflow is dispatched immediately for that exact PR,\n  head, source run, Assignment and Initiative, source identity and patch,\n  plan, closure, dependency, toolchain, environment, affected paths, delivery\n  class, and priority; the candidate is not left waiting for a patrol cron.\n  The shipped Buildchain caller and native template configure this handoff path\n  and accept the same complete input contract. A historical phase-less owner\n  uses the distinct `legacy-phase-less-active-owner` command path. That path\n  carries the exact queue state root observed before its duplicate submission,\n  fencing token, generation, PR, head, and source-run binding. The submission\n  receipt proves that pre-transition root even though the queue transition\n  advances the current state root. The path omits `environment-root`, `native-command`, and\n  `native-command-root`, and rejects readback drift. It therefore resumes the\n  historical non-native authority without inventing a native command contract\n  or upgrading the owner to native proof authority.\n\n  The PR-controlled native candidate runs in a distinct GitHub-hosted job with\n  no provider write credential in the step or process ancestry. The dependent\n  credentialed finalizer runs on another live-readback-proven GitHub-hosted job\n  and runner, verifies the content-addressed transfer, then independently rereads\n  the PR, protected base, and provider fence before qualification or settlement.\n  Detached descendants, including descendants that unset runner tracking, remain\n  in the native runner authority domain and cannot enter the fresh finalizer\n  domain. Exit zero alone is never treated as provider mutation authority,\n  Landing authority, or completed delivery.\n\n  Persistent self-hosted runners are intentionally outside this contract. A\n  `needs` edge alone does not prove process cleanup or a new authority domain, so\n  the finalizer rejects a self-hosted label. Supporting self-hosted execution\n  would require separately attested one-job runner destruction and a provider\n  readback contract at least as strong as the GitHub-hosted boundary.\n\n  Required-mode admission also performs a latest-base Project Cut immediately\n  before enqueue. If the protected base advanced, the controller reclassifies\n  the exact attributed delta against the rooted native proof. Only a disjoint,\n  fully attributed move may reuse that proof; overlap, unknown attribution,\n  missing composition, or merge conflict fails with a stable pre-enqueue reason.\n  The rooted Project Cut receipt binds the frozen and admitted base SHAs,\n  GitHub's exact synthetic merge commit and replay tree, and the unchanged PR\n  head. A final base/head/queue/Warrant compare-and-swap readback must still\n  match that receipt before the enqueue mutation is attempted.\n\n  The protected branch ref is the base authority for that compare-and-swap.\n  A pull request's `base.sha` may remain an older composition snapshot while\n  GitHub reports the pull request as behind, so it is diagnostic rather than a\n  substitute for the separately read protected ref and rooted Project Cut.\n\nFor a required native delivery class, the reusable controller rejects a\nmissing or malformed environment root before runtime checkout, candidate\nsubmission, Warrant selection, or native execution. The input remains\nconditionally optional so `off`, `shadow`, and `non-native-fast` callers keep\ntheir documented behavior.\n\nThe controller persists a completed native proof before its final base\nreclassification. A later exact retry can supply that proof and avoid the\nexpensive native command when the rooted delta still proves reuse safe. A\nduplicate dispatch against the same already-qualified Warrant returns the same\nproof and reuse roots plus a rooted qualification replay output without another\nqueue mutation. Both result forms carry\n`landingAuthority: false`: only the live qualified Warrant plus exact-head\nGitHub merge-queue admission can authorize landing.\n\nThe required controller checks the protected base again after native work. A\ndisjoint attributed delta reuses the proof. Overlap or unknown attribution\ntriggers one automatic revalidation on the latest base; continued overlap,\nnative failure, cancellation, semantic head movement, or an unrecoverable merge\nconflict closes the exact fence. The next queued candidate is notified through\nthe `buildchain-dev-delivery-wake` repository event. Its complete semantic\ncandidate is carried under the single `client_payload.candidate` envelope so\nGitHub's ten-property top-level limit cannot discard proof bindings. If\ncancellation prevents cleanup, lease expiry recovers retained queue age and\nmints a new fence.\n\nConsumers should deploy `shadow` first, inspect receipts, then change their\nprotected caller to `required`. Rollback is a reviewed caller change back to\n`off`; it does not delete queue history or reinterpret old receipts. The\nterminal reusable workflow creates the exact Integration Delivery Proof for a\nmerged candidate (or accepts explicit evidence for another terminal outcome),\nthen closes only the current fencing generation. The separate queued\ncancellation reusable workflow cannot close an active generation; it advances\nthe state ref only when the caller's complete terminal binding and expected-old\nroot still match. A delayed `dequeued` event is ignored when GitHub readback\nshows the same exact PR head is already queued again, so an earlier queue event\ncannot close a newer active Warrant generation.\n\nBuildchain uses the same contract for its own protected dev line through\n`buildchain-dev-delivery.yml`. The manual caller requires the exact PR head and\nsemantic source roots, accepts an optional reusable native proof, keeps both\nthe durable public selector and explicit runtime input on `v4-alpha`, selects\n`delivery-warrant-mode: required`, and targets GitHub Merge Queue. It does not\noffer an `off` switch: rollback is a reviewed change to this caller, not an\noperator-time weakening of a specific delivery attempt.\n\n`templates/native-dev-delivery.yml` provides the corresponding protected-dev\nconsumer workflow. It supports both explicit dispatch and the bounded wake\nevent, calls the allowed floating `@v4-alpha` selector, explicitly passes the v4\nruntime ref that locks every delivery job to the same checkout, and keeps the\nnative command in the consumer repository rather than inventing\nprovider-specific shards. Both callers explicitly bind the queue-admission\nand active-lease status contexts so write/readback fencing uses the same exact\nnames. The reusable workflow defaults the explicit runtime input to\n`v4-alpha`; an empty input or any v3 selector fails before the first runtime\ncheckout.\n\nThis mechanism schedules protected delivery only. It does not serialize local\ndevelopment, source-only checks, unrelated channels, release publication, or\nrunner provisioning. It never grants authority to enable cloud runner\ncampaigns."
     },
     {
       "id": "manual:dev-qualification-patrol",

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

@@ -7,7 +7,7 @@
     "workflowCount": 77,
     "actionCount": 8,
     "sitePageCount": 84,
-    "docCommandRefCount": 1049,
+    "docCommandRefCount": 1050,
     "failureCount": 0
   },
   "enumerated": {
@@ -4999,6 +4999,11 @@
         "path": "docs/dev-delivery-warrant.md",
         "command": "buildchain dev warrant cancel-queued"
       },
+      {
+        "id": "dev",
+        "path": "docs/dev-delivery-warrant.md",
+        "command": "buildchain dev warrant recover-legacy-terminal"
+      },
       {
         "id": "dev",
         "path": "docs/dev-delivery-warrant.md",
@@ -8911,8 +8916,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "fbc23073bbae240489a2f826b2c26daadc58e704050c5f8df366509f5c5a1c3e",
-    "workflowRegistryDigest": "90bcf16d6aef5528c10a7e78f21a89ab265ae2d4f8aedc15da9f6c4c2f0b3083",
-    "pageRegistryDigest": "82bd43842f419ff14cb2d1931a194647cf427fe3b18b6388efd5b50552c13351"
+    "workflowRegistryDigest": "48dcf0d6e798d64f8cb0acb2c7e6af7782b8332f9a254a83512abf9d8e31a49f",
+    "pageRegistryDigest": "620d7dd295b0ed42c046ebea1b2cfb97b69f9e10a0c4f5cb0b796e7e0f1219d1"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-08-28T20:22:42.731Z",
-  "publishedAt": "2026-08-28T20:22:42.731Z",
+  "generatedAt": "2026-08-28T20:30:35.956Z",
+  "publishedAt": "2026-08-28T20:30:35.956Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "9df599a42bebd6595ed92a598a569c40651d8c12",
+  "sourceRevision": "3881f9dea6fa750ce5e561fc86419a163ca19b90",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.1",
+    "version": "4.0.2-alpha.0",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-08-28T20:22:42.731Z",
-  "publishedAt": "2026-08-28T20:22:42.731Z",
+  "generatedAt": "2026-08-28T20:30:35.956Z",
+  "publishedAt": "2026-08-28T20:30:35.956Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "9df599a42bebd6595ed92a598a569c40651d8c12",
+  "sourceRevision": "3881f9dea6fa750ce5e561fc86419a163ca19b90",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.1",
+    "version": "4.0.2-alpha.0",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",

package/dist/site/workflow-registry.json

@@ -2039,7 +2039,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.1",
+      "introducedVersion": "4.0.2-alpha.0",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -2060,7 +2060,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.1",
+      "introducedVersion": "4.0.2-alpha.0",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -2081,7 +2081,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.1",
+      "introducedVersion": "4.0.2-alpha.0",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -2131,7 +2131,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.1",
+      "introducedVersion": "4.0.2-alpha.0",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",

package/docs/dev-delivery-warrant.md

@@ -203,6 +203,27 @@ buildchain dev warrant cancel-queued --repository owner/repository \
 Warrant-scoped mutations require the exact fencing token and lease generation.
 `close` also requires a rooted terminal evidence object.
 
+Legacy v3 queues that predate the native command contract can be observed but
+cannot enter ordinary mutation paths. If every live legacy candidate has an
+exact completed failed hosted run with zero nonterminal jobs, an operator may
+atomically terminalize that complete live set:
+
+```sh
+buildchain dev warrant recover-legacy-terminal \
+  --repository owner/repository --branch dev/v4/v4.0 \
+  --expected-old sha256:<current-state-root> \
+  --legacy-terminal-recovery legacy-terminal-recovery.json --execute
+```
+
+The request must cover every live legacy native candidate exactly once and
+bind each stored candidate, source workflow run, terminal provider result, and
+content-addressed evidence object. Each evidence object carries the exact
+provider job identities, attempts, conclusions, and completion timestamps; all
+jobs must be terminal and at least one must have failed. The transition writes
+one expected-old state update and requires the resulting queue to pass the
+current strict native-proof contract. The recovery cannot qualify, merge,
+requeue, or partially advance a legacy authority state.
+
 On the v4 line, `observe` also has an explicit `--read-mode v4` candidate. It requires retained exact semantic-diff qualification and source binding, invokes the effect-disabled Rust projection, retains parity evidence, and returns the existing observation shape. The default and rollback mode remains `v3`; mutation commands ignore the read switch. See [`v4-delivery-warrant-read-candidate.md`](v4-delivery-warrant-read-candidate.md).
 
 Expensive native commands must run through `dev-delivery-native-run.mjs` (or an

package/package.json

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

package/packages/core/dev-delivery-warrant-legacy-recovery.js

@@ -0,0 +1,246 @@
+import {
+  devDeliveryClone as clone,
+  devDeliveryContentRoot,
+  devDeliveryExactRoot as exactRoot,
+  devDeliveryExactSha as exactSha,
+  devDeliveryPositiveInteger as positiveInteger,
+  devDeliveryText as text,
+  devDeliveryTimestamp as timestamp,
+} from "./dev-delivery-common.js";
+import {
+  TERMINAL_STATES,
+  normalizeDevDeliveryQueue,
+} from "./dev-delivery-warrant-state.js";
+
+export const LEGACY_TERMINAL_RECOVERY_REQUEST_SCHEMA =
+  "kungfu.buildchain.legacy-terminal-recovery-request/v1";
+export const LEGACY_HOSTED_TERMINAL_EVIDENCE_SCHEMA =
+  "kungfu.buildchain.legacy-hosted-terminal-evidence/v1";
+export const LEGACY_TERMINAL_RECOVERY_RECEIPT_SCHEMA =
+  "kungfu.buildchain.legacy-terminal-recovery-receipt/v1";
+
+function legacyLiveNativeCandidate(candidate) {
+  return (
+    !TERMINAL_STATES.has(candidate.status) &&
+    candidate.deliveryClass !== "non-native-fast" &&
+    (!candidate.environmentRoot || !candidate.nativeCommandContract)
+  );
+}
+
+function normalizeProviderJob(input, runAttempt) {
+  const job = {
+    id: positiveInteger(input?.id, "provider job id"),
+    name: text(input?.name),
+    runAttempt: positiveInteger(input?.runAttempt, "provider job runAttempt"),
+    status: text(input?.status).toLowerCase(),
+    conclusion: text(input?.conclusion).toLowerCase(),
+    completedAt: timestamp(input?.completedAt, "provider job completedAt"),
+  };
+  if (job.runAttempt !== runAttempt) {
+    throw new Error("legacy provider job run attempt mismatch");
+  }
+  if (job.status !== "completed" || !job.conclusion) {
+    throw new Error(
+      "legacy recovery requires every provider job to be terminal",
+    );
+  }
+  return job;
+}
+
+function normalizeEvidence(input) {
+  const runAttempt = positiveInteger(input?.runAttempt, "runAttempt");
+  if (!Array.isArray(input?.jobs) || input.jobs.length === 0) {
+    throw new Error("legacy terminal evidence requires provider jobs");
+  }
+  const jobs = input.jobs
+    .map((job) => normalizeProviderJob(job, runAttempt))
+    .sort((left, right) => left.id - right.id);
+  if (new Set(jobs.map((job) => job.id)).size !== jobs.length) {
+    throw new Error(
+      "legacy terminal evidence contains duplicate provider jobs",
+    );
+  }
+  if (!jobs.some((job) => job.conclusion === "failure")) {
+    throw new Error(
+      "legacy failed run evidence requires a failed provider job",
+    );
+  }
+  const runUpdatedAt = timestamp(input?.runUpdatedAt, "runUpdatedAt");
+  if (
+    jobs.some((job) => Date.parse(job.completedAt) > Date.parse(runUpdatedAt))
+  ) {
+    throw new Error("legacy provider job completion follows the run readback");
+  }
+  const body = {
+    schema: text(input?.schema),
+    candidateId: exactRoot(input?.candidateId, "candidateId"),
+    pullRequestNumber: positiveInteger(
+      input?.pullRequestNumber,
+      "pullRequestNumber",
+    ),
+    sourceHead: exactSha(input?.sourceHead, "sourceHead"),
+    sourceWorkflowRunId: positiveInteger(
+      input?.sourceWorkflowRunId,
+      "sourceWorkflowRunId",
+    ),
+    runAttempt,
+    runStatus: text(input?.runStatus).toLowerCase(),
+    runConclusion: text(input?.runConclusion).toLowerCase(),
+    runUpdatedAt,
+    totalJobCount: jobs.length,
+    nonterminalJobCount: 0,
+    workerTerminationProven: true,
+    jobs,
+    reason: text(input?.reason),
+  };
+  if (body.schema !== LEGACY_HOSTED_TERMINAL_EVIDENCE_SCHEMA) {
+    throw new Error(
+      `legacy terminal evidence must use ${LEGACY_HOSTED_TERMINAL_EVIDENCE_SCHEMA}`,
+    );
+  }
+  if (
+    body.runStatus !== "completed" ||
+    body.runConclusion !== "failure" ||
+    !body.reason
+  ) {
+    throw new Error(
+      "legacy terminal evidence requires one completed failed run with zero nonterminal jobs and proven worker termination",
+    );
+  }
+  const evidenceRoot = devDeliveryContentRoot(body);
+  if (exactRoot(input?.evidenceRoot, "evidenceRoot") !== evidenceRoot) {
+    throw new Error("legacy terminal evidence root mismatch");
+  }
+  return { ...body, evidenceRoot };
+}
+
+function assertExactCoverage(candidates, evidence) {
+  const expected = candidates.map((candidate) => candidate.candidateId).sort();
+  const observed = evidence.map((entry) => entry.candidateId).sort();
+  if (
+    expected.length !== observed.length ||
+    expected.some((candidateId, index) => candidateId !== observed[index])
+  ) {
+    throw new Error(
+      "legacy terminal recovery must cover every live legacy native candidate exactly once",
+    );
+  }
+}
+
+export function recoverLegacyTerminalDevDeliveryQueue(
+  queueInput,
+  requestInput,
+  { now = new Date().toISOString() } = {},
+) {
+  const currentTime = timestamp(now, "now");
+  const request = requestInput || {};
+  if (request.schema !== LEGACY_TERMINAL_RECOVERY_REQUEST_SCHEMA) {
+    throw new Error(
+      `legacy terminal recovery must use ${LEGACY_TERMINAL_RECOVERY_REQUEST_SCHEMA}`,
+    );
+  }
+  const before = normalizeDevDeliveryQueue(queueInput, {
+    allowLegacyV3Readback: true,
+  });
+  const expectedOldStateRoot = exactRoot(
+    request.expectedOldStateRoot,
+    "expectedOldStateRoot",
+  );
+  if (expectedOldStateRoot !== before.stateRoot) {
+    throw new Error("legacy terminal recovery expected-old state drift");
+  }
+  const legacyCandidates = before.candidates.filter(legacyLiveNativeCandidate);
+  if (legacyCandidates.length === 0) {
+    throw new Error("legacy terminal recovery found no live legacy candidate");
+  }
+  if (!Array.isArray(request.evidence)) {
+    throw new Error("legacy terminal recovery evidence must be an array");
+  }
+  const evidence = request.evidence.map(normalizeEvidence);
+  if (
+    new Set(evidence.map((entry) => entry.candidateId)).size !== evidence.length
+  ) {
+    throw new Error(
+      "legacy terminal recovery evidence contains duplicate candidates",
+    );
+  }
+  assertExactCoverage(legacyCandidates, evidence);
+
+  const queue = clone(before);
+  delete queue.stateRoot;
+  const transitions = [];
+  for (const entry of evidence) {
+    const candidate = queue.candidates.find(
+      (row) => row.candidateId === entry.candidateId,
+    );
+    if (
+      !candidate ||
+      candidate.pullRequestNumber !== entry.pullRequestNumber ||
+      candidate.sourceHead !== entry.sourceHead ||
+      candidate.sourceWorkflowRunId !== entry.sourceWorkflowRunId
+    ) {
+      throw new Error(
+        "legacy terminal evidence does not match candidate identity",
+      );
+    }
+    const active = queue.activeWarrant?.candidateId === candidate.candidateId;
+    if (!active && candidate.status !== "queued") {
+      throw new Error(
+        `legacy candidate status ${candidate.status} requires the exact active Warrant`,
+      );
+    }
+    const priorStatus = candidate.status;
+    candidate.status = "terminal-failure";
+    candidate.updatedAt = currentTime;
+    candidate.terminal = {
+      outcome: "terminal-failure",
+      reason: entry.reason,
+      evidenceRoot: entry.evidenceRoot,
+      authority: "legacy-hosted-native-terminal-recovery",
+      sourceWorkflowRunId: entry.sourceWorkflowRunId,
+      runAttempt: entry.runAttempt,
+      workerTerminationProven: true,
+      closedAt: currentTime,
+      ...(active
+        ? {
+            fencingToken: queue.activeWarrant.fencingToken,
+            leaseGeneration: queue.activeWarrant.generation,
+          }
+        : {}),
+    };
+    transitions.push({
+      candidateId: candidate.candidateId,
+      pullRequestNumber: candidate.pullRequestNumber,
+      sourceHead: candidate.sourceHead,
+      priorStatus,
+      activeWarrant: active,
+      outcome: "terminal-failure",
+      evidenceRoot: entry.evidenceRoot,
+    });
+  }
+  queue.activeWarrant = null;
+  queue.generation += 1;
+  queue.updatedAt = currentTime;
+  queue.stateRoot = devDeliveryContentRoot(queue);
+  const after = normalizeDevDeliveryQueue(queue);
+  const requestBody = {
+    schema: LEGACY_TERMINAL_RECOVERY_REQUEST_SCHEMA,
+    expectedOldStateRoot,
+    evidence,
+  };
+  const requestRoot = devDeliveryContentRoot(requestBody);
+  const receipt = {
+    schema: LEGACY_TERMINAL_RECOVERY_RECEIPT_SCHEMA,
+    action: "legacy-terminal-recovery",
+    expectedOldStateRoot,
+    nextStateRoot: after.stateRoot,
+    requestRoot,
+    transitions,
+    nextAction: "Select the next strictly valid queued candidate, if any.",
+  };
+  return {
+    queue: after,
+    receipt,
+    receiptRoot: devDeliveryContentRoot(receipt),
+  };
+}

package/scripts/dev-delivery-warrant-options.mjs

@@ -33,11 +33,8 @@ function terminalEvidenceOptions(rest, environment) {
   };
 }
 
-export function devDeliveryCliOptions(args = [], environment = process.env) {
-  const [command = "", ...rest] = args;
+function authorityStateOptions(rest, environment) {
   return {
-    command,
-    repository: flag(rest, "repository", environment.GITHUB_REPOSITORY),
     branch: flag(
       rest,
       "branch",
@@ -53,6 +50,20 @@ export function devDeliveryCliOptions(args = [], environment = process.env) {
       "expected-old",
       environment.BUILDCHAIN_DEV_DELIVERY_EXPECTED_OLD,
     ),
+    legacyTerminalRecoveryPath: flag(
+      rest,
+      "legacy-terminal-recovery",
+      environment.BUILDCHAIN_DEV_DELIVERY_LEGACY_TERMINAL_RECOVERY,
+    ),
+  };
+}
+
+export function devDeliveryCliOptions(args = [], environment = process.env) {
+  const [command = "", ...rest] = args;
+  return {
+    command,
+    repository: flag(rest, "repository", environment.GITHUB_REPOSITORY),
+    ...authorityStateOptions(rest, environment),
     pullRequestNumber: flag(
       rest,
       "pull-request",

package/scripts/dev-delivery-warrant.mjs

@@ -15,6 +15,7 @@ import {
   settleDevDeliveryTerminalEvent,
   submitDevDeliveryCandidate,
 } from "../packages/core/dev-delivery-warrant.js";
+import { recoverLegacyTerminalDevDeliveryQueue } from "../packages/core/dev-delivery-warrant-legacy-recovery.js";
 import { runV4DeliveryWarrantReadCandidate } from "../packages/core/v4-delivery-warrant-read-candidate.js";
 
 import { GitHubDevDeliveryStore } from "./dev-delivery-warrant-store.mjs";
@@ -80,7 +81,9 @@ function reconcileTerminalEvidenceCommand(queue, options) {
 
 function requireTerminalEvidenceCas(options) {
   if (
-    options.command === "reconcile-terminal-evidence" &&
+    ["reconcile-terminal-evidence", "recover-legacy-terminal"].includes(
+      options.command,
+    ) &&
     options.execute &&
     !options.expectedOldStateRoot
   ) {
@@ -267,6 +270,13 @@ function transitionFor(command, queue, options) {
   }
   if (command === "recover")
     return recoverExpiredDevDeliveryWarrant(queue, { now: options.now });
+  if (command === "recover-legacy-terminal") {
+    return recoverLegacyTerminalDevDeliveryQueue(
+      queue,
+      jsonFile(options.legacyTerminalRecoveryPath, "legacy terminal recovery"),
+      { now: options.now },
+    );
+  }
   if (command === "close") {
     return closeDevDeliveryWarrant(queue, warrantIdentity(queue, options), {
       outcome: options.outcome,
@@ -416,7 +426,9 @@ export async function runDevDeliveryCommand(optionsInput = {}, clientInput) {
     stateRef: options.stateRef,
     protectedBase: options.branch,
     now: options.now,
-    allowLegacyV3Readback: options.command === "observe",
+    allowLegacyV3Readback: ["observe", "recover-legacy-terminal"].includes(
+      options.command,
+    ),
   });
   if (
     options.expectedOldStateRoot &&
@@ -496,7 +508,7 @@ export async function runDevDeliveryCommand(optionsInput = {}, clientInput) {
 }
 
 function usage() {
-  return "Usage:\n  buildchain dev warrant <submit|select|heartbeat|qualify|recover|close|settle|reconcile-terminal-evidence|cancel-queued|observe> --repository owner/repo --branch dev/vN/vN.M [--execute] [--output FILE] [--json]\n\nRead candidate:\n  observe --read-mode v4 --read-qualification FILE --read-qualification-root sha256:... --read-typescript-revision SHA --read-rust-revision SHA --read-validator-version TOKEN [--read-evidence-output FILE]\n";
+  return "Usage:\n  buildchain dev warrant <submit|select|heartbeat|qualify|recover|recover-legacy-terminal|close|settle|reconcile-terminal-evidence|cancel-queued|observe> --repository owner/repo --branch dev/vN/vN.M [--execute] [--output FILE] [--json]\n\nLegacy terminal recovery:\n  recover-legacy-terminal --expected-old sha256:... --legacy-terminal-recovery FILE [--execute]\n\nRead candidate:\n  observe --read-mode v4 --read-qualification FILE --read-qualification-root sha256:... --read-typescript-revision SHA --read-rust-revision SHA --read-validator-version TOKEN [--read-evidence-output FILE]\n";
 }
 
 async function main() {
@@ -513,6 +525,7 @@ async function main() {
       "heartbeat",
       "qualify",
       "recover",
+      "recover-legacy-terminal",
       "close",
       "settle",
       "reconcile-terminal-evidence",