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

package/docs/v4-compatibility-facts.md

@@ -0,0 +1,91 @@
+---
+status: active
+period: ongoing
+theme: buildchain-v4-compatibility-facts
+doc_type: technical-reference
+source_level: local-files
+confidence: high
+sensitivity: public
+evidence_grade: A
+review_state: unreviewed
+last_reviewed: 2026-08-16
+ai_provenance:
+  model_family: GPT-5
+  product: Codex
+  generated_at: 2026-08-16
+  invisible_context: not asserted
+---
+
+# Buildchain v4 compatibility Facts
+
+Buildchain v4 authorizes contract compatibility with immutable, directional
+Facts. `compatibleBreakingDigests` and the v1 proof objects remain public for
+older consumers, but they are deterministic projections. Neither can authorize
+a transition without the current Fact registry, its exact Project Cut, and a
+verified path receipt.
+
+## Authority chain
+
+The package source is
+`packages/core/buildchain-compatibility-facts.json`, retained from v3 exact head
+`6b96bdad8d9f8ccf9275f27d9370a226a9c78465`. Each declaration becomes a KFR2
+predicate and relation, then enters an append-only temporal bundle. The
+registry identity binds all Fact, proof, Cut, supersession, revocation, and
+bundle roots.
+
+V4 projects a legacy digest only when a verified Fact targets the exact current
+surface kind, ID, and breaking digest. The old proof's v2/v3 `majorLines` field
+is historical projection metadata; it does not narrow or enlarge the
+digest-and-Cut-bound Fact. A target digest that has changed since v3 receives no
+projection.
+
+## Decision semantics
+
+- Direction is always source to target. Reverse use rejects.
+- The only operation is `accept-contract-lock`.
+- Evaluation selects one direct Fact. It never searches for a path or infers
+  symmetry or transitivity.
+- Composition requires an ordered caller-supplied path and positive bounded
+  depth.
+- Supersession and revocation append lifecycle records. Old Cuts replay old
+  truth; later Cuts deterministically reject superseded or revoked relations.
+- A revocation is the safety-equivalent expiry boundary: compatibility has no
+  wall-clock-only truth outside a rooted Cut.
+- Missing, ambiguous, not-yet-valid, revoked, superseded, wrong-direction,
+  wrong-Cut, disconnected, cyclic, inactive, or corrupted inputs produce a
+  rooted rejected receipt.
+
+Rust and TypeScript implement the same KFR2 closed-field encoding and emit
+byte-identical JSON for the shared fixture in
+`contracts/fixtures/v4-compatibility-facts-v1/shared.json`.
+
+## CLI and Node API
+
+Project and verify the built-in registry:
+
+```sh
+npx @kungfu-tech/buildchain facts compatibility project --json
+npx @kungfu-tech/buildchain facts compatibility verify --json
+```
+
+Create a direct query template for one current Fact, then verify it:
+
+```sh
+npx @kungfu-tech/buildchain facts compatibility query-template \
+  --fact-root sha256:... --json
+npx @kungfu-tech/buildchain facts compatibility query \
+  --query query.json --registry registry.json --json
+```
+
+The `@kungfu-tech/buildchain/compatibility-fact-authority` export provides the
+same constructors, verifiers, resolver, and Release Passport evidence helper.
+Compatibility evidence explicitly sets `grantsReleaseAuthority: false`; it can
+be attached through the existing release-evidence route but cannot publish,
+merge, sign, or release anything.
+
+## Updating the registry
+
+Append a new source Fact or lifecycle record. Never rewrite an existing Fact,
+directly edit a surface digest allowlist, or convert a caller claim into
+authority. Regenerate references and site facts, then run the shared parity
+fixture and the complete repository check.

package/docs/v4-tail-reseal.md

@@ -0,0 +1,73 @@
+# V4 retained-candidate tail reseal
+
+Buildchain v4 can recover one narrowly defined late Alpha failure without
+rebuilding a qualified four-platform candidate. The recovery is not a cache hit
+and does not give Stage Capsule any provider authority. It is a fresh governed
+run that proves all retained bytes first, then executes only the explicitly
+fenced macOS signing-finalization tail.
+
+The authoritative request schema is
+[`contracts/v4-tail-reseal-v1.schema.json`](../contracts/v4-tail-reseal-v1.schema.json).
+It binds the failed run and source tree, four payload and manifest archive
+digests, four content roots, Stage Capsule roots and reuse decisions, Warrant
+lineage, retention, credential authority, signing delegation/result, release
+tail transaction, idempotency key, and independent provider readbacks. Any
+mismatch rejects reuse and requires a normal candidate build.
+
+## Authority boundary
+
+- `install`, `build`, `verify`, `package`, and the ordinary platform matrix are
+  skipped only when all 16 per-platform Stage Capsule decisions prove exact
+  reuse. Capsule reuse has no external effects.
+- Only `macos-arm64:signing-finalization` may change payload bytes. The public
+  workflow verifies the retained macOS bytes before the effect and verifies the
+  resealed bytes plus signing and release-tail readbacks afterward.
+- The signing token exists only in the macOS credential-island step. It is not
+  stored in a Capsule, request, artifact, log, Passport, or receipt.
+- A successful run emits the existing
+  `kungfu-buildchain-release-candidate-passport` contract. Tail reseal does not
+  create a second candidate or release artifact class.
+- Durable callers use `@v4-alpha` during Alpha evaluation or `@v4` after stable
+  promotion. Exact SHAs are runtime evidence from `job.workflow_sha`, never a
+  persisted selector.
+
+## CLI and Node API
+
+Plan locally from the deterministic data contract:
+
+```sh
+buildchain tail-reseal plan \
+  --request .buildchain/tail-reseal/request.json \
+  --output .buildchain/tail-reseal/plan.json
+```
+
+`tail-reseal admit` performs the provider readback of the exact failed run,
+jobs, retained GitHub artifact archives, and signing-authority result. Each
+fresh platform runner then uses `verify-platform --mode retained`. Only the
+macOS runner may follow with `--mode resealed --provider-readback-root ...`.
+After the ordinary Release Candidate Passport is generated, `tail-reseal seal`
+binds all four readbacks and the protected Warrant readback into the final
+receipt.
+
+The Node exports are `@kungfu-tech/buildchain/v4-tail-reseal` for request and
+plan logic and `@kungfu-tech/buildchain/v4-tail-reseal-receipt` for terminal
+receipt creation and verification.
+
+## Reusable workflow
+
+Consumers invoke
+`kungfu-systems/buildchain/.github/workflows/v4-tail-reseal.yml@v4-alpha` from a
+trusted, same-repository workflow. The caller supplies the rooted request, the
+original candidate consumer-policy receipt, a reviewed macOS finalization
+command, and the explicitly named signing secret. The command must write:
+
+- `.buildchain/tail-reseal/signing-provider-readback.json`
+- `.buildchain/tail-reseal/release-tail-provider-readback.json`
+
+Their byte digests must equal the roots fixed in the request. The workflow
+downloads the signing result by exact authority repository, run, artifact name,
+and archive digest; no credential or provider effect is replayed from a Stage
+Capsule.
+
+The v3-to-v4 invariant mapping is recorded in
+[`architecture/v4-tail-reseal-parity.json`](../architecture/v4-tail-reseal-parity.json).

