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

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

@@ -38,6 +38,36 @@ inspects, verifies, and diagnoses bounded v3 compatibility using the same core
 transaction format. The reusable workflow checks out an exact Buildchain ref
 and invokes the packaged Action; callers cannot inject an execution command.
 
+The reusable workflow is permission-neutral: it inherits the calling job's
+GitHub token permissions and never elevates them. A rehearsal caller can remain
+`contents: read` and must pass `execute: false`. An effectful production caller
+owns and declares its provider authority explicitly:
+
+<!-- release-tail-production-caller-contract -->
+
+```yaml
+name: Production release tail
+
+on:
+  workflow_dispatch:
+
+jobs:
+  release-tail:
+    permissions:
+      contents: write
+    uses: kungfu-systems/buildchain/.github/workflows/release-tail.yml@<exact-buildchain-sha>
+    with:
+      buildchain-ref: <exact-buildchain-sha>
+      declaration-path: .buildchain/release-tail/declaration.json
+      provider-bindings-path: .buildchain/release-tail/provider-bindings.json
+      execute: true
+```
+
+Omitting caller write authority cannot be repaired by the reusable workflow;
+GitHub rejects or constrains the call before provider execution. `execute:
+false` remains a plan/rehearsal boundary and does not authorize production
+mutation even when a caller token has broader ambient permissions.
+
 ## Inputs and secrets
 
 The declaration follows

package/docs/reusable-build-surface.md

@@ -102,6 +102,36 @@ The router is generated from `.build.yml`'s input/output surface. Run
 `node scripts/generate-channel-build-workflow.mjs` after changing the advanced
 build workflow; inventory and unit tests reject a stale generated router.
 
+### v4 floating consumer admission
+
+The v4 public surfaces add a source policy gate before dependency setup, matrix
+planning, build, publication, or promotion work. Tracked caller YAML may use
+only `@v4` or `@v4-alpha`, and the repository must commit both
+`.buildchain/contract-lock.json` and `.buildchain/alpha-contract-lock.json`.
+Source-persisted exact SHAs, exact defaults, repository/input/environment
+indirection, nested composite indirection, a missing lock, or a stale selected
+lock fail closed.
+
+Admission emits a rooted receipt binding the caller source, public workflow,
+visible selector and workflow-shell SHA, actual runtime SHA, both lock roots,
+and policy/scanner roots. A trusted `workflow_dispatch` train or SHA remains a
+non-persistent runtime override: the tracked floating selector and its selected
+lock still bind the visible workflow shell. Release-candidate evidence carries
+the receipt; promotion certifies it independently; final v4 Release Passport
+construction requires the matching certification.
+
+Transient train, authority, and exact-SHA selections additionally produce a
+provider-readback-bound runtime authorization receipt. A resumed failed tail
+uses a fresh attempt and records the original build runtime, the resume runtime,
+the exact sealed Stage Capsules reused per platform, and the platforms rebuilt
+in the final Release Passport. See
+[`v4-runtime-ref-resume-authority.md`](v4-runtime-ref-resume-authority.md).
+
+See the normative
+[`v4 floating consumer policy`](../architecture/v4-floating-consumer-policy.md)
+and its machine declaration for the exact acceptance boundary. This policy does
+not change v3 behavior.
+
 ## Advanced Workflow
 
 Consumers that need direct workflow-shell or runtime control call the advanced
@@ -699,6 +729,17 @@ For a declared macOS `archive`, the authority safely extracts the sealed
 container, signs and verifies every Mach-O payload, signs Mach-O payloads inside
 embedded Python wheels, rebuilds each affected wheel's PEP 427 `RECORD`, and
 recreates the original zip or tar.gz before returning the exact final bytes.
