@kungfu-tech/buildchain 3.0.6-alpha.1 → 3.0.6-alpha.3

package/docs/auditable-demo.md

@@ -8,7 +8,7 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: self-reviewed
-last_reviewed: 2026-08-02
+last_reviewed: 2026-08-05
 ai_provenance:
   model_family: GPT-5
   product: Codex
@@ -52,6 +52,39 @@ the default. Both classes retain 4 MiB per step, a clean Home/XDG environment,
 no inherited credentials, and a network-disabled read-only container with
 bounded tmpfs.
 
+Consumers may optionally add a
+`buildchain.declarative-demo-presentation/v1` presentation. This contract
+binds one consumer-owned proof label, question, summary, and optional
+transition to every demo in declared order. Buildchain verifies that each
+question is the same title used by capture and media; it does not invent or
+reinterpret the product argument.
+
+The presentation also chooses one of two README materialization modes. The
+default, when no presentation is declared, remains the original full generated
+block with commands, renditions, evidence, and claim boundary. `media-only`
+updates only the image inside each existing README marker so consumer-authored
+narrative and transitions survive regeneration. The generated technical
+details move to a separately declared Markdown specification, where stable
+per-demo markers preserve proof order and idempotent updates. The publication
+pull request stages that specification together with the README and
+content-addressed evidence. No presentation field grants publication or Work
+authority.
+
+The optional top-level `compositionMode` is an explicit visual contract.
+Omitting it preserves `presentation-framed`; declaring `terminal-fill` makes
+the bounded PTY replay the complete pixel surface without renderer-owned
+window chrome. Buildchain carries that choice into both native scenes. It does
+not infer full-frame intent from output resolution.
+
+The optional `buildchain.declarative-demo-playback/v1` contract separates
+observed command latency from presentation timing. Its
+`deterministic-readable` mode preserves the captured terminal event payloads
+and their order, records the observed final-event time as non-authoritative
+evidence, and maps event ordinals onto the declared `activeDurationMs` before a
+bounded `finalHoldMs`. Both native renditions therefore replay at the same
+readable pace even when an identical command runs faster or slower. Omitting
+the contract preserves the original PTY timestamp behavior.
+
 The uploaded metadata must bind the executable SHA-256, declare an empty
 runtime dependency set, and provide a bounded `executableFiles` array of exact
 artifact-relative paths and SHA-256 digests. GitHub Artifact transport does not
@@ -97,6 +130,7 @@ jobs:
       scenario-path: .buildchain/auditable-demo.json
       renderer-image: ghcr.io/kungfu-systems/build-images/demo-renderer@sha256:RENDERER_DIGEST
       render-media: true
+      render-failure-advisory: false
       media-profile: responsive-web-delivery-v1
       materialize: true
       materialize-base-ref: dev/v1/v1.0
@@ -193,6 +227,10 @@ The Gate:
   bounded tmpfs;
 - verifies the renderer manifest, media probe, exact input roots, exact output
   member set, and complete checksums;
+- independently verifies the requested composition mode, browser-observed
+  content viewport, PTY rows and columns, and deterministic cell geometry for
+  every frame set; `terminal-fill` is rejected unless the viewport and cell
+  grid resolve to the complete declared frame;
 - uploads a content-addressed qualified bundle plus an independent GitHub
   Artifact id, URL, archive digest, and expiry-bearing source coordinate.
 
@@ -202,9 +240,9 @@ passed gate receipt, and checksums covering every member exactly once.
 
 ## Selective Render
 
-`render-media: true` enables the second job. It downloads the just-uploaded Gate
-bundle by its content-addressed name, recomputes the Gate member root, verifies
-the exact source SHA and renderer digest, and only then renders the complete
+`render-media: true` enables the full-media step only after every declared demo
+has passed the required Gate. It recomputes each Gate member root, verifies the
+exact source SHA and renderer digest, and only then renders the complete
 qualified scene.
 
 The media bundle contains MP4, WebM, GIF, poster, probe, renderer manifest,
