Merge pull request #34 from engineeredsoftware/v30/gate-2-protocol-package-api-boundaries

V30 Gate 2: Protocol Package API Boundaries

Author: geraldarthurdavis

.github/workflows/bitcode-gate-quality.yml

@@ -80,6 +80,7 @@ jobs:
             node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V29 --draft-target V30
             node scripts/check-v29-gate10-local-staging-promotion-readiness.mjs --promotion-mode --skip-branch-check
             node scripts/check-v30-gate1-roadmap-and-gating.mjs --skip-branch-check
+            node scripts/check-v30-gate2-protocol-package-api-boundaries.mjs --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1

BITCODE_SPEC_V30_DELTA.md

@@ -93,6 +93,18 @@ Closure acceptance:
 - no commercial runtime code imports `protocol-demonstration/src/*`;
 - package READMEs name ownership boundaries and accepted imports.
 
+Gate 2 implementation centers the currently shared BTD route objects in
+`packages/btd/src/api-boundaries.ts`. API routes may authenticate, parse request
+bodies, resolve registry projections, commit explicit persistence writes, and
+serialize responses, but BTD mint drafts, registry snapshots, read-access
+decisions, BTC-fee settlements, ledger anchors, Exchange settlements, Terminal
+journal settlements, reconciliation settlements, deployment-readiness receipts,
+BigInt parsing, and JSON-safe conversion are package-owned.
+
+The package boundary is proven by `packages/btd/__tests__/api-boundaries.test.ts`,
+`packages/api/src/routes/__tests__/btd-crypto.test.ts`, and
+`scripts/check-v30-gate2-protocol-package-api-boundaries.mjs`.
+
 ### Gate 3: Bitcoin Taproot PSBT Fee Rigor
 
 Gate 3 hardens Bitcoin fee and signer semantics.

BITCODE_SPEC_V30_NOTES.md

@@ -68,6 +68,25 @@ V30 owns Protocol/BTD hardening:
    - Narrow package APIs for shared Protocol/BTD objects used by API, Terminal, MCP, ChatGPT App, and future Auxillaries/Exchange work.
    - Require package-owned builders, validators, parsers, tests, and JSON-safe serialization before cross-interface use.
 
+## Gate 2 protocol package API boundary notes
+
+Gate 2 moves reusable BTD route-facing construction into
+`packages/btd/src/api-boundaries.ts`. `packages/api/src/routes/btd-crypto.ts`
+remains the route owner: it authenticates requests, parses request bodies,
+resolves registry projections, commits explicit persistence writes, and returns
+JSON responses. It no longer owns BTD mint draft admission, registry snapshot
+construction, read-access policy derivation, BTC-fee settlement receipts,
+AssetPack ledger anchors, Exchange settlement receipts, Terminal journal
+settlements, reconciliation reports, deployment-readiness receipts, BigInt
+parsing, or JSON-safe conversion.
+
+The package test `packages/btd/__tests__/api-boundaries.test.ts` is the local
+contract for package-owned builders/parsers/serialization. The API route test
+imports those builders from `@bitcode/btd` and keeps route-handler coverage in
+the API package. `pnpm run check:v30-gate2` closes the gate by checking this
+seam, package README ownership language, and commercial runtime avoidance of
+standalone demonstration imports.
+
 3. **Gate 3: Bitcoin Taproot PSBT Fee Rigor**
    - Harden BTC fee quote, signer recovery, PSBT, Taproot/script posture, broadcast, replacement, reorg, finality, and testnet/mainnet boundaries.
 

BITCODE_SPEC_V30_PARITY_MATRIX.md

@@ -55,7 +55,7 @@ No `_legacy/` source is active source truth.
 | --- | --- | --- | --- | --- |
 | Draft family and branch posture | Gate 1 | `BITCODE_SPEC_V30.md`, DELTA, NOTES, PARITY, `BITCODE_SPEC.txt`, branch `v30/gate-1-roadmap-and-gating` | drafted | V30 family validates in draft mode over active V29 and `check:v30-gate1` passes. |
 | Roadmap truth | Gate 1 | `SPECIFICATIONS_ROADMAP.md`, README, PR template, workflow posture | drafted | Roadmap states V29 active, V30 draft, and coherent V31-V37 responsibilities. |