+Archives whose executable hosts a JIT runtime can additionally request the
+Buildchain-owned `entitlements_profile = "jit-executable-v1"` and exact paths,
+for example `entitlements_paths = ["product/runtime/python/bin/python3"]`.
+Paths are relative to the extracted archive root. The authority
+then attaches only `com.apple.security.cs.allow-jit` to the exact executable
+Mach-O files sealed in `entitlements_paths`, leaves every other executable and
+library without exception entitlements, and records the profile, paths, and
+entitled executable count in provider evidence. Consumer-provided entitlement
+files and wildcard target paths are unsupported. The profile is valid only for
+Apple `archive` requests and fails closed on an unsafe, missing,
+non-executable, duplicate, or unsealed target path.
 Windows `pe` and `binary` artifacts
 resolve to timestamped native `windows-authenticode`; Windows PE never falls
 back to a detached signature. Linux and other non-native binary files,

package/docs/runtime-train-validation.md

@@ -176,3 +176,13 @@ actions, configuration parsing, and lifecycle behavior. It cannot validate
 changes that require the outer reusable workflow YAML itself to change, such as
 new jobs, permissions, workflow outputs, or matrix topology. Those changes need
 a canary workflow path or a temporary explicit workflow ref.
+
+## v4 persisted-selector boundary
+
+For v4 consumers, never commit a train or exact SHA in a `uses` node. Keep the
+caller on `@v4` or `@v4-alpha`, retain both stable and alpha contract locks, and
+pass a temporary train/SHA only through the trusted `workflow_dispatch`
+`buildchain-ref` input. Consumer admission binds the selected lock to the exact
+workflow-shell commit while recording the separately resolved runtime SHA.
+Therefore a train can exercise candidate runtime code without weakening the
+durable floating-selector policy or masquerading as a channel promotion.

package/docs/v4-adopter-delivery.md

