V30 Gate 2: Package BTD API boundaries

Move shared BTD route-facing builders, parsers, settlement constructors, registry snapshots, and JSON-safe serialization into @bitcode/btd so API routes delegate protocol policy instead of owning it.

Add package boundary tests, update route tests to import package builders directly, document accepted import direction, and wire the V30 Gate 2 checker into gate-quality.

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', () => {