@@ -213,10 +251,19 @@ distribution checksums. A web-delivery profile also retains
 `media-inspection.json`, whose content root is bound into the receipt.
 `render-media: false` does not weaken or skip the Gate.
 
+`render-failure-advisory: true` makes only the full-media step advisory. A
+render failure remains visible as a failed step and workflow warning, while the
+required Gate keeps its normal failure semantics. Failed or partial media can
+never open a materialization PR. Use this for an Alpha lane whose binary
+publication must not depend on animation capacity; keep the default `false`
+for explicit media refreshes and other workflows that require complete media.
+
 When the Gate bundle contains a qualified terminal capture, the render job
 passes it read-only to the immutable renderer. The renderer manifest binds the
 capture root and terminal-state-machine version, but raw capture bytes remain
 in the Gate bundle rather than being copied into the public media bundle.
+Missing, malformed, out-of-bounds, non-full-frame, rendition-mismatched, or
+internally drifted composition evidence fails before media finalization.
 
 ## Media Qualification Profiles
 
@@ -225,13 +272,13 @@ The single machine-readable source is
 profile through `media-profile`; they cannot pass ffmpeg commands, codec flags,
 shell fragments, arbitrary profile paths, or transcoding instructions.
 
-| Profile | Meaning |
-| --- | --- |
-| `archive-v1` | Default compatibility contract. Retains the exact renderer outputs and classifies GIF as README compatibility evidence without making a browser-delivery claim. |
-| `web-delivery-v1` | Independently qualifies H.264 MP4 and VP9 WebM playback sources, forbids audio, requires exact scene dimensions and bounded duration/frame-rate drift, checks per-rendition byte ceilings, and proves MP4 `moov` precedes `mdat`. PNG remains the lossless evidence poster. |
-| `responsive-web-delivery-v1` | Extends `web-delivery-v1` with exact 1280x720 H.264 MP4 and VP9 WebM responsive sources plus a 1280x720 README GIF while keeping the primary MP4/WebM and evidence poster at the source scene dimensions. Every declared downscale must preserve the scene aspect ratio and may never upscale. |
-| `responsive-long-form-web-delivery-v1` | Extends the responsive profile for explicitly admitted long-form scenes. Its measured-baseline multipliers raise only the GIF ceiling to 8 MiB and the four video ceilings to 4 MiB; all codec, native-resolution, no-audio, duration, and authority checks remain unchanged. |
-| `site-hero-v1` | Extends `web-delivery-v1` and additionally requires a qualified WebP browser poster. The current Build Images v1 renderer does not emit that member, so selecting this profile fails closed until the producer adds it. |
+| Profile                                | Meaning                                                                                                                                                                                                                                                                                        |
+| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `archive-v1`                           | Default compatibility contract. Retains the exact renderer outputs and classifies GIF as README compatibility evidence without making a browser-delivery claim.                                                                                                                                |
+| `web-delivery-v1`                      | Independently qualifies H.264 MP4 and VP9 WebM playback sources, forbids audio, requires exact scene dimensions and bounded duration/frame-rate drift, checks per-rendition byte ceilings, and proves MP4 `moov` precedes `mdat`. PNG remains the lossless evidence poster.                    |
+| `responsive-web-delivery-v1`           | Extends `web-delivery-v1` with exact 1280x720 H.264 MP4 and VP9 WebM responsive sources plus a 1280x720 README GIF while keeping the primary MP4/WebM and evidence poster at the source scene dimensions. Every declared downscale must preserve the scene aspect ratio and may never upscale. |
+| `responsive-long-form-web-delivery-v1` | Extends the responsive profile for explicitly admitted long-form scenes. Its measured-baseline multipliers raise only the GIF ceiling to 8 MiB and the four video ceilings to 4 MiB; all codec, native-resolution, no-audio, duration, and authority checks remain unchanged.                  |
+| `site-hero-v1`                         | Extends `web-delivery-v1` and additionally requires a qualified WebP browser poster. The current Build Images v1 renderer does not emit that member, so selecting this profile fails closed until the producer adds it.                                                                        |
 
 For web-delivery profiles, Buildchain runs its own fixed `ffprobe` invocation
 inside the same immutable, network-disabled renderer image. That command is

