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

package/architecture/v3-core-mechanism-inventory.md

@@ -0,0 +1,67 @@
+---
+status: draft
+period: 2026-08-05
+theme: buildchain-v4-core-mechanism-inventory
+doc_type: analysis
+source_level: local-files
+confidence: high
+sensitivity: internal
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-08-06
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-06
+  boundary: Based only on visible repository sources, tests, generated registries, and exact-head Git metadata.
+---
+
+# v3 Core Mechanism Inventory
+
+This is the human projection of
+[`v3-core-mechanism-inventory.json`](v3-core-mechanism-inventory.json).
+The JSON inventory is authoritative and validated by
+`scripts/check-core-mechanism-inventory.mjs`.
+
+The exact `dev/v3/v3.0` cut is commit
+`e6d6ecd6204518298898962f01aba5d73ed70b60`, tree
+`26c8476dcc63d1b8cf9b32fe12ffbf3ee52246cf`. It contains 275
+hand-maintained source files, 104,953 source lines, 64 workflows, 225 internal
+dependency edges, and zero dependency cycles. These numbers constrain migration
+drift; they do not prove semantic correctness.
+
+## Authority map
+
+| Mechanism                   | Current authority and durable state                                        | v4 disposition                                       |
+| --------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------- |
+| Dev Delivery Warrant        | Rooted queue on a selected Git ref; leased candidate admission             | Rust authority with compatibility projection         |
+| Release Candidate Passport  | Immutable candidate workflow artifacts and Passport root                   | Preserve schema and byte semantics                   |
+| Candidate Recovery          | Original artifacts plus immutable recovery receipt                         | Port verifier first; preserve no-rebuild invariant   |
+| Stable Candidate Ledger     | Rooted ledger on `ledger-ref`                                              | Preserve contract; select store authority explicitly |
+| Publish Transaction         | Version state Git ref, local state projection, sealed evidence             | Primary Rust transaction authority with v3 reader    |
+| Release Activation          | Ordered six-phase transaction and receipt set                              | Port state machine and receipts together             |
+| Publication Authority       | Authority registry, admission, gate, provenance and qualification receipts | Rust primary authority; preserve JSON contracts      |
+| GitHub Governance           | Provider policy snapshot, CODEOWNERS, rulesets and receipt                 | Separate provider policy adapter                     |
+| Passport and Artifact Proof | `buildchain.release.json`, evidence, locators and verification reports     | Preserve public schemas and verifier semantics       |
+| Propagation Work Control    | Rooted Work, stage receipts, recovery cursor and family authority          | Reuse as v4 orchestration boundary                   |
+
+## Boundary
+
+This inventory does not choose the v4 store, provider adapter, bridge ABI, or
+migration sequence. It records those as unresolved per mechanism. It also does
+not change v3 behavior: the only executable addition validates the inventory
+against current files and generated/package public-surface registries.
+
+The reverse scan includes workflows, actions, the CLI command registry, package
+and Node exports, tests, generated references, and Git-ref-backed stores. A
+missing coordinate, absent public surface, empty evidence dimension, or
+ambiguous source owner fails the check instead of becoming an implicit v4
+assumption.
+
+The executable scan walks 13 declared discovery rules against the repository,
+not only against the paths already listed in the inventory. It currently owns
+50 exact source coordinates, independently rediscovers 38 state-bearing
+authority coordinates, validates 39 public surfaces across action, CLI, Node
+export, and workflow registries, and checks three concrete Git-ref store
+markers. A newly matching split state-machine or authority file therefore
+fails as an orphan until the inventory gives it one mechanism owner.

package/architecture/v4-adopter-delivery-parity.json

@@ -0,0 +1,47 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-v4-adopter-delivery-parity-plan",
+  "sourceAuthority": {
+    "branch": "dev/v3/v3.0",
+    "commit": "c3f58d76391c1c6ceddfc900a68e91c7ab82a575",
+    "vectorSuiteRoot": "sha256:cf329805d928a9883cbafbdfdf21ef66c6a0889ed8dfe14356b4e0d25d6738f9",
+    "kfdPackage": "@kungfu-tech/kfd@1.0.0-alpha.62"
+  },
+  "target": {
+    "branch": "dev/v4/v4.0",
+    "baseline": "3079091f770ce9fdca950e106259e34e5171f763",
+    "mode": "effect-disabled",
+    "productionWriterAuthority": false
+  },
+  "vectors": [
+    {
+      "id": "golden-two-driver-offline-replay",
+      "mode": "gate-core-parity"
+    },
+    {
+      "id": "negative-driver-mismatch",
+      "mode": "gate-core-parity"
+    },
+    {
+      "id": "negative-category-conflict",
+      "mode": "published-kfd-driver-parity"
+    },
+    {
+      "id": "negative-evidence-substitution",
+      "mode": "retained-v3-release-passport-boundary"
+    },
+    {
+      "id": "negative-stale-package-cut",
+      "mode": "published-kfd-driver-parity"
+    },
+    {
+      "id": "fault-driver-throw",
+      "mode": "gate-core-parity"
+    }
+  ],
+  "nonClaims": [
+    "The Rust projection has no provider, credential, release, signing or production-writer authority.",
+    "KFD semantics are evaluated only by exact published KFD bytes before the effect-disabled carrier projection.",
+    "Release Passport evidence substitution remains on the protected v3 boundary and is not reimplemented as a v4 writer."
+  ]
+}

