@kungfu-tech/buildchain 4.0.2-alpha.5 → 4.0.2-alpha.50

package/docs/oci-publication.md

@@ -0,0 +1,160 @@
+---
+status: draft
+period: ongoing
+theme: oci-publication
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-07
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-06
+  invisible_context_boundary: No credentials or production registry state inspected.
+---
+
+# OCI image family publication
+
+Buildchain v4 can publish a sealed family of container images to GHCR through
+`publish-artifact-kind: oci` on the public release candidate promotion workflow.
+The candidate build produces the image bytes and smoke evidence. The built-in
+provider verifies and uploads those bytes, reads back every public image digest,
+then allows release references and GitHub Release evidence to converge.
+
+## Candidate contract
+
+Publish exactly one `oci-family.json` alongside OCI layouts and smoke JSON files
+in the Build artifact. Import `sealOciPublicationBundle` from
+`@kungfu-tech/buildchain/oci-publication` to validate and seal the family. Its
+`body` contains:
+
+- `schema: kungfu-buildchain-oci-family/v1`, consumer `repository`, exact Git
+  `sourceSha`, and candidate package `version`.
+- `expectedImages`: the complete set of image names.
+- `images`: one entry for each expected image, with `name`, `repository`,
+  `digest`, `layout`, `platform`, `action`, `content`, and `smoke`.
+
+Destinations must be `ghcr.io/<consumer-owner>/<consumer-repo>/<image-name>`.
+`layout` is a relative OCI layout directory. Each image is a single Linux
+amd64 or arm64 manifest; OCI and Docker schema 2 manifests are supported.
+Layouts may share blobs and an index; each shared index entry identifies its
+image with the `org.opencontainers.image.ref.name` annotation.
+
+`content` records the image's original `sourceSha` and `version`, matching its
+OCI revision/version labels. For `action: built`, both equal the candidate.
+For `action: reused`, they retain the original content provenance while the
+family binds the current candidate. `smoke` records a relative `path` and SHA256
+`sha256`; its JSON must identify the image and record `passed: true`. The
+consumer owns the actual smoke command and must fail the build if it fails.
+
+Sealing verifies all config/layer sizes and digests, platform and provenance
+labels, smoke bytes, and family completeness. Absolute paths, traversal, and
+symlinks are rejected. The resolver derives the exact required image artifacts
+from this sealed family, including when recovering a previous candidate run.
+
+## Authority and publication
+
+The thin caller grants `packages: write` in addition to its existing promotion
+permissions. Reusable promotion wrappers inherit that caller envelope; npm
+consumers do not need to request package registry authority. The provider uses
+the action token only for GHCR, scoped to each declared consumer image.
+No consumer publish command is executed.
+
+The rooted product plan declares version-state materialization, OCI family
+publication, then release reference convergence. Each image uses the exact
+`v<version>` tag. A different existing digest aborts publication; a matching
+existing image is reused. After a partial failure, recovery validates the same
+candidate bytes and publishes only missing images. GHCR does not provide tag
+compare-and-swap: callers must serialize publishers for a version, and external
+writers must not race the publication workflow.
+
+Success requires anonymous readback of every declared image at its expected
+digest. Existing GHCR packages must permit the repository token to write and
+anonymous clients to pull. The provider does not change package visibility or
+access policy. It attaches `oci-publication-readback.json` to the GitHub Release;
+the caller should also include the family and smoke JSON files in
+`github-release-payload-patterns`.
+
+See [Runtime Train Validation](runtime-train-validation.md) for testing an
+unreleased runtime without persisting a train or exact SHA in the workflow.
+
+## Multi-platform images and Compose applications
+
+Use `schema: kungfu-buildchain-oci-family/v2` when the family includes an OCI
+index or a Compose application. Existing v1 families keep their published
+single-platform contract.
+
+An index entry declares `platform: multi-platform` and the complete `platforms`
+array, for example `["linux/amd64", "linux/arm64"]`. Every runnable child must
+have matching platform and content labels. Descriptor sizes, digests and media
+types are verified recursively; nested manifests are uploaded before their
+parent index. BuildKit attestation manifests must identify a runnable child and
+contain matching in-toto subjects. Missing platforms, duplicate platforms,
+foreign URLs and broken blob references fail sealing. Embedded descriptor `data`
+is accepted only as canonical Base64 for at most 1 MiB, with the declared size
+and digest matching the required local blob byte for byte. Malformed or
+inconsistent embedded content fails sealing; manifests are never rewritten.
+This follows the [OCI embedded-content contract](https://github.com/opencontainers/image-spec/blob/main/descriptor.md#embedded-content).
+
+A Compose entry declares `kind: compose`, `platform: compose`, and `targetImage`
+pointing to an image in the same family. Its unique family name may differ from
+that image, but its destination repository must match it. The immutable tag is
+`compose-v<version>`; image entries retain `v<version>`.
+
+The bounded Compose representation is an OCI 1.1 image manifest with
+`artifactType: application/vnd.docker.compose.project`, an empty JSON config
+and one `application/vnd.docker.compose.file+yaml` layer. That layer contains
+JSON, a YAML subset, so structural verification needs no executable YAML loader.
+Every service image is pinned to a digest and at least one uses the exact
+family image. Environment interpolation inside other fields can remain intact.
+These media types follow the [Docker Compose publisher](https://github.com/docker/compose/blob/v5.1.2/internal/oci/push.go).
+
+Candidate smoke evidence describes its actual pre-publication checks. It must
+not claim that an unpublished public Compose reference was installed. Public
+installation qualification occurs after immutable publication and before a
+preview alias moves.
+
+## Evidence-gated Compose preview
+
+An optional Compose `preview` declaration contains exactly the supported alias
+`compose-preview`, the previously accepted `previousDigest` (or `none`), and
+`qualificationWorkflow`, a repository workflow path. The immutable family seals
+this policy before any publication effect.
+
+After v4 publication is complete, dispatch that qualification workflow on the
+exact published alpha tag. It must pull the immutable public image and Compose,
+run fresh installation, restart, account-isolation, runtime-hardening, upgrade
+and rollback checks, and qualify both Linux architectures. The workflow has no
+registry write authority. Upload one artifact named
+`oci-compose-qualification-<run-id>-<run-attempt>` containing `qualification.json`
+and its hash-bound JSON evidence files.
+
+The receipt uses `schema: kungfu-buildchain-compose-qualification/v1` and binds
+`repository`, `tag`, published `sourceSha`, sealed `familyRoot`, `runId`,
+`runAttempt`, exact `image` and `application` repository/digest references,
+`previousDigest`, and `passed: true`. Its `checks` object requires all of
+`freshInstall`, `restartPersistence`, `upgradePersistence`, `rollbackPersistence`,
+`accountIsolation`, and `hardenedRuntime` to be true. Its `platforms` object
+requires `linux/amd64` and `linux/arm64` entries with `passed: true`; `evidence`
+contains nonempty `{path, sha256}` bindings to the actual JSON results.
+
+A thin consumer workflow listens to completion of that qualification workflow
+and calls `public-release-oci-compose-preview.yml@v4-alpha`, passing
+`BUILDCHAIN_PROMOTION_TOKEN`. The reusable workflow resolves its own exact
+runtime, enforces the dual floating-channel locks, verifies the public v4
+settlement, family and provider readback roots, and checks the live GitHub run's
+repository, source, workflow, event, attempt and successful conclusion. It never
+executes the consumer's artifact files. Only then does it copy the exact Compose
+manifest bytes to the declared alias and verify the public digest.
+
+The expected-old digest is checked immediately before mutation. An already
+matching target is an idempotent success; any other drift blocks the move.
+Publishers for this alias share repository-level concurrency. GHCR has no atomic
+tag compare-and-swap, so external writers must also avoid racing this workflow.
+The immutable release retains the appended
+`buildchain-compose-preview-<run-id>-<run-attempt>.json` receipt. A failed
+qualification leaves the existing preview intact, while the immutable alpha
+and its original publication evidence remain available for diagnosis.

package/docs/publication-authority.md

@@ -227,7 +227,7 @@ buildchain audit publication-control-plane \
   --source-sha <exact-merged-branch-sha> \
   --workflow .github/workflows/release-candidate-promote.yml \
   --workflow-ref <exact-buildchain-sha> \
-  --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \
+  --publisher-workflow .github/workflows/self-release-promote.yml \
   --job promote \
   --environment none
 
@@ -236,7 +236,7 @@ buildchain audit publication-control-plane \
   --repository kungfu-systems/buildchain \
   --branch dev/v3/v3.0 \
   --workflow .github/workflows/release-candidate-promote.yml \
-  --publisher-workflow .github/workflows/buildchain-ref-promotion.yml \
+  --publisher-workflow .github/workflows/self-release-promote.yml \
   --job promote \
   --environment none \
   --npm-trust-json sanitized-npm-trust.json

package/docs/publish-transaction.md

@@ -8,11 +8,11 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-08-06
+last_reviewed: 2026-09-06
 ai_provenance:
-  model_family: GPT-5
+  model_family: GPT-6
   product: Codex
-  generated_at: 2026-07-31
+  generated_at: 2026-09-06
   invisible_context: not asserted
 ---
 
@@ -113,6 +113,39 @@ a missing or different id fails before provider mutation. An absent transaction
 is created only when no expected existing identity was requested. See
 [Release Candidate: Resume from an existing candidate run](release-candidate.md#resume-from-an-existing-candidate-run).
 
+## V4 sealed npm package sets
+
+The v4 alpha provider accepts a sealed set of 2–64 npm tarballs with one main
+package and same-version platform packages. The candidate resolver records each
+package's name, version, role, relative path, size, SHA-256, and npm integrity in
+the candidate root. QUALIFY passes the set into the Rust/WASM publication
+planner, which binds every package to its own operation and orders platform
+packages by name before the main package. A single package retains the existing
+operation identity.
+
+Use `publish-package-main` to name the main package. The optional
+`publish-package-set-order: platforms-first-main-last` input states the same
+ordering. Omit legacy `publish-mode` and `publish-command` inputs: the v4 provider
+publishes the sealed tarballs through npm trusted publishing. It does not run a
+consumer publish command.
+
+Before any provider effect, APPLY checks the complete package inventory,
+tarball package identities, bytes, and integrity against the rooted intent.
+Each package receives independent registry readback and a Release Tail receipt.
+After an interrupted attempt, existing matching versions are observed without
+republishing; conflicting integrity stops the transaction. Release refs follow
+only after every package is confirmed.
+
+Anchored alpha versions such as `22.22.3-kf.5-alpha.4` remain unchanged. For
+`anchored/manual` repositories, successful publication leaves next development
+in `waiting-anchor`; it does not invent the next upstream anchor. Multi-package
+stable rematerialization is not supported by this provider and fails before
+publication. The existing singleton stable flow remains available.
+
+The contract is exercised by `v4-product-publication-topology.test.mjs`,
+`v4-product-provider-adapters.test.mjs`, and
+`v4-alpha-next-development-provider.test.mjs` under `tests/`.
+
 ## Lifecycle
 
 Repositories declare publish work in `.buildchain/buildchain.toml`:

package/docs/release-candidate.md

@@ -265,7 +265,7 @@ in the release passport.
 
 Standalone binary publication is a separate consumer capability. The promotion
 wrapper does not assume that an npm-only repository provides
-`.github/workflows/binary-distribution.yml`. Repositories that own that workflow
+`.github/workflows/self-build-binary-distribution.yml`. Repositories that own that workflow
 opt in with `standalone-binary-distribution: true`; Buildchain's self-promotion
 does so explicitly. Once enabled, a missing or invalid binary workflow remains a
 hard failure rather than being silently skipped.
@@ -303,7 +303,7 @@ short-lived admission JSON in repository-specific workflow code:
 ```yaml
       publication-auto-admission: true
       publication-auto-no-gate: true
-      publication-publisher-workflow-path: .github/workflows/buildchain-ref-promotion.yml
+      publication-publisher-workflow-path: .github/workflows/self-release-promote.yml
       publication-product: Example Product
       publication-target: npm:@example/product
       publication-package-name: "@example/product"
@@ -339,7 +339,7 @@ an npm package identity:
 ```yaml
       publication-auto-admission: true
       publication-auto-no-gate: true
-      publication-publisher-workflow-path: .github/workflows/buildchain-ref-promotion.yml
+      publication-publisher-workflow-path: .github/workflows/self-release-promote.yml
       publication-product: Example Binary
       publication-target: github-release:example/example-binary
       publication-package-name: ""

package/docs/release-flow.md

@@ -8,17 +8,17 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-07-31
+last_reviewed: 2026-09-05
 ai_provenance:
-  model_family: GPT-5
+  model_family: GPT-6
   product: Codex
-  generated_at: 2026-07-31
+  generated_at: 2026-09-05
   invisible_context: not asserted
 ---
 
 # Release Flow Diagrams
 
-This document describes the Buildchain v4 branch, tag, and version-state flow.
+This document describes v4 alpha publication and the legacy v3 release flow.
 See [Release governance](release-governance.md) for the design rationale.
 
 ## Architecture
@@ -142,7 +142,21 @@ published. Queue reconciliation runs after branch protection and before the
 default-branch switch, so a failed governance apply leaves the old active line
 in place and the idempotently created new refs can be retried.
 
-## Alpha Promotion
+## V4 Alpha Publication
+
+The protected `dev/v4/v4.0 -> alpha/v4/v4.0` channel PR admits the source.
+Publication creates the immutable `v4.0.Z-alpha.N` tag and advances the eligible
+floating alpha refs to that published source. Its completed receipt and original
+Release Passport remain the publication authority.
+
+A separate protected next-development PR prepares `4.0.Z-alpha.(N+1)` on
+`dev/v4/v4.0`. Preparing that version does not publish another exact tag or move
+the alpha refs. A review, queue, or transient API failure in that PR leaves
+publication complete and next-development incomplete; recovery resumes the
+missing tail. Binary distribution has its own evidence and completion state.
+See [What each verification proves](#what-each-verification-proves).
+
+## Legacy V3 Alpha Promotion
 
 ```mermaid
 sequenceDiagram
@@ -180,7 +194,7 @@ dev/vX/vX.Y
 
 all point at the generated alpha version-state commit.
 
-## Release Promotion
+## Legacy V3 Release Promotion
 
 ```mermaid
 sequenceDiagram
@@ -234,7 +248,7 @@ dev/vX/vX.Y
 
 point at the next alpha version-state commit.
 
-## State Machine
+## Legacy V3 State Machine
 
 ```mermaid
 stateDiagram-v2
@@ -249,28 +263,28 @@ stateDiagram-v2
 
 The same minor line can loop through this state machine many times.
 
-## Version Examples
+## Legacy V3 Version Examples
 
-Assume `v4.0.2-alpha.1` has been tested and a maintainer merges
-`alpha/v4/v4.0 -> release/v4/v4.0`.
+Assume `v3.0.2-alpha.1` has been tested and a maintainer merges
+`alpha/v3/v3.0 -> release/v3/v3.0`.
 
 Buildchain should produce:
 
 ```text
-v4.0.2                  exact production tag
-v4.0                    floating minor tag
-v4                      floating major tag when v4.0 is the selected major line
-release/v4/v4.0         production channel branch
+v3.0.2                  exact production tag
+v3.0                    floating minor tag
+v3                      floating major tag when v3.0 is the selected major line
+release/v3/v3.0         production channel branch
 ```
 
 It should also prepare:
 
 ```text
-v4.0.3-alpha.0          exact next alpha tag
-v4.0-alpha              floating alpha tag
-v4-alpha                floating major alpha tag when v4.0 is the highest published alpha minor
-alpha/v4/v4.0           alpha channel branch
-dev/v4/v4.0             development channel branch
+v3.0.3-alpha.0          exact next alpha tag
+v3.0-alpha              floating alpha tag
+v3-alpha                floating major alpha tag when v3.0 is the highest published alpha minor
+alpha/v3/v3.0           alpha channel branch
+dev/v3/v3.0             development channel branch
 ```
 
 This is expected behavior. A production release closes one patch and opens the
@@ -333,3 +347,37 @@ the current target ref contains or corresponds to the recorded
 `release_material_sha`. It must then tolerate exact tags, dev refs, or alpha
 refs that have already moved and continue filling any missing floating tags
 before writing the transaction state as `complete`.
+
+## What each verification proves
+
+| Evidence | Meaning and reuse boundary |
+| --- | --- |
+| Full source execution | `pnpm run check` runs source tests, Rust gates, policy checks and generated artifact checks. Each Node test file runs once; the focused `check:v4-contracts` command still includes its 22 contract test files. |
+| Merge queue proof | A successful full merge-group run seals its exact source SHA/tree, workflow, check definition, WASM runtime, toolchain versions, dependency locks, hosted image and platform. The proof expires after six hours and is verified against the completed GitHub run attempt and artifact archive digest. |
+| Push reuse | A Dev push may reuse that exact full execution. Its summary links the original run and proof; it does not claim to have rerun tests. Missing, failed, expired, ambiguous, tampered or unavailable evidence executes the full check. |
+| Version-state projection | Requires an authenticated full-source proof for the exact base and an ancestor-bound delta containing only declared version files and derived material. The base generator reconstructs every tracked byte, including derived digests. Any source, workflow, lock, configuration, file-mode or unexplained output change executes the full check. Projection results cannot issue a new full-source proof. |
+| Generated version-state check | `Version-state projection / <context>` describes generated material. It never uses a protected full-source check's name on v4. Required PR lineage, review and merge queue gates remain independent. |
+| Candidate qualification | Validates the sealed candidate, admitted runtime, source lock and publication authority. Source test reuse grants no provider mutation authority. |
+| Provider readback and settlement | Verifies actual tags, npm integrity, release assets and native receipt roots. Publication, next-development and binary distribution are reported separately. |
+
+The protected `check` context keeps its stable name while step names and summaries
+identify full execution, exact proof reuse, or generated projection. The two
+consumer-policy checks execute inside the root check, without duplicate Verify
+pre-steps. The root check uses the Rust-only contract command before its complete
+Node suite, removing 22 repeated test-file executions without removing tests.
+
+The public v4 consumer remains a thin floating-channel caller with both locks.
+Linux, macOS and Windows each execute the declared lifecycle, clean-process
+restore and runtime/source binding. Their platform and called-runtime identities
+differ from the source Verify lane, so a Linux source proof cannot replace them.
+The Stage Capsule checkpoint matrix also retains all three platforms. Shared
+platform-independent logic lives in the root check and public runtime; there is
+no Buildchain-only dogfood exception or persisted candidate runtime selector.
+
+A local Linux sample on 2026-09-05 measured the original full check at
+`a41c00a0c0b2dbd57c238cd9b326b167a1d27ca8` at 148.772 seconds and the updated check
+at 126.731 seconds, both exit 0. The original plan executed 226 Node test files
+plus 22 duplicate selections; the updated plan executes all 231 files once,
+including the new negative and recovery tests (2,047 tests). These are individual
+local measurements with existing tool caches; hosted queue/push reuse is proved
+separately by the exact run attempt and evidence roots in each job summary.

package/docs/release-governance.md

@@ -77,8 +77,8 @@ line.
 
 Buildchain implements the same governance loop with:
 
-- `.github/workflows/release-verify.yml` for PR verification;
-- `.github/workflows/buildchain-ref-promotion.yml` for post-verify ref
+- `.github/workflows/self-build-release-verify-compat.yml` for PR verification;
+- `.github/workflows/self-release-promote.yml` for post-verify ref
   promotion; this workflow dogfoods the declarative
   `release-candidate-promote.yml` wrapper and does not hand-wire resolver,
   artifact download, publish-gate, or promote action steps;
@@ -246,7 +246,7 @@ while exact tags and SHAs remain the reproducible audit choice.
 ### Buildchain Alpha Self-Dogfood
 
 Buildchain continuously consumes its own current major alpha through
-`.github/workflows/buildchain-alpha-self-dogfood.yml`. Both lanes call the
+`.github/workflows/self-build-alpha-dogfood.yml`. Both lanes call the
 released channel router at `build.yml@v3-alpha`. The auto lane must resolve
 `v3-alpha`; the explicit stable lane must resolve `v3`. Both execute the same
 declared install, build, and verify fixture, proving that a single consumer
@@ -295,7 +295,7 @@ resolution and evidence comparison.
 
 This is a post-publication consumer canary, not a release bootstrap. Source
 verification still runs the current commit, and
-`buildchain-ref-promotion.yml` still passes the verified exact SHA into the
+`self-release-promote.yml` still passes the verified exact SHA into the
 promotion workflow. Patrol, dev-merge, repair, and promotion defaults remain on
 stable or exact refs so a broken alpha cannot prevent Buildchain from publishing
 its fix. When Buildchain opens a new major, inventory validation requires this
@@ -526,7 +526,7 @@ The repository policy can be declared once instead of repeated as CLI flags:
 ```toml
 [governance.dev.merge_queue]
 mode = "inherit"
-required_workflows = [".github/workflows/verify.yml"]
+required_workflows = [".github/workflows/self-build-verify.yml"]
 ```
 
 `enabled` explicitly requires Buildchain to create or update an exact-branch
@@ -632,7 +632,7 @@ binds the caller commit/tree and both workflow digests.
 ```sh
 node .buildchain/workflow-contract-runtime/scripts/workflow-call-contract.mjs check \
   --caller-root . \
-  --caller-workflow .github/workflows/release-new-version.yml \
+  --caller-workflow .github/workflows/self-release-new-version-compat.yml \
   --caller-repository kungfu-systems/example \
   --job promote \
   --callee-root .buildchain/workflow-contract-runtime \
@@ -1009,8 +1009,8 @@ v3.0.1-alpha.0
 When debugging or extending release behavior, read in this order:
 
 1. `docs/release-flow.md`
-2. `.github/workflows/release-verify.yml`
-3. `.github/workflows/buildchain-ref-promotion.yml`
+2. `.github/workflows/self-build-release-verify-compat.yml`
+3. `.github/workflows/self-release-promote.yml`
 4. `.github/workflows/release-candidate-promote.yml`
 5. `.github/workflows/.release-candidate-promote.yml`
 6. `actions/promote-buildchain-ref/README.md`

package/docs/release-passport.md

@@ -1,3 +1,22 @@
+---
+status: active
+period: ongoing
+theme: generic-kfd-adopter-binding
+doc_type: reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: B
+review_state: unreviewed
+last_reviewed: 2026-09-06
+ai_provenance:
+  model_family: GPT-6
+  product: Codex
+  generated_at: 2026-09-06
+  visible_context: Buildchain v3 implementation and v4 source and regression tests.
+  invisible_context_boundary: No credentials or private runtime evidence inspected.
+---
+
 # Release Passport
 
 Buildchain Release Passport is the core product mechanism: a mature product
@@ -403,8 +422,14 @@ Pass the standard full-cut declaration with `--kfd-adopter-manifest-json`
 together with three `--kfd-product-gate-json` arguments for KFD-4, KFD-5, and
 KFD-7. The collector invokes the verifier from the exact installed
 `@kungfu-tech/kfd` package, binds the package artifact, registry and verifier
-roots, the exact Buildchain source, the manifest/report/bundle witness roots,
-and the existing product-gate roots. It emits `kfd-adopter-manifest.json`,
+roots, the collector's exact product repository and source, the
+manifest/report/bundle witness roots, and the existing product-gate roots. A
+non-Buildchain adopter is accepted only when its manifest identity, artifact
+coordinate, and all three product-gate repositories match the collector's
+`--repository` value. The lower-level Node API exposes the same boundary as
+`expectedAdopterId`, `expectedSourceRepository`, and `expectedSourceSha`, while
+omitted identity/repository values retain the Buildchain self-release default.
+It emits `kfd-adopter-manifest.json`,
 `kfd-adopter-manifest-gate.json`, and a legacy `kfd-support.json` projection.
 The release passport and `artifact-evidence.json` carry the same rooted
 `kfdAdopter` binding.

package/docs/reusable-build-surface.md

@@ -132,6 +132,22 @@ See the normative
 and its machine declaration for the exact acceptance boundary. This policy does
 not change v3 behavior.
 
+### Universal Bootstrap verified-caller admission
+
+The v4 Universal Bootstrap does not maintain a repository allowlist. Any
+repository that can call the public reusable workflow may submit the single
+versioned request envelope. Admission still fails closed unless the request's
+consumer repository, caller workflow path, and source SHA exactly match the
+GitHub-observed caller context.
+
+Open consumer admission does not mean open execution authority. The candidate
+must still be an exact Buildchain SHA selected through a governed discovery
+ref, bind the current candidate-owned admission root, have exact-head
+independent review and required checks, request an admitted capability and
+contract-root set, stay within the permission ceiling and validity window, and
+inherit only authority available from the caller. The candidate engine exposes
+bounded capability adapters; it does not accept caller-provided shell or code.
+
 ## Advanced Workflow
 
 Consumers that need direct workflow-shell or runtime control call the advanced

package/docs/v4-adopter-delivery.md

@@ -110,12 +110,12 @@ artifact_profile_selector = "package"
 ```
 
 The public reusable workflow is
-`kungfu-systems/buildchain/.github/workflows/v4-adopter-delivery.yml@v4` for
+`kungfu-systems/buildchain/.github/workflows/public-build-adopter-qualification.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)
+[`self-build-adopter-dogfood.yml`](../.github/workflows/self-build-adopter-dogfood.yml)
 caller, which contains no steps or local orchestration and persists only the
 floating `@v4-alpha` selector.
 

package/docs/v4-production-release.md

@@ -7,12 +7,12 @@ source_level: repository-contracts + protected-provider-readback
 confidence: high
 sensitivity: public
 evidence_grade: A
-review_state: self-reviewed
-last_reviewed: 2026-08-13
+review_state: unreviewed
+last_reviewed: 2026-09-05
 ai_provenance:
-  model_family: GPT-5
+  model_family: GPT-6
   product: Codex
-  generated_at: 2026-08-13
+  generated_at: 2026-09-05
   invisible_context: Provider credentials and private provider state were not read.
 ---
 
@@ -26,8 +26,9 @@ dev/v4/v4.0 -> alpha/v4/v4.0 -> release/v4/v4.0
 ```
 
 Public consumers use `v4-alpha` for the current prerelease channel and `v4`
-for stable. Reproducible consumers may pin an exact 40-character commit or an
-exact immutable release tag such as `v4.0.0`.
+for stable, with matching stable and alpha contract locks. Exact commits and
+immutable release tags identify retained evidence and explicitly admitted runtime
+inputs; tracked v4 reusable-workflow selectors remain `@v4` or `@v4-alpha`.
 
 The release transaction is fail-closed. The v4 provider-operation journal,
 activation plan, stable publication fence, and partial-mutation recovery plan
@@ -51,8 +52,9 @@ exact alpha tag, and npm's `alpha` tag.
 ## Non-destructive rollback
 
 Rollback never rewrites an exact tag, release, package version, Passport, or
-provider journal. Stop forward promotion, pin consumers to the last verified
-exact v4 SHA or exact stable tag, and use the retained `release/v3/v3.0`
+provider journal. Stop forward promotion and select the last verified exact
+v4 runtime through an admitted, non-persistent recovery input; keep tracked v4
+workflow selectors on their locked floating channel. Use `release/v3/v3.0`
 coordinate only as an explicit compatibility rollback reference. Restoring v3
 as production authority requires a new reviewed cutover; it is not an implicit
 fallback.
@@ -61,3 +63,64 @@ Before any retry, compare the current provider state with the retained
 transaction and operation roots. Resume only missing eligible operations.
 Conflicting state remains `repair-required` or terminal and must not be
 converted into success by moving a floating ref.
+
+## Publication settlement and binary recovery
+
+Publication, next-development advancement, and binary distribution have separate
+results. A completed native ReleaseReceipt remains publication evidence when the
+later generated Dev PR is still pending or its enqueue call fails. SETTLE verifies
+the immutable invocation, transaction, both provider states, receipt and Passport
+roots even when APPLY fails after publication. It has no provider write permission.
+
+APPLY retains that exact chain before waiting for next-development in the existing GitHub Release as
+`buildchain-publication-settlement.json`; it reads the exact tag and original
+`buildchain.release.json` before adding the packet. The APPLY artifact also retains
+`delivery-summary.json`, which reports publication and next-development separately.
+A green workflow label cannot substitute for this receipt verification.
+
+Binary Distribution reads this settlement and the original publication Passport.
+Tag creation can precede settlement, so it waits at most 40 observations, 15 seconds
+apart, for missing evidence. A mismatched source, tag, Passport or receipt fails
+immediately. It no longer requires a legacy `buildchain/release-state/*` ref for v4.
+
+The sealed binary publisher retains the publication Passport and writes its own
+Passport as `buildchain.binary.release.json`. All v4 asset collisions are checked
+before uploads: identical bytes are preserved, absent assets are added, and
+conflicting bytes are rejected. Each publication authorization is retained as
+`buildchain.binary.capability-<sha256>.json`, so a fresh recovery capability does
+not overwrite an earlier grant. Existing assets are never clobbered. Recovery uses
+the same exact successful Binary Distribution evidence run through
+`self-release-binary-assets.yml`; it does not rebuild already admitted archives or
+create another npm version. Read back all three platform archives, checksums,
+both Passports and the settlement packet before declaring distribution complete.
+
+The native publication receipt authorizes no stable promotion and makes no claim
+that a pending next-development PR has merged. Inspect the exact PR head, protected
+base and merge result independently. A retry of the publication phase must first
+read retained provider facts and resume only missing operations.
+
+## Automatic next-development review
+
+`self-release-next-development.yml` observes a successful exact `Verify` PR run
+for a same-repository `chore/next-development/*` branch. It executes only the
+protected default branch runtime. The PR must have one parent equal to the
+current protected Dev head. The protected generator reconstructs every tracked
+byte, permits only the declared immediate alpha version increment, and verifies
+the completed alpha settlement against the exact tag and original Passport.
+The published source tree must equal the protected development base tree.
+
+The verification step receives no approval credential and never executes PR
+code. A separate step uses `BUILDCHAIN_APPROVAL_TOKEN`, verifies that its identity
+is the independent `kungfu-origin` CODEOWNER, rereads the exact PR/run/base, and
+approves only that commit. Existing requests for changes stop automation.
+The exact approval is read back before queue admission with the separate
+`BUILDCHAIN_PROMOTION_TOKEN`. Required checks, CODEOWNER protection and native
+merge-group verification remain enforced. Missing credentials or evidence,
+forks, source changes and base/head drift fail closed.
+
+The producer waits for pending independent review and required checks with a
+bounded retry budget. Publication evidence is already durable during this wait,
+so binaries can proceed independently. The reviewer also enqueues the verified
+head idempotently, allowing a producer interruption to leave a recoverable PR.
+An interrupted producer run remains failed; a successful later release is needed
+to establish an uninterrupted end-to-end publication.