@kungfu-tech/buildchain 4.0.2 → 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/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-flow.md

@@ -352,7 +352,7 @@ before writing the transaction state as `complete`.
 
 | 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. |
+| 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. |

package/docs/reusable-build-surface.md

@@ -128,7 +128,7 @@ 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.
 

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
@@ -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,

package/docs/v4-delivery-warrant-semantic-diff.md

@@ -50,7 +50,7 @@ provider effects, modify v3 authority, or provide a v4 write cutover receipt.
 
 ## Run the gate
 
-Call `runV4DeliveryWarrantSemanticDiffGate` with exact source revisions,
+Call `runDeliveryWarrantSemanticDiffGate` with exact source revisions,
 explicit observation time, schema and runner roots, public-safe retained cases,
 bounded fault probes, an observation retention sink, and a report retention
 sink. The returned report is canonical JSON data suitable for a caller-owned
@@ -59,7 +59,7 @@ retained evidence file.
 The checked-in focused suite exercises that API against the real Rust host:
 
 ```sh
-node --test tests/v4-delivery-warrant-fixture-runner.test.mjs
+node --test tests/delivery-warrant-fixture-runner.test.mjs
 ```
 
 A qualified report makes only the next
@@ -71,5 +71,5 @@ documented in
 Focused verification:
 
 ```sh
-pnpm run check:v4-contracts
+pnpm run check:contracts
 ```

package/docs/v4-production-release.md

@@ -8,11 +8,11 @@ confidence: high
 sensitivity: public
 evidence_grade: A
 review_state: unreviewed
-last_reviewed: 2026-09-05
+last_reviewed: 2026-09-07
 ai_provenance:
   model_family: GPT-6
   product: Codex
-  generated_at: 2026-09-05
+  generated_at: 2026-09-07
   invisible_context: Provider credentials and private provider state were not read.
 ---
 
@@ -30,6 +30,12 @@ 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`.
 
+Before qualifying a new release, run `node scripts/check-universal-workflow-bootstrap.mjs`.
+The required repository check rejects an expired or not-yet-valid candidate admission
+policy before publication. Renew the bounded validity window through protected review;
+keep its capability, permission, reviewer and exact-source requirements unchanged.
+Historical publication receipts remain immutable when a later admission window expires.
+
 The release transaction is fail-closed. The v4 provider-operation journal,
 activation plan, stable publication fence, and partial-mutation recovery plan
 bind the exact source, qualification, policy, provider readback, protected

package/docs/v4-publication-rehearsal.md

@@ -27,7 +27,7 @@ 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),
+[`architecture/publication-rehearsal-parity.json`](../architecture/publication-rehearsal-parity.json),
 and the public schema is
 [`v4-publication-rehearsal-capsule-v1.schema.json`](../contracts/v4-publication-rehearsal-capsule-v1.schema.json).
 
@@ -125,6 +125,6 @@ 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
+node scripts/publication-rehearsal-fixture.mjs
+node scripts/publication-rehearsal-fixture.mjs --check
 ```

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

@@ -60,9 +60,9 @@ construction and verification.
 
 Normative files:
 
-- `architecture/v4-runtime-ref-resume-authority.json`
+- `architecture/runtime-ref-resume-authority.json`
 - `contracts/v4-runtime-ref-resume-authority-v1.schema.json`
-- `packages/core/v4-runtime-ref-resume-authority.js`
+- `packages/core/runtime-ref-resume-authority.js`
 - `scripts/authorize-promotion-runtime-override.cjs`
 
 This contract changes no v3 behavior, grants no provider mutation authority,

package/docs/v4-rust-wasm-production-authority.md

@@ -19,16 +19,16 @@ ai_provenance:
 # Buildchain v4 Rust/WASM production authority
 
 Buildchain v4 的确定性发布语义由
-`crates/buildchain-v4-contracts` 编译出的同一份 WebAssembly artifact 执行。Node
+`crates/buildchain-domain-contracts` 编译出的同一份 WebAssembly artifact 执行。Node
 仍是 GitHub Action 和 npm 包的宿主，但只负责 provider SDK、文件系统、凭据、环境变量及
 workflow 输入输出等副作用边界。权威契约见
-`architecture/v4-rust-wasm-production-authority.json`。
+`architecture/rust-wasm-production-authority.json`。
 
 ## 分发与调用
 
-`packages/core/buildchain-v4-domain.wasm` 与 JavaScript 一起提交和发布。三个生产 Action
+`packages/core/buildchain-domain.wasm` 与 JavaScript 一起提交和发布。三个生产 Action
 在构建时把完全相同的字节复制到各自 `dist/`；运行时不进入调用方仓库寻找 Rust
-源码，也不要求安装 Rust。`packages/core/v4-domain-wasm.js` 从自身相邻路径同步读取
+源码，也不要求安装 Rust。`packages/core/domain-wasm.js` 从自身相邻路径同步读取
 artifact，先核验生成元数据中的 SHA-256，再实例化 WebAssembly 并通过封闭 JSON/bytes
 ABI 调用领域操作。
 
@@ -38,9 +38,9 @@ ABI 调用领域操作。
 
 ## 构建和审计
 