package/docs/aws-us-elastic-runner-burst-plane.md

@@ -210,21 +210,25 @@ Each stack owns a stack-scoped reaper log group, so an independent retained
 one-shot campaign stack can be created without colliding with another
 campaign's audit log resource.
 
-The tag-filtered AWS Budget is defense in depth, not the authoritative launch
+The account-native AWS Budget is defense in depth, not the authoritative launch
 gate. It is owned by the singleton
 `kungfu-buildchain-windows-jit-budget-guard` stack rather than any retained
 campaign stack. This prevents Budget-name collisions and prevents a stale
 campaign reaper from becoming the provider-wide cost authority. The Budget
-filters exactly `user:kungfu:provider$windows-ec2-jit`; its 80% and 95% actual
-notifications persist the provider kill sentinel, terminate every tagged
-Windows JIT instance, and delete scoped JIT parameters. Every launch controller
-refuses to proceed when the sentinel exists or when the Budget identity or tag
-filter does not match.
-
-Budget installation fails closed until the AWS Organizations management
-account activates `kungfu:provider` and Cost Explorer returns
-`windows-ec2-jit` for that key. A linked account cannot activate the tag. Do not
-create an unfiltered fallback Budget or treat a tag-filtered zero as evidence.
+filters exactly `USAGE_TYPE=BoxUsage:c7i.4xlarge`,
+`OPERATION=RunInstances:0002` (Windows), and `REGION=us-east-1`; its 80% and
+95% actual notifications persist the provider kill sentinel, terminate every
+tagged Windows JIT instance, and delete scoped JIT parameters. Every launch
+controller refuses to proceed when the sentinel exists or when the Budget
+identity or dimension filter does not match.
+
+Budget installation is intentionally deployable by the workload account without
+AWS Organizations management-account access. It fails closed unless Cost
+Explorer exposes all three AWS-owned billing dimensions in the requested phase
+window. The `kungfu:provider=windows-ec2-jit` resource tag remains mandatory for
+ownership, cleanup, and IAM scoping, but it is not a billing filter. Do not
+create an unfiltered fallback Budget or treat an incomplete dimension readback
+as evidence.
 The DynamoDB campaign reservation remains the atomic launch authority because
 Cost Explorer and AWS Budgets can lag provider activity.
 
@@ -250,12 +254,12 @@ The modes are deliberately separated:
   provider kill sentinel, campaign stack, and zero EC2/EBS/SSM/JIT/runner
   residue.
 - `install-budget --execute` deploys or updates only the singleton Budget guard.
-  It refuses to mutate unless the provider tag value is visible, the Windows
-  workflow is disabled, and the account, campaign, source, Budget, and plan
-  digest confirmations match.
+  It refuses to mutate unless all exact Windows billing dimensions are visible,
+  the Windows workflow is disabled, and the account, campaign, source, Budget,
+  and plan digest confirmations match.
 - `prepare --execute` requires the installed Budget guard, absent kill
-  sentinel, fresh Cost Explorer readback filtered by both
-  `kungfu:provider=windows-ec2-jit` and `BoxUsage:c7i.4xlarge`, zero residue, a
+  sentinel, fresh Cost Explorer readback filtered by `BoxUsage:c7i.4xlarge`,
+  `RunInstances:0002`, and `us-east-1`, zero residue, a
   never-used campaign stack name, and the disabled workflow. The receipt binds
   the query timestamp and exact filter identity. Preparation deploys the
   campaign stack and atomically arms the ledger with that provider-spend
@@ -310,9 +314,9 @@ clear or re-arm operation.
 Every `scripts/aws-windows-jit-controller.mjs --execute` call must provide the
 same `--account-id`, `--campaign-id`, `--confirm-campaign-id`, `--state-table`,
 and `--confirm-state-table`. Before GitHub JIT material is created, the