@@ -0,0 +1,133 @@
+---
+status: preview
+period: 2026-08-16
+theme: buildchain-v4-adopter-delivery
+doc_type: product-manual
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-16
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-16
+  visible_context: Exact protected v3 adopter-delivery cut, v4 pure contract core, published npm archive bytes, and public consumer policy.
+  invisible_context_boundary: No credentials, provider mutations, signing operations, publication operations, or release authority were used.
+---
+
+# V4 Public Adopter Delivery
+
+Buildchain v4 carries the v3 adopter-delivery capability through a public,
+protocol-neutral boundary. Consumers select an exact protocol driver and
+artifact profile, retain the rooted gate result, and independently recompute
+that readback. Buildchain does not interpret a protocol owned by another
+project and a passing result never grants runtime, provider, signing,
+publication, or release authority.
+
+The parity source is the read-only protected cut
+`dev/v3/v3.0@6b96bdad8d9f8ccf9275f27d9370a226a9c78465`. Work began from the
+minimal v4 absorption base
+`dev/v4/v4.0@e5611377efc03178f8687d99968cfdfa3ce2825b` and absorbed the
+verified protected-base advances through
+`dev/v4/v4.0@e0342713c7447960c13bd73377282b2e93f4853d` before delivery. These
+identities, the v3 vector-suite root, and the KFD package cut are committed in
+[`v4-adopter-delivery-parity.json`](../architecture/v4-adopter-delivery-parity.json)
+and exposed by the public Node API.
+
+## Public contract
+
+The JSON input schema is
+[`v4-adopter-delivery-v1.schema.json`](../contracts/v4-adopter-delivery-v1.schema.json).
+An input names both selectors and the exact request identities. A selector
+whose implementation identity differs from the request fails closed. The
+public selectors are `json-assertion`, `kfd-category`, and `legacy-kfd`, with
+`git-commit` and `package` artifact profiles.
+
+Applications can also import the lower-level driver interface from
+`@kungfu-tech/buildchain/adopter-delivery-gate` and define an isolated driver.
+The v4 convenience runtime, exact source declaration, readback verification,
+N-1 lineage check, and published archive loader are exported from
+`@kungfu-tech/buildchain/v4-adopter-delivery`.
+
+## CLI
+
+All four operations are offline after the declared archive bytes exist:
+
+```sh
+buildchain adopter-delivery run \
+  --input contracts/fixtures/v4-adopter-delivery-v1/gate-positive.json \
+  --output .buildchain/adopter-delivery/readback.json
+
+buildchain adopter-delivery verify \
+  --input contracts/fixtures/v4-adopter-delivery-v1/gate-positive.json \
+  --readback .buildchain/adopter-delivery/readback.json
+
+buildchain adopter-delivery bootstrap \
+  --input contracts/fixtures/v4-adopter-delivery-v1/bootstrap-positive.json
+
+buildchain adopter-delivery archive \
+  --input contracts/fixtures/v4-adopter-delivery-v1/archive-template.json
+```
+
+`verify` requires the complete rooted readback and recomputes it. Missing or
+substituted readback, unknown selector, unknown driver, protocol-version
+mismatch, archive-byte or package-identity mismatch, and altered bootstrap
+lineage all fail closed.
+
+## N-1 and published archives
+
+N-1 bootstrap is distinct from the candidate. The lineage wrapper requires
+the exact v3 authority commit, exact v4 absorption base, and exact public
+Buildchain archive root. The retained v3 bootstrap also requires protected and
+published N-1 authority, rejects self-authorization, binds the candidate gate
+artifact, and requires merged Warrant-shaped evidence. Protocol, profile, or
+gate changes require independently reviewed transition evidence.
+
+Published authority loading verifies compressed bytes before extraction,
+rejects unsafe paths and links, verifies extracted package identity, verifies
+KFD's semantic package root, and imports only declared public delivery modules.
+The caller must supply an independently retained authority readback root. The
+fixture binds `@kungfu-tech/buildchain@3.0.9-alpha.16` and
+`@kungfu-tech/kfd@1.0.0-alpha.65`; a package version is not treated as proof of
+the Git source cut.
+
+## Config and reusable workflow
+
+Consumer configuration is closed and repository-relative:
+
+```toml
+[adopter_delivery]
+contract = "kungfu-buildchain-v4-adopter-delivery/v1"
+input_path = "contracts/adopter-delivery/input.json"
+readback_path = ".buildchain/adopter-delivery/readback.json"
+bootstrap_path = "contracts/adopter-delivery/bootstrap.json"
+archive_path = "contracts/adopter-delivery/archives.json"
+result_path = ".buildchain/adopter-delivery/result.json"
+driver_selector = "kfd-category"
+artifact_profile_selector = "package"
+```
+
+The public reusable workflow is
+`kungfu-systems/buildchain/.github/workflows/v4-adopter-delivery.yml@v4` for
+stable use and `@v4-alpha` during prerelease evaluation. It resolves the exact
+called-workflow SHA, enforces floating selector plus dual-lock consumer
+admission, and runs the same CLI on Linux, macOS, and Windows. Buildchain
+dogfoods it through the thin
+[`v4-adopter-delivery-dogfood.yml`](../.github/workflows/v4-adopter-delivery-dogfood.yml)
+caller, which contains no steps or local orchestration and persists only the
+floating `@v4-alpha` selector.
+
+The reusable workflow downloads exact public N-1 npm archives and uses the
+committed byte roots, semantic identity, and authority readback root. It has
+only `contents: read`; no provider credential or production writer is accepted
+or synthesized.
+
+## Offline vectors
+
+[`offline-vectors.json`](../contracts/fixtures/v4-adopter-delivery-v1/offline-vectors.json)
+indexes positive driver, N-1, and archive cases plus negative selector, driver,
+archive identity, bootstrap lineage, protocol version, and tampered readback
+cases. Tests synthesize archives locally so extraction and identity failures do
+not depend on the network.

package/docs/v4-compatibility-facts.md