package/architecture/v4-architecture-constitution.md

@@ -0,0 +1,210 @@
+---
+status: draft
+period: 2026-08-07
+theme: buildchain-v4-architecture-constitution
+doc_type: architecture-constitution
+source_level: local-files + protected-git-evidence
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-13
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-07
+  boundary: Derived from the exact v3 mechanism inventory, retained v4 qualification evidence, and visible repository contracts; provider credentials and private provider state were not read.
+---
+
+# Buildchain v4 Architecture Constitution
+
+This constitution governs the `dev/v4/v4.0` release line. The executable
+authority is [`v4-capability-state-machine-manifest.json`](v4-capability-state-machine-manifest.json),
+validated by `buildchain architecture validate`. This document explains that
+contract; it cannot override it.
+
+## 1. Release-line authority
+
+The first v4 line was created from the exact protected v3 merge that contains
+this constitution and
+[`v4-bootstrap-authority.json`](v4-bootstrap-authority.json). The exact source,
+bootstrap revision, N-1 qualification, protection, and merge-queue evidence are
+recorded there under the state `qualified-protected-v4-bootstrap`; a local
+branch or unrecorded candidate commit is not release-line authority.
+
+Later v4 candidates are qualified by an exact N-1 Git revision. The verifier
+loads the authority files with `git show <authority-revision>:<path>` and rejects
+an authority revision equal to the candidate revision. A candidate therefore
+cannot qualify itself by editing its own manifest, ceilings, or exception
+ledger.
+
+## 2. Dependency direction
+
+Dependencies point inward only:
+
+```text
+workflows -> TypeScript adapters -> libnode host -> Rust domain -> contracts
+legacy compatibility -> TypeScript adapters / contracts
+```
+
+Contracts contain serialization and compatibility facts, not provider SDK
+types. Rust domain code contains semantic state transitions, not GitHub, npm,
+filesystem, credential, or workflow adapters. Provider SDK imports in contracts
+or Rust domain are hard-zero violations. Cycles are forbidden.
+
+## 3. Single-writer rule
+
+Every state machine has exactly one authoritative writer. The v4 cutover marks
+the TypeScript v4 control and provider plane authoritative and the legacy v3
+writer retired. Rust v4 owns the deterministic release-activation, journal,
+stable-fence, and recovery domain semantics while the TypeScript v4 adapter
+remains byte-equivalent at that boundary. A second writer, permanent dual
+write, cross-machine mutable file, or implicit compatibility authority has a
+hard-zero budget.
+
+## 4. Explicit complexity budgets
+
+Complexity is governed by independent dimensions: authority, semantic state,
+boundary, structural, Agent cognitive, and recovery/fault. There is no
+aggregate score, so a favorable metric cannot cancel an authority or recovery
+violation. Every delta is reported by dimension.
+
+Hard-zero ceilings cannot be raised by a candidate. A non-zero temporary
+exception must already exist in the N-1 authority ledger and name its owner,
+scope, evidence, expiry, removal condition, and budget dimension. Expired,
+ownerless, broadened, or candidate-created exceptions fail qualification.
+
+## 5. Manifest and projection
+
+The manifest declares capability ownership and every governed state machine's
+writer, schemas, store, states, events, invariants, effects, adapters, tests,
+migration phase, recovery policy, and budgets. `architecture list` and
+`architecture show` are generated directly from the validated manifest; no
+second hand-maintained architecture list is authoritative.
+
+## 6. Production cutover boundary
+
+The v4 line owns Delivery Warrant, Release Transaction, activation,
+publication, propagation, and release-tail state. This does not introduce a
+daemon, a service database, provider SDKs in contracts or Rust domain code, or
+a second writer. The retained `release/v3/v3.0` coordinate is rollback evidence
+only and cannot regain production authority without a new reviewed cutover.
+
+## 7. Wave 0 host boundary
+
+The bounded Rust/libnode bridge spike is recorded in
+[`v4-rust-libnode-bridge-spike.md`](v4-rust-libnode-bridge-spike.md). Wave 0
+uses a replaceable subprocess host behind a closed byte-oriented contract; the
+Rust trunk owns process lifecycle and transport, while existing TypeScript
+remains the only production writer. This selection is evidence for later
+qualification, not a final ABI or consumer migration.
+
+## 8. Wave 2 Stage Capsule contract
+
+The executable Stage Capsule architecture contract is
+[`v4-stage-capsule-contract.json`](v4-stage-capsule-contract.json). It fixes one
+schema authority, one TypeScript v3 writer, validation-only Rust, and zero
+provider imports or production write-authority changes. Identity, retention
+promise, current availability, qualification, content roots, and rooted
+transport observations remain distinct. Later store, checkpoint, resume, and
+reconciliation work must consume this contract rather than create competing
+identity or writer authority.
+
+The successor storage slice is governed by
+[`v4-stage-capsule-store-contract.json`](v4-stage-capsule-store-contract.json).
+It adds provider-neutral output-manifest, retention-state, transport, and store
+receipt roots plus a deterministic no-network local filesystem reference
+store. GitHub Artifact and S3-compatible adapters remain effect-disabled or
+fixture-backed. Provider locations, retention promises, observed availability,
+and qualification evidence stay separate facts; none becomes Capsule identity,
+qualification authority, or a production writer.
+
+Final Wave 2 qualification is governed by
+[`v4-stage-capsule-qualification.json`](v4-stage-capsule-qualification.json).
+It consumes the existing Capsule, store, checkpoint, and resume authorities for
+six real-runner shadow campaigns and one exact terminal reconciliation. A
+qualification root is evidence only: TypeScript v3 remains production
+authority, retained state is non-destructive, and production reuse, provider
+effects, release effects, and public cutover remain outside this transition.
+
+## 9. Wave 3 provider operation journal
+
+The executable provider operation journal contract is
+[`v4-provider-operation-journal-contract.json`](v4-provider-operation-journal-contract.json).
+It freezes one closed schema authority and one Rust v4 state-fold authority
+for append-only intent, attempt, rooted observation, confirmation, and
+reconciliation records. The TypeScript v4 plane performs provider adaptation
+and conformance projection against the same fixtures; v4 is the sole
+production writer.
+
+Logical operation identity excludes attempt ordinals and mutable provider or
+runner facts. Every retry preserves `operationRoot`, while every attempt and
+observation has a distinct causal entry root. The fold rejects impossible
+transitions, non-append sequence, confirmation without successful rooted
+observation, conflicting confirmation, reconciliation disagreement, and
+authority-root escalation. Provider SDK imports, live mutations, production
+write-authority changes, and v3 behavior changes retain hard-zero budgets.
+
+GitHub release, npm publication, and OCI manifest readback adapters remain
+fixture-backed and effect-disabled. They discard provider-shaped transport
+fields at the boundary and emit only rooted, provider-neutral samples. Duplicate
+and reordered samples fold by byte-sorted sample root into one journal
+observation. Not-found and eventually-visible reads stay unknown; already
+applied reads may become a successful observation, but no adapter may confirm
+the operation or advance release state without independent journal
+qualification. Conflicting, malformed, and root-mismatched evidence fails
+closed with typed faults.
+
+## 10. Release activation production domain
+
+The executable release activation boundary is
+[`v4-release-activation-shadow-domain.json`](v4-release-activation-shadow-domain.json).
+It consumes an explicit qualification root, dependency graph, compensation
+boundaries, provider-operation identities, and append-only journal facts to
+derive one deterministic activation plan and resume state. Rust is the sole v4
+plan-and-fold authority; TypeScript must remain byte-equivalent against
+the same closed schema and fixture.
+
+Confirmed operations are never eligible for replay. Attempting, observed, and
+confirmable operations require provider-neutral readback before any retry,
+while planned or retryable operations become eligible only after every declared
+dependency is confirmed. Missing qualification, dependency cycles, operation or
+authority drift, conflicting event ordinals, and impossible journal transitions
+fail closed. This pure domain performs no provider call itself; the TypeScript
+v4 provider adapter may execute only exact eligible operations and must append
+rooted readback before confirmation or retry.
+
+## 11. Stable publication production fence
+
+The stable-candidate production publication boundary is governed by
+[`v4-stable-publication-fence.json`](v4-stable-publication-fence.json). It
+binds one exact candidate root to source, metadata, provider-operation journal,
+protected ancestry, provider confirmations, and an independently sealed
+qualification before a production publication plan can exist.
+
+Candidate generation N cannot qualify itself. An N-1 policy requires the
+immediately preceding authority generation; an independent-seal policy requires
+a qualifier authority distinct from the publisher authority. Stable refs, npm
+tags, OCI tags, and GitHub Releases remain exact target-shaped facts. The pure
+fence authorizes the exact target count but performs no network or credential
+operation itself; only the TypeScript v4 provider adapter may apply authorized
+targets, and it must read them back before completion.
+
+## 12. Wave 3 partial-mutation recovery qualification
+
+The executable recovery qualification boundary is
+[`v4-partial-mutation-recovery-qualification.json`](v4-partial-mutation-recovery-qualification.json).
+It consumes retained Stage Capsule resume evidence and release-activation journal
+state only after exact source, policy, platform, qualification, plan, state,
+operation, journal, and compensation-boundary roots agree.
+
+Every nonterminal operation maps deterministically to `retry`, `wait`,
+`reconcile`, `compensate`, or `escalate`; confirmed operations are permanent
+`terminal-noop` facts and never re-enter the next-operation set. Missing,
+expired, corrupt, conflicting, cross-boundary, or attempt-budget-exhausted
+evidence fails closed at an exact Stage Capsule or provider-operation
+checkpoint. The Rust domain is the sole v4 planner and TypeScript is a
+byte-equivalent projection. Both are pure: they perform zero provider,
+filesystem, network, credential, ref, package, image, or release mutation.
+Their exact plan is the only recovery authority consumed by the TypeScript v4
+provider adapter.

