@kungfu-tech/buildchain 4.0.0 → 4.0.1-alpha.10

package/AGENTS.md

@@ -109,12 +109,20 @@ called only by the public reusable workflow and tests. `version-state`,
 `publish`, provider, signing, release, credential, AWS, and production-reuse
 effects remain excluded.
 
+Buildchain v4 workflow calls persisted in tracked source use only `@v4` or
+`@v4-alpha` and retain matching stable and alpha contract locks.
+A source-persisted exact commit SHA, exact default, repository-variable indirection, nested
+composite indirection, missing lock, or stale selected lock fails consumer
+admission. Exact resolved SHAs remain evidence and runtime data, never a durable
+selector.
+
 If public workflow recursion prevents candidate validation, publish the exact
-candidate at `train/v4/v4.0/<capability>` and make the thin caller consume that
-fully qualified public train ref. Fix failures in the train/public contract;
-never solve recursion with an internal exception. After qualification and
-protected merge, repin the durable caller to the exact protected commit when
-the delivery plan requires it. `pnpm run check` and protected Verify run
+candidate at `train/v4/v4.0/<capability>`, keep the thin caller on `@v4-alpha`,
+and pass the train only through the trusted non-persistent runtime input. Fix
+failures in the train/public contract; never solve recursion with an internal exception.
+Never use a persisted train/SHA selector. After qualification and protected
+merge, the durable caller remains on the floating channel with refreshed dual
+contract locks. `pnpm run check` and protected Verify run
 `scripts/check-v4-public-dogfood-contract.mjs`; changing this rule, its gate, or
 the protected caller requires independent `@kungfu-origin` review.
 

package/actions/promote-buildchain-ref/README.md

