@kungfu-tech/buildchain 3.0.7 → 3.0.8

package/docs/release-governance.md

@@ -723,13 +723,13 @@ status to failure, while the merge group must still produce its own final check.
 that want a stable day-to-day operations contract, Buildchain also exposes a
 patrol workflow family:
 
-| Workflow | Intended cadence | Default intent |
-| --- | --- | --- |
-| `.github/workflows/patrol-daily.yml` | daily | lightweight inspection plus ready dev PR maintenance |
-| `.github/workflows/patrol-weekly.yml` | weekly | release-state, passport, gate, and stale-state health checks as they are added |
-| `.github/workflows/patrol-monthly.yml` | monthly | governance, permission, branch-protection, and workflow drift checks as they are added |
-| `.github/workflows/patrol-observed-evidence.yml` | caller-selected schedule | validated immutable observation plus atomic last-known-good publication; no per-refresh PR |
-| `.github/workflows/stable-candidate-patrol.yml` | repository-selected release window | qualify immutable alpha candidates and open the exact source-lock stable PR |
+| Workflow                                         | Intended cadence                   | Default intent                                                                             |
+| ------------------------------------------------ | ---------------------------------- | ------------------------------------------------------------------------------------------ |
+| `.github/workflows/patrol-daily.yml`             | daily                              | lightweight inspection plus ready dev PR maintenance                                       |
+| `.github/workflows/patrol-weekly.yml`            | weekly                             | release-state, passport, gate, and stale-state health checks as they are added             |
+| `.github/workflows/patrol-monthly.yml`           | monthly                            | governance, permission, branch-protection, and workflow drift checks as they are added     |
+| `.github/workflows/patrol-observed-evidence.yml` | caller-selected schedule           | validated immutable observation plus atomic last-known-good publication; no per-refresh PR |
+| `.github/workflows/stable-candidate-patrol.yml`  | repository-selected release window | qualify immutable alpha candidates and open the exact source-lock stable PR                |
 
 The cadence names describe patrol intensity, not release cadence:
 
@@ -792,9 +792,12 @@ The separate workflow names keep consumer schedules readable and stable while
 Buildchain adds new checks behind the cadence wrappers.
 
 Branch and pull-request residue uses the separate
-[`Engineering Housekeeper`](engineering-housekeeper.md) contract. Its scheduled
-callers are report-only and read-only by default; apply requires a manual,
-explicit two-part gate, exact provider-state revalidation, scoped job
+[`Engineering Housekeeper`](engineering-housekeeper.md) contract. Its reusable
+surface remains report-first, while Buildchain's committed daily, weekly, and
+monthly callers run unattended apply across all discovered protected mainlines.
+Only the positive temporary-development allowlist is mutable; unknown branch
+families remain report-only. Every apply still requires the caller's explicit
+two-part policy inputs, exact provider-state revalidation, scoped job
 permissions, and rooted plan/report/receipt evidence.
 
 ## Package-Manager Adapters

package/docs/release-train.md

