@kungfu-tech/buildchain 4.0.1-alpha.4 → 4.0.1-alpha.5

package/architecture/decisions/0002-next-development-transition.md

@@ -0,0 +1,101 @@
+---
+status: accepted
+period: 2026-08-11
+theme: next-development-transition
+doc_type: architecture-decision-record
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: self-reviewed
+last_reviewed: 2026-08-11
+---
+
+# ADR 0002: Alpha Publication and Next-development Are Separate Transactions
+
+## Status
+
+Accepted. This decision is normative for Buildchain promotion controllers and
+for generated consumer guidance.
+
+## Context
+
+An Alpha publication and preparation of the following development version have
+different trust boundaries. Alpha publication establishes public, immutable
+facts about version N. Preparing N+1 changes repository version material and
+may require a protected pull request or an upstream anchor that does not exist
+when Alpha N completes. Treating both operations as one success condition makes
+a post-publication conflict appear to invalidate a publication that already
+succeeded, and encourages retries to move Alpha refs while repairing Dev.
+
+Buildchain supports two legal version models:
+
+- `semver` with `next = "auto"`, where N+1 increments the Alpha sequence on
+  the same semantic patch; and
+- `anchored` with `next = "manual"`, where no version may be inferred before a
+  declared anchor manifest is materialized and rooted.
+
+The crossed combinations `semver/manual` and `anchored/auto` have no defined
+meaning and are rejected.
+
+## Decision
+
+Alpha publication reaches its own terminal success before a next-development
+transition is created. The transition records the completed Alpha exact tag,
+release commit, tree, publication evidence root, and completion time. A
+deterministic idempotency key covers that completed-Alpha root together with
+the repository, legal version model, and the role-separated adapter path set.
+
+The independent next-development state machine is:
+
+```text
+planned ----------------------> materialized -> pr-pending -> merged -> verified
+   \                              \---------------------------> merged
+    -> waiting-anchor ----------> materialized
+```
+
+`semver/auto` derives its target while planned. `anchored/manual` remains in
+`waiting-anchor` until an exact semantic version and the digest of the declared
+anchor manifest are supplied. `pr-pending` is durable incomplete state, not a
+publication failure. Direct materialization may proceed to `merged` or
+`verified` when repository governance does not require a pull request.
+
+Every non-initial state transition is compare-and-swap guarded and rooted in
+explicit evidence. Replaying an identical request is a no-op. Alpha outcome is
+always `preserved-success`; no transition may write an Alpha branch, exact tag,
+or floating tag. A controller that needs to repair next-development state may
+write only paths declared by `version.files` and `version.derived_files`; the
+configured anchor manifest is declared read-only authority.
+
+## Local adapter boundary
+
+The reference adapter is provider-neutral. It reads the checked-in
+`buildchain.toml`, derives the sorted path allowlist, validates the completed
+Alpha and optional anchor, and plans version-file content. It never invokes Git,
+network clients, lifecycle commands, package registries, or provider APIs.
+Mutation requires explicit `--write`, rejects symlinks and path escapes, and is
+limited to configured `version.files`. The standard repository transaction
+adapter passes the exact target in `BUILDCHAIN_VERSION`, permits changes only
+to `version.files` plus `version.derived_files`, runs
+`lifecycle.version-state` when derived files are declared, and then runs
+`lifecycle.verify`. The reference writer fails closed rather than invoking
+those consumer commands because transaction execution is a separate slice.
+For anchored/manual, the consumer must
+materialize the declared manifest first; the adapter verifies its exact digest
+and does not invent or edit upstream anchor data.
+
+Preparing development state alone creates no Git tag, GitHub Release, public
+package, or release candidate.
+
+## Consequences
+
+- A completed Alpha N remains successful when N+1 waits for an anchor, a
+  protected PR, merge, or verification.
+- Retrying development preparation cannot republish Alpha N or change any
+  Alpha ref.
+- Semver and anchored consumers share one lifecycle while retaining their
+  distinct version authority.
+- Provider adapters may project pull-request identifiers and merge evidence,
+  but those observations do not become part of the local mutation authority.
+- Generated config, Agent instructions, and public documentation are checked
+  against the same constants; projection drift fails repository checks.

package/architecture/internal-capabilities.json

@@ -6,6 +6,10 @@
     "bin/internal",
     "packages/core/release-passport.js",
     "packages/core/buildchain-contract.js",