package/docs/versioning.md

@@ -79,9 +79,10 @@ repository changes are patch".
 
 | Date       | Action       | Line    | Faces                                                                                                                                                                        | Class    | Rationale                                                                                                                                                                                                                                                                                                                              | PR    |
 | ---------- | ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
-| 2026-08-14 | extend-minor | `v4.0`  | source-qualification-proof-v2, source-proof-reuse-decision, reusable-check-workflow                                                                                           | additive | Forward-port opt-in exact accepted source-proof reuse for merge groups, binding source, base, patch, runtime, plan, policy, closure, dependency, required-context, producer receipt, and caller run. Any missing or changed predicate fails closed to the existing full source lifecycle, which remains the default.                      |       |
-| 2026-08-11 | extend-minor | `v4.0`  | release-blocker-repair-contract, release-blocker-priority-claim, release-train-node-export, dev-delivery-warrant-node-export                                                 | additive | Forward-port rooted successor candidate generations, exact semantic patch identity across cut and Dev landings, publication blocking through conflict or mismatch, and the narrow non-preemptive Warrant blocker lane already protected and self-dogfood-proven on v3.                                                               |       |
-| 2026-08-10 | extend-minor | `v4.0`  | release-cut-contract, release-train-state-machine, release-train-node-export                                                                                                | additive | Forward-port the provider-neutral rooted Release Cut and idempotent Release Train state contract already proven on v3; candidate, tree, Alpha base, runtime, generation, and authority stay frozen while later Dev movement remains an observation rather than implicit supersession.                                                   |       |
+| 2026-08-16 | extend-minor | `v4.0`  | next-development-transition, next-development-controller, next-development-projection, next-development-cli                                                                  | additive | Forward-port the rooted completed-Alpha successor contract, semver/auto and anchored/manual modes, CAS recovery, protected Dev reconciliation, reservation readback, public templates, and consumer-equivalent lifecycle proof from the exact v3 evidence into v4.                                                                     |       |
+| 2026-08-14 | extend-minor | `v4.0`  | source-qualification-proof-v2, source-proof-reuse-decision, reusable-check-workflow                                                                                          | additive | Forward-port opt-in exact accepted source-proof reuse for merge groups, binding source, base, patch, runtime, plan, policy, closure, dependency, required-context, producer receipt, and caller run. Any missing or changed predicate fails closed to the existing full source lifecycle, which remains the default.                   |       |
+| 2026-08-11 | extend-minor | `v4.0`  | release-blocker-repair-contract, release-blocker-priority-claim, release-train-node-export, dev-delivery-warrant-node-export                                                 | additive | Forward-port rooted successor candidate generations, exact semantic patch identity across cut and Dev landings, publication blocking through conflict or mismatch, and the narrow non-preemptive Warrant blocker lane already protected and self-dogfood-proven on v3.                                                                 |       |
+| 2026-08-10 | extend-minor | `v4.0`  | release-cut-contract, release-train-state-machine, release-train-node-export                                                                                                 | additive | Forward-port the provider-neutral rooted Release Cut and idempotent Release Train state contract already proven on v3; candidate, tree, Alpha base, runtime, generation, and authority stay frozen while later Dev movement remains an observation rather than implicit supersession.                                                  |       |
 | 2026-08-08 | extend-minor | `v4.0`  | dev-delivery-warrant-read-candidate, rust-state-projection, dev-delivery-cli                                                                                                 | additive | Add an opt-in, qualification-bound read projection behind `observe --read-mode v4`; v3 remains the sole writer and default reader, mutation commands ignore the switch, failures stop, and rollback is the explicit caller change back to v3.                                                                                          |       |
 | 2026-08-05 | extend-minor | `v3.0`  | auditable-demo-scenario, auditable-demo-capture, auditable-demo-adapter                                                                                                      | additive | Add an opt-in deterministic readable-playback declaration that preserves captured terminal payloads and order while normalizing only presentation timing; omitted playback continues to use observed PTY timestamps, and existing composition modes remain unchanged.                                                                  |       |
 | 2026-08-04 | extend-minor | `v3.0`  | dev-delivery-warrant-queue, source-qualification-proof, integration-delivery-proof, dev-delivery-cli, reusable-dev-delivery-workflows                                        | additive | Add durable fair and fenced protected-dev scheduling plus split source/integration proof contracts. Existing PR admission remains available through explicit `off` and `shadow` rollout modes; no existing command, export, or release flow is removed.                                                                                |       |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kungfu-tech/buildchain",
-  "version": "4.0.1-alpha.3",
+  "version": "4.0.1-alpha.5",
   "private": false,
   "description": "Buildchain Release Passport, release governance, CLI toolkit, and site facts.",
   "repository": "https://github.com/kungfu-systems/buildchain",