@@ -0,0 +1,91 @@
+---
+status: active
+period: ongoing
+theme: buildchain-v4-compatibility-facts
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-08-16
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-16
+  invisible_context: not asserted
+---
+
+# Buildchain v4 compatibility Facts
+
+Buildchain v4 authorizes contract compatibility with immutable, directional
+Facts. `compatibleBreakingDigests` and the v1 proof objects remain public for
+older consumers, but they are deterministic projections. Neither can authorize
+a transition without the current Fact registry, its exact Project Cut, and a
+verified path receipt.
+
+## Authority chain
+
+The package source is
+`packages/core/buildchain-compatibility-facts.json`, retained from v3 exact head
+`6b96bdad8d9f8ccf9275f27d9370a226a9c78465`. Each declaration becomes a KFR2
+predicate and relation, then enters an append-only temporal bundle. The
+registry identity binds all Fact, proof, Cut, supersession, revocation, and
+bundle roots.
+
+V4 projects a legacy digest only when a verified Fact targets the exact current
+surface kind, ID, and breaking digest. The old proof's v2/v3 `majorLines` field
+is historical projection metadata; it does not narrow or enlarge the
+digest-and-Cut-bound Fact. A target digest that has changed since v3 receives no
+projection.
+
+## Decision semantics
+
+- Direction is always source to target. Reverse use rejects.
+- The only operation is `accept-contract-lock`.
+- Evaluation selects one direct Fact. It never searches for a path or infers
+  symmetry or transitivity.
+- Composition requires an ordered caller-supplied path and positive bounded
+  depth.
+- Supersession and revocation append lifecycle records. Old Cuts replay old
+  truth; later Cuts deterministically reject superseded or revoked relations.
+- A revocation is the safety-equivalent expiry boundary: compatibility has no
+  wall-clock-only truth outside a rooted Cut.
+- Missing, ambiguous, not-yet-valid, revoked, superseded, wrong-direction,
+  wrong-Cut, disconnected, cyclic, inactive, or corrupted inputs produce a
+  rooted rejected receipt.
+
+Rust and TypeScript implement the same KFR2 closed-field encoding and emit
+byte-identical JSON for the shared fixture in
+`contracts/fixtures/v4-compatibility-facts-v1/shared.json`.
+
+## CLI and Node API
+
+Project and verify the built-in registry:
+
+```sh
+npx @kungfu-tech/buildchain facts compatibility project --json
+npx @kungfu-tech/buildchain facts compatibility verify --json
+```
+
+Create a direct query template for one current Fact, then verify it:
+
+```sh
+npx @kungfu-tech/buildchain facts compatibility query-template \
+  --fact-root sha256:... --json
+npx @kungfu-tech/buildchain facts compatibility query \
+  --query query.json --registry registry.json --json
+```
+
+The `@kungfu-tech/buildchain/compatibility-fact-authority` export provides the
+same constructors, verifiers, resolver, and Release Passport evidence helper.
+Compatibility evidence explicitly sets `grantsReleaseAuthority: false`; it can
+be attached through the existing release-evidence route but cannot publish,
+merge, sign, or release anything.
+
+## Updating the registry
+
+Append a new source Fact or lifecycle record. Never rewrite an existing Fact,
+directly edit a surface digest allowlist, or convert a caller claim into
+authority. Regenerate references and site facts, then run the shared parity
+fixture and the complete repository check.

package/docs/v4-publication-rehearsal.md

