@kungfu-tech/buildchain 4.0.1-alpha.4 → 4.0.1-alpha.6

package/docs/cli-reference.md

@@ -22,6 +22,63 @@ ai_provenance:
 
 Every listed help command is intercepted before dispatch, exits zero, and performs no command side effects.
 
+## `adopter-delivery`
+
+### `buildchain adopter-delivery`
+
+- Help: `buildchain adopter-delivery --help`
+- Canonical id: `adopter-delivery`
+- Options: none declared
+- Syntax:
+
+```text
+buildchain adopter-delivery
+```
+
+### `buildchain adopter-delivery archive`
+
+- Help: `buildchain adopter-delivery archive --help`
+- Canonical id: `adopter-delivery`
+- Options: `--input`, `--output`
+- Syntax:
+
+```text
+buildchain adopter-delivery archive --input <json-or-path> [--output <path>]
+```
+
+### `buildchain adopter-delivery bootstrap`
+
+- Help: `buildchain adopter-delivery bootstrap --help`
+- Canonical id: `adopter-delivery`
+- Options: `--input`, `--output`
+- Syntax:
+
+```text
+buildchain adopter-delivery bootstrap --input <json-or-path> [--output <path>]
+```
+
+### `buildchain adopter-delivery run`
+
+- Help: `buildchain adopter-delivery run --help`
+- Canonical id: `adopter-delivery`
+- Options: `--input`, `--output`
+- Syntax:
+
+```text
+buildchain adopter-delivery run --input <json-or-path> [--output <path>]
+```
+
+### `buildchain adopter-delivery verify`
+
+- Help: `buildchain adopter-delivery verify --help`
+- Canonical id: `adopter-delivery`
+- Options: `--input`, `--output`, `--readback`
+- Syntax:
+
+```text
+buildchain adopter-delivery verify --input <json-or-path> --readback <json-or-path> [--output <path>]
+```
+
 ## `architecture`
 
 ### `buildchain architecture`
@@ -728,6 +785,50 @@ buildchain facts
 buildchain facts aggregate [--cwd <dir>] [--product <id>] [--module-fact <file>]... [--artifact <path>]... [--output <file>] [--json]
 ```
 
+### `buildchain facts compatibility project`
+
+- Help: `buildchain facts compatibility project --help`
+- Canonical id: `build-facts`
+- Options: `--cwd`, `--json`, `--output`, `--registry`
+- Syntax:
+
+```text
+buildchain facts compatibility project [--cwd <dir>] [--registry <json-or-path>] [--output <file>] [--json]
+```
+
+### `buildchain facts compatibility query`
+
+- Help: `buildchain facts compatibility query --help`
+- Canonical id: `build-facts`
+- Options: `--cwd`, `--json`, `--query`, `--registry`
+- Syntax:
+
+```text
+buildchain facts compatibility query --query <json-or-path> [--registry <json-or-path>] [--cwd <dir>] [--json]
+```
+
+### `buildchain facts compatibility query-template`
+
+- Help: `buildchain facts compatibility query-template --help`
+- Canonical id: `build-facts`
+- Options: `--cwd`, `--fact-root`, `--json`, `--query-id`, `--registry`
+- Syntax:
+
+```text
+buildchain facts compatibility query-template --fact-root <sha256:...> [--query-id <id>] [--registry <json-or-path>] [--cwd <dir>] [--json]
+```
+
+### `buildchain facts compatibility verify`
+
+- Help: `buildchain facts compatibility verify --help`
+- Canonical id: `build-facts`
+- Options: `--cwd`, `--json`, `--registry`
+- Syntax:
+
+```text
+buildchain facts compatibility verify [--cwd <dir>] [--registry <json-or-path>] [--json]
+```
+
 ### `buildchain facts module`
 
 - Help: `buildchain facts module --help`
@@ -1586,6 +1687,30 @@ buildchain log <info|warn|error> --event <name> [--phase <phase>] [--component <
 buildchain mark --event <name> [--phase <phase>] [--component <name>] [--attribute key=value]... [--path <jsonl>] [--json]
 ```
 
+## `next-development`
+
+### `buildchain next-development`
+
+- Help: `buildchain next-development --help`
+- Canonical id: `next-development`
+- Options: none declared
+- Syntax:
+
+```text
+buildchain next-development
+```
+
+### `buildchain next-development materialize`
+
+- Help: `buildchain next-development materialize --help`
+- Canonical id: `next-development`
+- Options: `--cwd`, `--input`, `--json`, `--output`, `--write`
+- Syntax:
+
+```text
+buildchain next-development materialize --input <request.json> [--cwd <dir>] [--write] [--output <path>] [--json]
+```
+
 ## `npm`
 
 ### `buildchain npm`