@@ -23,6 +23,7 @@
     "./detached-artifact-signature": "./packages/core/detached-artifact-signature.js",
     "./anchored-version-material": "./packages/core/anchored-version-material.js",
     "./buildchain-contract": "./packages/core/buildchain-contract.js",
+    "./compatibility-fact-authority": "./packages/core/buildchain-compatibility-proof.js",
     "./candidate-timeline": "./packages/core/candidate-timeline.js",
     "./channel-candidate": "./packages/core/channel-candidate.js",
     "./cache-evidence": "./packages/core/cache-evidence.js",
@@ -43,6 +44,8 @@
     "./public-surface-audit": "./packages/core/public-surface-audit.js",
     "./v4-floating-consumer-policy": "./packages/core/v4-floating-consumer-policy.js",
     "./v4-runtime-ref-resume-authority": "./packages/core/v4-runtime-ref-resume-authority.js",
+    "./v4-tail-reseal": "./packages/core/v4-tail-reseal.js",
+    "./v4-tail-reseal-receipt": "./packages/core/v4-tail-reseal-receipt.js",
     "./logging": "./packages/core/logging.js",
     "./portable-dev-cache": "./packages/core/portable-dev-cache.js",
     "./publication-artifact": "./packages/core/publication-artifact.js",
@@ -60,6 +63,9 @@
     "./release-candidate": "./packages/core/release-candidate.js",
     "./release-candidate-recovery": "./packages/core/release-candidate-recovery.js",
     "./release-train": "./packages/core/release-train.js",
+    "./next-development-transition": "./packages/core/next-development-transition.js",
+    "./next-development-controller": "./packages/core/next-development-controller.js",
+    "./next-development-projection": "./packages/core/next-development-projection.js",
     "./stable-candidate-ledger": "./packages/core/stable-candidate-ledger.js",
     "./release-passport": "./packages/core/release-passport.js",
     "./release-passport-contract": "./packages/core/release-passport-contract.js",
@@ -92,6 +98,7 @@
     "./site/schemas/kfd-product-gate-input-v1.schema.json": "./dist/site/schemas/kfd-product-gate-input-v1.schema.json",
     "./site/schemas/kfd-support-projection-v1.schema.json": "./dist/site/schemas/kfd-support-projection-v1.schema.json",
     "./site/schemas/dev-delivery-authority-v2.schema.json": "./dist/site/schemas/dev-delivery-authority-v2.schema.json",
+    "./site/schemas/v4-compatibility-facts-v1.schema.json": "./dist/site/schemas/v4-compatibility-facts-v1.schema.json",
     "./site/buildchain-contract.json": "./dist/site/buildchain-contract.json",
     "./site/product-mechanism.json": "./dist/site/product-mechanism.json",
     "./site/release-provenance.json": "./dist/site/release-provenance.json",
@@ -130,14 +137,16 @@
     "precheck:static": "prettier --check architecture/decisions/0003-two-phase-delivery-warrant.md architecture/v4-delivery-authority-parity.json contracts/dev-delivery-authority-v2.schema.json dist/site/schemas/dev-delivery-authority-v2.schema.json docs/dev-delivery-qualification-landing-adr.md packages/core/dev-delivery-authority-candidate.js packages/core/dev-delivery-authority-evidence.js packages/core/dev-delivery-authority-landing.js packages/core/dev-delivery-authority-observation.js packages/core/dev-delivery-authority-qualification.js packages/core/dev-delivery-authority-settlement.js packages/core/dev-delivery-authority-state.js packages/core/dev-delivery-execution-failure.js packages/core/dev-delivery-execution-transfer.js packages/core/dev-delivery-landing-readback.js packages/core/dev-delivery-landing-terminal-evidence.js packages/core/dev-delivery-landing-testing-port.js packages/core/dev-delivery-native-execution.js packages/core/dev-delivery-native-proof.js packages/core/dev-delivery-process-boundary.js packages/core/dev-delivery-warrant-qualification.js packages/core/dev-delivery-warrant-state.js scripts/dev-delivery-authority-command-adapters.mjs scripts/dev-delivery-authority-provider.mjs scripts/dev-delivery-authority.mjs scripts/dev-delivery-native-run.mjs scripts/dev-delivery-process-boundary.mjs scripts/dev-delivery-two-phase-resume.mjs scripts/dev-delivery-two-phase.mjs scripts/dev-delivery-warrant-options.mjs scripts/dev-delivery-warrant-store.mjs templates/native-dev-delivery.yml",
     "operator:windows-jit": "bash scripts/aws-windows-jit-operator.sh",
     "check": "pnpm run check:static && node scripts/check-v4-public-dogfood-contract.mjs && node scripts/check-v4-floating-consumer-policy-contract.mjs && pnpm run check:v4-bridge && pnpm run check:v4-contracts && node scripts/check-maintainability.mjs && node scripts/check-internal-architecture.mjs && node scripts/check-inventory.mjs && node scripts/check-core-mechanism-inventory.mjs && node scripts/check-release-tail-contract.mjs && node scripts/v4-architecture.mjs validate && node scripts/v4-warrant-shadow-plan.mjs validate && pnpm run check:site && pnpm run check:workflows && pnpm run test:unit && pnpm run check:golden-path && node scripts/check-action-bundles.mjs",