package/architecture/v4-bootstrap-authority.json

@@ -0,0 +1,56 @@
+{
+  "schemaVersion": 1,
+  "contract": "kungfu-buildchain-v4-bootstrap-authority",
+  "releaseLine": {
+    "candidateBranch": "dev/v4/v4.0",
+    "sourceBranch": "dev/v3/v3.0",
+    "sourceCommit": "b9fbfd9d6ee909ee3a8c4bd6116e7ddafd7b05e1",
+    "sourceTree": "20abc99c7fb11f1ad63eb11be7c5bef3172abec1",
+    "bootstrapCommit": "d827bb223e4b78551feed69827f3e67839821171",
+    "bootstrapTree": "6d52d21f25a65b09cb9b344c7dffea192ff5b1d9",
+    "status": "qualified-protected-v4-bootstrap"
+  },
+  "qualification": {
+    "schemaVersion": 1,
+    "contract": "kungfu-buildchain-v4-n-minus-one-qualification",
+    "authorityRevision": "b9fbfd9d6ee909ee3a8c4bd6116e7ddafd7b05e1",
+    "candidateRevision": "d827bb223e4b78551feed69827f3e67839821171",
+    "qualificationRoot": "sha256:ea58bf84bd8ba32d0d7931328a2209f937bd3b81d3215b27f2ca67abc704a673",
+    "candidateSelfQualified": false,
+    "frozenManifestFields": 4,
+    "activeExceptions": 0,
+    "protectedDelivery": {
+      "pullRequest": 2408,
+      "mergeGroupHead": "b9fbfd9d6ee909ee3a8c4bd6116e7ddafd7b05e1",
+      "requiredCheck": "check",
+      "requiredCheckRun": 31134446779
+    },
+    "releaseLineCreation": {
+      "dryRun": 31140240480,
+      "applyRun": 31140281203,
+      "applyRunOutcome": "refs-created-protection-completed-by-exact-reconcile",
+      "devMergeQueueRuleset": 20536161,
+      "defaultBranch": "dev/v3/v3.0",
+      "alphaPullRequestCreated": false
+    },
+    "verifiedAt": "2026-08-07T02:20:03Z"
+  },
+  "authorityFiles": [
+    "architecture/v4-bootstrap-authority.json",
+    "architecture/v4-capability-state-machine-manifest.json",
+    "architecture/v4-exception-ledger.json"
+  ],
+  "bootstrapRule": {
+    "authorityRevision": "the exact protected dev/v3/v3.0 merge containing this contract",
+    "candidateRevision": "the exact dev/v4/v4.0 candidate revision",
+    "requiredRelationship": "candidate descends from authority revision",
+    "selfQualification": "forbidden",
+    "fallback": "dev/v3/v3.0 remains production and bootstrap authority"
+  },
+  "handoffRule": {
+    "condition": "a protected v4 release has passed N-1 qualification, recovery, independent review, and exact readback",
+    "nextAuthority": "the exact prior qualified protected v4 revision",
+    "candidateMayWidenCeilings": false,
+    "candidateMayCreateQualificationExceptions": false
+  }
+}

