@kungfu-tech/buildchain 3.0.9-alpha.9 → 4.0.0-alpha.0

package/docs/dev-delivery-qualification-landing-adr.md

@@ -1,137 +0,0 @@
----
-status: accepted
-period: ongoing
-theme: dev-delivery-qualification-landing-authority
-doc_type: architecture-decision-record
-source_level: local-files
-confidence: high
-sensitivity: public
-evidence_grade: A
-review_state: self-reviewed
-last_reviewed: 2026-08-12
----
-
-# ADR: Qualification Leases and the exclusive Landing Warrant
-
-## Decision
-
-Buildchain has two explicit protected-dev authority modes:
-
-1. `single-flight-warrant` is the default and continues to use the
-   `kungfu-buildchain-dev-delivery-warrant-queue` v1 state and
-   `buildchain dev warrant` commands unchanged.
-2. `bounded-qualification-landing` is opt-in and uses the
-   `kungfu-buildchain-dev-delivery-authority` v2 state. It may issue up to the
-   configured number of Qualification Leases, but it may issue exactly one
-   Landing Warrant.
-
-The modes use different contracts, state refs, and CLI command families. There
-is no implicit reinterpretation of a v1 Warrant. A consumer turns the new mode
-on only by explicitly migrating the exact current v1 state and deploying the
-v2 controller against the dedicated
-`buildchain/dev-delivery-authority/<dev-line>` state ref.
-
-Migration preserves the immutable v1 `stateRoot`, candidate identity, source
-and proof roots, fencing token, generation, and lease times in a rooted
-migration receipt. An active provisional Warrant becomes a
-qualification-only lease and remains unable to admit `merge_group`; an active
-qualified Warrant becomes the one exclusive Landing Warrant. The migration is
-one-shot: a v2 state is never accepted as v1 input, and source/evidence bytes
-are not regenerated. The legacy ref remains immutable rollback evidence.
-
-## Authority invariants
-
-A Qualification Lease carries:
-
-- `authority = qualification-only`;
-- `mergeGroupAdmission = false`;
-- one exact candidate id, token, generation, issue time, and expiry; and
-- a place in a list bounded by `policy.maxQualificationLeases`.
-
-It authorizes expensive qualification work only. It cannot authorize GitHub
-`merge_group`, cannot be upgraded in place to landing authority, and is removed
-when qualification evidence is recorded. Each new candidate declares a sorted
-set of rooted `qualificationDomains`. Candidates with disjoint sets may hold
-leases concurrently. An overlapping set is serialized; an empty set is treated
-as unknown and therefore conflicts with every active candidate. The scheduler
-returns a content-rooted reason for either refusal.
-
-The Landing Warrant carries:
-
-- `authority = merge-group-admission`;
-- `mergeGroupAdmission = true`;
-- one exact qualified candidate id, token, generation, issue time, and expiry;
-  and
-- the only non-null `landingWarrant` slot in the durable state.
-
-Only `admitDevDeliveryMergeGroup` and `buildchain dev authority
-admit-merge-group` consume Landing authority. They bind the exact current state
-root, candidate, protected base, source head, merge-group head, token, and
-generation. A Qualification Lease fails closed at this boundary.
-
-The state normalizer rejects a lease beyond the configured bound, duplicate
-Qualification Leases for one candidate, a candidate holding qualification and
-Landing authority together, a Landing Warrant without its exact landing
-candidate, and any state-root drift. Git expected-old, non-force ref advancement
-continues to serialize durable mutations. These checks retain the existing
-two-phase safety rule: source/native qualification is evidence, while the
-exclusive final authority is candidate- and integration-specific.
-
-## Bounded scheduler and recovery
-
-Landing selection is FIFO among candidates that have completed qualification.
-When a later candidate receives a Landing Warrant, each older nonterminal
-candidate consumes one durable overtake from its
-`policy.maxLandingOvertakes` budget. Once an older candidate reaches that
-bound, later candidates cannot receive a Warrant. The older candidate receives
-the next landing priority after qualification, or reaches a rooted terminal
-failure after `policy.maxQualificationAttempts` heartbeat expiries. This makes
-the bound independent of controller restart frequency or later arrival rate;
-setting it to zero enforces strict FIFO landing priority.
-
-Qualification Leases and Landing Warrants both support fenced heartbeats. A
-missed heartbeat is recovered at expiry; recovery releases capacity and emits
-a deterministic content-rooted wake instruction for the next domain-eligible
-qualification candidates and the next fair landing candidate. Completion,
-cancellation, terminal failure, dequeue, and already-merged settlement emit the
-same wake shape. Exact duplicate heartbeats, recovery, and terminal events are
-state-root-preserving no-ops. Competing controllers still commit through one
-expected-old, non-force ref update, so only one transition can become durable.
-
-## Terminal settlement
-
-Terminal provider evidence is authoritative cleanup input. A matching merged,
-failed, dequeued, or cancelled candidate releases its Qualification Lease or
-Landing Warrant in the same expected-old state transition, even when the lease
-TTL has not expired. An active authority requires its exact token and
-generation for that transition. Repeating the same outcome and evidence is a
-root-preserving no-op; outcome or evidence drift fails closed. A terminal event
-for a candidate that never entered the state is also an explicit no-op.
-
-TTL recovery remains crash recovery, not the normal terminal cleanup path.
-
-## Public contract
-
-- Machine schema:
-  [`contracts/dev-delivery-authority-v2.schema.json`](../contracts/dev-delivery-authority-v2.schema.json),
-  packaged as `dist/site/schemas/dev-delivery-authority-v2.schema.json`.
-- Node API: `@kungfu-tech/buildchain/dev-delivery-authority` exports the v2
-  state, migration, lease, heartbeat, recovery, Landing, admission,
-  observation, and settlement functions. `@kungfu-tech/buildchain/dev-delivery-warrant`
-  remains byte- and behavior-compatible for v1 consumers.
-- CLI: `buildchain dev authority
-<migrate|submit|lease-qualification|heartbeat-qualification|complete-qualification|lease-landing|heartbeat-landing|recover|admit-merge-group|settle|observe>`.
-- Generated references: [`cli-reference.md`](cli-reference.md) and
-  [`node-api-reference.md`](node-api-reference.md).
-
-All mutations are plan-only unless `--execute` is supplied. Merge-group
-admission is always a read-only authority check; it never mutates GitHub Merge
-Queue itself.
-
-## Consequences
-
-Qualification throughput can increase without increasing the number of
-candidates permitted to land. Consumers retain the byte- and behavior-compatible
-single-flight default until they deliberately deploy the v2 mode. The tradeoff
-is a second state contract and controller family; Buildchain keeps that
-separation explicit so a rollout cannot silently weaken Warrant semantics.