-| Protocol package API boundaries | Gate 2 | `packages/protocol`, `packages/btd`, `packages/api`, package READMEs/tests | pending | Shared Protocol/BTD objects have package-owned builders, parsers, validators, JSON-safe serializers, and tests. |
+| Protocol package API boundaries | Gate 2 | `packages/btd/src/api-boundaries.ts`, `packages/api/src/routes/btd-crypto.ts`, package READMEs/tests | drafted | Shared Protocol/BTD objects have package-owned builders, parsers, validators, JSON-safe serializers, and tests. |
 | Bitcoin Taproot PSBT fee rigor | Gate 3 | BTD fee/signer/PSBT primitives, API route adapters, tests | pending | BTC fee and signer states are typed, testnet/mainnet-safe, no-custody, and proof-rooted. |
 | BTD AssetPack mint/read receipts | Gate 4 | BTD receipt primitives, asset-pack postprocess, harness evidence, Terminal/API readback | pending | Mint, read, and rights-transfer receipts bind BTD range, preview, paid unlock, delivery, and ledger projection. |
 | Testnet ledger projection hardening | Gate 5 | BTD reconciliation, Supabase readback, object-storage evidence, repair tests | pending | Ledger/database/object-storage projections are synchronized or blocked with deterministic repair posture. |
@@ -93,6 +93,25 @@ No `_legacy/` source is active source truth.
 
 - Gate 1 does not implement Protocol/BTD package hardening.
 - Gate 1 does not create `BITCODE_SPEC_V30_PROVEN.md`.
+
+## Gate 2 Parity
+
+| Requirement | Source evidence | Current V30 judgment |
+| --- | --- | --- |
+| Package-owned BTD builders and parsers exist | `packages/btd/src/api-boundaries.ts` exports mint, registry, read-access, fee, ledger-anchor, Exchange, journal, reconciliation, deployment-readiness builders plus `parseBtdRequiredBigInt`, `parseBtdOptionalBigInt`, and `toBtdJsonSafe` | drafted |
+| API route delegates BTD policy and receipt derivation | `packages/api/src/routes/btd-crypto.ts` imports package builders from `@bitcode/btd` and keeps route code scoped to auth, request parsing, registry projection reads/writes, and responses | drafted |
+| Package tests cover the boundary | `packages/btd/__tests__/api-boundaries.test.ts` proves mint drafts, registry snapshots, read-access decisions, parsers, and JSON-safe serialization | drafted |
+| Route tests consume package-owned builders | `packages/api/src/routes/__tests__/btd-crypto.test.ts` imports BTD builders from `@bitcode/btd` and route handlers from the API route module | drafted |
+| Commercial runtime avoids standalone demonstration imports | `scripts/check-v30-gate2-protocol-package-api-boundaries.mjs` scans runtime source import statements for `protocol-demonstration/src` and `@bitcode/protocol-demonstration` | drafted |
+| Package READMEs state accepted imports | `packages/btd/README.md`, `packages/api/README.md`, and `packages/protocol/README.md` name package ownership and accepted import direction | drafted |
+| Gate checker protects the seam | `pnpm run check:v30-gate2` and gate-quality workflow call `scripts/check-v30-gate2-protocol-package-api-boundaries.mjs` | drafted |
+
+## Gate 2 accepted boundaries
+
+- Gate 2 does not change the active canon pointer.
+- Gate 2 does not introduce bridge chain-of-record behavior.
+- Gate 2 does not admit value-bearing mainnet settlement.
+- Gate 2 does not remove existing API route persistence adapters; it narrows their policy and receipt derivation responsibilities to package calls.
 - Gate 1 does not promote `BITCODE_SPEC.txt` to V30.
 - Gate 1 may retarget workflows to active V29 / draft V30 so later gates are greenable.
 - Gate 1 may update roadmap scope for V31-V37 to align with V28/V29 promotion learning without opening those versions.

README.md

@@ -69,7 +69,11 @@ and commit promotion artifacts plus the `BITCODE_SPEC.txt` pointer change from
 `V29` to `V30` on the version branch.
 Gate 10 is the local/staging promotion-readiness gate; run the V30 Gate 10
 checker before opening the final gate PR. V30 Gate 1 wires the first checker as
-`pnpm run check:v30-gate1`.
+`pnpm run check:v30-gate1`. V30 Gate 2 wires the Protocol/BTD package boundary
+checker as `pnpm run check:v30-gate2`; shared BTD objects consumed by API,
+Terminal, MCP, ChatGPT App, Auxillaries, or Exchange must be built, parsed,
+validated, and JSON-serialized by package owners before route or interface code
+uses them.
 The promoted V29 closure remains reproducible through `pnpm run check:v29-gate10`
 and [v29-canon-promotion.yml](.github/workflows/v29-canon-promotion.yml).
 The application CI workflow uses the root pnpm workspace install, runs uapi

