@kungfu-tech/buildchain 3.0.9-alpha.2 → 3.0.9-alpha.3

package/dist/site/public-surface-audit.json

@@ -6,7 +6,7 @@
     "cliCommandCount": 114,
     "workflowCount": 69,
     "actionCount": 7,
-    "sitePageCount": 71,
+    "sitePageCount": 72,
     "docCommandRefCount": 924,
     "failureCount": 0
   },
@@ -3266,6 +3266,10 @@
         "id": "manual:migration-inventory",
         "category": "manual"
       },
+      {
+        "id": "manual:next-development-transition",
+        "category": "manual"
+      },
       {
         "id": "manual:node-api-reference",
         "category": "manual"
@@ -8003,8 +8007,8 @@
     "workflowRegistryPath": "dist/site/workflow-registry.json",
     "pageRegistryPath": "dist/site/page-registry.json",
     "cliRegistryDigest": "099c0db9c5346942aee236af2cb7b6a7a91fbb2c54ebb17b7a2544a339c00d40",
-    "workflowRegistryDigest": "65c832629ee164235674ec4da7cd1bc47229fae1152d7487d09876d03d7ded91",
-    "pageRegistryDigest": "adfef59fcc28508390dac4c634a65b52e49f8500545ac86fbdad1134ed480bc5"
+    "workflowRegistryDigest": "9ab17af52207b301bb5876f8a4c314706a2d2aeb9e9270351f0da67bd0bd5a67",
+    "pageRegistryDigest": "00c95f4f0f75fcaa386b9b615d692cae622dbf9bd854aa62357d0b8dce310955"
   },
   "comparison": {
     "missingCliRegistry": [],

package/dist/site/publication-registry.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-publication-release-registry",
-  "generatedAt": "2026-08-11T09:59:20.000Z",
-  "publishedAt": "2026-08-11T09:59:20.000Z",
+  "generatedAt": "2026-08-11T13:41:03.000Z",
+  "publishedAt": "2026-08-11T13:41:03.000Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "dbad2f383a6ab93abd192c4edefb4689c9eebc78",
+  "sourceRevision": "9362236c143df3d0e65c3746dbaa8e06923d08f6",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -32,7 +32,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "3.0.9-alpha.2",
+    "version": "3.0.9-alpha.3",
     "versionSource": "package.json#version"
   },
   "sourceKind": "package-site-bundle",

package/dist/site/release-provenance.json

@@ -54,6 +54,9 @@
       "./release-candidate": "./packages/core/release-candidate.js",
       "./release-candidate-recovery": "./packages/core/release-candidate-recovery.js",
       "./release-train": "./packages/core/release-train.js",
+      "./next-development-transition": "./packages/core/next-development-transition.js",
+      "./next-development-controller": "./packages/core/next-development-controller.js",
+      "./next-development-projection": "./packages/core/next-development-projection.js",
       "./stable-candidate-ledger": "./packages/core/stable-candidate-ledger.js",
       "./release-passport": "./packages/core/release-passport.js",
       "./release-passport-contract": "./packages/core/release-passport-contract.js",

package/dist/site/site-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "contract": "kungfu-buildchain-site-manifest",
-  "generatedAt": "2026-08-11T09:59:20.000Z",
-  "publishedAt": "2026-08-11T09:59:20.000Z",
+  "generatedAt": "2026-08-11T13:41:03.000Z",
+  "publishedAt": "2026-08-11T13:41:03.000Z",
   "reproducible": true,
   "timestampPolicy": "ci-injected",
   "deterministicInputs": [
@@ -19,7 +19,7 @@
     "declared Buildchain surface manifest contract"
   ],
   "sourceDateEpoch": "0",
-  "sourceRevision": "dbad2f383a6ab93abd192c4edefb4689c9eebc78",
+  "sourceRevision": "9362236c143df3d0e65c3746dbaa8e06923d08f6",
   "timestampPolicyDetails": {
     "contract": "kungfu-buildchain-surface-timestamp-policy",
     "timestampFields": [
@@ -37,7 +37,7 @@
   },
   "package": {
     "name": "@kungfu-tech/buildchain",
-    "version": "3.0.9-alpha.2",
+    "version": "3.0.9-alpha.3",
     "versionSource": "package.json#version"
   },
   "entrypoint": "buildchain-site.json",
@@ -53,7 +53,7 @@
       "path": "docs/MAP.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:5292461118df2ec99a15411b6ed50c288abeb05d992677e3500b9bd46255a001"
+      "digest": "sha256:a1c408b13658f225113ede0ee4f4309cbae466178e8f248f4290a616ce39194c"
     },
     {
       "id": "getting-started",
@@ -135,6 +135,14 @@
       "exists": true,
       "digest": "sha256:5ec5534ee48790df09c71a2578e1ca364a14dadf6ba662685ee66f78ae2589e7"
     },
