@kungfu-tech/buildchain 4.0.2-alpha.9 → 4.0.3-alpha.0

package/docs/oci-publication.md

@@ -0,0 +1,173 @@
+---
+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
+
+Compose preview uses the workflow's scoped `packages: write` token for GHCR
+requests. The separate `BUILDCHAIN_PROMOTION_TOKEN` serves GitHub governance
+and receipt publication; it is never a fallback registry credential. Missing
+registry identity fails before a write, and an unsuccessful registry response
+reports only its HTTP status while retaining the exact qualification for recovery.
+
+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.
+
+The verified publication Passport distinguishes the built candidate from the
+protected publication commit. Compose family source identity follows
+`source.builtSourceSha`; `source.builtSourceTreeSha` must equal the admitted
+invocation tree. Registry readback and qualification runs remain bound to the
+protected publication SHA. A tree-equivalent protected merge therefore retains
+the original image identity without accepting a different source tree.

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 `product-publication-topology.test.mjs`,
+`product-provider-adapters.test.mjs`, and
+`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: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

@@ -128,10 +128,26 @@ 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)
+[`v4 floating consumer policy`](../architecture/floating-consumer-policy.md)
 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

@@ -33,7 +33,7 @@ minimal v4 absorption base
 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)
+[`adopter-delivery-parity.json`](../architecture/adopter-delivery-parity.json)
 and exposed by the public Node API.
 
 ## Public contract
@@ -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.
 
@@ -139,7 +139,7 @@ terminal verification and N-1 bootstrap must pass, and the independent
 The workflow then reconciles one exact report from each platform. Final family
 qualification combines the Buildchain self-dogfood and `agent-hub-demo`
 matrices through the exported
-`@kungfu-tech/buildchain/v4-cross-platform-adopter-qualification` aggregator.
+`@kungfu-tech/buildchain/cross-platform-adopter-qualification` aggregator.
 The report and aggregate explicitly grant no production, provider, release, or
 stable-publication authority.
 

package/docs/v4-canonical-contracts.md

@@ -41,21 +41,21 @@ Event, receipt, and typed-fault objects use closed versioned shapes in [`contrac
 
 ## Implementations and proof
 
-- JavaScript: [`packages/core/v4-canonical-contracts.js`](../packages/core/v4-canonical-contracts.js)
-- Rust: [`crates/buildchain-v4-contracts`](../crates/buildchain-v4-contracts)
-- Shared golden and adversarial cases: [`architecture/v4-canonical-contract-fixtures.json`](../architecture/v4-canonical-contract-fixtures.json)
+- JavaScript: [`packages/core/canonical-contracts.js`](../packages/core/canonical-contracts.js)
+- Rust: [`crates/buildchain-domain-contracts`](../crates/buildchain-domain-contracts)
+- Shared golden and adversarial cases: [`architecture/canonical-contract-fixtures.json`](../architecture/canonical-contract-fixtures.json)
 
 Run the focused proof with:
 
 ```sh
-pnpm run check:v4-contracts
+pnpm run check:contracts
 ```
 
 The check validates both implementations, compares exact UTF-8 bytes and SHA-256 roots, exercises invalid numbers, keys, clocks, domains, and envelope shapes, and scans the pure libraries for ambient clock or provider imports. Delivery Warrant decide/fold, shadow invocation, provider effects, and production authority remain outside this contract slice.
 
 ## Shared Delivery Warrant fixture runner
 
-The versioned trace contract in [`contracts/v4-delivery-warrant-trace-v1.schema.json`](../contracts/v4-delivery-warrant-trace-v1.schema.json) is the language-neutral boundary for retained Delivery Warrant fixtures. The JavaScript runner in [`packages/core/v4-delivery-warrant-fixture-runner.js`](../packages/core/v4-delivery-warrant-fixture-runner.js) and the Rust runner in [`crates/buildchain-v4-contracts`](../crates/buildchain-v4-contracts) consume the same UTF-8 fixture bytes and emit the same deterministic semantic projection.
+The versioned trace contract in [`contracts/v4-delivery-warrant-trace-v1.schema.json`](../contracts/v4-delivery-warrant-trace-v1.schema.json) is the language-neutral boundary for retained Delivery Warrant fixtures. The JavaScript runner in [`packages/core/delivery-warrant-fixture-runner.js`](../packages/core/delivery-warrant-fixture-runner.js) and the Rust runner in [`crates/buildchain-domain-contracts`](../crates/buildchain-domain-contracts) consume the same UTF-8 fixture bytes and emit the same deterministic semantic projection.
 
 Each trace is closed and ordered. It binds the exact prior root, event, action or typed fault, canonical successor bytes and root, generation, fencing counter, ordered declarative effects, provider-neutral observations, and rooted receipt. The runner verifies the full root chain before returning a projection. Malformed JSON, missing or unknown fields, reordered sequences, stale roots, and unsupported contract versions fail closed.
 