-`pnpm run build:v4-wasm` 使用锁定的 Rust 工具链和 `wasm32-unknown-unknown` target 生成
+`pnpm run build:wasm` 使用锁定的 Rust 工具链和 `wasm32-unknown-unknown` target 生成
 artifact 与绑定元数据，并把 Cargo 依赖源目录映射到稳定的虚拟路径，禁止主机 Cargo
-registry 路径进入 artifact。`pnpm run check:v4-wasm` 在干净临时 target 目录重新构建并逐字节
+registry 路径进入 artifact。`pnpm run check:wasm` 在干净临时 target 目录重新构建并逐字节
 比较已跟踪 artifact。这个检查不是生产运行时的重复编译：生产只加载已提交字节；检查
 用于证明这些字节仍能由当前 Rust 真相源和锁定工具链唯一导出，从而阻止源码、二进制或
 生成元数据静默漂移。

package/docs/v4-stage-capsule.md

@@ -20,7 +20,7 @@ ai_provenance:
 
 ## Platform checkpoint projection
 
-`architecture/v4-platform-stage-checkpoints.json` is the single declaration
+`architecture/platform-stage-checkpoints.json` is the single declaration
 for the macOS arm64, Linux x64, and Windows x64 shadow checkpoint lanes. It
 defines the allowed platform/stage pairs and the exact declared inputs,
 outputs, environment names, toolchains, and portable restore paths.
@@ -100,19 +100,19 @@ GitHub Artifact and S3-compatible adapters expose only `effect-disabled` and
 `fixture-backed` modes in this slice. They accept rooted locators, never raw
 credentials or signed URLs, and cannot perform a provider upload or restore.
 The executable architecture ceiling is
-[`v4-stage-capsule-store-contract.json`](../architecture/v4-stage-capsule-store-contract.json),
+[`stage-capsule-store-contract.json`](../architecture/stage-capsule-store-contract.json),
 and the shared Rust/JavaScript fixture is
 [`shared.json`](../contracts/fixtures/v4-stage-capsule-store-v1/shared.json).
 
 Focused verification:
 
 ```sh
-pnpm run check:v4-contracts
+pnpm run check:contracts
 ```
 
 ## Deterministic resume planning
 
-`architecture/v4-stage-capsule-resume-planner.json` closes the Wave 2 resume
+`architecture/stage-capsule-resume-planner.json` closes the Wave 2 resume
 planner. Its request is an explicit topological stage graph with targets,
 expected Capsule identity and retention, current Capsule/availability
 observations, an evaluation clock, and separately declared provider or
@@ -133,7 +133,7 @@ shadow-only: it does not skip a v3 production stage or move v3 authority.
 
 ## Three-platform qualification and Wave reconciliation
 
-`architecture/v4-stage-capsule-qualification.json` closes the Wave 2
+`architecture/stage-capsule-qualification.json` closes the Wave 2
 qualification boundary. Buildchain and external repositories use the same
 Buildchain-owned public reusable workflow,
 `.github/workflows/public-build-stage-capsule-canary.yml`. Buildchain's caller is the thin
@@ -182,12 +182,12 @@ authorized by this qualification.
 Focused local rehearsal:
 
 ```sh
-node scripts/v4-stage-capsule-qualification.mjs campaign \
+node scripts/stage-capsule-qualification.mjs campaign \
   --work-root /tmp/buildchain-v4-stage-qualification \
   --platform linux-x64 \
   --consumer buildchain \
   --runtime-ref <exact-buildchain-commit> \
   --consumer-source-revision <exact-consumer-commit> \
   --consumer-root . \
-  --lifecycle-evidence-root .buildchain/artifacts/v4-stage-capsule-canary
+  --lifecycle-evidence-root .buildchain/artifacts/stage-capsule-canary
 ```

package/docs/v4-tail-reseal.md

@@ -70,4 +70,4 @@ 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).
+[`architecture/tail-reseal-parity.json`](../architecture/tail-reseal-parity.json).

package/docs/workflow-catalog.md

@@ -90,6 +90,7 @@ all related declarations. Run `pnpm run generate:workflows` and
 | [public-ops-warrant-cancel.yml](../.github/workflows/public-ops-warrant-cancel.yml) | ops | reusable | active | Dev Delivery Warrant Queued Candidate Cancel | `dev-delivery-warrant-cancel.yml` |
 | [public-ops-warrant-close.yml](../.github/workflows/public-ops-warrant-close.yml) | ops | reusable | active | Dev Delivery Warrant Close | `dev-delivery-warrant-close.yml` |
 | [public-release-artifact-attestation.yml](../.github/workflows/public-release-artifact-attestation.yml) | release | reusable | active | Buildchain GitHub Artifact Attestation | `github-artifact-attestation.yml` |
+| [public-release-oci-compose-preview.yml](../.github/workflows/public-release-oci-compose-preview.yml) | release | reusable | active | Buildchain OCI Compose Preview | — |
 | [public-release-paper-sealed.yml](../.github/workflows/public-release-paper-sealed.yml) | release | reusable | active | Buildchain Sealed Paper Release | `paper-release-sealed.yml` |
 | [public-release-paper.yml](../.github/workflows/public-release-paper.yml) | release | reusable | active | Buildchain Paper Release | `paper-release.yml` |
 | [public-release-promote.yml](../.github/workflows/public-release-promote.yml) | release | reusable | active | Release Candidate Promote | `release-candidate-promote.yml` |