-controller verifies the exact provider Budget/tag filter and proves the global
-Budget kill sentinel absent. After the GitHub, AMI, active-instance, SSM, and
-EC2 DryRun checks pass, the controller
+controller verifies the exact provider Budget/dimension filter and proves the
+global Budget kill sentinel absent. After the GitHub, AMI, active-instance,
+SSM, and EC2 DryRun checks pass, the controller
 atomically reserves one run. Duplicate run-attempt-qualification identities,
 source mismatch, expiry, `KILLED`, the sixth accepted instance, or a
 reservation that would exceed the USD 110 ceiling after combining the persisted

package/docs/cli-reference.md

@@ -223,6 +223,160 @@ buildchain dev
 buildchain dev merge-queue --repository <owner/repo> --branch <dev/vN/vN.M> [--from-config | --workflow <required-workflow.yml>...] [--cwd <dir>] [--check-response-timeout-minutes <n>] [--max-entries-to-build <n>] [--apply]
 ```
 
+### `buildchain dev pr-admit`
+
+- Help: `buildchain dev pr-admit --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--expected-head`, `--json`, `--output`, `--pull-request`, `--repository`
+- Syntax:
+
+```text
+buildchain dev pr-admit --repository <owner/repo> --branch <dev/vN/vN.M> --pull-request <n> --expected-head <sha> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev proof classify`
+
+- Help: `buildchain dev proof classify --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev proof integration`
+
+- Help: `buildchain dev proof integration --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev proof replay`
+
+- Help: `buildchain dev proof replay --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev proof source`
+
+- Help: `buildchain dev proof source --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev proof verify-integration`
+
+- Help: `buildchain dev proof verify-integration --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev proof verify-source`
+
+- Help: `buildchain dev proof verify-source --help`
+- Canonical id: `dev`
+- Options: `--json`, `--output`
+- Syntax:
+
+```text
+buildchain dev proof <source|verify-source|classify|replay|integration|verify-integration> [--output <file>] [--json]
+```
+
+### `buildchain dev warrant cancel-queued`
+
+- Help: `buildchain dev warrant cancel-queued --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant close`
+
+- Help: `buildchain dev warrant close --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant heartbeat`
+
+- Help: `buildchain dev warrant heartbeat --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant observe`
+
+- Help: `buildchain dev warrant observe --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant recover`
+
+- Help: `buildchain dev warrant recover --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant select`
+
+- Help: `buildchain dev warrant select --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
+### `buildchain dev warrant submit`
+
+- Help: `buildchain dev warrant submit --help`
+- Canonical id: `dev`
+- Options: `--branch`, `--execute`, `--json`, `--output`, `--repository`
+- Syntax:
+
+```text
+buildchain dev warrant <submit|select|heartbeat|recover|close|cancel-queued|observe> --repository <owner/repo> --branch <dev/vN/vN.M> [--execute] [--output <file>] [--json]
+```
+
 ## `diagnostics`
 
 ### `buildchain diagnostics`

package/docs/dev-alpha-candidate-patrol.md

@@ -8,12 +8,12 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: self-reviewed
-last_reviewed: 2026-08-03
+last_reviewed: 2026-08-04
 ai_provenance:
   model_family: GPT-5
   product: Codex
-  generated_at: 2026-07-29
-  visible_context: Existing Buildchain source locks, Kungfu exact-source Alpha preflight, Dev Patrol, protected auto-merge policy, repository release governance, and the consumer-owned settlement renderer threat model.
+  generated_at: 2026-08-04
+  visible_context: Existing Buildchain source locks, Kungfu exact-source Alpha preflight, Dev Patrol, cancelled duplicate runs, protected auto-merge policy, repository release governance, and the consumer-owned settlement renderer threat model.
   invisible_context_boundary: No credentials, private logs, or private configuration were used.
 ---
 
@@ -27,8 +27,10 @@ bounded development history from newest to oldest (stopping early at the Alpha
 head), and selects the newest commit that satisfies all of these conditions:
 
 - the source is strictly ahead of the recorded target head;