@@ -156,8 +156,10 @@ trusted channel workflow:
 
 ```yaml
 - uses: kungfu-systems/buildchain/actions/promote-buildchain-ref@v3
+  env:
+    BUILDCHAIN_TAG_UPDATE_TOKEN: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
   with:
-    token: ${{ secrets.BUILDCHAIN_PROMOTION_TOKEN }}
+    token: ${{ github.token }}
     generated-ref-update-token: ${{ github.token }}
     sha: ${{ github.sha }}
     target-ref: release/v3/v3.0
@@ -511,11 +513,14 @@ governance semantics:
   with either the `verification-command` input or `buildchain.toml`
   `lifecycle.verify` before any tags or channel refs move.
 
-The reusable promotion workflow keeps governance reads, generated status checks,
-and generated ref updates on the run-scoped `github.token`. When branch
-protection rejects generated bookkeeping, it supplies `BUILDCHAIN_PROMOTION_TOKEN`
-only through `generated-pull-request-token` so the same-repository recovery PR can
-be listed or created without broadening the governance client. Protected branch
+The reusable promotion workflow keeps governance reads, provider finalization,
+generated status checks, and generated ref updates on the run-scoped
+`github.token`. It exposes `BUILDCHAIN_PROMOTION_TOKEN` only through the
+step-scoped `BUILDCHAIN_TAG_UPDATE_TOKEN` environment variable and the
+`generated-pull-request-token`: the former creates or moves public release tags,
+while the latter lists or creates the
+same-repository recovery PR when branch protection rejects generated bookkeeping.
+Protected branch
 review and check rules guard human channel merges, while the reusable build trust
 gate checks the source-lock channel HEAD and merged same-repository PR lineage
 before heavy build runners start. This action still independently rechecks PR

package/actions/release-tail/README.md

@@ -11,3 +11,11 @@ not the adapter, compares the observed subject and target roots, owns retry and
 terminal classification, checkpoints state and emits the standardized receipt.
 Tokens remain Action inputs and are never written to the transaction or
 receipt.
+
+When `rehearsal-capsule` is supplied, the same Action switches to the v4
+Publication Rehearsal Capsule boundary. `simulate` and `replay` remain
+effect-disabled. `provider` additionally requires exact capsule-bound
+rehearsal authority, consumes only the capsule-rooted data bindings, and
+records every request/readback while still emitting
+`productionAuthority: false` and no Release Passport. See
+[`docs/v4-publication-rehearsal.md`](../../docs/v4-publication-rehearsal.md).

package/architecture/ci-lane-change-budget.json

@@ -0,0 +1,187 @@
+{
+  "schema": "buildchain.ci-lane-change-budget/v1",
+  "authorityClassification": "repository-policy-enforcement",
+  "baseline": {
+    "gitRevision": "7fdf0b560670df65929ab2ee833c3d6339372d8a",
+    "source": "protected dev/v4/v4.0 before CI lane change-budget enforcement",
+    "laneSetRoot": "sha256:5bed17dc265f424e5d528949231146c633be954b8c3c2535ba18aec6ac1465a4",
+    "lanes": [
+      ".github/workflows/.auditable-demo.yml#gate",
+      ".github/workflows/.auditable-demo.yml#render",
+      ".github/workflows/.binary-release-assets.yml#publication-authority",
+      ".github/workflows/.binary-release-assets.yml#publish",
+      ".github/workflows/.build.yml#anchored-release-preflight",
+      ".github/workflows/.build.yml#artifact-signing-control",
+      ".github/workflows/.build.yml#artifact-transfer",
+      ".github/workflows/.build.yml#build-linux-container",
+      ".github/workflows/.build.yml#build-native",
+      ".github/workflows/.build.yml#controller-plan",
+      ".github/workflows/.build.yml#controller-receipt",
+      ".github/workflows/.build.yml#credential-island-macos",
+      ".github/workflows/.build.yml#finalize-artifact-signing",
+      ".github/workflows/.build.yml#relay-artifacts",
+      ".github/workflows/.build.yml#resolve-contract",
+      ".github/workflows/.build.yml#resolve-source",
+      ".github/workflows/.build.yml#summarize",
+      ".github/workflows/.build.yml#trust-gate",
+      ".github/workflows/.bump-minor-version.yml#bump",
+      ".github/workflows/.declarative-auditable-demo.yml#capture",
+      ".github/workflows/.declarative-auditable-demo.yml#publish",
+      ".github/workflows/.declarative-auditable-demo.yml#qualify",
+      ".github/workflows/.gate-profile.yml#aggregate",
+      ".github/workflows/.gate-profile.yml#plan",
+      ".github/workflows/.gate-profile.yml#run-gates",
+      ".github/workflows/.publication-authority.yml#verify",
+      ".github/workflows/.release-candidate-promote.yml#controller-plan",
+      ".github/workflows/.release-candidate-promote.yml#controller-receipt",
+      ".github/workflows/.release-candidate-promote.yml#github-artifact-attestation",
+      ".github/workflows/.release-candidate-promote.yml#preflight",
+      ".github/workflows/.release-candidate-promote.yml#promote",
+      ".github/workflows/.release-candidate-promote.yml#publication-authority",
+      ".github/workflows/.release-candidate-promote.yml#publication-plan",
+      ".github/workflows/.release-candidate-promote.yml#publication-qualification",
+      ".github/workflows/.release-candidate-promote.yml#publish-github-artifact-attestation-evidence",
+      ".github/workflows/.release-candidate-promote.yml#qualification-plan",
+      ".github/workflows/.release-candidate-promote.yml#release-candidate-preflight",
+      ".github/workflows/.release-docker.yml#retired",
+      ".github/workflows/.release-elastic-beanstalk.yml#retired",
+      ".github/workflows/.release-new-version.yml#retired",
+      ".github/workflows/.release-verify.yml#build",
+      ".github/workflows/.release-verify.yml#build_local",
+      ".github/workflows/.release-verify.yml#prepare",
+      ".github/workflows/.release-verify.yml#verify",
+      ".github/workflows/.sam-release.yml#retired",
+      ".github/workflows/.sam-verify.yml#build",
+      ".github/workflows/.sam-verify.yml#prepare",
+      ".github/workflows/.sam-verify.yml#verify",
+      ".github/workflows/.sync-release-page.yml#sync-release-page",
+      ".github/workflows/.sync-remote-git.yml#sync",
+      ".github/workflows/.web-surface.yml#apply-input-gate",
+      ".github/workflows/.web-surface.yml#controller-plan",
+      ".github/workflows/.web-surface.yml#controller-receipt",
+      ".github/workflows/.web-surface.yml#external-publication-authority",
+      ".github/workflows/.web-surface.yml#open-production-release-pr",
+      ".github/workflows/.web-surface.yml#plan",
+      ".github/workflows/.web-surface.yml#preview-apply",
+      ".github/workflows/.web-surface.yml#preview-cleanup",
+      ".github/workflows/.web-surface.yml#production-apply",
+      ".github/workflows/.web-surface.yml#publication-authority",
+      ".github/workflows/.web-surface.yml#publication-decision",
+      ".github/workflows/.web-surface.yml#release-intent",
+      ".github/workflows/.web-surface.yml#runtime",
+      ".github/workflows/.web-surface.yml#staging-apply",
+      ".github/workflows/.wheel-release.yml#retired",
+      ".github/workflows/.wheel-verify.yml#build",
+      ".github/workflows/.wheel-verify.yml#prepare",
+      ".github/workflows/.wheel-verify.yml#verify",
+      ".github/workflows/artifact-signing-authority.yml#deliver",
+      ".github/workflows/artifact-signing-authority.yml#detached",
+      ".github/workflows/artifact-signing-authority.yml#intake",
+      ".github/workflows/artifact-signing-authority.yml#macos",
+      ".github/workflows/artifact-signing-authority.yml#windows",
+      ".github/workflows/auditable-demo-media-profile-qualification.yml#qualify",
+      ".github/workflows/auditable-demo.yml#dogfood",
+      ".github/workflows/auditable-demo.yml#exact-binary",
+      ".github/workflows/binary-distribution.yml#binary",
+      ".github/workflows/binary-distribution.yml#dispatch-publication",
+      ".github/workflows/binary-distribution.yml#passport",
+      ".github/workflows/binary-distribution.yml#preflight",
+      ".github/workflows/binary-release-assets.yml#publish",
+      ".github/workflows/binary-release-assets.yml#resolve",
+      ".github/workflows/build-surface-fixture.yml#buildchain-package-candidate",
+      ".github/workflows/build-surface-fixture.yml#libnode-shaped",
+      ".github/workflows/build.yml#alpha",
+      ".github/workflows/build.yml#controller-plan",
+      ".github/workflows/build.yml#controller-receipt",
+      ".github/workflows/build.yml#override",
+      ".github/workflows/build.yml#resolve-channel",
+      ".github/workflows/build.yml#stable",
+      ".github/workflows/build.yml#summarize",
+      ".github/workflows/buildchain-alpha-self-dogfood.yml#alpha-consumer",
+      ".github/workflows/buildchain-alpha-self-dogfood.yml#stable-consumer",
+      ".github/workflows/buildchain-alpha-self-dogfood.yml#verify-floating-refs",
+      ".github/workflows/buildchain-candidate-recovery-dogfood-failure.yml#deterministic-startup-router-failure",
+      ".github/workflows/buildchain-dev-delivery.yml#deliver",
+      ".github/workflows/buildchain-patrol-daily.yml#patrol",
+      ".github/workflows/buildchain-patrol-monthly.yml#patrol",
+      ".github/workflows/buildchain-patrol-weekly.yml#patrol",
+      ".github/workflows/buildchain-patrol.yml#patrol",
+      ".github/workflows/buildchain-ref-promotion-recovery.yml#consumer-admission",
+      ".github/workflows/buildchain-ref-promotion-recovery.yml#promote-alpha-recovery",
+      ".github/workflows/buildchain-ref-promotion.yml#promote-alpha",
+      ".github/workflows/buildchain-ref-promotion.yml#promote-stable",
+      ".github/workflows/buildchain-ref-promotion.yml#reject-invalid-candidate-recovery",
+      ".github/workflows/buildchain-ref-promotion.yml#reject-invalid-durable-recovery",
+      ".github/workflows/buildchain-ref-promotion.yml#reject-manual-apply",
+      ".github/workflows/buildchain-stable-candidate-patrol.yml#patrol",
+      ".github/workflows/buildchain-stable-candidate-qualification.yml#qualify",
+      ".github/workflows/candidate-lab.yml#lab",
+      ".github/workflows/check.yml#check",
+      ".github/workflows/dev-alpha-candidate-patrol.yml#observe",
+      ".github/workflows/dev-alpha-candidate-patrol.yml#settle",
+      ".github/workflows/dev-delivery-warrant-cancel.yml#cancel",
+      ".github/workflows/dev-delivery-warrant-close.yml#close",
+      ".github/workflows/dev-merge-queue-governance.yml#reconcile",
+      ".github/workflows/dev-pr-auto-merge.yml#admission",
+      ".github/workflows/dev-pr-auto-merge.yml#delivery-heartbeat",
+      ".github/workflows/dev-pr-auto-merge.yml#merge-dev-prs",
+      ".github/workflows/dev-pr-auto-merge.yml#native-execution",
+      ".github/workflows/dev-pr-auto-merge.yml#seal-native-execution",
+      ".github/workflows/dev-qualification-patrol.yml#mutate",
+      ".github/workflows/dev-qualification-patrol.yml#observe",
+      ".github/workflows/engineering-housekeeper-daily.yml#apply",
+      ".github/workflows/engineering-housekeeper-daily.yml#invalid-apply-gate",
+      ".github/workflows/engineering-housekeeper-daily.yml#report",
+      ".github/workflows/engineering-housekeeper-monthly.yml#apply",
+      ".github/workflows/engineering-housekeeper-monthly.yml#invalid-apply-gate",
+      ".github/workflows/engineering-housekeeper-monthly.yml#report",
+      ".github/workflows/engineering-housekeeper-weekly.yml#apply",
+      ".github/workflows/engineering-housekeeper-weekly.yml#invalid-apply-gate",
+      ".github/workflows/engineering-housekeeper-weekly.yml#report",
+      ".github/workflows/engineering-housekeeper.yml#delete-branches",
+      ".github/workflows/engineering-housekeeper.yml#label-pull-requests",
+      ".github/workflows/engineering-housekeeper.yml#plan",
+      ".github/workflows/github-artifact-attestation.yml#attest",
+      ".github/workflows/github-governance-audit.yml#audit",
+      ".github/workflows/npm-publish.yml#dry-run",
+      ".github/workflows/paper-release-sealed.yml#publication-authority",
+      ".github/workflows/paper-release-sealed.yml#publication-candidate",
+      ".github/workflows/paper-release-sealed.yml#publish",
+      ".github/workflows/paper-release.yml#paper-release",
+      ".github/workflows/paper-release.yml#publication-authority",
+      ".github/workflows/patrol-daily.yml#patrol",
+      ".github/workflows/patrol-monthly.yml#patrol",
+      ".github/workflows/patrol-observed-evidence.yml#publish",
+      ".github/workflows/patrol-weekly.yml#patrol",
+      ".github/workflows/publication-artifact.yml#publication",
+      ".github/workflows/release-candidate-promote.yml#alpha",
+      ".github/workflows/release-candidate-promote.yml#consumer-admission",
+      ".github/workflows/release-candidate-promote.yml#resolve-promotion",
+      ".github/workflows/release-candidate-promote.yml#stable",
+      ".github/workflows/release-governance-reconcile.yml#reconcile",
+      ".github/workflows/release-line-bootstrap.yml#bootstrap",
+      ".github/workflows/release-new-version.yml#buildchain-self-release",
+      ".github/workflows/release-propagation.yml#propagate",
+      ".github/workflows/release-tail.yml#release-tail",
+      ".github/workflows/release-verify.yml#try",
+      ".github/workflows/release-verify.yml#verify",
+      ".github/workflows/schedule-purge-artifacts.yml#delete-artifacts",
+      ".github/workflows/self-hosted-runner-smoke.yml#smoke",
+      ".github/workflows/stable-candidate-patrol.yml#patrol",
+      ".github/workflows/v4-adopter-delivery-dogfood.yml#dogfood",
+      ".github/workflows/v4-adopter-delivery.yml#conformance",
+      ".github/workflows/v4-adopter-delivery.yml#consumer-admission",
+      ".github/workflows/v4-public-consumer-dogfood.yml#dogfood",
+      ".github/workflows/v4-publication-rehearsal-dogfood.yml#rehearsal",
+      ".github/workflows/v4-stage-capsule-canary.yml#consumer-admission",
+      ".github/workflows/v4-stage-capsule-canary.yml#qualify",
+      ".github/workflows/v4-stage-capsule-canary.yml#reconcile",
+      ".github/workflows/v4-tail-reseal.yml#plan",
+      ".github/workflows/v4-tail-reseal.yml#platforms",
+      ".github/workflows/v4-tail-reseal.yml#seal",
+      ".github/workflows/verify.yml#check",
+      ".github/workflows/verify.yml#stage-capsule-checkpoints"
+    ]
+  },
+  "declarations": []
+}

package/architecture/decisions/0002-next-development-transition.md

@@ -0,0 +1,101 @@
+---
+status: accepted
+period: 2026-08-11
+theme: next-development-transition
+doc_type: architecture-decision-record
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-11
+---
+
+# ADR 0002: Alpha Publication and Next-development Are Separate Transactions
+
+## Status
+
+Accepted. This decision is normative for Buildchain promotion controllers and
+for generated consumer guidance.
+
+## Context
+
+An Alpha publication and preparation of the following development version have
+different trust boundaries. Alpha publication establishes public, immutable
+facts about version N. Preparing N+1 changes repository version material and
+may require a protected pull request or an upstream anchor that does not exist
+when Alpha N completes. Treating both operations as one success condition makes
+a post-publication conflict appear to invalidate a publication that already
+succeeded, and encourages retries to move Alpha refs while repairing Dev.
+
+Buildchain supports two legal version models:
+
+- `semver` with `next = "auto"`, where N+1 increments the Alpha sequence on
+  the same semantic patch; and
+- `anchored` with `next = "manual"`, where no version may be inferred before a
+  declared anchor manifest is materialized and rooted.
+
+The crossed combinations `semver/manual` and `anchored/auto` have no defined
+meaning and are rejected.
+
+## Decision
+
+Alpha publication reaches its own terminal success before a next-development
+transition is created. The transition records the completed Alpha exact tag,
+release commit, tree, publication evidence root, and completion time. A
+deterministic idempotency key covers that completed-Alpha root together with
+the repository, legal version model, and the role-separated adapter path set.
+
+The independent next-development state machine is:
+
+```text
+planned ----------------------> materialized -> pr-pending -> merged -> verified
+   \                              \---------------------------> merged
+    -> waiting-anchor ----------> materialized
+```
+
+`semver/auto` derives its target while planned. `anchored/manual` remains in
+`waiting-anchor` until an exact semantic version and the digest of the declared
+anchor manifest are supplied. `pr-pending` is durable incomplete state, not a
+publication failure. Direct materialization may proceed to `merged` or
+`verified` when repository governance does not require a pull request.
+
+Every non-initial state transition is compare-and-swap guarded and rooted in
+explicit evidence. Replaying an identical request is a no-op. Alpha outcome is
+always `preserved-success`; no transition may write an Alpha branch, exact tag,
+or floating tag. A controller that needs to repair next-development state may
+write only paths declared by `version.files` and `version.derived_files`; the
+configured anchor manifest is declared read-only authority.
+
+## Local adapter boundary
+
+The reference adapter is provider-neutral. It reads the checked-in
+`buildchain.toml`, derives the sorted path allowlist, validates the completed
+Alpha and optional anchor, and plans version-file content. It never invokes Git,
+network clients, lifecycle commands, package registries, or provider APIs.
+Mutation requires explicit `--write`, rejects symlinks and path escapes, and is
+limited to configured `version.files`. The standard repository transaction
+adapter passes the exact target in `BUILDCHAIN_VERSION`, permits changes only
+to `version.files` plus `version.derived_files`, runs
+`lifecycle.version-state` when derived files are declared, and then runs
+`lifecycle.verify`. The reference writer fails closed rather than invoking
+those consumer commands because transaction execution is a separate slice.
+For anchored/manual, the consumer must
+materialize the declared manifest first; the adapter verifies its exact digest
+and does not invent or edit upstream anchor data.
+
+Preparing development state alone creates no Git tag, GitHub Release, public
+package, or release candidate.
+
+## Consequences
+
+- A completed Alpha N remains successful when N+1 waits for an anchor, a
+  protected PR, merge, or verification.
+- Retrying development preparation cannot republish Alpha N or change any
+  Alpha ref.
+- Semver and anchored consumers share one lifecycle while retaining their
+  distinct version authority.
+- Provider adapters may project pull-request identifiers and merge evidence,
+  but those observations do not become part of the local mutation authority.
+- Generated config, Agent instructions, and public documentation are checked
+  against the same constants; projection drift fails repository checks.

package/architecture/decisions/0003-two-phase-delivery-warrant.md

@@ -0,0 +1,152 @@
+---
+status: accepted
+period: 2026-08-11
+theme: two-phase-delivery-warrant
+doc_type: architecture-decision-record
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-15
+---
+
+# ADR 0003: Delivery Order Is Reserved Before Native Qualification
+
+## Status
+
+Accepted. This decision is normative for the v3 Delivery Warrant state machine,
+reusable delivery workflows, and generated native consumer workflows.
+
+## Context
+
+A slow native pull request can pass source acceptance, obtain approval, and then
+spend long enough in platform qualification for the protected dev base to move
+many times. Requiring all native shards to finish before the pull request owns
+a delivery turn permits a stream of later fast candidates to overtake it.
+Freezing dev or disabling protection would avoid the race only by stopping
+unrelated work or removing the authority that must be proven.
+
+Native evidence also has two identities that must not be conflated. Semantic
+source, affected closure, dependency graph, and toolchain determine whether a
+native result remains valid. The current dev commit and replay tree determine
+the final integration composition. A dev-only documentation change should not
+invalidate semantic native evidence, while a change inside the affected closure
+must never be silently reused.
+
+## Decision
+
+Delivery Warrant ownership has two phases:
+
+```text
+queued -> provisional --native proof accepted--> qualified -> GitHub merge queue
+              |                  |
+              +--failure--------+--> terminal release -> wake next candidate
+              +--expiry------------> recovered queue entry with a new fence
+```
+
+Source acceptance, the ready label, current approval, and required source checks
+are established before selection. Selection issues a `provisional` Warrant with
+one TTL, heartbeat protocol, lease generation, and fencing token. It reserves
+the next protected-dev delivery turn but is not merge-queue authority. Later
+pull requests may run source and CI work and remain visible in the durable FIFO
+plus aging queue; none may enter the protected merge queue while another exact
+candidate owns the active Warrant.
+
+Native success upgrades the same fenced generation atomically to `qualified`.
+The transition binds a Native Qualification Proof and a rooted reuse decision.
+Only a qualified Warrant may authorize enqueue. The upgrade does not mint a new
+fence and cannot change the PR head or semantic source roots.
+
+Native Qualification Proof v3 binds semantic source identity, semantic patch,
+qualification plan, affected closure, dependency graph, toolchain, execution
+environment contract, covered paths, exact shard evidence roots, the dev base
+used for qualification, and the exact native execution receipt. That receipt
+contains the normalized repository, protected base, source head, qualified
+base, toolchain root, and environment root binding established before the
+native process starts. The proof repeats and roots that binding, and includes
+the receipt root in its shard evidence. Its
+timestamp is observational rather than part of proof identity. Reuse on another
+base requires an attributed base delta. Identical base is accepted directly; a
+descendant base with no overlap against the affected closure reuses the proof;
+overlap requires affected or full native revalidation; unknown ancestry,
+truncated attribution, semantic change, closure change, dependency change, or
+toolchain change requires full revalidation.
+
+The reusable controller composes the exact PR head with the observed protected
+base before running native work, heartbeats while the command is active, and
+checks base drift after completion. It may perform one automatic revalidation
+on the latest base. Continued overlapping drift fails closed. Native failure,
+cancel, semantic head movement, unrecoverable composition conflict, or exhausted
+revalidation closes only the current fence. The controller then emits a rooted
+`buildchain-dev-delivery-wake` repository event for the next queued candidate.
+Cancellation that prevents cleanup is covered by TTL recovery; the stale worker
+cannot renew or qualify after a new fence is minted.
+
+PR-controlled native execution is a credentialless candidate job on a
+GitHub-hosted runner. Its child process and complete `/proc` ancestry receive no
+controller or provider write credential. The ancestry sentinel treats unreadable
+process state as failure and detects generic auth, credential, key, password,
+secret, and token variable names. Only a dependent credentialed finalizer on a
+provider-readback-proven distinct GitHub-hosted job and runner may independently
+verify the content-addressed proof/state transfer, reread the same live fence,
+PR head, and protected base, and qualify or settle the attempt. A successful
+candidate exit is evidence input, not authority to mutate provider state or a
+completion signal by itself. Persistent self-hosted runners are unsupported
+because job ordering alone cannot prove detached-descendant cleanup.
+
+GitHub `merge_group` checks and the protected dev ref remain final integration
+authority. No transition disables a check, changes branch protection, force
+updates the Warrant ref, or freezes dev.
+
+Required native delivery validates the environment root before candidate
+submission, Warrant selection, checkout/composition, or native process spawn.
+An empty or malformed root is therefore an admission failure, not a terminal
+failure after native capacity has been spent. `off`, `shadow`, and
+`non-native-fast` compatibility does not turn the reusable workflow input into
+an unconditional requirement.
+
+## Compatibility
+
+Existing v1 queue documents remain readable. An historical active Warrant that
+does not contain `phase` is interpreted as the former already-qualified shape
+without rewriting its state root. Newly selected Warrants always contain
+`phase: provisional`. Existing `off` and `shadow` workflow modes remain
+available; `required` now enforces the two-phase upgrade. Native Qualification
+Proof v1 and v2 documents remain verifiable as historical evidence, but their
+execution receipts do not bind the environment root. They cannot gain v3 exact
+reuse authority and must be replaced by an explicit native revalidation.
+
+In bounded authority mode, every newly issued Landing Warrant requires the
+complete verified-native qualification shape, including the qualification
+contract, execution binding, execution receipt, command, source proof, and native
+proof roots. A migrated `legacy-compatibility-only` qualification may preserve
+the exact already-active historical Landing fence for safe handoff, but it can
+never mint a new Landing Warrant or acquire native proof authority.
+
+Elapsed lease time is not provider-stop evidence. Cleanup of an expired Landing
+fence requires a separate independent provider terminal verifier whose rooted
+readback matches the exact state root, candidate, source head, fencing token,
+generation, provider run, and provider job and is fresh for that Warrant
+generation. Caller-asserted, forged, mismatched, nonterminal, or stale readback
+cannot release the exclusive slot.
+
+## Consequences
+
+- Slow approved candidates stop starving without serializing development or CI.
+- A provisional receipt is intentionally insufficient for merge admission.
+- Base-only replay churn can reuse native evidence when closure attribution is
+  complete and disjoint.
+- Overlap and uncertainty spend more native compute but cannot create an
+  unproven protected-dev landing.
+- Consumers need a promotion token that can advance the Warrant state ref and
+  emit the wake event, plus a native command or an exact reusable proof.
+- Invalid required-native environment inputs fail before they can allocate a
+  Warrant or native runner time.
+- Legacy unbound native evidence remains readable but intentionally spends a
+  new validation run before qualification.
+- Candidate execution remains credentialless; credentialed readback,
+  qualification, and settlement happen only in a distinct, live-evidenced fresh
+  GitHub-hosted finalizer job after candidate job completion.
+- Expired Landing cleanup is rooted in exact independent provider readback, not
+  a timeout or the controller's own assertion.