@@ -0,0 +1,130 @@
+---
+status: preview
+period: 2026-08-16
+theme: buildchain-v4-publication-rehearsal
+doc_type: product-manual
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-16
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-16
+  visible_context: Exact v3 rehearsal runtime, v4 release-tail core, Stage Capsule contracts, public workflow and offline vectors.
+  invisible_context_boundary: No credentials, private provider state, signed URLs or production publication receipts were read.
+---
+
+# V4 Publication Rehearsal Capsule
+
+The v4 Publication Rehearsal Capsule is the content-addressed input for
+testing publication behavior without acquiring production publication
+authority. It is deliberately not a Stage Capsule. A Stage Capsule retains a
+pure platform-stage build checkpoint; a Publication Rehearsal Capsule binds a
+release candidate and asks the production release-tail planner and executor to
+simulate, replay, or observe provider-facing publication behavior.
+
+The rooted parity matrix is
+[`architecture/v4-publication-rehearsal-parity.json`](../architecture/v4-publication-rehearsal-parity.json),
+and the public schema is
+[`v4-publication-rehearsal-capsule-v1.schema.json`](../contracts/v4-publication-rehearsal-capsule-v1.schema.json).
+
+## Bound identity
+
+One capsule commits to all of these values:
+
+- its own canonical capsule root;
+- the exact source repository, Git revision, and source root;
+- the sorted candidate file inventory and candidate root;
+- the exact candidate manifest and Buildchain config paths and roots;
+- the canonical data-only provider bindings and `providerBindingsRoot`;
+- the effect-disabled provider policy and its exact capability/adapter set;
+- expected provider observations and their root;
+- the initial transaction produced by the production release-tail planner;
+- `buildchain.release-tail/v1` as the shared core version.
+
+Changing any one of those values, or changing a candidate byte, fails closed.
+Candidate paths must remain regular non-symlink files below an explicit
+absolute root. Every artifact, provider document, and released-evidence input
+named by the bindings must also appear in the rooted file inventory. The
+evidence output may be absent, but its path and every existing ancestor must
+remain below that root without symlinks.
+
+## Modes and authority
+
+`simulate` uses in-memory adapters and makes no provider call. `replay` feeds a
+recorded response sequence through the same production transaction executor.
+`provider` requires a capsule-bound
+`buildchain-v4-publication-rehearsal-authority/v1` receipt plus the declared
+provider adapters. The authority binds `providerBindingsRoot` directly as well
+as through `capsuleRoot`, so request bytes cannot be replaced while retaining
+authority. It is rehearsal-only: its
+`productionAuthority` field is always `false`, and it binds a separately
+supplied live `authorizationRoot` rather than minting authority from the
+capsule alone.
+
+Every provider readback and apply request is retained in the rooted transcript.
+The resulting evidence always contains `productionAuthority: false` and
+`releasePassport: null`. It therefore cannot publish by itself, authorize a
+production release tail, or stand in for a Release Passport, protected
+readback, or Delivery Warrant.
+
+## CLI and Node API
+
+Local simulation and replay use the public `release-tail` command:
+
+```sh
+buildchain release-tail rehearse \
+  --capsule "$PWD/contracts/fixtures/v4-publication-rehearsal-v1/capsule.json" \
+  --candidate-root "$PWD/contracts/fixtures/v4-publication-rehearsal-v1/candidate" \
+  --mode simulate \
+  --state "$PWD/.buildchain/publication-rehearsal/state.json" \
+  --evidence "$PWD/.buildchain/publication-rehearsal/evidence.json"
+```
+
+Applications import `@kungfu-tech/buildchain/v4-publication-rehearsal` to
+create and verify capsules, create provider-rehearsal authority, and execute
+all three modes. The API delegates planning, transaction initialization, and
+execution to the same `release-tail-provider-plane` functions used by the
+production Action.
+
+## Config and public workflow
+
+The consumer config is closed and effect-disabled:
+
+```toml
+[publication_rehearsal]
+contract = "buildchain-v4-publication-rehearsal-capsule/v1"
+capsule_path = "contracts/fixtures/v4-publication-rehearsal-v1/capsule.json"
+candidate_root = "contracts/fixtures/v4-publication-rehearsal-v1/candidate"
+state_path = ".buildchain/publication-rehearsal/state.json"
+evidence_path = ".buildchain/publication-rehearsal/evidence.json"
+effect_default = "disabled"
+```
+
+The public reusable
+[`release-tail.yml`](../.github/workflows/release-tail.yml) accepts the same
+capsule, candidate root, mode, state and evidence paths. Before publication,
+Buildchain dogfoods that public surface through a thin same-commit local reusable
+call with the exact PR-head or dispatch SHA as its runtime. The reusable is
+permission-neutral and the self-dogfood caller stays `contents: read`, passes
+`execute: false`, and therefore cannot inherit or synthesize production write
+authority. Effectful production callers must explicitly declare their own
+provider permission. Durable external consumers remain on the floating
+`@v4-alpha` contract. Provider mode additionally requires the exact authority
+path. Provider bindings come from the capsule; an optional external bindings
+input is accepted only when its canonical exact root and payload equal the
+capsule binding. Ordinary calls default to `simulate`.
+
+## Offline portability vectors
+
+[`offline-vectors.json`](../contracts/fixtures/v4-publication-rehearsal-v1/offline-vectors.json)
+records Linux, macOS and Windows projections. Their capsule, transaction,
+state, and evidence roots are byte-identical. Regenerate or verify them with:
+
+```sh
+node scripts/v4-publication-rehearsal-fixture.mjs
+node scripts/v4-publication-rehearsal-fixture.mjs --check
+```