@@ -0,0 +1,102 @@
+---
+status: preview
+period: ongoing
+theme: buildchain-release-train
+doc_type: architecture-and-usage
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-10
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-10
+  visible_context: Buildchain v3 release candidate, recovery, Dev to Alpha Candidate Patrol, Warrant, publication transaction, and release governance sources.
+  invisible_context_boundary: Live provider state and credentials were not read.
+---
+
+# Release Train and Release Cut
+
+Buildchain v3 exposes a pure, provider-neutral Release Train contract for
+retaining one authorized Alpha candidate while the development branch keeps
+moving. The contract does not select a candidate, write a Git ref, open a pull
+request, publish a package, or replace any existing provider gate. Controllers
+own those effects and persist the rooted contract in their declared store.
+
+## Frozen Release Cut
+
+`createReleaseCut()` records one exact candidate generation. It binds:
+
+- repository, source branch, and target branch;
+- the development head from which the cut was authorized;
+- candidate commit and tree;
+- exact Alpha base and Buildchain runtime commits;
+- a positive generation;
+- sorted, duplicate-free authority roots; and
+- a canonical creation timestamp.
+
+The resulting `cutRoot` covers all of those fields. A generation greater than
+one must name the prior cut root and one of four supersession causes:
+
+- `incompatible-semantics`;
+- `alpha-base-incompatibility`;
+- `invalid-authority`; or
+- `severe-security`.
+
+Latest-development movement is deliberately absent from that list. Merely
+observing a newer development head therefore cannot replace the candidate or
+increment its generation.
+
+## Release Train state
+
+`createReleaseTrain()` wraps the frozen cut in
+`kungfu-buildchain-release-train/v1`. The train identity root covers only the
+immutable Release Cut. Its state chain can move through:
+
+```text
+preparing -> building -> publication-blocked -> publishable -> terminal
+                   \-> repair-required --------^          \-> superseded
+```
+
+The complete transition table is enforced by the Node API. `superseded` and
+`terminal` are terminal states. A superseded transition must bind its explicit
+cause, replacement cut root, and replacement candidate commit.
+
+Every transition uses compare-and-swap against the exact current `stateRoot`,
+binds non-empty authority roots, and produces deterministic request,
+transition, and next-state roots. Replaying the exact same request after it has
+already landed returns the existing train unchanged. A stale expected state or
+an invalid transition fails closed.
+
+`observeReleaseTrain()` appends a rooted development-head observation without
+changing `trainRoot`, `cutRoot`, candidate identity, generation, or state. The
+same exact observation is idempotent.
+
+## Readback and legacy state
+
+`validateReleaseCut()` checks the standalone immutable cut and its canonical
+root. `validateReleaseTrain()` replays the complete transition and observation
+chain from that frozen cut and rejects root drift, stale compare-and-swap
+edges, duplicate observations, or an invalid lifecycle path.
+
+`readReleaseTrain()` also recognizes the existing
+`kungfu-buildchain-dev-alpha-candidate-state/v1` patrol marker. That path is a
+read-only compatibility projection with `authoritative: false` and `train:
+null`. It exposes the legacy generation and candidate SHA when present, but it
+never invents a Release Cut, authority root, runtime binding, Alpha base, or
+candidate tree retroactively. A controller must create a new, fully witnessed
+Release Cut before it can claim Release Train authority.
+
+## Public API and schemas
+
+Import the contract from `@kungfu-tech/buildchain/release-train`. Machine
+schemas are published with the package:
+
+- `contracts/release-cut-v1.schema.json`;
+- `contracts/release-train-v1.schema.json`; and
+- `contracts/release-train-transition-v1.schema.json`.
+
+The schemas check structure. The Node validator remains authoritative for
+canonical roots, state-chain replay, idempotence, and cross-field semantics.

package/docs/reusable-build-surface.md

@@ -338,7 +338,8 @@ ref is not blind trust. Each released Buildchain ref carries a package-owned
 runtime contract world in `dist/site/buildchain-contract.json`. Consumers may
 keep a small lock file, `.buildchain/contract-lock.json`, recording the
 Buildchain ref, resolved SHA, contract digest, compatibility digest, accepted
-major line, and compatibility policy they reviewed.
+major line, compatibility proof registry root, per-surface proof roots, and the
+compatibility policy they reviewed.
 
 The reusable build trust gate checks this lock before any heavy matrix job:
 
@@ -355,6 +356,14 @@ promise changes, or the major line changes. Additive changes such as optional
 inputs, optional outputs, diagnostics, or documentation updates continue under
 the default `major-compatible` policy.
 