-- the latest completed Dev Patrol for that exact commit SHA succeeded;
-- the latest completed Alpha preflight for the same commit SHA succeeded; and
+- the latest completed, non-cancelled Dev Patrol for that exact commit SHA
+  succeeded;
+- the latest completed, non-cancelled Alpha preflight for the same commit SHA
+  succeeded; and
 - both runs are within the caller's evidence age limit.
 
 The selected commit can be behind the observed development head when newer
@@ -37,6 +39,12 @@ head, selected SHA, and count of skipped newer commits. This makes a slow native
 verification lane live under continuous development without silently treating
 an unqualified head as releasable.
 
+A cancelled workflow run carries no qualification verdict, so a newer
+cancelled duplicate does not erase the prior completed verdict for the same
+workflow and source SHA. Other non-success conclusions remain authoritative:
+a newer failed, timed-out, skipped, or otherwise non-successful completed run
+still excludes that SHA and forces the controller to fall back or fail closed.
+
 History discovery is bounded to the newest 1000 development commits. The
 controller then compares the selected SHA to the exact Alpha head before it can
 be eligible, so a bounded scan cannot turn a commit outside the promotion

package/docs/dev-delivery-warrant.md

@@ -0,0 +1,158 @@
+---
+status: draft
+period: ongoing
+theme: dev-delivery-warrant
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-08-05
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-04
+  invisible_context: not asserted
+---
+
+# Dev Delivery Warrant Queue
+
+Buildchain's Dev Delivery Warrant Queue gives a qualified slow pull request a
+durable, non-preemptive delivery turn without replacing GitHub Merge Queue as
+the final protected-ref authority.
+
+The queue is stored on a dedicated Git ref below
+`buildchain/dev-delivery-warrant/`. Every update creates a child Git commit and
+advances the ref without force. The transition receipt binds the expected old
+state root; a competing controller receives a visible non-fast-forward failure
+instead of a second authority claim.
+
+## Contract
+
+A submission binds the repository, protected dev line, pull request, semantic
+source identity, exact source head, native Assignment and Initiative roots,
+source patch or tree intent, reusable Source Qualification Proof, plan,
+affected closure, dependencies, toolchain, delivery class, priority, attempts,
+and retained enqueue time.
+
+Selection is deterministic FIFO plus aging with bounded priority. Priority may
+reorder queued work, but it cannot preempt the active Warrant. Exactly one
+candidate receives a leased Warrant containing a fencing token, lease
+generation, expected-old state root, expiry, and the complete exact source
+binding. Heartbeat extends only that generation. Expiry recovery rejects the
+old token, retains queue age, and returns the candidate to selection.
+
+A terminal event may cancel a candidate before selection without minting a
+Warrant. This transition is limited to an exact non-active queued candidate and
+binds its candidate root, pull request, recorded source head, event-observed
+source head, terminal event action, evidence root, and expected-old queue root.
+An active candidate still requires its current fencing token and lease
+generation. Exact duplicate cancellation evidence is a visible no-op; identity,
+state, event, or evidence drift fails closed.
+
+The reusable terminal controller uses one `settle` operation for active,
+queued, already-terminal, and never-admitted pull requests. An active Warrant
+still requires its exact fence and evidence. A matching queued cancellation is
+persisted normally. A duplicate terminal event or a pull request that never
+entered Warrant authority returns a rooted explicit no-op instead of failing
+the workflow or inventing queue state.
+
+The supported priority classes are `ordinary`, `expedited`, and `emergency`.
+The queue does not infer an emergency: callers must choose it explicitly under
+their reviewed policy. Delivery classes are `non-native-fast`,
+`native-proof-required`, `cross-platform`, and `release`.
+
+## Split proof authority
+
+Source Qualification Proof is independent of the moving dev base. It binds the
+semantic source, exact source head and patch/tree intent, plan, affected
+closure, dependencies, toolchain, covered paths, and shard evidence.
+
+Before reuse, the consumer classifies the dev delta:
+
+- unchanged roots plus an unrelated attributed delta reuse source
+  qualification and run only a cheap Project Cut replay. GitHub's `behind`
+  state is accepted only when a rooted replay proof binds the exact current
+  protected base, unchanged PR head and source patch, replay tree, required
+  context roots, and a qualified `project.cut.merge-queue-admission/v1`
+  receipt;
+- an overlapping delta reruns the affected source shards;
+- an unknown graph or changed source, plan, closure, dependency, or toolchain
+  root fails closed to full source qualification.
+
+Integration Delivery Proof is separate and cannot be cached across candidates.
+It binds the exact current dev base, replay tree, GitHub `merge_group` head and
+tree, active Warrant fencing generation, Source Qualification Proof root, and
+final required-context roots. GitHub's exact merge-group checks remain the
+final integration authority.
+
+## CLI
+
+Queue commands are dry-run by default:
+
+```sh
+buildchain dev warrant submit --repository owner/repository \
+  --branch dev/v4/v4.0 --pull-request 123 --source-head <sha> \
+  --assignment-root <root> --initiative-root <root> \
+  --source-identity-root <root> --source-patch-root <root> \
+  --source-proof-root <root> --plan-root <root> --closure-root <root> \
+  --dependency-root <root> --toolchain-root <root> \
+  --delivery-class native-proof-required
+
+buildchain dev warrant select --repository owner/repository \
+  --branch dev/v4/v4.0 --execute
+
+buildchain dev warrant cancel-queued --repository owner/repository \
+  --branch dev/v4/v4.0 --candidate-id <root> --pull-request 123 \
+  --expected-source-head <queued-sha> --observed-source-head <event-sha> \
+  --expected-old <queue-root> --event-action closed --outcome cancelled \
+  --evidence-root <terminal-event-root> --execute
+```
+
+`heartbeat`, `recover`, `close`, `settle`, `cancel-queued`, and `observe` use the same durable authority.
+Warrant-scoped mutations require the exact fencing token and lease generation.
+`close` also requires a rooted terminal evidence object.
+
+Proof commands create, verify, classify, and compose the two proof layers:
+
+```sh
+buildchain dev proof source ...
+buildchain dev proof classify --source-proof source-proof.json ...
+buildchain dev proof replay ...
+buildchain dev proof replay-proof \
+  --qualification-receipt project-cut-admission.json ...
+buildchain dev proof integration --warrant-result warrant.json ...
+```
+
+## Workflow rollout and rollback
+
+The reusable `dev-pr-auto-merge.yml` supports three explicit rollout modes:
+
+- `off` preserves the previous exact-head admission controller;
+- `shadow` qualifies the source and emits a read-only queue submission plan;
+- `required` persists the submission, selects the Warrant, and refuses GitHub
+  enqueue unless the immutable queue commit, state root, active Warrant, and
+  selected candidate all pass exact readback validation.
+
+Consumers should deploy `shadow` first, inspect receipts, then change their
+protected caller to `required`. Rollback is a reviewed caller change back to
+`off`; it does not delete queue history or reinterpret old receipts. The
+terminal reusable workflow creates the exact Integration Delivery Proof for a
+merged candidate (or accepts explicit evidence for another terminal outcome),
+then closes only the current fencing generation. The separate queued
+cancellation reusable workflow cannot close an active generation; it advances
+the state ref only when the caller's complete terminal binding and expected-old
+root still match.
+
+Buildchain uses the same contract for its own protected dev line through
+`buildchain-dev-delivery.yml`. The manual caller requires the exact PR head and
+all native/source proof roots, pins the runtime to the caller commit, selects
+`delivery-warrant-mode: required`, and targets GitHub Merge Queue. It does not
+offer an `off` switch: rollback is a reviewed change to this caller, not an
+operator-time weakening of a specific delivery attempt.
+
+This mechanism schedules protected delivery only. It does not serialize local
+development, source-only checks, unrelated channels, release publication, or
+runner provisioning. It never grants authority to enable cloud runner
+campaigns.