package/docs/v4-runtime-ref-resume-authority.md

@@ -0,0 +1,69 @@
+---
+status: draft
+period: ongoing
+theme: buildchain-v4-runtime-ref-resume-authority
+doc_type: contract-guide
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-08-15
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-14
+  invisible_context: not asserted
+---
+
+# Buildchain v4 transient runtime and resume authority
+
+Buildchain v4 consumers keep `v4` or `v4-alpha` in tracked workflow source.
+A train, authority ref, or exact SHA is transient run data, never a new
+committed default. The public promotion router accepts that escape only from a
+trusted `workflow_dispatch` actor with write, maintain, or admin permission.
+Before heavy promotion work, it binds an exact source tree, operator reason,
+dual consumer contract-lock roots, the floating-consumer policy receipt, a
+clean persistence scan, and GitHub provider readbacks proving that the selected
+runtime is reachable from an approved v4 ref.
+
+The persistence scan covers tracked workflow, composite-action, JSON, TOML, and
+YAML surfaces. Exact SHA, train/authority defaults, and runtime selectors hidden
+through repository variables, secrets, or environment indirection reject the
+run. OIDC, IAM, and other external authority references are inventoried as
+metadata only; credential values are never read or written to evidence.
+
+## Resume after a floating ref moves
+
+A late platform failure is resumed as a new governed attempt. It is not a
+GitHub failed-job rerun. The lineage keeps runtime A (the runtime that built and
+sealed each reusable Stage Capsule) separate from runtime B (the authorized
+runtime executing the new attempt). A Capsule is reusable only when its source
+SHA, source tree, platform, policy root, build runtime, identity root, Capsule
+root, and artifact digest still match. Valid unaffected platforms are restored;
+only missing platforms rebuild. Stale, ambiguous, unsealed, cross-source, or
+cross-policy evidence fails closed.
+
+This deliberately does not weaken the existing Stage Capsule resume planner's
+`runtime-changed` invalidation. That planner decides whether a stage may be
+reused under one expected build identity. This contract instead proves that an
+already sealed output built under runtime A remains the exact product input
+while a distinct orchestration attempt runs under runtime B. Runtime B never
+rewrites the Capsule's build identity.
+
+Final Release Passport evidence embeds the complete authorization receipt and
+the A+B resume lineage under `v4RuntimeResume`. The section binds the new
+attempt, floating-ref movement, reused and rebuilt platform partition,
+consumer-policy receipt, resume plan, and final public readback roots. Tampering
+with either document or crossing authorization/lineage roots rejects Passport
+construction and verification.
+
+Normative files:
+
+- `architecture/v4-runtime-ref-resume-authority.json`
+- `contracts/v4-runtime-ref-resume-authority-v1.schema.json`
+- `packages/core/v4-runtime-ref-resume-authority.js`
+- `scripts/authorize-promotion-runtime-override.cjs`
+
+This contract changes no v3 behavior, grants no provider mutation authority,
+and stores no credential material.