+    {
+      "id": "next-development-transition",
+      "title": "Next-development transition",
+      "path": "docs/next-development-transition.md",
+      "plane": "verify",
+      "exists": true,
+      "digest": "sha256:93b2687be0e36744cb7b0b9d0d76588d89569120ffdb577f13c8c0827988ba28"
+    },
     {
       "id": "release-propagation",
       "title": "Release propagation",
@@ -245,7 +253,7 @@
       "path": "docs/node-api-reference.md",
       "plane": "use",
       "exists": true,
-      "digest": "sha256:bbef23e4f489376f759e5678d61e2f07c69dfa5542f5538e14c68a0714233ea3"
+      "digest": "sha256:cf2137143bb567a11430cf35c3faaff7e16861af4e68554af5cbea1b3a0a1077"
     },
     {
       "id": "build-facts",
@@ -349,7 +357,7 @@
       "path": "docs/versioning.md",
       "plane": "why",
       "exists": true,
-      "digest": "sha256:68934ebe8330a13376d1b71d1a875d67d2970b1036e0f185a923175ca2a257fe"
+      "digest": "sha256:948957c9170437e2a383efba01d99d9b137ef56ce71ae8036545daaed625d09c"
     },
     {
       "id": "web-surface-deployments",

package/dist/site/workflow-registry.json

@@ -1961,7 +1961,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "3.0.9-alpha.2",
+      "introducedVersion": "3.0.9-alpha.3",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -1982,7 +1982,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "3.0.9-alpha.2",
+      "introducedVersion": "3.0.9-alpha.3",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -2003,7 +2003,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "3.0.9-alpha.2",
+      "introducedVersion": "3.0.9-alpha.3",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",
@@ -2053,7 +2053,7 @@
       "status": "preview",
       "owner": "buildchain-workflows",
       "maturity": "preview",
-      "introducedVersion": "3.0.9-alpha.2",
+      "introducedVersion": "3.0.9-alpha.3",
       "compatibilityPromise": "preserved-through-the-v3-major-line",
       "deprecationReplacement": "",
       "sunsetCondition": "explicit-breaking-change-review-in-a-future-major-line",

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` | [`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 |
@@ -118,6 +118,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/aws-us-elastic-runner-burst-plane.md

@@ -380,7 +380,7 @@ host, including at least one full run, plus proof that:
 ### Phase 3 lifecycle controller
 
 `scripts/aws-macos-jit-controller.mjs` is the operator boundary for the paid
-campaign. It has four explicit mutation modes:
+campaign. It has five explicit mutation modes:
 
 - `launch-campaign` binds the exact repository source, AMI, availability zone,
   tagged Dedicated Host, and reusable instance. Before paid allocation it
@@ -390,6 +390,12 @@ campaign. It has four explicit mutation modes:
   a DryRun parameter for `AllocateHosts`, it requires an allowed IAM policy
   simulation for the exact tagged allocation before the real call, then a
   successful `RunInstances` DryRun before launching the instance.
+- `rehydrate-instance` creates a replacement instance on the one already-paid,
+  empty campaign host after an interrupted or failed instance lifecycle. It
+  rechecks the exact account, disabled workflow, Budget, source, host identity
+  and allocation time, zero runner residue, zero active JIT instances, and no
+  other active Mac host in either admitted region. It then requires a
+  successful same-host `RunInstances` DryRun and never calls `AllocateHosts`.
 - `run-job` binds one queued exact-source GitHub job to the existing campaign
   host and instance. It writes the repository JIT configuration through a
   mode-0600 temporary file into a distinct SSM SecureString, sends only the
@@ -417,8 +423,10 @@ through `--confirm-source-sha` and `--confirm-campaign-id`. `run-job` also
 requires `--confirm-run-id`; `launch-campaign` additionally requires the
 expected workload account through `--account-id`. `rebind-campaign`
 additionally repeats the prior source, host, and instance identities and
-requires `--confirm-zero-allocation`. Omitting `--execute` emits a deterministic
-plan without changing AWS or GitHub state.
+requires `--confirm-zero-allocation`. `rehydrate-instance` additionally repeats
+the existing host and replaced instance identities and requires
+`--confirm-no-host-allocation`. Omitting `--execute` emits a deterministic plan
+without changing AWS or GitHub state.
 
 ## Provider lifecycle
 

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,119 @@
+---
+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.
+
+## Hosted self-dogfood and adoption
+
+`.github/workflows/buildchain-alpha-self-dogfood.yml` calls the same public
+`build.yml@v3-alpha` router as a consumer. After the hosted build succeeds, one
+runner uses the real version-state adapter and checkpoints an injected transient
+durable-state write failure. A separate runner restores the adapter operation
+without rebuilding Alpha, supersedes it when protected Dev moves, and preserves
+`pr-pending` while the protected PR is delayed. The final artifact roots the
+exact runtime SHA, controller transaction, both legal version-model outcomes,
+and an exact hosted protected Dev readback. Stable qualification recomputes and
+rejects evidence that omits or drifts any of those bindings.
+
+Production consumers, including Kungfu, adopt the proved contract through
+`kungfu-systems/buildchain/.github/workflows/build.yml@v3`. The evidence retains
+the exact resolved SHA for audit, but the committed production coordinate is the
+floating major contract rather than an exact-SHA pin.
+
+## 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/`.