-    "check:static": "node scripts/check-javascript-syntax.mjs && prettier --check architecture/*.json contracts/release-tail-provider-bindings-v1.schema.json contracts/v4-canonical-contracts-v1.schema.json contracts/v4-delivery-warrant-semantic-diff-report-v1.schema.json contracts/v4-delivery-warrant-trace-v1.schema.json contracts/v4-floating-consumer-policy-receipt-v1.schema.json contracts/v4-runtime-ref-resume-authority-v1.schema.json contracts/v4-host-contract-v1.schema.json contracts/v4-provider-operation-journal-v1.schema.json contracts/v4-release-activation-shadow-v1.schema.json contracts/v4-stable-publication-fence-v1.schema.json contracts/v4-partial-mutation-recovery-v1.schema.json contracts/v4-stage-capsule-v1.schema.json contracts/v4-stage-capsule-store-v1.schema.json contracts/v4-stage-capsule-resume-v1.schema.json contracts/release-tail-capabilities-v1.schema.json contracts/fixtures/release-tail-capabilities-v1/*.json contracts/fixtures/v4-delivery-warrant-trace-v1/*.json contracts/fixtures/v4-floating-consumer-policy-v1/*.json contracts/fixtures/v4-runtime-ref-resume-authority-v1/*.json contracts/fixtures/v4-provider-operation-journal-v1/*.json contracts/fixtures/v4-provider-readback-idempotency-v1/*.json contracts/fixtures/v4-release-activation-shadow-v1/*.json contracts/fixtures/v4-stable-publication-fence-v1/*.json contracts/fixtures/v4-partial-mutation-recovery-v1/*.json contracts/fixtures/v4-stage-capsule-v1/*.json contracts/fixtures/v4-stage-capsule-store-v1/*.json contracts/fixtures/v4-stage-capsule-resume-v1/*.json bin/internal/command-registry.mjs packages/core/v4-canonical-contracts.js packages/core/v4-floating-consumer-evidence.js packages/core/v4-floating-consumer-policy.js packages/core/v4-floating-consumer-release-passport.js packages/core/v4-runtime-ref-resume-authority.js packages/core/v4-runtime-selector-persistence.js packages/core/v4-provider-operation-journal.js packages/core/v4-provider-readback-idempotency.js packages/core/v4-release-activation-shadow.js packages/core/v4-stable-publication-fence.js packages/core/v4-partial-mutation-recovery-qualification.js packages/core/v4-stage-capsule.js packages/core/v4-stage-capsule-store.js packages/core/v4-stage-capsule-local-store.js packages/core/v4-platform-stage-checkpoints.js packages/core/v4-stage-capsule-resume-planner.js packages/core/v4-stage-capsule-qualification.js packages/core/v4-stage-capsule-qualification-campaign.js packages/core/v4-delivery-warrant-fixture-runner.js packages/core/v4-delivery-warrant-read-candidate.js packages/core/v4-delivery-warrant-semantic-diff-gate.js packages/core/v4-delivery-warrant-shadow-adapter.js scripts/authorize-promotion-runtime-override.cjs scripts/check-core-mechanism-inventory.mjs scripts/check-release-tail-contract.mjs scripts/check-javascript-syntax.mjs scripts/check-maintainability.mjs scripts/dev-pr-prequeue-guard.mjs scripts/check-v4-public-dogfood-contract.mjs scripts/maintainability-metrics.mjs scripts/public-reference.mjs scripts/site-reference-registry.mjs scripts/generate-public-reference.mjs scripts/v4-architecture.mjs scripts/v4-bridge-bootstrap.mjs scripts/v4-bridge-evidence.mjs scripts/v4-consumer-policy.mjs scripts/v4-host-adapter.mjs scripts/v4-platform-stage-checkpoint-rehearsal.mjs scripts/v4-stage-capsule-resume-rehearsal.mjs scripts/v4-stage-capsule-qualification.mjs scripts/v4-warrant-shadow-plan.mjs scripts/verify-golden-path.mjs tests/authorize-promotion-runtime-override.test.mjs tests/command-registry.test.mjs tests/core-mechanism-inventory.test.mjs tests/release-tail-contract.test.mjs tests/maintainability.test.mjs tests/promotion-responsibilities.test.mjs tests/public-reference.test.mjs tests/v4-architecture.test.mjs tests/v4-bridge.test.mjs tests/v4-canonical-contracts.test.mjs tests/v4-delivery-warrant-fixture-runner.test.mjs tests/v4-delivery-warrant-read-candidate.test.mjs tests/v4-floating-consumer-policy.test.mjs tests/v4-runtime-ref-resume-authority.test.mjs tests/v4-platform-stage-checkpoints.test.mjs tests/v4-provider-operation-journal.test.mjs tests/v4-provider-readback-idempotency.test.mjs tests/v4-public-dogfood-contract.test.mjs tests/v4-release-activation-shadow.test.mjs tests/v4-stable-publication-fence.test.mjs tests/v4-partial-mutation-recovery-qualification.test.mjs tests/v4-stage-capsule.test.mjs tests/v4-stage-capsule-store.test.mjs tests/v4-stage-capsule-resume-planner.test.mjs tests/v4-stage-capsule-qualification.test.mjs tests/v4-warrant-shadow-plan.test.mjs",
+    "check:static": "node scripts/check-javascript-syntax.mjs && prettier --check architecture/*.json contracts/release-tail-provider-bindings-v1.schema.json contracts/v4-canonical-contracts-v1.schema.json contracts/v4-compatibility-facts-v1.schema.json contracts/v4-delivery-warrant-semantic-diff-report-v1.schema.json contracts/v4-delivery-warrant-trace-v1.schema.json contracts/v4-floating-consumer-policy-receipt-v1.schema.json contracts/v4-runtime-ref-resume-authority-v1.schema.json contracts/v4-tail-reseal-v1.schema.json contracts/v4-host-contract-v1.schema.json contracts/v4-provider-operation-journal-v1.schema.json contracts/v4-release-activation-shadow-v1.schema.json contracts/v4-stable-publication-fence-v1.schema.json contracts/v4-partial-mutation-recovery-v1.schema.json contracts/v4-stage-capsule-v1.schema.json contracts/v4-stage-capsule-store-v1.schema.json contracts/v4-stage-capsule-resume-v1.schema.json contracts/release-tail-capabilities-v1.schema.json contracts/fixtures/release-tail-capabilities-v1/*.json contracts/fixtures/v4-delivery-warrant-trace-v1/*.json contracts/fixtures/v4-floating-consumer-policy-v1/*.json contracts/fixtures/v4-runtime-ref-resume-authority-v1/*.json contracts/fixtures/v4-tail-reseal-v1/*.json contracts/fixtures/v4-compatibility-facts-v1/*.json contracts/fixtures/v4-provider-operation-journal-v1/*.json contracts/fixtures/v4-provider-readback-idempotency-v1/*.json contracts/fixtures/v4-release-activation-shadow-v1/*.json contracts/fixtures/v4-stable-publication-fence-v1/*.json contracts/fixtures/v4-partial-mutation-recovery-v1/*.json contracts/fixtures/v4-stage-capsule-v1/*.json contracts/fixtures/v4-stage-capsule-store-v1/*.json contracts/fixtures/v4-stage-capsule-resume-v1/*.json bin/internal/command-registry.mjs bin/internal/compatibility-facts-cli.mjs packages/core/v4-canonical-contracts.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/v4-floating-consumer-evidence.js packages/core/v4-floating-consumer-policy.js packages/core/v4-floating-consumer-release-passport.js packages/core/v4-runtime-ref-resume-authority.js packages/core/v4-tail-reseal-contract.js packages/core/v4-tail-reseal-github.js packages/core/v4-tail-reseal-receipt.js packages/core/v4-tail-reseal.js packages/core/v4-runtime-selector-persistence.js packages/core/v4-provider-operation-journal.js packages/core/v4-provider-readback-idempotency.js packages/core/v4-release-activation-shadow.js packages/core/v4-stable-publication-fence.js packages/core/v4-partial-mutation-recovery-qualification.js packages/core/v4-stage-capsule.js packages/core/v4-stage-capsule-store.js packages/core/v4-stage-capsule-local-store.js packages/core/v4-platform-stage-checkpoints.js packages/core/v4-stage-capsule-resume-planner.js packages/core/v4-stage-capsule-qualification.js packages/core/v4-stage-capsule-qualification-campaign.js packages/core/v4-delivery-warrant-fixture-runner.js packages/core/v4-delivery-warrant-read-candidate.js packages/core/v4-delivery-warrant-semantic-diff-gate.js packages/core/v4-delivery-warrant-shadow-adapter.js scripts/authorize-promotion-runtime-override.cjs scripts/check-core-mechanism-inventory.mjs scripts/check-release-tail-contract.mjs scripts/check-javascript-syntax.mjs scripts/check-maintainability.mjs scripts/dev-pr-prequeue-guard.mjs scripts/check-v4-public-dogfood-contract.mjs scripts/maintainability-metrics.mjs scripts/public-reference.mjs scripts/site-reference-registry.mjs scripts/generate-public-reference.mjs scripts/v4-architecture.mjs scripts/v4-bridge-bootstrap.mjs scripts/v4-bridge-evidence.mjs scripts/v4-consumer-policy.mjs scripts/v4-host-adapter.mjs scripts/v4-platform-stage-checkpoint-rehearsal.mjs scripts/v4-stage-capsule-resume-rehearsal.mjs scripts/v4-stage-capsule-qualification.mjs scripts/v4-tail-reseal-macos-rehearsal.mjs scripts/v4-tail-reseal.mjs scripts/v4-warrant-shadow-plan.mjs scripts/verify-golden-path.mjs tests/authorize-promotion-runtime-override.test.mjs tests/command-registry.test.mjs tests/core-mechanism-inventory.test.mjs tests/release-tail-contract.test.mjs tests/maintainability.test.mjs tests/promotion-responsibilities.test.mjs tests/public-reference.test.mjs tests/v4-architecture.test.mjs tests/v4-bridge.test.mjs tests/v4-canonical-contracts.test.mjs tests/v4-delivery-warrant-fixture-runner.test.mjs tests/v4-delivery-warrant-read-candidate.test.mjs tests/v4-floating-consumer-policy.test.mjs tests/v4-runtime-ref-resume-authority.test.mjs tests/v4-tail-reseal.test.mjs tests/v4-tail-reseal-parity.test.mjs tests/v4-compatibility-facts.test.mjs tests/v4-platform-stage-checkpoints.test.mjs tests/v4-provider-operation-journal.test.mjs tests/v4-provider-readback-idempotency.test.mjs tests/v4-public-dogfood-contract.test.mjs tests/v4-release-activation-shadow.test.mjs tests/v4-stable-publication-fence.test.mjs tests/v4-partial-mutation-recovery-qualification.test.mjs tests/v4-stage-capsule.test.mjs tests/v4-stage-capsule-store.test.mjs tests/v4-stage-capsule-resume-planner.test.mjs tests/v4-stage-capsule-qualification.test.mjs tests/v4-warrant-shadow-plan.test.mjs",
     "check:v4-bridge": "cargo fmt --manifest-path crates/buildchain-v4-bridge/Cargo.toml -- --check && cargo clippy --locked --manifest-path crates/buildchain-v4-bridge/Cargo.toml -- -D warnings && cargo test --locked --manifest-path crates/buildchain-v4-bridge/Cargo.toml",