+    "packages/core/kungfu-temporal-fact.js",
+    "packages/core/buildchain-compatibility-fact.js",
+    "packages/core/buildchain-compatibility-authority.js",
+    "packages/core/buildchain-compatibility-proof.js",
     "packages/core/workflow-call-contract.js",
     "packages/core/workflow-yaml-contract.js",
     "packages/core/paper-fleet.js",
@@ -50,6 +54,12 @@
     "crates/buildchain-v4-bridge/src/main.rs",
     "packages/core/v4-runtime-ref-resume-authority.js",
     "packages/core/v4-runtime-selector-persistence.js",
+    "packages/core/v4-tail-reseal-contract.js",
+    "packages/core/v4-tail-reseal.js",
+    "packages/core/v4-tail-reseal-github.js",
+    "packages/core/v4-tail-reseal-receipt.js",
+    "scripts/v4-tail-reseal.mjs",
+    "scripts/v4-tail-reseal-macos-rehearsal.mjs",
     "packages/core/v4-provider-operation-journal.js",
     "packages/core/v4-stage-capsule.js",
     "packages/core/v4-stage-capsule-store.js",
@@ -106,7 +116,9 @@
     "packages/core/v4-partial-mutation-recovery-qualification.js",
     "crates/buildchain-v4-contracts/src/partial_mutation_recovery.rs",
     "packages/core/v4-adopter-delivery-parity.js",
-    "crates/buildchain-v4-contracts/src/adopter_delivery.rs"
+    "crates/buildchain-v4-contracts/src/adopter_delivery.rs",
+    "crates/buildchain-v4-contracts/src/compatibility_facts.rs",
+    "crates/buildchain-v4-contracts/src/compatibility_facts"
   ],
   "ownershipRules": [
     {
@@ -512,6 +524,30 @@
         "docs/dev-delivery-qualification-landing-adr.md"
       ]
     },
+    {
+      "id": "v4-compatibility-facts",
+      "owner": "Buildchain compatibility authority maintainers",
+      "implementation": [
+        "bin/internal/compatibility-facts-cli.mjs",
+        "packages/core/kungfu-temporal-fact.js",
+        "packages/core/buildchain-compatibility-fact.js",
+        "packages/core/buildchain-compatibility-authority.js",
+        "packages/core/buildchain-compatibility-proof.js",
+        "crates/buildchain-v4-contracts/src/compatibility_facts.rs",
+        "crates/buildchain-v4-contracts/src/compatibility_facts/encoding.rs",
+        "crates/buildchain-v4-contracts/src/compatibility_facts/fixture.rs",
+        "crates/buildchain-v4-contracts/src/compatibility_facts/lifecycle.rs",
+        "crates/buildchain-v4-contracts/src/compatibility_facts/verifier.rs"
+      ],
+      "tests": ["tests/v4-compatibility-facts.test.mjs"],
+      "contracts": [
+        "architecture/v4-compatibility-facts-parity.json",
+        "contracts/v4-compatibility-facts-v1.schema.json",
+        "contracts/fixtures/v4-compatibility-facts-v1/shared.json",
+        "dist/site/schemas/v4-compatibility-facts-v1.schema.json",
+        "docs/v4-compatibility-facts.md"
+      ]
+    },
     {
       "id": "v4-architecture-governance",
       "owner": "Buildchain architecture maintainers",
@@ -529,6 +565,12 @@
         "packages/core/v4-adopter-delivery-parity.js",
         "packages/core/v4-runtime-ref-resume-authority.js",
         "packages/core/v4-runtime-selector-persistence.js",
+        "packages/core/v4-tail-reseal-contract.js",
+        "packages/core/v4-tail-reseal.js",
+        "packages/core/v4-tail-reseal-github.js",
+        "packages/core/v4-tail-reseal-receipt.js",
+        "scripts/v4-tail-reseal.mjs",
+        "scripts/v4-tail-reseal-macos-rehearsal.mjs",
         "packages/core/v4-stage-capsule.js",
         "packages/core/v4-stage-capsule-store.js",
         "packages/core/v4-stage-capsule-local-store.js",
@@ -562,7 +604,9 @@
         "tests/v4-platform-stage-checkpoints.test.mjs",
         "tests/v4-stage-capsule-qualification.test.mjs",
         "tests/v4-adopter-delivery-parity.test.mjs",
-        "tests/v4-runtime-ref-resume-authority.test.mjs"
+        "tests/v4-runtime-ref-resume-authority.test.mjs",
+        "tests/v4-tail-reseal.test.mjs",
+        "tests/v4-tail-reseal-parity.test.mjs"
       ],
       "contracts": [
         "architecture/v4-architecture-constitution.md",
@@ -597,8 +641,13 @@
         "contracts/fixtures/v4-partial-mutation-recovery-v1/shared.json",
         "contracts/v4-runtime-ref-resume-authority-v1.schema.json",
         "contracts/fixtures/v4-runtime-ref-resume-authority-v1/scenario.json",
+        "architecture/v4-tail-reseal-parity.json",
+        "contracts/v4-tail-reseal-v1.schema.json",
+        "contracts/fixtures/v4-tail-reseal-v1/valid.json",
+        ".github/workflows/v4-tail-reseal.yml",
         "docs/v4-stage-capsule.md",
-        "docs/v4-runtime-ref-resume-authority.md"
+        "docs/v4-runtime-ref-resume-authority.md",
+        "docs/v4-tail-reseal.md"
       ]
     }
   ]

