@kungfu-tech/buildchain 4.0.1-alpha.3 → 4.0.1-alpha.5

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-08-15T19:57:44.433Z",
-  "publishedAt": "2026-08-15T19:57:44.433Z",
+  "generatedAt": "2026-08-16T06:14:57.817Z",
+  "publishedAt": "2026-08-16T06:14:57.817Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "cfc0256de1826e0e0ec4a4e55644c869f3286f91",
+  "sourceRevision": "358df2d1ab42465111896a42cde85dcca08549d5",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "4.0.1-alpha.3",
+    "version": "4.0.1-alpha.5",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:16120e34c1a178b00309887d7903c2c8acb95815326091cf46a608d375435b99"
+      "digest": "sha256:fd63caf537bdc0dc2a220688dcb89534f6f84f6223e8c45f399a7d1bb8f8faf8"
     },
     {
       "id": "getting-started",
@@ -135,6 +135,14 @@
       "exists": true,
       "digest": "sha256:6989ada03d381e68fdec55b26b76b2070fb37969826eadc0a989844a732ba557"
     },
+    {
+      "id": "next-development-transition",
+      "title": "Next-development transition",
+      "path": "docs/next-development-transition.md",
+      "plane": "verify",
+      "exists": true,
+      "digest": "sha256:c33c017ae163650b422f7ec294a05f3db8b8e99b87c55ab2d8ac3cce1726448f"
+    },
     {
       "id": "release-propagation",
       "title": "Release propagation",
@@ -237,7 +245,7 @@
       "path": "docs/cli-reference.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:82b5d7afa63fc4cfa29ffb813f1830b30eeee3d9b0da821f77240a9ddb25584e"
+      "digest": "sha256:157d6259dd8f884833f7065f52bff0d482878eca72623dcc607e4204692e4970"
     },
     {
       "id": "node-api-reference",
@@ -245,7 +253,7 @@
       "path": "docs/node-api-reference.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:8f0c42d4453003d9bff861392c890f557a54608662e1cc380ed9aaa6635df016"
+      "digest": "sha256:34a2feafe2f6183afbc0a72fa6362d39db6968c2bac187a1a1dd376d7ca50e50"
     },
     {
       "id": "build-facts",
@@ -319,6 +327,14 @@
       "exists": true,
       "digest": "sha256:6dfe8a9b974040fc1465b0da696519b4e97b0b901e30d852ffacda0d193810af"
     },
+    {
+      "id": "v4-compatibility-facts",
+      "title": "Buildchain v4 compatibility Facts",
+      "path": "docs/v4-compatibility-facts.md",
+      "plane": "verify",
+      "exists": true,
+      "digest": "sha256:d29c904a17aca0ca3ad4f48a826f530610d77ffca8bde76ef7e5b4c245c2ca47"
+    },
     {
       "id": "release-flow",
       "title": "Release flow",
@@ -341,7 +357,7 @@
       "path": "docs/versioning.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:fa094ca11fe51b2f23b2154523414676d6f8c8fa50493c5027a469da9115a414"
+      "digest": "sha256:a2fc36e62ac3adfa0dd499972f22cad22131ccc526e11e890e2cbdc4d3a31341"
     },
     {
       "id": "web-surface-deployments",

package/dist/site/workflow-registry.json

@@ -2006,7 +2006,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.1-alpha.3",
+      "introducedVersion": "4.0.1-alpha.5",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -2027,7 +2027,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.1-alpha.3",
+      "introducedVersion": "4.0.1-alpha.5",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -2048,7 +2048,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.1-alpha.3",
+      "introducedVersion": "4.0.1-alpha.5",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -2098,7 +2098,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "4.0.1-alpha.3",
+      "introducedVersion": "4.0.1-alpha.5",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -3029,6 +3029,38 @@
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
       "nonDuplicationRationale": "Existing workflow identity retained for caller compatibility and repository orchestration."
     },