-    "check:v4-contracts": "cargo fmt --manifest-path crates/buildchain-v4-contracts/Cargo.toml -- --check && cargo clippy --locked --manifest-path crates/buildchain-v4-contracts/Cargo.toml -- -D warnings && cargo test --locked --manifest-path crates/buildchain-v4-contracts/Cargo.toml && node --test tests/v4-canonical-contracts.test.mjs tests/v4-delivery-warrant-fixture-runner.test.mjs tests/v4-delivery-warrant-read-candidate.test.mjs tests/v4-floating-consumer-policy-contract.test.mjs tests/v4-floating-consumer-policy.test.mjs tests/v4-runtime-ref-resume-authority.test.mjs tests/v4-platform-stage-checkpoints.test.mjs tests/v4-provider-operation-journal.test.mjs tests/v4-provider-readback-idempotency.test.mjs tests/v4-public-dogfood-contract.test.mjs tests/v4-release-activation-shadow.test.mjs tests/v4-stable-publication-fence.test.mjs tests/v4-partial-mutation-recovery-qualification.test.mjs tests/v4-stage-capsule.test.mjs tests/v4-stage-capsule-store.test.mjs tests/v4-stage-capsule-resume-planner.test.mjs tests/v4-stage-capsule-qualification.test.mjs",
+    "check:v4-contracts": "cargo fmt --manifest-path crates/buildchain-v4-contracts/Cargo.toml -- --check && cargo clippy --locked --manifest-path crates/buildchain-v4-contracts/Cargo.toml -- -D warnings && cargo test --locked --manifest-path crates/buildchain-v4-contracts/Cargo.toml && node --test tests/v4-canonical-contracts.test.mjs tests/v4-delivery-warrant-fixture-runner.test.mjs tests/v4-delivery-warrant-read-candidate.test.mjs tests/v4-floating-consumer-policy-contract.test.mjs tests/v4-floating-consumer-policy.test.mjs tests/v4-runtime-ref-resume-authority.test.mjs tests/v4-tail-reseal.test.mjs tests/v4-tail-reseal-parity.test.mjs tests/v4-compatibility-facts.test.mjs tests/v4-platform-stage-checkpoints.test.mjs tests/v4-provider-operation-journal.test.mjs tests/v4-provider-readback-idempotency.test.mjs tests/v4-public-dogfood-contract.test.mjs tests/v4-release-activation-shadow.test.mjs tests/v4-stable-publication-fence.test.mjs tests/v4-partial-mutation-recovery-qualification.test.mjs tests/v4-stage-capsule.test.mjs tests/v4-stage-capsule-store.test.mjs tests/v4-stage-capsule-resume-planner.test.mjs tests/v4-stage-capsule-qualification.test.mjs",
     "check:workflows": "bash scripts/check-workflows.sh",
     "generate:reference": "node scripts/generate-public-reference.mjs",
     "check:reference": "node scripts/generate-public-reference.mjs --check",