package/architecture/v4-canonical-contract-fixtures.json

@@ -0,0 +1,105 @@
+{
+  "schemaVersion": 1,
+  "contract": "buildchain-v4-canonical-contract-fixtures",
+  "canonicalization": "buildchain-canonical-json/v1",
+  "rootConstruction": "sha256(domain + NUL + canonical-bytes)",
+  "validCases": [
+    {
+      "id": "ascii-key-order",
+      "domain": "queue-state",
+      "clock": "2026-08-07T15:00:00.000Z",
+      "value": { "z": 1, "a": 2, "A": [true, null] },
+      "expectedCanonicalUtf8": "{\"A\":[true,null],\"a\":2,\"z\":1}\n",
+      "expectedRoot": "sha256:55693e621e85b454876b11af9842c106ab7eb7ab92c6ca5ea7fa498ea6cf74f4"
+    },
+    {
+      "id": "utf8-string-and-escapes",
+      "domain": "observation",
+      "clock": "2024-02-29T23:59:59.999Z",
+      "value": { "line": "一行\\n二行", "quote": "\\\"", "slash": "/" },
+      "expectedCanonicalUtf8": "{\"line\":\"一行\\\\n二行\",\"quote\":\"\\\\\\\"\",\"slash\":\"/\"}\n",
+      "expectedRoot": "sha256:54a49dcafaac0e3e480c9fb63ff50a976490a5cf467cb2c34fb0ec02e2d16afd"
+    },
+    {
+      "id": "safe-integer-boundaries",
+      "domain": "transition-receipt",
+      "clock": "2000-02-29T00:00:00.000Z",
+      "value": { "maximum": 9007199254740991, "minimum": -9007199254740991 },
+      "expectedCanonicalUtf8": "{\"maximum\":9007199254740991,\"minimum\":-9007199254740991}\n",
+      "expectedRoot": "sha256:52f61241c03d451b7568a704c502eac50e12ef53717ee49f4a89109e65bc6b8c"
+    }
+  ],
+  "invalidCases": [
+    {
+      "id": "fractional-number",
+      "kind": "canonical",
+      "value": 1.5,
+      "fault": "unsupported-number"
+    },
+    {
+      "id": "unsafe-integer",
+      "kind": "canonical",
+      "value": 9007199254740992,
+      "fault": "unsupported-number"
+    },
+    {
+      "id": "non-ascii-key",
+      "kind": "canonical",
+      "value": { "键": 1 },
+      "fault": "unsupported-object-key"
+    },
+    {
+      "id": "bad-clock-offset",
+      "kind": "clock",
+      "value": "2026-08-07T23:00:00.000+08:00",
+      "fault": "invalid-clock"
+    },
+    {
+      "id": "bad-clock-date",
+      "kind": "clock",
+      "value": "2026-02-30T00:00:00.000Z",
+      "fault": "invalid-clock"
+    },
+    {
+      "id": "bad-clock-year-zero",
+      "kind": "clock",
+      "value": "0000-01-01T00:00:00.000Z",
+      "fault": "invalid-clock"
+    },
+    {
+      "id": "unknown-domain",
+      "kind": "root",
+      "value": "provider-state",
+      "fault": "unsupported-root-domain"
+    },
+    {
+      "id": "event-extra-key",
+      "kind": "event",
+      "value": {
+        "schema": "buildchain-v4-event-envelope/v1",
+        "eventId": "sha256:1111111111111111111111111111111111111111111111111111111111111111",
+        "eventType": "candidate-submitted",
+        "occurredAt": "2026-08-07T15:00:00.000Z",
+        "subjectRoot": "sha256:2222222222222222222222222222222222222222222222222222222222222222",
+        "payload": {},
+        "sampledNow": "2026-08-07T15:00:00.000Z"
+      },
+      "fault": "invalid-envelope-shape"
+    },
+    {
+      "id": "receipt-fault-outcome-drift",
+      "kind": "receipt",
+      "value": {
+        "schema": "buildchain-v4-receipt-envelope/v1",
+        "receiptType": "candidate-submitted",
+        "recordedAt": "2026-08-07T15:00:00.000Z",
+        "eventRoot": "sha256:3333333333333333333333333333333333333333333333333333333333333333",
+        "priorStateRoot": null,
+        "nextStateRoot": null,
+        "outcome": "rejected",
+        "fault": null
+      },
+      "fault": "invalid-receipt"
+    }
+  ]
+}