package/docs/v4-tail-reseal.md

@@ -0,0 +1,73 @@
+# V4 retained-candidate tail reseal
+
+Buildchain v4 can recover one narrowly defined late Alpha failure without
+rebuilding a qualified four-platform candidate. The recovery is not a cache hit
+and does not give Stage Capsule any provider authority. It is a fresh governed
+run that proves all retained bytes first, then executes only the explicitly
+fenced macOS signing-finalization tail.
+
+The authoritative request schema is
+[`contracts/v4-tail-reseal-v1.schema.json`](../contracts/v4-tail-reseal-v1.schema.json).
+It binds the failed run and source tree, four payload and manifest archive
+digests, four content roots, Stage Capsule roots and reuse decisions, Warrant
+lineage, retention, credential authority, signing delegation/result, release
+tail transaction, idempotency key, and independent provider readbacks. Any
+mismatch rejects reuse and requires a normal candidate build.
+
+## Authority boundary
+
+- `install`, `build`, `verify`, `package`, and the ordinary platform matrix are
+  skipped only when all 16 per-platform Stage Capsule decisions prove exact
+  reuse. Capsule reuse has no external effects.
+- Only `macos-arm64:signing-finalization` may change payload bytes. The public
+  workflow verifies the retained macOS bytes before the effect and verifies the
+  resealed bytes plus signing and release-tail readbacks afterward.
+- The signing token exists only in the macOS credential-island step. It is not
+  stored in a Capsule, request, artifact, log, Passport, or receipt.
+- A successful run emits the existing
+  `kungfu-buildchain-release-candidate-passport` contract. Tail reseal does not
+  create a second candidate or release artifact class.
+- Durable callers use `@v4-alpha` during Alpha evaluation or `@v4` after stable
+  promotion. Exact SHAs are runtime evidence from `job.workflow_sha`, never a
+  persisted selector.
+
+## CLI and Node API
+
+Plan locally from the deterministic data contract:
+
+```sh
+buildchain tail-reseal plan \
+  --request .buildchain/tail-reseal/request.json \
+  --output .buildchain/tail-reseal/plan.json
+```
+
+`tail-reseal admit` performs the provider readback of the exact failed run,
+jobs, retained GitHub artifact archives, and signing-authority result. Each
+fresh platform runner then uses `verify-platform --mode retained`. Only the
+macOS runner may follow with `--mode resealed --provider-readback-root ...`.
+After the ordinary Release Candidate Passport is generated, `tail-reseal seal`
+binds all four readbacks and the protected Warrant readback into the final
+receipt.
+
+The Node exports are `@kungfu-tech/buildchain/v4-tail-reseal` for request and
+plan logic and `@kungfu-tech/buildchain/v4-tail-reseal-receipt` for terminal
+receipt creation and verification.
+
+## Reusable workflow
+
+Consumers invoke
+`kungfu-systems/buildchain/.github/workflows/v4-tail-reseal.yml@v4-alpha` from a
+trusted, same-repository workflow. The caller supplies the rooted request, the
+original candidate consumer-policy receipt, a reviewed macOS finalization
+command, and the explicitly named signing secret. The command must write:
+
+- `.buildchain/tail-reseal/signing-provider-readback.json`
+- `.buildchain/tail-reseal/release-tail-provider-readback.json`
+
+Their byte digests must equal the roots fixed in the request. The workflow
+downloads the signing result by exact authority repository, run, artifact name,
+and archive digest; no credential or provider effect is replayed from a Stage
+Capsule.
+
+The v3-to-v4 invariant mapping is recorded in
+[`architecture/v4-tail-reseal-parity.json`](../architecture/v4-tail-reseal-parity.json).

package/docs/versioning.md