@@ -2178,6 +2303,17 @@ buildchain release-tail init --declaration <json-or-path> [--state <path>]
 buildchain release-tail plan --declaration <json-or-path> [--output <path>]
 ```
 
+### `buildchain release-tail rehearse`
+
+- Help: `buildchain release-tail rehearse --help`
+- Canonical id: `release-tail`
+- Options: `--candidate-root`, `--capsule`, `--evidence`, `--mode`, `--state`
+- Syntax:
+
+```text
+buildchain release-tail rehearse --capsule <absolute-path> --candidate-root <absolute-path> --mode <simulate|replay> --state <absolute-path> --evidence <absolute-path>
+```
+
 ### `buildchain release-tail status`
 
 - Help: `buildchain release-tail status --help`
@@ -2237,6 +2373,63 @@ buildchain sample process-tree [--interval-ms <n>] [--label <name>] [--output <j
 buildchain span --event <name> [--phase <phase>] [--component <name>] [--path <jsonl>] -- <command> [args...]
 ```
 
+## `tail-reseal`
+
+### `buildchain tail-reseal`
+
+- Help: `buildchain tail-reseal --help`
+- Canonical id: `tail-reseal`
+- Options: none declared
+- Syntax:
+
+```text
+buildchain tail-reseal
+```
+
+### `buildchain tail-reseal admit`
+
+- Help: `buildchain tail-reseal admit --help`
+- Canonical id: `tail-reseal`
+- Options: `--output`, `--request`
+- Syntax:
+
+```text
+buildchain tail-reseal admit --request <request.json> [--output <admission.json>]
+```
+
+### `buildchain tail-reseal plan`
+
+- Help: `buildchain tail-reseal plan --help`
+- Canonical id: `tail-reseal`
+- Options: `--output`, `--request`
+- Syntax:
+
+```text
+buildchain tail-reseal plan --request <request.json> [--output <plan.json>]
+```
+
+### `buildchain tail-reseal seal`
+
+- Help: `buildchain tail-reseal seal --help`
+- Canonical id: `tail-reseal`
+- Options: `--output`, `--passport`, `--plan`, `--protected-readback-root`, `--readbacks`, `--request`
+- Syntax:
+
+```text
+buildchain tail-reseal seal --request <request.json> --plan <plan.json> --readbacks <dir> --passport <passport.json> --protected-readback-root <sha256:...> [--output <receipt.json>]
+```
+
+### `buildchain tail-reseal verify-platform`
+
+- Help: `buildchain tail-reseal verify-platform --help`
+- Canonical id: `tail-reseal`
+- Options: `--artifact-root`, `--mode`, `--output`, `--platform`, `--provider-readback-root`, `--request`
+- Syntax:
+
+```text
+buildchain tail-reseal verify-platform --request <request.json> --platform <id> [--artifact-root <dir>] [--mode retained|resealed] [--provider-readback-root <sha256:...>] [--output <readback.json>]
+```
+
 ## `transaction`
 
 ### `buildchain transaction`

package/docs/cli.md

@@ -1033,6 +1033,14 @@ The command validates `package.json`, infers the exact release tag
 `npm publish --dry-run --access public --tag <alpha|latest>` unless
 `--skip-npm-publish-dry-run` is passed. It never performs a real publish.
 
+## V4 Adopter Delivery
+
+`buildchain adopter-delivery` exposes the public v4 driver gate, exact
+readback, N-1 bootstrap lineage, and published archive loader. `run` emits a
+rooted non-authoritative readback, `verify` recomputes it, `bootstrap` binds the
+exact v3 authority and v4 base, and `archive` verifies public npm archive bytes
+and package identity. See [`v4-adopter-delivery.md`](v4-adopter-delivery.md).
+
 ## npm Publish Gate
 
 Buildchain's own npm package is published from

package/docs/dev-alpha-candidate-patrol.md

@@ -59,6 +59,14 @@ controller then compares the selected SHA to the exact Alpha head before it can
 be eligible, so a bounded scan cannot turn a commit outside the promotion
 ancestry into a candidate.
 
+Generated next-development version preparation is not a product candidate. The
+observer skips both the signed `chore(release): prepare ...` commit and its
+two-parent integration commit. When later product work becomes qualified, the
+nearest preparation becomes a reservation: Patrol reads every path changed by
+that preparation at both exact SHAs and requires identical Git blob identities.
+A missing or stale reserved path blocks selection before the Release Cut and
+therefore before any heavy candidate build.
+
 The decision is `kungfu-buildchain-channel-candidate-decision/v1`. It records the
 source and target branches and SHAs, comparison distance, workflow paths, run
 identities and attempts, completion times, URLs, policy, and a canonical decision

package/docs/next-development-transition.md