-    "generate:site": "pnpm run generate:reference && node scripts/generate-site-bundle.mjs",
-    "check:site": "pnpm run check:reference && node scripts/generate-site-bundle.mjs --check",
+    "generate:next-development": "node scripts/generate-next-development-guidance.mjs",
+    "check:next-development": "node scripts/generate-next-development-guidance.mjs --check",
+    "generate:site": "pnpm run generate:next-development && pnpm run generate:reference && node scripts/generate-site-bundle.mjs",
+    "check:site": "pnpm run check:next-development && pnpm run check:reference && node scripts/generate-site-bundle.mjs --check",
     "check:golden-path": "node scripts/verify-golden-path.mjs",
     "test:unit": "node --test tests/*.test.mjs",
     "build": "pnpm -r --filter \"./actions/**\" build",

package/packages/core/buildchain-agent-manuals.js

@@ -10,6 +10,7 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "github-governance-authority", title: "GitHub governance authority", path: "docs/github-governance-authority.md", plane: "verify" },
   { id: "release-candidate", title: "Release Candidate Passport", path: "docs/release-candidate.md", plane: "verify" },
   { id: "release-train", title: "Release Train and Release Cut", path: "docs/release-train.md", plane: "verify" },
+  { id: "next-development-transition", title: "Next-development transition", path: "docs/next-development-transition.md", plane: "verify" },
   { id: "release-propagation", title: "Release propagation", path: "docs/release-propagation.md", plane: "use" },
   { id: "readme-badges", title: "README badge blocks", path: "docs/readme-badges.md", plane: "use" },
   { id: "homebrew", title: "Homebrew distribution indexes", path: "docs/homebrew.md", plane: "use" },