package.json

@@ -55,6 +55,7 @@
     "check:v29-gate9": "node scripts/check-v29-gate9-terminal-ux-browser-proof.mjs",
     "check:v29-gate10": "node scripts/check-v29-gate10-local-staging-promotion-readiness.mjs",
     "check:v30-gate1": "node scripts/check-v30-gate1-roadmap-and-gating.mjs",
+    "check:v30-gate2": "node scripts/check-v30-gate2-protocol-package-api-boundaries.mjs",
     "check:spec-quality": "node scripts/run-bitcode-spec-quality.mjs --mode basic",
     "check:spec-quality:title": "node scripts/run-bitcode-spec-quality.mjs --mode strict-from-title",
     "check:spec-quality:v24": "node scripts/run-bitcode-spec-quality.mjs --mode strict-version --version V24",

packages/api/README.md

@@ -6,6 +6,14 @@ Unified Bitcode API orchestration layer. This package owns route-level request l
 
 Interface-owned route bindings such as `uapi/app/api/*` should stay thin. They import formal route handlers from `packages/api` entry modules such as `@bitcode/api/src/routes/*`, while those handlers import narrower functionality from the appropriate subsystem packages.
 
+For BTD routes, the accepted import direction is route code importing
+package-owned builders, parsers, validators, and JSON serializers from
+`@bitcode/btd`. The route-owned behavior is limited to authentication, request body
+parsing, registry projection reads, explicit persistence commits, response
+status decisions, and framework-compatible response serialization. Route code
+must not duplicate BTD policy, mint admission, receipt derivation, settlement
+state construction, or JSON-safe conversion already exported by `@bitcode/btd`.
+
 In V26 fourth-gate this package is where merged-world Bitcode becomes concrete:
 - `/conversations` continuity
 - `/executions` compatibility and pipeline-run APIs

packages/api/src/routes/__tests__/btd-crypto.test.ts

@@ -14,6 +14,7 @@ jest.mock(
 );
 
 import {
+  advanceBtcFeeQuote,
   buildBtdAncestryReviewSettlement,
   buildBtdAssetPackLedgerAnchorSettlement,
   buildBtdAssetPackExchangeSettlement,
@@ -25,6 +26,10 @@ import {
   buildBtdOrganizationInterfaceAuthorityDecision,
   buildBtdReadAccessDecision,
   buildBtdTerminalJournalSettlement,
+  buildBtcFeeQuote,
+  createBtdMeasureMintState,
+} from '@bitcode/btd';
+import {
   buildGetBtdRegistrySnapshotRoute,
   buildPostBtdAncestryReviewRoute,
   buildPostBtdAssetPackLedgerAnchorRoute,
@@ -38,11 +43,6 @@ import {
   buildPostBtdReadAccessRoute,
   buildPostBtdTerminalJournalRoute,
 } from '../btd-crypto';
-import {
-  advanceBtcFeeQuote,
-  buildBtcFeeQuote,
-  createBtdMeasureMintState,
-} from '@bitcode/btd';
 
 const issuedAt = '2026-05-06T00:00:00.000Z';
 
@@ -215,7 +215,7 @@ describe('BTD crypto API builders', () => {
     const body = await response.json();
 
     expect(response.status).toBe(400);
-    expect(body.error).toBe('V27 BTD mint draft requires accepted Read.');
+    expect(body.error).toBe('BTD mint draft requires accepted Read.');
   });
 
   it('fails mint drafts closed when Fit admission is absent', async () => {
@@ -231,7 +231,7 @@ describe('BTD crypto API builders', () => {
     const body = await response.json();
 
     expect(response.status).toBe(400);
-    expect(body.error).toBe('V27 BTD mint draft requires accepted Fit.');
+    expect(body.error).toBe('BTD mint draft requires accepted Finding Fits result.');
   });
 
   it('fails mint drafts closed when uncommitted proof inputs are missing', async () => {
@@ -263,7 +263,7 @@ describe('BTD crypto API builders', () => {
     const body = await response.json();
 
     expect(response.status).toBe(400);
-    expect(body.error).toBe('V27 BTD mint draft requires a positive Exchange sequence.');
+    expect(body.error).toBe('BTD mint draft requires a positive Exchange sequence.');
   });
 
   it('builds read-access decisions without merging owner-read and licensed-read rights', () => {