package/architecture/maintainability-policy.json

@@ -5,12 +5,12 @@
   "enforcementRevision": "5308189b09bcb5a1314195412f2807a40d678838",
   "repositoryBudgets": {
     "baselineRevision": "c70e6ac28431888b24fefc218246cc69f8dde85a",
-    "maxHandMaintainedSourceFiles": 384,
-    "maxHandMaintainedSourceLines": 146550,
-    "maxWorkflowFiles": 71,
-    "maxWorkflowLines": 25259,
-    "latestTransition": "Delivery authority now migrates a rechecked live v1 ref with the configured v2 policy, rejects GitHub artifact runtime credentials in candidate ancestry, binds containment comparison to the exact protected-base head, and keeps v2 migration promises out of the v1 workflow contract.",
-    "rationale": "Bounded modules separate candidate, evidence, native proof and execution, canonical failure verification, closed-set execution transfer, process-boundary verification, Warrant state and qualification, authority state, qualification, Landing acquisition, verified-attempt admission, Landing settlement and fence validation, provider attempt and heartbeat readback, sealed terminal evidence, hosted heartbeat, resume, store, options, command-specific adapters, and CLI orchestration responsibilities. The protected delivery workflow gives candidate and seal jobs no provider write credential, recursively rejects transfer drift, scopes every transfer artifact to the exact provider run attempt, chains every durable heartbeat state and receipt root on a distinct hosted runner domain, and permits qualification or exact failure settlement only after the finalizer verifies live jobs and the latest durable authority state. Public Landing admission and heartbeat always perform non-injectable fresh exact-attempt provider readback, and heartbeat-loss coordination never invokes GitHub's run-scoped cancellation API where a successor rerun could race. V2 mutation cannot initialize a second empty authority beside a legacy ref: migration reads and roots the canonical live v1 ref, rechecks it, applies the explicit configured v2 policy, and atomically replaces its bytes through one expected-old non-force update, so old v1 controllers fail closed while the prior commit remains immutable history. Candidate ancestry classifies the GitHub artifact runtime token as credential authority. Every Landing settlement, including an unexpired fence, requires product-owned terminal readback. Terminal cleanup reads the immutable historical attempt, derives workflow and hosted Landing job identity from live run data, reads the exact protected ref head and compares containment against that immutable SHA, and seals merged only when the admitted merge-group head is contained by that protected base; a later different-head merge settles the old attempt as dequeued. Terminal normalization preserves transfer, finalizer boundary, native and seal job, admitted provider attempt, protected-base head, containment result, and terminal readback coordinates. The public reusable workflow truthfully retains its single-flight v1 authority without advertising v2 migration, while bounded v2 remains a separate opt-in CLI, Node API, and schema contract; the tracked self-caller stays on public v4-alpha with matching stable and alpha locks, and transient train selection is dispatch-only. These exact 384-file, 146550-source-line and 25259-workflow-line ceilings cannot grow implicitly."
+    "maxHandMaintainedSourceFiles": 408,
+    "maxHandMaintainedSourceLines": 154384,
+    "maxWorkflowFiles": 72,
+    "maxWorkflowLines": 25634,
+    "latestTransition": "Compatibility Facts parity adds a closed public schema, split Rust and TypeScript KFR2 cores, append-only lifecycle verification, shared fail-closed fixtures, CLI and Node projections, Release Passport lineage evidence, and generated site facts.",
+    "rationale": "Bounded modules separate candidate, evidence, native proof and execution, canonical failure verification, closed-set execution transfer, process-boundary verification, Warrant state and qualification, authority state, qualification, Landing acquisition, verified-attempt admission, Landing settlement and fence validation, provider attempt and heartbeat readback, sealed terminal evidence, hosted heartbeat, resume, store, options, command-specific adapters, and CLI orchestration responsibilities. The protected delivery workflow gives candidate and seal jobs no provider write credential, recursively rejects transfer drift, scopes every transfer artifact to the exact provider run attempt, chains every durable heartbeat state and receipt root on a distinct hosted runner domain, and permits qualification or exact failure settlement only after the finalizer verifies live jobs and the latest durable authority state. Public Landing admission and heartbeat always perform non-injectable fresh exact-attempt provider readback, tolerate only a not-yet-materialized seal job while retaining exact native and duplicate-job rejection, and heartbeat-loss coordination never invokes GitHub's run-scoped cancellation API where a successor rerun could race. The hosted process boundary anchors trust in the kernel-resolved versioned Runner.Worker path while accepting an equivalent argv-zero spelling with the same basename; its public boundary marker is allowed only at the one exact non-secret value, so a forged value under the same credential-like name still fails closed. The credentialless transfer seal validates the rooted native reuse decision against the Warrant-bound source, closure, dependency, toolchain, environment and command inputs; qualifiedBase stays in the proof and decision where it is rooted and later independently rechecked, rather than being assumed on the Warrant schema. V2 mutation cannot initialize a second empty authority beside a legacy ref: migration reads and roots the canonical live v1 ref, rechecks it, applies the explicit configured v2 policy, and atomically replaces its bytes through one expected-old non-force update, so old v1 controllers fail closed while the prior commit remains immutable history. Candidate ancestry classifies the GitHub artifact runtime token as credential authority. Every Landing settlement, including an unexpired fence, requires product-owned terminal readback. Terminal cleanup reads the immutable historical attempt, derives workflow and hosted Landing job identity from live run data, reads the exact protected ref head and compares containment against that immutable SHA, and seals merged only when the admitted merge-group head is contained by that protected base; a later different-head merge settles the old attempt as dequeued. Terminal normalization preserves transfer, finalizer boundary, native and seal job, admitted provider attempt, protected-base head, containment result, and terminal readback coordinates. The public reusable workflow truthfully retains its single-flight v1 authority without advertising v2 migration, while bounded v2 remains a separate opt-in CLI, Node API, and schema contract; the tracked self-caller stays on public v4-alpha with matching stable and alpha locks, and transient train selection is dispatch-only. Next-development parity adds one versioned transition authority, one durable controller, one bounded reservation adapter, and pure public-contract recovery evidence while retaining the existing thin floating-channel callers byte-for-byte. The floating-consumer gate reuses the existing contract-world evaluator so SHA drift passes only under the selected lock's compatibility policy, breaking surface drift still fails closed, and external certification reconstructs the receipt from the observed workflow SHA rather than the lock's historical evidence SHA. Tail reseal adds no Stage Capsule effect or general rebuild authority: it verifies the exact retained four-platform bytes, admits one known macOS tail failure through live provider readback, fences signing and finalization to explicit credentials and Warrant identity, and requires standard candidate Passport plus provider and protected readback. Compatibility Facts parity isolates canonical encoding, temporal verification, lifecycle validation, fixture projection, public authority projection, and CLI adaptation into bounded modules; legacy digest and proof arrays are derived only from exact current Fact lineage. These exact 408-file, 154384-source-line, 72-workflow-file and 25634-workflow-line ceilings cannot grow implicitly."
   },
   "sourceBudgets": {
     "newFileLines": 600,
@@ -19,6 +19,18 @@
     "existingDebtPolicy": "no-widening"
   },
   "approvedNewFileTransitions": {
+    "packages/core/next-development-transition.js": {
+      "maxLines": 738,
+      "rationale": "The single versioned authority keeps completed-Alpha identity, legal successor models, role-separated adapter bounds, materialization roots, compare-and-swap transitions and deterministic replay validation together. Anchored and manual initial state persists as waiting-anchor after reviewed input and exposes rooted anchor binding plus controller materialization recording; this exact reviewed ceiling cannot grow implicitly."
+    },
+    "packages/core/next-development-controller.js": {
+      "maxLines": 728,
+      "rationale": "The durable controller keeps atomic child identity, rooted checkpoints, idempotent materialization operations, latest protected Dev revalidation, PR settlement and exact source and derived root readback in one provider-neutral authority. It exposes no Alpha publication effect and resumes only through injected atomic store and executor boundaries; this exact reviewed ceiling cannot grow implicitly."
+    },
+    "actions/promote-buildchain-ref/internal/promote-alpha-channel.js": {
+      "maxLines": 599,
+      "rationale": "The extracted Alpha promotion stage replaces the former non-fast-forward skip with the existing exact-current-Dev regeneration contract, protected PR fallback, and fail-closed workspace binding; this exact reviewed ceiling cannot grow implicitly."
+    },
     "scripts/dev-delivery-source-proof-reuse.mjs": {
       "maxLines": 631,
       "rationale": "The bounded source-proof driver seals one exact PR qualification and verifies either the reviewed two-parent merge or GitHub's exact linear replay by base ancestry, commit count and every intermediate tree. Unknown, nonlinear, extra-commit or tree-drift compositions still fail closed to the full lifecycle, and this exact file ceiling cannot grow implicitly."
@@ -131,8 +143,8 @@
       "rationale": "The new-file budget evaluator recognizes only explicit path-scoped transitions with exact ceilings and mandatory rationales; the default budget and every existing no-widening check remain unchanged."
     },
     "scripts/check-inventory.mjs": {
-      "maxLines": 1486,
-      "rationale": "Inventory retains the recovery, sealed-bundle, no-product-install, and durable-finalization checks, requires the self-dogfood lock to match the current major, and binds every channel-router lane to the exact caller shell without unresolved static channel refs. This exact post-integration ceiling cannot grow implicitly."
+      "maxLines": 1497,
+      "rationale": "Inventory retains the complete recovery and publication authority set and additionally requires both bounded next-development self-dogfood command and harness files beside the contract, controller, schemas, fixtures, adapter, generated guidance and public documentation; this exact post-integration ceiling cannot grow implicitly."
     },
     "scripts/generate-channel-promotion-workflow.mjs": {
       "maxFunctionLines": 290,
@@ -149,8 +161,8 @@
       "rationale": "The existing Gate validator admits an explicit bounded long-form duration class while preserving the standard 60-second default and exact capture-to-scene binding; this exact post-integration ceiling cannot grow implicitly."
     },
     "scripts/dev-alpha-candidate-patrol.mjs": {
-      "maxLines": 1184,
-      "rationale": "The existing single-flight exact-source Alpha controller now idempotently registers repository-selected GitHub auto-merge intent only after settlement revalidation, with explicit merge-method validation and no direct merge or approval path; this exact ceiling cannot grow implicitly."
+      "maxLines": 1197,
+      "rationale": "The existing single-flight exact-source Alpha controller delegates next-development reservation validation to the bounded core reader, carries the rooted result into selection, and retains the no-publication boundary; this exact ceiling cannot grow implicitly."
     },
     "scripts/build-contract-core.mjs": {
       "maxLines": 1229,

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

@@ -69,6 +69,11 @@
         "root": "packages/core",
         "pattern": "^release-activation-transaction\\.js$"
       },
+      {
+        "mechanismId": "next-development-controller",
+        "root": "packages/core",
+        "pattern": "^next-development-(?:transition|controller|candidate-reservation)\\.js$"
+      },
       {
         "mechanismId": "publication-authority",
         "root": "packages/core",
@@ -130,6 +135,90 @@
     "orphanPolicy": "Every state-bearing mechanism must own source, tests, public surfaces, durable-store disposition, recovery, and v4 migration disposition; missing or ambiguous ownership fails validation."
   },
   "mechanisms": [
+    {
+      "id": "next-development-controller",
+      "owner": "Buildchain protected development version plane",
+      "writers": [
+        "completed Alpha terminal-success schedulers",
+        "packages/core/next-development-controller.js"
+      ],
+      "schemas": [
+        "kungfu-buildchain-next-development-transition/v1",
+        "kungfu-buildchain-next-development-controller/v1"
+      ],
+      "stores": [
+        "atomic child store keyed by repository and completed-Alpha root",
+        "compare-and-swap rooted controller checkpoints"
+      ],
+      "states": [
+        "planned",
+        "waiting-anchor",
+        "materialized",
+        "pr-pending",
+        "merged",
+        "verified"
+      ],
+      "events": [
+        "schedule",
+        "bind-reviewed-anchor",
+        "materialize-current-dev",
+        "open-protected-version-pr",
+        "record-merge",
+        "verify-protected-dev-readback"
+      ],
+      "transitions": [
+        "one completed Alpha creates or reuses one deterministic durable child",
+        "stale Dev material is superseded before protected delivery",
+        "merged reaches verified only after exact source and derived root readback"
+      ],
+      "recovery": [
+        "fresh runners load the durable child and resume the last rooted checkpoint",
+        "idempotent materialization operation keys reuse effects after lost responses"
+      ],
+      "effects": [
+        "declared source and derived version material",
+        "protected Dev version pull request"
+      ],
+      "retry": [
+        "Dev movement supersedes only the stale materialization attempt",
+        "readback mismatch remains merged and retries observation without rebuilding"
+      ],
+      "invalidation": [
+        "completed Alpha identity drift",
+        "undeclared changed path",
+        "durable compare-and-swap conflict",
+        "protected Dev version or root disagreement"
+      ],
+      "providerReadback": [
+        "latest protected Dev SHA",
+        "protected version PR status",
+        "protected Dev ancestry, target version, source roots, and derived roots"
+      ],
+      "publicSurfaces": [
+        "cli:next-development",
+        "export:./next-development-transition",
+        "export:./next-development-controller",
+        "export:./next-development-projection"
+      ],
+      "compatibilityCallers": [
+        "v4 completed-Alpha schedulers through the atomic store and executor interfaces"
+      ],
+      "sourcePaths": [
+        "packages/core/next-development-transition.js",
+        "packages/core/next-development-controller.js",
+        "packages/core/next-development-candidate-reservation.js"
+      ],
+      "testPaths": [
+        "tests/next-development-transition.test.mjs",
+        "tests/next-development-controller.test.mjs",
+        "tests/dev-alpha-candidate-patrol.test.mjs",
+        "tests/next-development-self-dogfood.test.mjs"
+      ],
+      "migrationDisposition": "v4-authoritative-with-public-consumer-lifecycle-proof",
+      "unresolved": [
+        "provider-specific durable-store retention and workflow wake policy remain caller-owned integration choices"
+      ]
+    },
     {
       "id": "dev-delivery-warrant",
       "owner": "Buildchain Dev delivery control plane",

package/architecture/v4-capability-state-machine-manifest.json

@@ -83,6 +83,18 @@
     }
   },
   "capabilities": [
+    {
+      "id": "next-development-controller",
+      "owner": "Buildchain protected development version plane",
+      "sourceInventoryId": "next-development-controller",
+      "surfaces": [
+        "cli:next-development",
+        "export:./next-development-transition",
+        "export:./next-development-controller",
+        "export:./next-development-projection"
+      ],
+      "migrationPhase": "legacy-retired"
+    },
     {
       "id": "dev-delivery-warrant",
       "owner": "Buildchain Dev delivery control plane",
@@ -198,6 +210,67 @@
     }
   ],
   "stateMachines": [
+    {
+      "id": "next-development-controller",
+      "capabilityId": "next-development-controller",
+      "owner": "Buildchain protected development version plane",
+      "writer": {
+        "runtime": "typescript-v4",
+        "authoritative": true,
+        "secondWriterBudget": 0
+      },
+      "schemas": [
+        "kungfu-buildchain-next-development-transition/v1",
+        "kungfu-buildchain-next-development-controller/v1"
+      ],
+      "store": "atomic child store with compare-and-swap rooted checkpoints",
+      "states": [
+        "planned",
+        "waiting-anchor",
+        "materialized",
+        "pr-pending",
+        "merged",
+        "verified"
+      ],
+      "events": [
+        "schedule",
+        "bind-reviewed-anchor",
+        "materialize-current-dev",
+        "open-protected-version-pr",
+        "record-merge",
+        "verify-protected-dev-readback"
+      ],
+      "invariants": [
+        "completed Alpha remains terminal and immutable",
+        "one deterministic child exists per completed-Alpha root",
+        "verified requires exact protected Dev version and root readback"
+      ],
+      "effects": [
+        "write declared version source and derived material",
+        "request one protected Dev version pull request"
+      ],
+      "adapters": [
+        "atomic durable child store",
+        "version-state materialization adapter",
+        "protected Dev pull-request and readback adapter"
+      ],
+      "tests": [
+        "tests/next-development-transition.test.mjs",
+        "tests/next-development-controller.test.mjs",
+        "tests/next-development-self-dogfood.test.mjs",
+        "tests/dev-alpha-candidate-patrol.test.mjs"
+      ],
+      "recovery": [
+        "fresh runners resume the last rooted checkpoint and reuse idempotent materialization operations",
+        "moved protected Dev supersedes only stale preparation and readback mismatch retries observation"
+      ],
+      "migrationPhase": "legacy-retired",
+      "budgets": {
+        "undeclaredStates": 0,
+        "undeclaredEvents": 0,
+        "unboundedRetries": 0
+      }
+    },
     {
       "id": "dev-delivery-warrant",
       "capabilityId": "dev-delivery-warrant",

package/architecture/v4-compatibility-facts-parity.json

@@ -0,0 +1,77 @@
+{
+  "schema": "buildchain.v4.compatibility-facts-parity/v1",
+  "source": {
+    "branch": "dev/v3/v3.0",
+    "commit": "6b96bdad8d9f8ccf9275f27d9370a226a9c78465",
+    "factRegistry": "packages/core/buildchain-compatibility-facts.json"
+  },
+  "target": {
+    "branch": "dev/v4/v4.0",
+    "commit": "60e61d0a17bdf41262454a3499aae430248036fc",
+    "schema": "contracts/v4-compatibility-facts-v1.schema.json"
+  },
+  "rootProtocol": "kungfu.fact-root.canonical/v2",
+  "matrixRoot": "sha256:be099fcb4ecc5ec0bf24e86853246d12210b2f6d082e928ce90a40b00345f262",
+  "matrix": [
+    {
+      "invariant": "immutable-directional-relation",
+      "v3": "source-to-target Fact",
+      "v4": "source-to-target Fact",
+      "parity": "exact"
+    },
+    {
+      "invariant": "operation-scope",
+      "v3": "accept-contract-lock",
+      "v4": "accept-contract-lock",
+      "parity": "exact"
+    },
+    {
+      "invariant": "time-awareness",
+      "v3": "validFromCutRoot plus Cut ancestry",
+      "v4": "validFromCutRoot plus Cut ancestry",
+      "parity": "exact"
+    },
+    {
+      "invariant": "append-only-current-truth",
+      "v3": "supersede and revoke records",
+      "v4": "supersede and revoke records",
+      "parity": "exact"
+    },
+    {
+      "invariant": "explicit-path",
+      "v3": "direct default and explicit bounded composition",
+      "v4": "direct default and explicit bounded composition",
+      "parity": "exact"
+    },
+    {
+      "invariant": "negative-receipts",
+      "v3": "rooted accepted or rejected path receipt",
+      "v4": "byte-identical Rust and TypeScript receipt",
+      "parity": "safety-equivalent"
+    },
+    {
+      "invariant": "legacy-digest-projection",
+      "v3": "compatibleBreakingDigests derived from proofs and Facts",
+      "v4": "exact-target current Facts derive digest arrays",
+      "parity": "safety-equivalent"
+    },
+    {
+      "invariant": "legacy-proof-projection",
+      "v3": "v1 proof roots retained",
+      "v4": "v1 proof roots retained as non-authoritative lineage",
+      "parity": "exact"
+    },
+    {
+      "invariant": "release-passport",
+      "v3": "Fact lineage available to verification receipt",
+      "v4": "Fact, Cut, proof and path roots attach as non-release-authority evidence",
+      "parity": "safety-equivalent"
+    },
+    {
+      "invariant": "unknown-state",
+      "v3": "fail closed",
+      "v4": "missing ambiguous expired revoked wrong-direction wrong-Cut disconnected and corrupt fail closed",
+      "parity": "exact"
+    }
+  ]
+}