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

package/architecture/v4-delivery-warrant-shadow-bootstrap-plan.md

@@ -0,0 +1,223 @@
+---
+status: draft
+period: ongoing
+theme: buildchain-v4-delivery-warrant
+doc_type: architecture-plan
+source_level: local-files-and-public-evidence
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-08-08
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-08
+  invisible_context: not asserted
+---
+
+# Delivery Warrant v4 Shadow and Bootstrap Plan
+
+This plan makes the current Delivery Warrant behavior implementable as a
+provider-free Rust domain without changing production authority. The normative
+machine-readable plan is
+[`v4-delivery-warrant-shadow-bootstrap-plan.json`](./v4-delivery-warrant-shadow-bootstrap-plan.json).
+The shared traces and frozen JavaScript projection roots are in
+[`v4-delivery-warrant-shadow-fixtures.json`](./v4-delivery-warrant-shadow-fixtures.json).
+
+## Decision
+
+TypeScript v3 remains the sole production writer through shadow and v4-read.
+Rust may decide and fold the same canonical events, but it emits only a
+non-authoritative projection until an independently reviewed protected revision
+passes every write-cutover gate. At cutover there is still one authority: Rust
+owns pure decision/fold and one TypeScript adapter owns ordered effects. A
+per-request authority switch and permanent dual writes are forbidden.
+
+The bootstrap authority is exact, not narrative:
+
+- v3 authority revision: `b9fbfd9d6ee909ee3a8c4bd6116e7ddafd7b05e1`
+- qualified v4 bootstrap revision: `d827bb223e4b78551feed69827f3e67839821171`
+- qualification root:
+  `sha256:ea58bf84bd8ba32d0d7931328a2209f937bd3b81d3215b27f2ca67abc704a673`
+- candidate self-qualification: forbidden
+- later authority: the exact prior qualified protected v4 revision (N-1)
+
+## Source audit
+
+The plan is grounded at repository revision
+`3fd14c7a6237c3a1709ce29fc9fcb4ac150a0e5d` and preserves the current v3
+inventory rather than reconstructing it from workflow prose.
+
+| Concern                                          | Source of record                                                                   | Result                                                                       |
+| ------------------------------------------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Current states, events, writers, stores, effects | `v3-core-mechanism-inventory.json` and `v4-capability-state-machine-manifest.json` | Nine states, seven manifest events, TypeScript v3 sole writer                |
+| Queue roots, generation, selection, leases       | `packages/core/dev-delivery-warrant.js`                                            | Rooted successors, bounded FIFO/aging, one active fence                      |
+| Terminal behavior                                | settlement and cancellation modules plus Warrant tests                             | Active fenced close, exact queued cancellation, terminal/no-authority no-ops |
+| Durable compare-and-set                          | `scripts/dev-delivery-warrant.mjs`                                                 | Immutable Git commit plus expected commit/root readback                      |
+| Protected effects                                | Buildchain dev delivery, close, and cancel workflows                               | GitHub admission occurs after exact state readback                           |
+| Bootstrap and N-1                                | `v4-bootstrap-authority.json` and `v4-architecture.mjs`                            | v3 bootstrap authority, protected v4 handoff, no self-qualification          |
+
+Public state-ref observations at the source audit showed an idle v4 queue at
+generation 9/fencing counter 3 and an idle v3 queue at generation 103/fencing
+counter 32. The history includes real expiry recovery and retained attempts,
+not only unit fixtures. Protected delivery evidence includes successful runs
+for [PR 2420](https://github.com/kungfu-systems/buildchain/actions/runs/31155672200)
+and [PR 2421](https://github.com/kungfu-systems/buildchain/actions/runs/31154367136),
+plus fail-closed attempts where admission or source identity disagreed before a
+later corrected run. These observations are evidence samples, not a new
+authority source.
+
+## Transition semantics
+
+The JSON plan is the complete matrix. Each row freezes source states, guards,
+generation behavior, fencing, clock, roots, errors, recovery, and idempotence.
+The important semantic distinctions are:
+
+| Event              | Authoritative result                                                                                                                                                                                                     |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `submit`           | Append a candidate, safely repair the same attempt's head while retaining age, or append a chained attempt after terminal history. The legacy duplicate receipt says no-op but still changes queue time/generation/root. |
+| `select` / `lease` | Recover expiry first, retain a live active Warrant non-preemptively, otherwise deterministically select and mint the next fence. `lease` is a manifest alias, not a second operation.                                    |
+| `renew`            | Require the exact live candidate, fencing token, lease generation, and unexpired lease; extend expiry and project the candidate to `proving`.                                                                            |
+| `recover-expired`  | Reject the old fence, retain enqueue age, increment attempts/recoveries, and return to `queued`.                                                                                                                         |
+| `settle`           | Close an active exact fence, cancel an exact queued candidate, accept an exact terminal duplicate, or report a rooted never-admitted no-op.                                                                              |
+| `cancel`           | Cancel only an exact queued candidate without minting a Warrant; active states must use fenced settlement.                                                                                                               |
+
+`waiting` and `blocked` are accepted active states but have no exported legacy
+transition that enters them. This is a cutover blocker: Wave 1 must add explicit
+events or remove those states through a protected manifest change. The plan
+does not invent missing behavior.
+
+## Canonical core and boundary
+
+Wave 1 implements nine reusable primitives: canonical JSON, content roots,
+expected-old comparison, explicit clock, decide/fold, declarative effects,
+provider-neutral observations, typed bounded retry, and rooted receipts.
+
+Canonical JSON v1 is deliberately narrow: schemas use ASCII property names and
+integer numbers; object keys use ASCII code-point order; arrays preserve order;
+JSON bytes are UTF-8 and end with one LF. This makes JavaScript/Rust fixtures
+portable while exposing the legacy `localeCompare` key ordering as an explicit
+disagreement. The queue root excludes its `stateRoot` member.
+
+Rust domain code may import canonical contracts, hashing, and time value types.
+It may not import provider SDKs, access the network/filesystem, or sample an
+ambient clock. TypeScript adapters sample time once, execute Git/GitHub effects,
+perform exact readback, enforce retry budgets, and retain evidence.
+
+## Shadow and fault proof
+
+Both implementations consume the same fixture bytes. The semantic projection
+compares decisions/errors, successor queue bytes and roots, generation/fencing,
+ordered effects, and receipt bytes/roots. The checked-in fixture suite covers:
+
+- submission, duplicate submission, priority selection, renewal, and close;
+- lease expiry, reselection, and rejection of the stale fence;
+- never-admitted settlement, active settlement, and terminal duplicate;
+- queued cancellation and exact duplicate cancellation;
+- accepted and stale expected-old checks, response-loss readback, and provider
+  conflict stop behavior.
+
+A gate is zero-diff only when every required fixture and captured production
+replay has no unexplained semantic difference. Replay inputs, both projections,
+the diff, source revisions, and validator version are retained for 90 days.
+Provider conflict or indeterminate readback stops; it never manufactures state.
+
+The executable gate and its closed report contract are documented in
+[`v4-delivery-warrant-semantic-diff.md`](../docs/v4-delivery-warrant-semantic-diff.md).
+It adds bounded property traces and fault probes around the paired shadow
+observation. A passing report only opens the reversible v4-read candidate; its
+write-authorization field is permanently false.
+
+## Bootstrap, cutover, and rollback
+
+| Stage                        | Sole authority                                      | Exit evidence                                                             | Rollback                                                         |
+| ---------------------------- | --------------------------------------------------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------- |
+| Legacy-authoritative shadow  | TypeScript v3                                       | Fixture and captured-replay zero-diff; fault injection                    | Disable Rust invocation; queue unchanged                         |
+| Legacy-authoritative v4 read | TypeScript v3                                       | One protected-release window of read parity; rollback drill               | Route reads to v3                                                |
+| v4-authoritative write       | Rust decide/fold plus one TypeScript effect adapter | Cutover receipt, single-writer proof, exact readback, response-loss drill | Stop v4, restore exact pre-cutover v3 root and retained receipts |
+| Legacy removal               | Rust decide/fold plus one TypeScript effect adapter | No legacy callers; history replayable; N-1 fallback is protected v4       | Revert to exact prior qualified protected v4 revision            |
+
+Every stage has explicit entry, exit, evidence, rollback, and stop conditions in
+the JSON plan. A rollback chooses one last-known-qualified writer for the whole
+protected line. It never creates permanent dual authority.
+
+The read candidate implements that boundary only for `observe`: v3 is the
+default, v4 requires an explicit caller switch plus the exact retained
+qualification root and source revisions, and any qualification, projection,
+timeout, cancellation, parity, or retention failure stops. Mutation commands
+never consult the read switch. The rollback drill is the explicit switch back
+to v3 while retaining the v4 evidence for diagnosis.
+
+## Wave 1 entry
+
+Wave 0 reconciliation proves the four protected child deliveries and opens the
+implementation entry for Wave 1. The earlier wording made the whole wave depend
+on the zero-diff gate even though that gate is produced by the wave itself; that
+circular gate is invalidated. Zero-diff remains mandatory specifically before
+the reversible v4-read candidate.
+
+The dependency order is canonical contracts, shared fixture runner, Rust pure
+domain and TypeScript shadow adapter, semantic-diff gate, then the read
+candidate. The first five nodes do not move authority. Rust writer effects,
+Release Transaction, Candidate Capsule, resume planning, consumer migration,
+and actual provider effects remain out of scope.
+
+## Wave 0 reconciliation
+
+The machine-readable plan records exact protected PR, source, merge, review,
+and check evidence for the inventory, constitution, bridge spike, and Warrant
+plan. All four deliveries are proved. The Initiative matrix is deliberately
+stricter than child completion: the Agent state/explain/plan interface and
+cross-platform bridge evidence are partial, while resumable release, self
+dogfood, migration, legacy removal, and final v4 qualification are missing.
+TypeScript v3 remains the sole production authority throughout.
+
+## Wave 1 reconciliation
+
+All six Wave 1 child Assignments are terminal and independently delivered to
+the protected `dev/v4/v4.0` line in dependency order: canonical contracts,
+shared fixtures, the provider-free Rust Warrant domain, the effect-disabled
+TypeScript shadow adapter, the fail-closed semantic-diff gate, and the
+reversible read candidate. The machine-readable reconciliation binds every
+child to its native capture receipt and portable terminal seal as well as its
+exact source, merge, tree, review, and check evidence. The final protected
+child revision is `955639299f6b94bdcc8affd91b3361ad1bb42d06`.
+
+The Initiative acceptance matrix is intentionally not inferred from six green
+children. v3 safety, the protected v4 line, authority, dependency direction,
+semantic budgets, and the Warrant pilot are proved. Agent state/explain/plan
+and bridge portability remain partial. Resumable release, self dogfood,
+consumer migration and legacy removal, and final v4 qualification remain
+missing. No responsibility row is invalidated: the former Wave 1 entry-cycle
+conflict is resolved by the protected zero-diff gate and read candidate.
+
+The parent Initiative remains inert and TypeScript v3 remains the sole
+production writer. Wave 1 does not authorize a provider effect, release,
+cutover, migration, or legacy removal.
+
+## Wave 2 capture boundary
+
+The exact residual opens five bounded, effect-disabled Stage Capsule and
+cross-run resume assignments: canonical Stage Capsule contracts,
+content-addressed storage and retention, three-platform checkpoints, a
+deterministic minimal resume planner, and a final qualification reconciliation.
+Their dependency graph is recorded in the machine plan. Capturing those
+assignments does not execute them and does not move production authority;
+Candidate Capsule completion, Release Transaction authority, real provider
+calls, release publication, read/write cutover, consumer migration, and legacy
+removal remain explicit future gates.
+
+## Verification
+
+Run the focused contract and fixture checks with:
+
+```sh
+node scripts/v4-warrant-shadow-plan.mjs validate
+node --test tests/v4-warrant-shadow-plan.test.mjs
+node scripts/v4-architecture.mjs validate
+```
+
+The repository `check` command runs the plan validator and the unit suite. A
+protected design PR must also pass schema/format checks, independent review,
+exact N-1 qualification, and the existing architecture gate.

package/architecture/v4-delivery-warrant-shadow-bootstrap-plan.schema.json

@@ -0,0 +1,318 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://buildchain.libkungfu.dev/schemas/v4-delivery-warrant-shadow-bootstrap-plan-v1.schema.json",
+  "title": "Buildchain v4 Delivery Warrant Shadow and Bootstrap Plan",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "contract",
+    "releaseLine",
+    "sourceCut",
+    "legacyAuthority",
+    "canonicalContract",
+    "transitionMatrix",
+    "primitives",
+    "boundaries",
+    "faultModel",
+    "shadow",
+    "authority",
+    "rollout",
+    "legacyDisagreements",
+    "wave0Reconciliation",
+    "wave1",
+    "wave1Reconciliation",
+    "wave2",
+    "protectedDelivery"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "contract": {
+      "const": "kungfu-buildchain-v4-delivery-warrant-shadow-bootstrap-plan"
+    },
+    "releaseLine": { "const": "dev/v4/v4.0" },
+    "sourceCut": { "$ref": "#/$defs/object" },
+    "legacyAuthority": { "$ref": "#/$defs/object" },
+    "canonicalContract": { "$ref": "#/$defs/object" },
+    "transitionMatrix": {
+      "type": "array",
+      "minItems": 7,
+      "items": { "$ref": "#/$defs/transition" }
+    },
+    "primitives": {
+      "type": "array",
+      "minItems": 9,
+      "maxItems": 9,
+      "items": { "$ref": "#/$defs/primitive" }
+    },
+    "boundaries": { "$ref": "#/$defs/object" },
+    "faultModel": { "$ref": "#/$defs/nonEmptyObjectArray" },
+    "shadow": { "$ref": "#/$defs/object" },
+    "authority": { "$ref": "#/$defs/object" },
+    "rollout": {
+      "type": "array",
+      "minItems": 4,
+      "maxItems": 4,
+      "items": { "$ref": "#/$defs/rollout" }
+    },
+    "legacyDisagreements": { "$ref": "#/$defs/nonEmptyObjectArray" },
+    "wave0Reconciliation": { "$ref": "#/$defs/reconciliation" },
+    "wave1": { "$ref": "#/$defs/wave" },
+    "wave1Reconciliation": { "$ref": "#/$defs/wave1Reconciliation" },
+    "wave2": { "$ref": "#/$defs/wave2" },
+    "protectedDelivery": { "$ref": "#/$defs/object" }
+  },
+  "$defs": {
+    "object": { "type": "object", "minProperties": 1 },
+    "stringArray": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "nonEmptyObjectArray": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "$ref": "#/$defs/object" }
+    },
+    "transition": {
+      "type": "object",
+      "required": [
+        "event",
+        "from",
+        "guards",
+        "generation",
+        "fencing",
+        "clock",
+        "roots",
+        "errors",
+        "recovery",
+        "idempotence"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "event": { "type": "string", "minLength": 1 },
+        "from": { "$ref": "#/$defs/stringArray" },
+        "guards": { "$ref": "#/$defs/stringArray" },
+        "generation": { "type": "string", "minLength": 1 },
+        "fencing": { "type": "string", "minLength": 1 },
+        "clock": { "type": "string", "minLength": 1 },
+        "roots": { "$ref": "#/$defs/stringArray" },
+        "errors": { "$ref": "#/$defs/stringArray" },
+        "recovery": { "type": "string", "minLength": 1 },
+        "idempotence": { "type": "string", "minLength": 1 }
+      }
+    },
+    "primitive": {
+      "type": "object",
+      "required": ["id", "input", "output", "effects"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "input": { "type": "string", "minLength": 1 },
+        "output": { "type": "string", "minLength": 1 },
+        "effects": { "type": "string", "minLength": 1 }
+      }
+    },
+    "rollout": {
+      "type": "object",
+      "required": [
+        "id",
+        "authority",
+        "entry",
+        "exit",
+        "rollback",
+        "evidence",
+        "stopConditions"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "authority": { "type": "string", "minLength": 1 },
+        "entry": { "$ref": "#/$defs/stringArray" },
+        "exit": { "$ref": "#/$defs/stringArray" },
+        "rollback": { "$ref": "#/$defs/stringArray" },
+        "evidence": { "$ref": "#/$defs/stringArray" },
+        "stopConditions": { "$ref": "#/$defs/stringArray" }
+      }
+    },
+    "reconciliation": {
+      "type": "object",
+      "required": [
+        "sourceRevision",
+        "productionAuthority",
+        "children",
+        "initiativeMatrix",
+        "conflicts",
+        "entryDecision",
+        "residualResponsibility"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "sourceRevision": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+        "productionAuthority": { "const": "typescript-v3" },
+        "children": {
+          "type": "array",
+          "minItems": 4,
+          "maxItems": 4,
+          "items": { "$ref": "#/$defs/childEvidence" }
+        },
+        "initiativeMatrix": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/matrixRow" }
+        },
+        "conflicts": { "$ref": "#/$defs/nonEmptyObjectArray" },
+        "entryDecision": { "const": "wave1-implementation-open" },
+        "residualResponsibility": { "$ref": "#/$defs/stringArray" }
+      }
+    },
+    "childEvidence": {
+      "type": "object",
+      "required": [
+        "id",
+        "status",
+        "base",
+        "pullRequest",
+        "sourceRevision",
+        "mergeRevision",
+        "review",
+        "checks"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "status": { "const": "proved" },
+        "base": { "type": "string", "pattern": "^dev/v[34]/v[34]\\.0$" },
+        "pullRequest": { "type": "integer", "minimum": 1 },
+        "sourceRevision": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+        "mergeRevision": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+        "review": { "const": "exact-head-approved-by-kungfu-origin" },
+        "checks": { "type": "string", "minLength": 1 }
+      }
+    },
+    "matrixRow": {
+      "type": "object",
+      "required": ["id", "status"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["proved", "partial", "missing", "invalidated"] }
+      }
+    },
+    "wave": {
+      "type": "object",
+      "required": ["entryGate", "readCandidateEntryGate", "nodes"],
+      "additionalProperties": false,
+      "properties": {
+        "entryGate": { "const": "wave0-reconciliation-proved" },
+        "readCandidateEntryGate": {
+          "const": "all-shadow-zero-diff-gates-pass"
+        },
+        "nodes": {
+          "type": "array",
+          "minItems": 6,
+          "maxItems": 6,
+          "items": { "$ref": "#/$defs/waveNode" }
+        }
+      }
+    },
+    "waveNode": {
+      "type": "object",
+      "required": ["id", "dependsOn", "deliverable"],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "dependsOn": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "deliverable": { "type": "string", "minLength": 1 }
+      }
+    },
+    "wave1Reconciliation": {
+      "type": "object",
+      "required": [
+        "sourceRevision",
+        "productionAuthority",
+        "parentInitiativeState",
+        "children",
+        "initiativeMatrix",
+        "conflicts",
+        "decision",
+        "residualResponsibility"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "sourceRevision": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+        "productionAuthority": { "const": "typescript-v3" },
+        "parentInitiativeState": { "const": "inert" },
+        "children": {
+          "type": "array",
+          "minItems": 6,
+          "maxItems": 6,
+          "items": { "$ref": "#/$defs/wave1ChildEvidence" }
+        },
+        "initiativeMatrix": {
+          "type": "array",
+          "minItems": 12,
+          "maxItems": 12,
+          "items": { "$ref": "#/$defs/matrixRow" }
+        },
+        "conflicts": { "$ref": "#/$defs/nonEmptyObjectArray" },
+        "decision": {
+          "const": "capture-wave2-resumable-release-foundation"
+        },
+        "residualResponsibility": { "$ref": "#/$defs/stringArray" }
+      }
+    },
+    "wave1ChildEvidence": {
+      "type": "object",
+      "required": [
+        "id",
+        "assignmentId",
+        "status",
+        "pullRequest",
+        "sourceRevision",
+        "mergeRevision",
+        "treeRevision",
+        "captureReceiptRoot",
+        "sealRoot",
+        "review",
+        "checks"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "assignmentId": { "type": "string", "minLength": 1 },
+        "status": { "const": "proved" },
+        "pullRequest": { "type": "integer", "minimum": 1 },
+        "sourceRevision": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+        "mergeRevision": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+        "treeRevision": { "type": "string", "pattern": "^[0-9a-f]{40}$" },
+        "captureReceiptRoot": {
+          "type": "string",
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "sealRoot": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+        "review": { "const": "exact-head-approved-by-kungfu-origin" },
+        "checks": { "type": "string", "minLength": 1 }
+      }
+    },
+    "wave2": {
+      "type": "object",
+      "required": ["authority", "mode", "nodes"],
+      "additionalProperties": false,
+      "properties": {
+        "authority": { "const": "typescript-v3" },
+        "mode": { "const": "effect-disabled-shadow-foundation" },
+        "nodes": {
+          "type": "array",
+          "minItems": 5,
+          "maxItems": 5,
+          "items": { "$ref": "#/$defs/waveNode" }
+        }
+      }
+    }
+  }
+}