@@ -79,8 +79,10 @@ repository changes are patch".
 
 | Date       | Action       | Line    | Faces                                                                                                                                                                        | Class    | Rationale                                                                                                                                                                                                                                                                                                                              | PR    |
 | ---------- | ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
-| 2026-08-11 | extend-minor | `v4.0`  | release-blocker-repair-contract, release-blocker-priority-claim, release-train-node-export, dev-delivery-warrant-node-export                                                 | additive | Forward-port rooted successor candidate generations, exact semantic patch identity across cut and Dev landings, publication blocking through conflict or mismatch, and the narrow non-preemptive Warrant blocker lane already protected and self-dogfood-proven on v3.                                                               |       |
-| 2026-08-10 | extend-minor | `v4.0`  | release-cut-contract, release-train-state-machine, release-train-node-export                                                                                                | additive | Forward-port the provider-neutral rooted Release Cut and idempotent Release Train state contract already proven on v3; candidate, tree, Alpha base, runtime, generation, and authority stay frozen while later Dev movement remains an observation rather than implicit supersession.                                                   |       |
+| 2026-08-16 | extend-minor | `v4.0`  | next-development-transition, next-development-controller, next-development-projection, next-development-cli                                                                  | additive | Forward-port the rooted completed-Alpha successor contract, semver/auto and anchored/manual modes, CAS recovery, protected Dev reconciliation, reservation readback, public templates, and consumer-equivalent lifecycle proof from the exact v3 evidence into v4.                                                                     |       |
+| 2026-08-14 | extend-minor | `v4.0`  | source-qualification-proof-v2, source-proof-reuse-decision, reusable-check-workflow                                                                                          | additive | Forward-port opt-in exact accepted source-proof reuse for merge groups, binding source, base, patch, runtime, plan, policy, closure, dependency, required-context, producer receipt, and caller run. Any missing or changed predicate fails closed to the existing full source lifecycle, which remains the default.                   |       |
+| 2026-08-11 | extend-minor | `v4.0`  | release-blocker-repair-contract, release-blocker-priority-claim, release-train-node-export, dev-delivery-warrant-node-export                                                 | additive | Forward-port rooted successor candidate generations, exact semantic patch identity across cut and Dev landings, publication blocking through conflict or mismatch, and the narrow non-preemptive Warrant blocker lane already protected and self-dogfood-proven on v3.                                                                 |       |
+| 2026-08-10 | extend-minor | `v4.0`  | release-cut-contract, release-train-state-machine, release-train-node-export                                                                                                 | additive | Forward-port the provider-neutral rooted Release Cut and idempotent Release Train state contract already proven on v3; candidate, tree, Alpha base, runtime, generation, and authority stay frozen while later Dev movement remains an observation rather than implicit supersession.                                                  |       |
 | 2026-08-08 | extend-minor | `v4.0`  | dev-delivery-warrant-read-candidate, rust-state-projection, dev-delivery-cli                                                                                                 | additive | Add an opt-in, qualification-bound read projection behind `observe --read-mode v4`; v3 remains the sole writer and default reader, mutation commands ignore the switch, failures stop, and rollback is the explicit caller change back to v3.                                                                                          |       |
 | 2026-08-05 | extend-minor | `v3.0`  | auditable-demo-scenario, auditable-demo-capture, auditable-demo-adapter                                                                                                      | additive | Add an opt-in deterministic readable-playback declaration that preserves captured terminal payloads and order while normalizing only presentation timing; omitted playback continues to use observed PTY timestamps, and existing composition modes remain unchanged.                                                                  |       |
 | 2026-08-04 | extend-minor | `v3.0`  | dev-delivery-warrant-queue, source-qualification-proof, integration-delivery-proof, dev-delivery-cli, reusable-dev-delivery-workflows                                        | additive | Add durable fair and fenced protected-dev scheduling plus split source/integration proof contracts. Existing PR admission remains available through explicit `off` and `shadow` rollout modes; no existing command, export, or release flow is removed.                                                                                |       |