@@ -68,13 +68,13 @@ The runner is not a state-machine implementation and does not sample time, execu
 
 ## TypeScript shadow adapter
 
-The adapter in [`packages/core/v4-delivery-warrant-shadow-adapter.js`](../packages/core/v4-delivery-warrant-shadow-adapter.js) runs the existing TypeScript v3 fixture projection first and preserves that exact result as the only authoritative output. When explicitly enabled, it sends the same canonical input bytes to the replaceable Rust host command, requires the effect-disabled host capability, and captures the returned semantic projection only as a non-authoritative observation. Rust never receives effect authority, and success, failure, timeout, cancellation, malformed output, or an unsupported host cannot change the v3 result.
+The adapter in [`packages/core/delivery-warrant-shadow-adapter.js`](../packages/core/delivery-warrant-shadow-adapter.js) runs the existing TypeScript v3 fixture projection first and preserves that exact result as the only authoritative output. When explicitly enabled, it sends the same canonical input bytes to the replaceable Rust host command, requires the effect-disabled host capability, and captures the returned semantic projection only as a non-authoritative observation. Rust never receives effect authority, and success, failure, timeout, cancellation, malformed output, or an unsupported host cannot change the v3 result.
 
 Shadow retention accepts only checked-in fixtures or captured replays explicitly marked public-safe. Each returned observation binds the input root, exact TypeScript and Rust source revisions, validator version, capture time, fixed retention deadline, both projections, and sanitized diagnostics. It contains no comparison verdict or cutover signal. The adapter is disabled unless the caller opts in or sets `BUILDCHAIN_V4_WARRANT_SHADOW=enabled`; even then, invalid source bindings or an unsafe retention class skip Rust invocation.
 
 ## Pure Rust Delivery Warrant domain
 
-The `warrant` module in [`crates/buildchain-v4-contracts`](../crates/buildchain-v4-contracts) implements the protected Delivery Warrant manifest as provider-free typed state, seven event decisions, and a separate fold. It freezes all nine candidate states and all nine primitives from the shadow bootstrap plan. Every decision binds the event's exact `subjectRoot`, takes time only from the validated event envelope, and returns a typed action or fault. Fold produces a canonical successor; the combined transition produces only ordered `persist-successor` and `request-admission` intents plus a rooted receipt. It never executes either intent.
+The `warrant` module in [`crates/buildchain-domain-contracts`](../crates/buildchain-domain-contracts) implements the protected Delivery Warrant manifest as provider-free typed state, seven event decisions, and a separate fold. It freezes all nine candidate states and all nine primitives from the shadow bootstrap plan. Every decision binds the event's exact `subjectRoot`, takes time only from the validated event envelope, and returns a typed action or fault. Fold produces a canonical successor; the combined transition produces only ordered `persist-successor` and `request-admission` intents plus a rooted receipt. It never executes either intent.
 
 Duplicate submission deliberately retains the legacy generation/root mutation for shadow comparability. Manifest aliases remain explicit, waiting and blocked remain valid states without invented public transitions, and response-loss reconciliation is symmetric for every declarative effect. Stale expected-old roots and fences, lease expiry, terminal duplicates, cancellation, response loss, provider conflict, and retry exhaustion are closed typed outcomes. The retry policy permits at most one reread/redecision and then stops.
 

package/docs/v4-delivery-warrant-read-candidate.md

@@ -52,7 +52,7 @@ buildchain dev warrant observe \
   --read-typescript-revision <sha> \
   --read-rust-revision <sha> \
   --read-validator-version semantic-diff-gate-v1 \
-  --read-evidence-output .buildchain/dev-delivery/v4-read-evidence.json
+  --read-evidence-output .buildchain/dev-delivery/read-evidence.json
 ```
 
 The returned command result keeps the existing v3 observation schema for
@@ -64,8 +64,8 @@ root, and the retained evidence receipt root.
 Focused verification:
 
 ```sh
-node --test tests/v4-delivery-warrant-read-candidate.test.mjs
-pnpm run check:v4-contracts
+node --test tests/delivery-warrant-read-candidate.test.mjs
+pnpm run check:contracts
 ```
 
 This candidate does not authorize a v4 write cutover. Protected-window parity,