+A changed breaking digest is never accepted because it appears in a handwritten
+allowlist. Each historical digest must resolve to exactly one immutable,
+directed compatibility proof for the current surface digest. The proof binds
+the operation scope, protected authority, exact Git cut, and protected-merge
+evidence. The legacy `compatibleBreakingDigests` arrays remain in the site
+contract only as deterministic, parity-checked projections of those proofs;
+an orphan digest or ambiguous proof fails source acceptance.
+
 ```yaml
 jobs:
   build:
@@ -371,11 +380,12 @@ jobs:
 
 When compatible drift is detected, the build continues and Buildchain opens or
 updates a low-priority issue in the consumer repository. The issue records the
-old SHA/digest, new SHA/digest, compatibility result, workflow run, and the next
-action: review the Buildchain release notes and update the lock. When breaking
-drift is detected, the same issue path is used, but the trust gate fails before
-matrix build or publish work starts. If the workflow token cannot write issues,
-Buildchain writes a copyable issue body into the job summary.
+old SHA/digest, new SHA/digest, compatibility result, workflow run, exact proof
+root, direction, scope, evidence, authority, cut, and rooted verification
+receipt. When breaking drift is detected, the same issue path is used, but the
+trust gate fails before matrix build or publish work starts. If the workflow
+token cannot write issues, Buildchain writes a copyable issue body into the job
+summary.
 
 The lock is intentionally small. It does not copy the full contract. The full
 contract remains in the Buildchain ref and package; the consumer records only

package/docs/site-bundle-contract.md

@@ -54,7 +54,11 @@ overview, and fixture guides.
 `buildchain-contract.json` is the machine-readable Buildchain runtime contract
 world used by floating-ref contract locks. It records public workflow/action/CLI
 surfaces, compatibility digests, and audit digests for the files that implement
-those surfaces.
+those surfaces. Its immutable compatibility proofs bind historical breaking
+digests to exact target surfaces, operation scopes, protected authority,
+evidence, and Git cuts. `compatibleBreakingDigests` and per-surface proof-root
+lists are generated projections; site consumers must not edit or reinterpret
+them as independent authority.
 `manual-registry.json` enumerates the packaged Markdown manuals with source
 digests so an agent can find complete operating documentation from the npm
 artifact. `node-api-registry.json` enumerates public Node import surfaces from

package/docs/versioning.md

@@ -79,6 +79,7 @@ repository changes are patch".
 
 | Date       | Action       | Line    | Faces                                                                                                                                                                        | Class    | Rationale                                                                                                                                                                                                                                                                                                                              | PR    |
 | ---------- | ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| 2026-08-10 | extend-minor | `v3.0`  | release-cut-contract, release-train-state-machine, release-train-node-export                                                                                                | additive | Add a provider-neutral rooted Release Cut and idempotent Release Train state contract that freezes candidate, tree, Alpha base, runtime, generation, and authority while treating later Dev movement as observation rather than implicit supersession.                                                                                 |       |
 | 2026-08-05 | extend-minor | `v3.0`  | auditable-demo-scenario, auditable-demo-capture, auditable-demo-adapter                                                                                                      | additive | Add an opt-in deterministic readable-playback declaration that preserves captured terminal payloads and order while normalizing only presentation timing; omitted playback continues to use observed PTY timestamps, and existing composition modes remain unchanged.                                                                 |       |
 | 2026-08-04 | extend-minor | `v3.0`  | dev-delivery-warrant-queue, source-qualification-proof, integration-delivery-proof, dev-delivery-cli, reusable-dev-delivery-workflows                                        | additive | Add durable fair and fenced protected-dev scheduling plus split source/integration proof contracts. Existing PR admission remains available through explicit `off` and `shadow` rollout modes; no existing command, export, or release flow is removed.                                                                                |       |
 | 2026-08-01 | extend-minor | `v3.0`  | cli-reference-registry, node-api-symbol-registry, golden-path-manual                                                                                                         | additive | Add generated, drift-checked CLI and Node API reference registries to the public site bundle, plus a package-tested first-user Golden Path; existing command execution and import semantics remain unchanged.                                                                                                                          |       |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "3.0.7",
+  "version": "3.0.8",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -54,6 +54,7 @@
     "./kfd-gate": "./packages/core/kfd-gate.js",
     "./release-candidate": "./packages/core/release-candidate.js",
     "./release-candidate-recovery": "./packages/core/release-candidate-recovery.js",
+    "./release-train": "./packages/core/release-train.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/packages/core/buildchain-agent-manuals.js

@@ -9,6 +9,7 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "publication-authority", title: "Sealed publication authority", path: "docs/publication-authority.md", plane: "verify" },
   { id: "github-governance-authority", title: "GitHub governance authority", path: "docs/github-governance-authority.md", plane: "verify" },
   { id: "release-candidate", title: "Release Candidate Passport", path: "docs/release-candidate.md", plane: "verify" },
+  { id: "release-train", title: "Release Train and Release Cut", path: "docs/release-train.md", plane: "verify" },
   { id: "release-propagation", title: "Release propagation", path: "docs/release-propagation.md", plane: "use" },
   { id: "readme-badges", title: "README badge blocks", path: "docs/readme-badges.md", plane: "use" },
   { id: "homebrew", title: "Homebrew distribution indexes", path: "docs/homebrew.md", plane: "use" },