package/docs/next-development-transition.md

@@ -1,119 +0,0 @@
----
-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/`.

package/docs/publication-rehearsal.md

@@ -1,94 +0,0 @@
----
-status: preview
-period: 2026-08-08
-theme: buildchain-publication-rehearsal
-doc_type: product-manual
-source_level: local-files
-confidence: high
-sensitivity: public
-evidence_grade: A
-review_state: self-reviewed
-last_reviewed: 2026-08-08
-ai_provenance:
-  model_family: GPT-5
-  product: Codex
-  generated_at: 2026-08-08
-  visible_context: Public rehearsal capsule runtime, release-tail provider plane, CLI, Action, workflow, and generated consumer surfaces.
-  invisible_context_boundary: No credentials, private provider state, signed URLs, or external publication receipts were read.
----
-
-# Publication rehearsal
-
-Buildchain publication rehearsal runs the deterministic release tail locally
-from one `kungfu.buildchain.publication-rehearsal-capsule/v1` document. The
-normative rule is [ADR 0001](../architecture/decisions/0001-release-local-constructibility.md):
-every non-external release behavior must be locally constructible, and no
-semantic path may depend on GitHub runner state.
-
-The machine-readable shape is
-[`publication-rehearsal-capsule-v1.schema.json`](../contracts/publication-rehearsal-capsule-v1.schema.json).
-
-## Exact local command
-
-Run from the repository root after restoring the content-addressed candidate:
-
-```sh
-buildchain release-tail rehearse \
-  --capsule "$PWD/.buildchain/publication/rehearsal-capsule.json" \
-  --capsule-root "$PWD/.buildchain/publication/candidate" \
-  --mode simulate \
-  --state "$PWD/.buildchain/publication/rehearsal-state.json" \
-  --evidence "$PWD/.buildchain/publication/rehearsal-evidence.json"
-```
-
-Use `--mode replay` only when the capsule contains a complete recorded
-provider-response sequence. Both modes produce rooted evidence with
-`externalPublicationClaimed: false`.
-
-## Daily fixture and sealed-candidate modes
-
-For daily development, build a synthetic capsule with
-`createPublicationRehearsalCapsule`, use synthetic files and provider
-observations, and run `--mode simulate` or `--mode replay`. This fixture mode is
-for deterministic regression evidence only.
-
-Before publication qualification, restore the exact sealed candidate bytes,
-Passport, policy roots, initial transaction and recorded observations named by
-the retained capsule, then run the exact command above. Preserve the resulting
-binding root, transaction root, state root, receipt roots and evidence root.
-These roots qualify deterministic construction only; external publication and
-public readback still require their own authorities.
-
-## Capsule contents
-
-The capsule root commits to the release-tail declaration, ordered policy roots,
-Passport path/root, initial durable transaction, complete file inventory,
-data-only provider bindings, recorded observations, portable platform policy,
-declared environment keys, and the exact list of external effects. Every input
-file is a regular non-symlink file under the explicit absolute capsule root and
-must match its size and SHA-256 root.
-
-The CLI never reads `GITHUB_*`, infers a runner workspace, selects behavior from
-`process.platform`, or accepts executable hooks. An explicit environment JSON
-object must match the capsule declaration exactly.
-
-## Hosted parity
-
-The reusable `release-tail.yml` workflow passes the explicit capsule to the
-`actions/release-tail` wrapper. The wrapper supplies only GitHub/HTTP transport
-and declared secret inputs, then invokes the same
-`executePublicationRehearsal` public core used locally. Provider requests,
-responses, failures, transaction roots, receipt roots, and the final evidence
-root are retained together.
-
-Simulation or replay is development evidence. Provider mode can record real
-external observations, but it still does not replace Release Passport,
-attestation, registry, activation, public-readback, or protected-delivery
-authority.
-
-## Failure handling
-
-Diagnostics use
-`kungfu.buildchain.publication-rehearsal-diagnostic/v1`. Preserve the capsule,
-diagnostic root, binding root, and exact failed files. Repair the shared core or
-capsule locally and rerun before spending another hosted runner attempt.