@@ -0,0 +1,118 @@
+---
+status: preview
+period: ongoing
+theme: next-development-transition
+doc_type: generated-contract-guidance
+source_level: generated-from-node-contract
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-11
+---
+
+# Next-development Transition
+
+This document is generated from
+`packages/core/next-development-transition.js` and
+`packages/core/next-development-controller.js` and
+`packages/core/next-development-projection.js`. Edit those sources and run
+`node scripts/generate-next-development-guidance.mjs`; direct edits fail the
+projection drift check.
+
+## Contract
+
+- Contract: `kungfu-buildchain-next-development-transition/v1`
+- Durable controller: `kungfu-buildchain-next-development-controller/v1`
+- ADR: [ADR 0002](../architecture/decisions/0002-next-development-transition.md)
+- States: `planned`, `waiting-anchor`, `materialized`, `pr-pending`, `merged`, `verified`
+- Legal version models: `semver/auto` and `anchored/manual`
+- Invariant: A completed Alpha remains successful and its refs remain immutable while the next-development transition is incomplete.
+
+An Alpha publication is terminal success independently of this transition.
+The idempotency key is a deterministic hash of the completed-Alpha root,
+repository, legal model, and sorted declared paths. Incomplete Dev preparation
+therefore cannot relabel Alpha N as failed, and replay cannot select a different
+Alpha or path set.
+
+## Durable controller
+
+`scheduleNextDevelopmentController` atomically creates one child for the
+repository and completed-Alpha root. Identical wakes reuse it. The store
+boundary requires read, create-if-absent, and compare-and-swap operations; the
+controller root fences every checkpoint. Materialization uses an operation key
+derived from the child, exact current protected Dev SHA, and reviewed target,
+so a fresh runner can recover an already-created commit instead of rebuilding
+the Alpha candidate or depending on the original runner workspace.
+
+Before opening the protected version PR, the controller reads Dev again. A
+moved head makes the prepared attempt `superseded`; the following wake
+regenerates only declared version material from that latest SHA. After merge,
+`verified` remains unreachable until protected Dev readback contains the
+prepared commit and its target version, source roots, and derived roots exactly
+match the checkpoint. The executor surface contains no Alpha publication, tag,
+release, or package operation.
+
+Alpha finalization no longer treats a non-fast-forward Dev update as successful
+bookkeeping. It requires an exact checkout of the current Dev head, regenerates
+the declared version lifecycle there, and uses a non-force merge or reusable
+protected version PR. Candidate Patrol ignores both the generated preparation
+commit and its two-parent integration commit. Before a later product candidate
+can settle, Patrol reads every prepared version path at the candidate SHA and
+requires the exact reserved blob identities; missing or stale state blocks
+before a Release Cut or heavy candidate build.
+
+## Version models
+
+`semver/auto` increments the Alpha sequence on the same semantic patch. For
+example, completed `1.4.2-alpha.7` plans `1.4.2-alpha.8`. It must not accept an anchor or an
+operator-selected target.
+
+`anchored/manual` enters `waiting-anchor` until the caller provides both a
+semantic target and the exact digest of the configured anchor manifest. The
+adapter verifies the manifest already present in the checkout; it never invents
+or edits upstream anchor facts. `semver/manual` and `anchored/auto` are
+invalid.
+
+## Public self-dogfood and adoption
+
+`.github/workflows/v4-public-consumer-dogfood.yml` remains the exact thin
+consumer of the public `v4-stage-capsule-canary.yml@v4-alpha` contract. Its
+declared `lifecycle.verify` runs `pnpm run check`, so the same public path
+executes pure recovery tests that inject a transient durable-state write
+failure, restore the adapter operation on a fresh runner, supersede stale work
+when protected Dev moves, preserve `pr-pending` during protected-PR delay, and
+prove both legal version models. No caller-local qualification job, action,
+or private self-dogfood route is added.
+
+The existing dual-channel self-consumer separately retains exact hosted
+`build.yml@v4-alpha` and `build.yml@v4` runtime evidence. Consumers adopt
+the proved contract through the floating v4 coordinates; exact resolved SHAs
+remain audit evidence and never become durable selectors.
+
+## Local adapter
+
+From a normal Buildchain checkout:
+
+```sh
+node scripts/next-development-transition.mjs materialize --cwd . --input <request.json>
+```
+
+The command prints a rooted plan and performs no write by default. `--write`
+may change only regular, non-symlink source files listed by `version.files`
+in the loaded Buildchain config. The rooted adapter contract separately names
+`version.derived_files` as allowed changes, `version.manifest` as read-only,
+`BUILDCHAIN_VERSION` as the target input, `lifecycle.version-state` as the
+derived-material stage, and `lifecycle.verify` as the truth gate. The
+reference writer fails closed when derived files exist because transaction
+execution is outside this contract slice. It performs no Git operation, ref
+update, network request, provider call, lifecycle command, or anchor edit.
+
+Preparing development state creates no tag, Release, public package, or
+candidate. Those public effects remain outside the local adapter contract.
+
+The request schema is
+`contracts/next-development-request-v1.schema.json`; the durable record schema
+is `contracts/next-development-transition-v1.schema.json`. Positive and
+negative examples live under
+`contracts/fixtures/next-development-transition-v1/`.