@@ -33,6 +34,7 @@ export const BUILDCHAIN_AGENT_MANUALS = Object.freeze([
   { id: "release-tail-contract", title: "Declarative release-tail contract", path: "docs/release-tail-contract.md", plane: "verify" },
   { id: "release-tail-provider-plane", title: "Declarative release-tail provider plane", path: "docs/release-tail-provider-plane.md", plane: "use" },
   { id: "release-governance", title: "Release governance", path: "docs/release-governance.md", plane: "why" },
+  { id: "v4-compatibility-facts", title: "Buildchain v4 compatibility Facts", path: "docs/v4-compatibility-facts.md", plane: "verify" },
   { id: "release-flow", title: "Release flow", path: "docs/release-flow.md", plane: "verify" },
   { id: "runtime-train-validation", title: "Runtime train validation", path: "docs/runtime-train-validation.md", plane: "verify" },
   { id: "versioning", title: "Versioning", path: "docs/versioning.md", plane: "why" },

package/packages/core/buildchain-compatibility-authority.js

@@ -0,0 +1,336 @@
+import {
+  devDeliveryContentRoot as contentRoot,
+  devDeliveryExactRoot as exactRoot,
+  devDeliveryExactSha as exactSha,
+  devDeliveryText as text,
+} from "./dev-delivery-common.js";
+import {
+  BUILDCHAIN_COMPATIBILITY_PROOF_REGISTRY_SCHEMA,
+  BUILDCHAIN_COMPATIBILITY_RELEASE_EVIDENCE_SCHEMA,
+  createBuildchainCompatibilityFactRegistry,
+  createHistoricalBuildchainCompatibilityProofs,
+  verifyBuildchainCompatibilityProof,
+} from "./buildchain-compatibility-fact.js";
+import {
+  KUNGFU_TEMPORAL_PATH_QUERY_SCHEMA,
+  verifyKungfuTemporalPath,
+} from "./kungfu-temporal-fact.js";
+
+const COMPATIBILITY_OPERATION = "accept-contract-lock";
+const COMPATIBILITY_DIRECTION = "source-to-target";
+
+function exactText(value, label) {
+  const normalized = text(value);
+  if (!normalized) throw new Error(`${label} must not be empty`);
+  return normalized;
+}
+
+function factInputFromProof(proof) {
+  return {
+    proofId: proof.proofId,
+    surfaceId: proof.source.surfaceId,
+    surfaceKind: proof.source.surfaceKind,
+    sourceBreakingDigest: proof.source.breakingDigest,
+    targetBreakingDigest: proof.target.breakingDigest,
+    scope: proof.scope,
+    evidence: proof.evidence,
+    authority: proof.authority,
+    cut: proof.cut,
+  };
+}
+
+function projectionForSurface({ proofs, factByProofRoot, surface }) {
+  const matching = proofs.filter(
+    (proof) =>
+      proof.target.surfaceId === surface.id &&
+      proof.target.surfaceKind === surface.kind &&
+      proof.target.breakingDigest === surface.breakingDigest &&
+      proof.operation === COMPATIBILITY_OPERATION,
+  );
+  const bySource = new Map();
+  for (const proof of matching) {
+    const sourceDigest = proof.source.breakingDigest;
+    if (bySource.has(sourceDigest))
+      throw new Error(
+        `ambiguous compatibility proof for ${surface.id} ${sourceDigest}`,
+      );
+    bySource.set(sourceDigest, proof);
+  }
+  return [...bySource.values()]
+    .sort((left, right) =>
+      left.source.breakingDigest.localeCompare(right.source.breakingDigest),
+    )
+    .map((proof) => ({
+      breakingDigest: proof.source.breakingDigest,
+      proofRoot: proof.proofRoot,
+      factRoot: factByProofRoot.get(proof.proofRoot)?.factRoot || "",
+    }));
+}
+
+export function createBuildchainCompatibilityProofRegistry({
+  proofs = createHistoricalBuildchainCompatibilityProofs(),
+  surfaces = [],
+  majorLine = "",
+} = {}) {
+  const verifiedProofs = proofs
+    .map((proof) => {
+      const verification = verifyBuildchainCompatibilityProof(proof);
+      if (!verification.ok)
+        throw new Error(
+          `invalid compatibility proof: ${verification.reason}${verification.error ? `: ${verification.error}` : ""}`,
+        );
+      return verification.proof;
+    })
+    .sort((left, right) => left.proofRoot.localeCompare(right.proofRoot));
+  const factRegistry = createBuildchainCompatibilityFactRegistry({
+    factInputs: verifiedProofs.map(factInputFromProof),
+  });
+  const factByProofRoot = new Map(
+    factRegistry.facts.map((fact) => [fact.proof.proofRoot, fact]),
+  );
+  const projections = Object.fromEntries(
+    [...surfaces]
+      .sort((left, right) => left.id.localeCompare(right.id))
+      .map((surface) => [
+        surface.id,
+        projectionForSurface({
+          proofs: verifiedProofs,
+          factByProofRoot,
+          surface,
+        }),
+      ])
+      .filter(([, entries]) => entries.length > 0),
+  );
+  const identity = {
+    schema: BUILDCHAIN_COMPATIBILITY_PROOF_REGISTRY_SCHEMA,
+    proofRoots: verifiedProofs.map((proof) => proof.proofRoot),
+  };
+  return {
+    ...identity,
+    proofs: verifiedProofs,
+    facts: factRegistry.facts,
+    factRegistry,
+    factRegistryRoot: factRegistry.registryRoot,
+    factCutRoot: factRegistry.currentCutRoot,
+    projections,
+    registryRoot: contentRoot(identity),
+  };
+}
+
+export function assertBuildchainCompatibilityProjection(contractWorld) {
+  if (
+    !Array.isArray(contractWorld?.compatibilityFacts) ||
+    !Array.isArray(contractWorld?.compatibilityProofs)
+  ) {
+    throw new Error(
+      "compatibility Facts and their proof projection are required",
+    );
+  }
+  const registry = createBuildchainCompatibilityProofRegistry({
+    proofs: contractWorld.compatibilityProofs,
+    surfaces: contractWorld.surfaces || [],
+    majorLine: contractWorld.majorLine,
+  });
+  if (contractWorld.compatibilityProofRegistryRoot !== registry.registryRoot) {
+    throw new Error("compatibility proof registry root mismatch");
+  }
+  if (
+    contractWorld.compatibilityFactRegistryRoot !== registry.factRegistryRoot
+  ) {
+    throw new Error("compatibility Fact registry root mismatch");
+  }
+  if (contractWorld.compatibilityFactCutRoot !== registry.factCutRoot) {
+    throw new Error("compatibility Fact Cut root mismatch");
+  }
+  if (
+    JSON.stringify(contractWorld.compatibilityFacts) !==
+    JSON.stringify(registry.facts)
+  ) {
+    throw new Error("compatibility Facts drift from the verified registry");
+  }
+  for (const surface of contractWorld.surfaces || []) {
+    const expected = registry.projections[surface.id] || [];
+    const expectedDigests = expected.map((entry) => entry.breakingDigest);
+    const expectedRoots = expected.map((entry) => entry.proofRoot);
+    const expectedFactRoots = expected.map((entry) => entry.factRoot);
+    const actualDigests = surface.compatibleBreakingDigests || [];
+    const actualRoots = surface.compatibilityProofRoots || [];
+    const actualFactRoots = surface.compatibilityFactRoots || [];
+    if (JSON.stringify(actualDigests) !== JSON.stringify(expectedDigests)) {
+      throw new Error(
+        `compatibleBreakingDigests projection mismatch for ${surface.id}`,
+      );
+    }
+    if (JSON.stringify(actualRoots) !== JSON.stringify(expectedRoots)) {
+      throw new Error(
+        `compatibilityProofRoots projection mismatch for ${surface.id}`,
+      );
+    }
+    if (JSON.stringify(actualFactRoots) !== JSON.stringify(expectedFactRoots)) {
+      throw new Error(
+        `compatibilityFactRoots projection mismatch for ${surface.id}`,
+      );
+    }
+  }
+  return {
+    ok: true,
+    reason: "exact-Fact-backed-projection",
+    registryRoot: registry.registryRoot,
+    factRegistryRoot: registry.factRegistryRoot,
+    factCutRoot: registry.factCutRoot,
+  };
+}
+
+export function verifyBuildchainCompatibilityPath({ registry, query } = {}) {
+  if (!registry?.temporalBundle)
+    throw new Error("compatibility Fact registry is required");
+  return verifyKungfuTemporalPath(registry.temporalBundle, query);
+}
+
+export function createBuildchainCompatibilityPathQuery({
+  registry,
+  queryId,
+  sourceRoot,
+  targetRoot,
+  relationPathRoots,
+  maxDepth = 1,
+} = {}) {
+  if (!registry?.temporalBundle || registry.predicateRoots?.length !== 1) {
+    throw new Error(
+      "one exact compatibility Fact registry predicate is required",
+    );
+  }
+  const predicateRoot = registry.predicateRoots[0];
+  const predicate = registry.temporalBundle.predicates.find(
+    (entry) => entry.root === predicateRoot,
+  )?.record;
+  return {
+    schema: KUNGFU_TEMPORAL_PATH_QUERY_SCHEMA,
+    queryId: exactText(queryId, "queryId"),
+    operation: COMPATIBILITY_OPERATION,
+    predicateRoot,
+    sourceRoot: exactRoot(sourceRoot, "sourceRoot"),
+    targetRoot: exactRoot(targetRoot, "targetRoot"),
+    cutRoot: exactRoot(registry.currentCutRoot, "currentCutRoot"),
+    relationPathRoots: (relationPathRoots || []).map((entry) =>
+      exactRoot(entry, "relationPathRoot"),
+    ),
+    requiredAuthorityRoot: exactRoot(
+      predicate?.authorityRoot,
+      "requiredAuthorityRoot",
+    ),
+    maxDepth,
+  };
+}
+
+export function resolveBuildchainCompatibilityProof({
+  registry,
+  surface,
+  sourceBreakingDigest,
+  majorLine,
+} = {}) {
+  const candidates = (registry?.proofs || []).filter(
+    (proof) =>
+      proof.source.surfaceId === surface.id &&
+      proof.source.surfaceKind === surface.kind &&
+      proof.source.breakingDigest === sourceBreakingDigest &&
+      proof.target.breakingDigest === surface.breakingDigest &&
+      proof.operation === COMPATIBILITY_OPERATION,
+  );
+  if (candidates.length === 0)
+    return { ok: false, reason: "compatibility-proof-missing" };
+  if (candidates.length > 1)
+    return { ok: false, reason: "ambiguous-compatibility-proof" };
+  const verification = verifyBuildchainCompatibilityProof(candidates[0]);
+  if (!verification.ok) return verification;
+  const projection = registry.projections?.[surface.id] || [];
+  if (
+    !projection.some(
+      (entry) =>
+        entry.breakingDigest === sourceBreakingDigest &&
+        entry.proofRoot === verification.proofRoot,
+    )
+  ) {
+    return { ok: false, reason: "compatibility-proof-projection-missing" };
+  }
+  const fact = registry.factRegistry?.facts.find(
+    (entry) => entry.proof.proofRoot === verification.proofRoot,
+  );
+  if (!fact) return { ok: false, reason: "compatibility-fact-missing" };
+  const query = createBuildchainCompatibilityPathQuery({
+    registry: registry.factRegistry,
+    queryId: `buildchain:compatibility:${surface.id}:${sourceBreakingDigest}:${surface.breakingDigest}`,
+    sourceRoot: fact.sourceRoot,
+    targetRoot: fact.targetRoot,
+    relationPathRoots: [fact.factRoot],
+    maxDepth: 1,
+  });
+  const pathReceipt = verifyBuildchainCompatibilityPath({
+    registry: registry.factRegistry,
+    query,
+  });
+  if (pathReceipt.record.status !== "accepted") {
+    return {
+      ok: false,
+      reason: pathReceipt.record.failureCode,
+      pathReceipt,
+      pathReceiptRoot: pathReceipt.root,
+    };
+  }
+  return {
+    ok: true,
+    reason: "Fact-backed-compatible-relation",
+    proof: verification.proof,
+    proofRoot: verification.proofRoot,
+    fact,
+    factRoot: fact.factRoot,
+    pathReceipt,
+    pathReceiptRoot: pathReceipt.root,
+  };
+}
+
+export function createBuildchainCompatibilityReleaseEvidence({
+  contractWorld,
+  release,
+  decisions = [],
+} = {}) {
+  const projection = assertBuildchainCompatibilityProjection(contractWorld);
+  const normalizedRelease = {
+    sourceSha: exactSha(release?.sourceSha, "release.sourceSha"),
+    tag: exactText(release?.tag, "release.tag"),
+    channel: exactText(release?.channel, "release.channel"),
+  };
+  const rootSet = (field) =>
+    [...new Set(decisions.map((entry) => entry[field]).filter(Boolean))]
+      .map((entry) => exactRoot(entry, field))
+      .sort();
+  const compatibility = {
+    operation: COMPATIBILITY_OPERATION,
+    direction: COMPATIBILITY_DIRECTION,
+    authority: "Fact-registry-only",
+    grantsReleaseAuthority: false,
+    contractDigest: exactRoot(
+      contractWorld.contractDigest,
+      "contractWorld.contractDigest",
+    ),
+    compatibilityDigest: exactRoot(
+      contractWorld.compatibilityDigest,
+      "contractWorld.compatibilityDigest",
+    ),
+    factRegistryRoot: projection.factRegistryRoot,
+    factCutRoot: projection.factCutRoot,
+    proofRegistryRoot: projection.registryRoot,
+    usedFactRoots: rootSet("factRoot"),
+    usedProofRoots: rootSet("proofRoot"),
+    pathReceiptRoots: rootSet("pathReceiptRoot"),
+  };
+  const body = {
+    schemaVersion: 1,
+    contract: BUILDCHAIN_COMPATIBILITY_RELEASE_EVIDENCE_SCHEMA,
+    id: "buildchain-compatibility-facts",
+    kind: "compatibility-fact-lineage",
+    release: normalizedRelease,
+    compatibility,
+  };
+  return { ...body, evidenceRoot: contentRoot(body) };
+}