+    {
+      "id": "v4-tail-reseal",
+      "path": ".github/workflows/v4-tail-reseal.yml",
+      "reusable": true,
+      "inputs": [
+        "artifact-retention-days",
+        "consumer-policy-receipt-json",
+        "macos-finalization-command",
+        "request-json"
+      ],
+      "inputCount": 4,
+      "secrets": [
+        "BUILDCHAIN_EVIDENCE_READ_TOKEN",
+        "BUILDCHAIN_SIGNING_TOKEN"
+      ],
+      "secretCount": 2,
+      "outputs": [
+        "release-candidate-passport-json",
+        "tail-reseal-receipt-root"
+      ],
+      "outputCount": 2,
+      "surface": "repository-workflow",
+      "capabilityGroup": "api-cli-reference",
+      "status": "active",
+      "owner": "buildchain-workflows",
+      "maturity": "active",
+      "introducedVersion": "pre-3.0.2-alpha.4",
+      "compatibilityPromise": "preserved-through-the-v3-major-line",
+      "deprecationReplacement": "",
+      "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
+      "nonDuplicationRationale": "Existing workflow identity retained for caller compatibility and repository orchestration."
+    },
     {
       "id": "verify",
       "path": ".github/workflows/verify.yml",

package/docs/MAP.md

@@ -66,7 +66,7 @@ workflow, action, and Node API export also carries a `capabilityGroup`,
 | Publication Artifacts | `publication-registry.json`, `workflow-registry.json`, `node-api-registry.json`, `manual-registry.json`, `kungfu-buildchain-publication-artifact-registry` | [`publication-artifacts.md`](publication-artifacts.md), [`reusable-build-surface.md`](reusable-build-surface.md) |
 | Distribution Indexes and Badges | `badge-endpoint-registry.json`, `node-api-registry.json`, `manual-registry.json` | [`readme-badges.md`](readme-badges.md), [`homebrew.md`](homebrew.md) |
 | Build Facts, Observability, and Diagnostics | `cli-registry.json`, `node-api-registry.json`, lifecycle artifacts | [`build-facts.md`](build-facts.md), [`toolkit-observability.md`](toolkit-observability.md), [`consumer-issue-reporting.md`](consumer-issue-reporting.md) |
-| Governance, Versioning, and Runtime Drift | `buildchain-contract.json`, `workflow-registry.json`, `release-model.json` | [`github-governance-authority.md`](github-governance-authority.md), [`release-governance.md`](release-governance.md), [`release-flow.md`](release-flow.md), [`versioning.md`](versioning.md), [`runtime-train-validation.md`](runtime-train-validation.md), [`cli.md`](cli.md) |
+| Governance, Versioning, and Runtime Drift | `buildchain-contract.json`, `workflow-registry.json`, `release-model.json`, `schemas/v4-compatibility-facts-v1.schema.json` | [`v4-compatibility-facts.md`](v4-compatibility-facts.md), [`github-governance-authority.md`](github-governance-authority.md), [`release-governance.md`](release-governance.md), [`release-flow.md`](release-flow.md), [`next-development-transition.md`](next-development-transition.md), [`versioning.md`](versioning.md), [`runtime-train-validation.md`](runtime-train-validation.md), [`cli.md`](cli.md) |
 | CLI and Node API Reference | `cli-registry.json`, `node-api-registry.json`, `workflow-registry.json`, `manual-registry.json` | [`cli-reference.md`](cli-reference.md), [`node-api-reference.md`](node-api-reference.md), [`cli.md`](cli.md), [`../packages/core/README.md`](../packages/core/README.md) |
 
 | Capability | Machine-readable entry | Manual entry |
@@ -80,6 +80,7 @@ workflow, action, and Node API export also carries a `capabilityGroup`,
 | KFD-1 / KFD-2 / KFD-3 first-class CLI and Node API | `.buildchain/kfd/kfd-3/surfaces.json`, `dist/site/kfd-claims.json`, `buildchain.release.json`, KFD schemas from `@kungfu-tech/kfd` | [`kfd-support.md`](kfd-support.md), [`cli.md`](cli.md#commands) |
 | Declarative KFD Agent Hub adapter conformance and Passport evidence | `.buildchain/kfd/agent-hub.json`, `.buildchain/artifacts/kfd-agent-hub/evidence.json`, `buildchain.release.json#kfdAgentHub` | [`kfd-agent-hub.md`](kfd-agent-hub.md) |
 | Floating `@v3` drift detection and compatibility issues | `dist/site/buildchain-contract.json` | [`reusable-build-surface.md`](reusable-build-surface.md#floating-ref-contract-lock) |
+| Directional, Cut-bound v4 contract compatibility and legacy digest projections | `dist/site/buildchain-contract.json`, `dist/site/schemas/v4-compatibility-facts-v1.schema.json` | [`v4-compatibility-facts.md`](v4-compatibility-facts.md) |
 | npm publish transactions, evidence, dist-tags, and recovery | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`publish-transaction.md`](publish-transaction.md) |
 | Git/source/version/module/product build facts | `dist/site/node-api-registry.json`, `dist/site/cli-registry.json`, `kungfu-buildchain-module-build-facts`, `kungfu-buildchain-product-build-facts` | [`build-facts.md`](build-facts.md) |
 | GitHub Release passport/evidence publication | `dist/site/release-model.json`, `dist/site/artifact-schemas.json` | [`release-governance.md`](release-governance.md), [`release-candidate.md`](release-candidate.md) |
@@ -114,6 +115,7 @@ replace them.
 | What exact canonical bytes, roots, clocks, event, receipt, and typed-fault contracts do Rust and JavaScript share in v4? | [`v4-canonical-contracts.md`](v4-canonical-contracts.md) | use/verify | preview |
 | How is one per-platform v4 build stage identified, retained, observed, and reused without provider identity or a second writer? | [`v4-stage-capsule.md`](v4-stage-capsule.md) | use/verify | preview |
 | How does a late platform failure deterministically reuse qualified Stage Capsules and rebuild only invalid or missing dependencies? | [`v4-stage-capsule.md`](v4-stage-capsule.md#deterministic-resume-planning) | use/verify | preview |
+| How does a late macOS signing failure reuse an exact retained v4 Alpha candidate and rerun only the fenced release tail? | [`v4-tail-reseal.md`](v4-tail-reseal.md) | use/verify | preview |
 | How do Rust and JavaScript read the same retained Delivery Warrant traces and emit one semantic projection? | [`v4-canonical-contracts.md`](v4-canonical-contracts.md#shared-delivery-warrant-fixture-runner) | use/verify | preview |
 | How does an explicit caller try the qualified v4 read projection and roll back without moving v3 writer authority? | [`v4-delivery-warrant-read-candidate.md`](v4-delivery-warrant-read-candidate.md) | use/verify | preview |
 | How do protected dev branches and scheduled ready-PR merging work? | [`release-governance.md`](release-governance.md#protected-dev-branches) | use | stable |
@@ -125,6 +127,7 @@ replace them.
 | How do I report or safely apply branch and pull-request engineering hygiene? | [`engineering-housekeeper.md`](engineering-housekeeper.md) | use/verify | preview |
 | How does Buildchain decide patch, minor, and major release lines? | [`versioning.md`](versioning.md) | why | stable |
 | What exact branch/tag state machine runs on alpha, release, and major gate? | [`release-flow.md`](release-flow.md) | verify | stable |
+| How does a completed Alpha remain successful while the following development version is prepared? | [`next-development-transition.md`](next-development-transition.md), [`../architecture/decisions/0002-next-development-transition.md`](../architecture/decisions/0002-next-development-transition.md) | verify/use | preview |
 | What did Buildchain migrate or retire from old action repositories? | [`migration-inventory.md`](migration-inventory.md) | verify | stable |
 | What is the active action and workflow source of truth? | [`ownership.md`](ownership.md) | verify | stable |
 | How do I declare version files and custom lifecycle commands? | [`lifecycle-protocol.md`](lifecycle-protocol.md) | use | stable |

package/docs/cli-reference.md

@@ -728,6 +728,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 +1630,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`
@@ -2237,6 +2305,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/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/dev-delivery-warrant.md

@@ -383,8 +383,10 @@ The reusable `dev-pr-auto-merge.yml` supports three explicit rollout modes:
   The shipped Buildchain caller and native template configure this handoff path
   and accept the same complete input contract. A historical phase-less owner
   uses the distinct `legacy-phase-less-active-owner` command path. That path
-  carries the exact queue state root, fencing token, generation, PR, head, and
-  source-run binding, omits `environment-root`, `native-command`, and
+  carries the exact queue state root observed before its duplicate submission,
+  fencing token, generation, PR, head, and source-run binding. The submission
+  receipt proves that pre-transition root even though the queue transition
+  advances the current state root. The path omits `environment-root`, `native-command`, and
   `native-command-root`, and rejects readback drift. It therefore resumes the
   historical non-native authority without inventing a native command contract
   or upgrading the owner to native proof authority.
@@ -471,8 +473,10 @@ consumer workflow. It supports both explicit dispatch and the bounded wake
 event, calls the allowed floating `@v4-alpha` selector, explicitly passes the v4
 runtime ref that locks every delivery job to the same checkout, and keeps the
 native command in the consumer repository rather than inventing
-provider-specific shards. The reusable workflow defaults that explicit input
-to `v4-alpha`; an empty input or any v3 selector fails before the first runtime
+provider-specific shards. Both callers explicitly bind the queue-admission
+and active-lease status contexts so write/readback fencing uses the same exact
+names. The reusable workflow defaults the explicit runtime input to
+`v4-alpha`; an empty input or any v3 selector fails before the first runtime
 checkout.
 
 This mechanism schedules protected delivery only. It does not serialize local

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/`.