Merge pull request #39 from engineeredsoftware/v30/gate-7-bridge-readiness-research-boundaries

V30 Gate 7: Bridge Readiness Research Boundaries

Author: geraldarthurdavis

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

@@ -85,6 +85,7 @@ jobs:
             node scripts/check-v30-gate4-btd-assetpack-mint-read-receipts.mjs --skip-branch-check
             node scripts/check-v30-gate5-testnet-ledger-projection-hardening.mjs --skip-branch-check
             node scripts/check-v30-gate6-source-to-shares-proof-cleanup.mjs --skip-branch-check
+            node scripts/check-v30-gate7-bridge-readiness-research-boundaries.mjs --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1

BITCODE_SPEC_V30.md

@@ -242,6 +242,26 @@ Gate 6 source-to-shares precision:
   Prepared, signed, broadcast, replaced, reorged, and failed fee receipts do
   not unlock protected source.
 
+Gate 7 bridge-readiness research boundaries:
+
+- `BridgeReadinessResearchPosture` is package-owned in `@bitcode/btd` and is
+  the reusable policy boundary for bridge and distribution research.
+- The required research paths are Taproot, BitVM, BSC/opBNB, Binance Web3
+  Wallet, and future distribution paths. Each path must have a posture record
+  naming feasibility, risks, current non-admission, rereview triggers, required
+  proof before admission, and required policy before admission.
+- V30 admits no bridge path as current `$BTD` chain-of-record truth.
+  The posture root must retain `bitcoin_btd_registry` as the active BTD chain
+  of record and `no_bridge_chain_of_record` as the bridge truth.
+- Bridge-readiness records are source-safe research facts. They may not contain
+  secrets or protected source, and they may not become wrappers, transfers,
+  settlement rails, ownership claims, or fee rails without a future promoted
+  version that supplies proof, policy, repair, telemetry, and disclosure
+  admission.
+- Terminal and API surfaces may show bridge-readiness posture as operational
+  research evidence, but they must fail closed on any payload attempting to
+  set `chainOfRecordAdmitted` or to mark a bridge as current BTD truth.
+
 ## V30 whole Bitcode operator chain
 
 The V30 Terminal operator chain is:

BITCODE_SPEC_V30_DELTA.md

@@ -254,6 +254,19 @@ Closure acceptance:
 - each record names feasibility, risks, current non-admission, rereview triggers, and required proof before admission;
 - no bridge path is treated as current `$BTD` chain-of-record truth.
 
+Gate 7 implementation centers `BridgeReadinessResearchPosture` in
+`packages/btd/src/bridge-readiness.ts`.
+It deliberately models bridge and distribution candidates as research facts,
+not as live chain-of-record adapters.
+The package builder synthesizes the required Taproot, BitVM, BSC/opBNB,
+Binance Web3 Wallet, and future-distribution records, rejects duplicate paths,
+rejects secret-looking posture text, and fails closed when a caller attempts
+`chainOfRecordAdmitted`.
+The BTD API boundary exposes `/btd/bridge-readiness-research` as a source-safe
+route for policy/readiness posture only; it returns a Terminal journal
+`proof_admission` entry and never writes bridge ownership, settlement, or fee
+state.
+
 ### Gate 8: Protocol Telemetry And Proof Hooks
 
 Gate 8 adds Protocol/BTD telemetry and proof hooks.

BITCODE_SPEC_V30_NOTES.md

@@ -212,6 +212,25 @@ slices, or BTC fee allocations.
 10. **Gate 10: V30 Promotion Readiness**
     - Close local/staging proof, generated artifacts, V30 promotion workflow, and post-promotion V30 active / V31 draft posture.
 
+## Gate 7 bridge-readiness research notes
+
+Gate 7 keeps bridge work honest by making bridge candidates typed research
+posture instead of latent implementation claims.
+Taproot, BitVM, BSC/opBNB, Binance Web3 Wallet, and future distribution paths
+are all represented as records with feasibility, risks, rereview triggers,
+required proof, and required policy, but every record remains
+`research_only`.
+
+The accepted implementation is package-owned:
+`packages/btd/src/bridge-readiness.ts` builds
+`BridgeReadinessResearchPosture`; `packages/btd/src/api-boundaries.ts` wraps it
+in a Terminal journal `proof_admission` settlement; and
+`packages/api/src/routes/btd-crypto.ts` exposes the source-safe
+`/btd/bridge-readiness-research` route.
+No Gate 7 code may mint, wrap, transfer, settle, or unlock BTD through a bridge.
+The only current chain-of-record posture is `bitcoin_btd_registry` plus
+`no_bridge_chain_of_record`.
+
 ## Gate 1 working notes
 
 Gate 1 is complete only when the V30 family exists, validates in draft mode over active V29, and makes the roadmap truthful enough to drive V31 through V37 without stale V27/V28/V29 posture.

BITCODE_SPEC_V30_PARITY_MATRIX.md

@@ -60,7 +60,7 @@ No `_legacy/` source is active source truth.
 | BTD AssetPack mint/read receipts | Gate 4 | `packages/btd/src/receipts.ts`, `packages/btd/src/api-boundaries.ts`, asset-pack harness evidence, Terminal detail snapshot/read model tests, gate checker | drafted | Mint, read, and rights-transfer receipts bind BTD range, preview, paid unlock, delivery, and ledger projection. |
 | Testnet ledger projection hardening | Gate 5 | `packages/btd/src/reconciliation.ts`, API route tests, asset-pack harness evidence, Terminal journal reconciliation UI/tests, gate checker | drafted | Ledger/database/object-storage/private facts are distinct; staging-testnet readback is secret-free; drift, quarantine, retry, and unlock blocking are tested. |
 | Source-to-shares proof cleanup | Gate 6 | `packages/btd/src/source-to-shares.ts`, API route boundary, focused BTD/API tests, gate checker | drafted | Measurement contribution, fee allocation, zero-cell/refit tail, ancestry evidence, and conservation invariants are testable. |
-| Bridge-readiness research boundaries | Gate 7 | Protocol/BTD research notes, policy posture tests, docs | pending | Bridge paths are documented as research until admitted by explicit future proof and policy. |
+| Bridge-readiness research boundaries | Gate 7 | `packages/btd/src/bridge-readiness.ts`, BTD/API tests, route boundary, docs, gate checker | drafted | Bridge paths are typed research-only records until admitted by explicit future proof and policy. |
 | Protocol telemetry/proof hooks | Gate 8 | telemetry schema, proof hooks, generated-artifact inventory, tests | pending | Receipts, fee states, projections, and source-to-shares facts emit source-safe telemetry and proof hooks. |
 | Interface integration regression | Gate 9 | Terminal/API/MCP/ChatGPT App adapters and tests | pending | Existing interfaces consume package-owned objects without regressing V29 behavior. |
 | Promotion readiness | Gate 10 | V30 promotion workflow, generated `.bitcode/v30-*`, `BITCODE_SPEC_V30_PROVEN.md` | pending | `version/v30` can promote to `main` only after all V30 checks pass and promotion automation can commit generated canon. |
@@ -192,6 +192,24 @@ No `_legacy/` source is active source truth.
 - Gate 6 does not admit bridge chain-of-record semantics; Gate 7 owns bridge-readiness boundaries.
 - Gate 6 does not promote V30 or change the active canon pointer.
 
+## Gate 7 Parity
+
+| Requirement | Source evidence | Current V30 judgment |
+| --- | --- | --- |
+| Bridge-readiness posture is package-owned | `packages/btd/src/bridge-readiness.ts`, `packages/btd/src/index.ts` | drafted |
+| Taproot, BitVM, BSC/opBNB, Binance Web3 Wallet, and future distribution paths are covered | `BRIDGE_READINESS_RESEARCH_PATHS`, `packages/btd/__tests__/bridge-readiness.test.ts` | drafted |
+| Every bridge path remains research-only and not current BTD chain-of-record truth | `assertNoBridgeChainOfRecordAdmission`, `bridgeChainOfRecordTruth: no_bridge_chain_of_record` | drafted |
+| API and Terminal boundary expose source-safe research posture only | `buildBtdBridgeReadinessResearchSettlement`, `buildPostBtdBridgeReadinessResearchRoute`, `uapi/app/api/btd/bridge-readiness-research/route.ts` | drafted |
+| Gate checker protects bridge research boundaries | `scripts/check-v30-gate7-bridge-readiness-research-boundaries.mjs`, `pnpm run check:v30-gate7`, gate-quality workflow | drafted |
+
+## Gate 7 accepted boundaries
+
+- Gate 7 does not implement a bridge chain-of-record path.
+- Gate 7 does not mint, wrap, transfer, settle, unlock, or deliver `$BTD` through Taproot, BitVM, BSC/opBNB, Binance Web3 Wallet, or any future distribution path.
+- Gate 7 does not store secrets or protected source in bridge-readiness records.
+- Gate 7 may expose source-safe research posture to Terminal/API callers for operator review.
+- Gate 7 does not promote V30 or change the active canon pointer.
+
 ## completion condition
 
 Gate 1 is complete when the V30 draft family validates, `check:v30-gate1` passes, workflow posture is V30-aware, README and roadmap reflect V30 initiation, V31-V37 scopes are current enough to guide future gates, diff hygiene passes, and the gate branch is committed and pushed for review into `version/v30`.

package.json

@@ -60,6 +60,7 @@
     "check:v30-gate4": "node scripts/check-v30-gate4-btd-assetpack-mint-read-receipts.mjs",
     "check:v30-gate5": "node scripts/check-v30-gate5-testnet-ledger-projection-hardening.mjs",
     "check:v30-gate6": "node scripts/check-v30-gate6-source-to-shares-proof-cleanup.mjs",
+    "check:v30-gate7": "node scripts/check-v30-gate7-bridge-readiness-research-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/src/routes/__tests__/btd-crypto.test.ts

@@ -19,6 +19,7 @@ import {
   buildBtdAssetPackLedgerAnchorSettlement,
   buildBtdAssetPackExchangeSettlement,
   buildBtdBtcFeeTransactionSettlement,
+  buildBtdBridgeReadinessResearchSettlement,
   buildBtdDeploymentReadinessSettlement,
   buildBtdLedgerDatabaseReconciliationSettlement,
   buildBtdLicensedReadRevenueSettlement,
@@ -36,6 +37,7 @@ import {
   buildPostBtdAssetPackLedgerAnchorRoute,
   buildPostBtdAssetPackExchangeRoute,
   buildPostBtdBtcFeeTransactionRoute,
+  buildPostBtdBridgeReadinessResearchRoute,
   buildPostBtdDeploymentReadinessRoute,
   buildPostBtdLedgerDatabaseReconciliationRoute,
   buildPostBtdLicensedReadRevenueRoute,
@@ -206,6 +208,15 @@ function sourceToSharesProofBody(overrides: Record<string, unknown> = {}) {
   };
 }
 
+function bridgeReadinessResearchBody(overrides: Record<string, unknown> = {}) {
+  return {
+    postureId: 'bridge-readiness-api-1',
+    exchangeSequence: '19',
+    issuedAt,
+    ...overrides,
+  };
+}
+
 describe('BTD crypto API builders', () => {
   it('builds a deterministic mint draft from accepted Read-Fit semantic units', () => {
     const draft = buildBtdMintDraft(mintDraftInput());
@@ -967,6 +978,30 @@ describe('BTD crypto API builders', () => {
     );
   });
 
+  it('builds bridge-readiness research settlements without chain-of-record admission', () => {
+    const settlement = buildBtdBridgeReadinessResearchSettlement({
+      actorId: 'user-1',
+      ...bridgeReadinessResearchBody(),
+      exchangeSequence: 19n,
+    } as any);
+
+    expect(settlement.kind).toBe('btd_bridge_readiness_research_settlement');
+    expect(settlement.committed).toBe(false);
+    expect(settlement.posture.bridgeChainOfRecordTruth).toBe('no_bridge_chain_of_record');
+    expect(settlement.posture.records.map((record) => record.path)).toEqual([
+      'bitcoin_taproot_anchor',
+      'bitvm_execution_bridge',
+      'bsc_opbnb_distribution',
+      'binance_web3_wallet_distribution',
+      'future_distribution_path',
+    ]);
+    expect(settlement.posture.records.every((record) => record.chainOfRecordAdmitted === false)).toBe(
+      true,
+    );
+    expect(settlement.terminalJournalEntry.transactionKind).toBe('proof_admission');
+    expect(settlement.terminalJournalEntry.receiptRoots).toContain(settlement.posture.proofRoot);
+  });
+
   it('builds deployment readiness, telemetry, and upgrade settlements', () => {
     const readiness = buildBtdDeploymentReadinessSettlement({
       actorId: 'user-1',
@@ -1535,6 +1570,28 @@ describe('BTD crypto API builders', () => {
     expect(body.terminalJournalEntry.exchangeSequence).toBe('18');
   });
 
+  it('returns JSON-safe bridge-readiness research posture from the route boundary', async () => {
+    const route = buildPostBtdBridgeReadinessResearchRoute({
+      resolveAuthenticatedUser: async () => ({ userId: 'user-1' }),
+    });
+    const response = await route(
+      new Request('https://bitcode.test/api/btd/bridge-readiness-research', {
+        method: 'POST',
+        body: JSON.stringify(bridgeReadinessResearchBody()),
+      }),
+    );
+    const body = await response.json();
+
+    expect(response.status).toBe(200);
+    expect(body.kind).toBe('btd_bridge_readiness_research_settlement');
+    expect(body.committed).toBe(false);
+    expect(body.posture.activeBtdChainOfRecord).toBe('bitcoin_btd_registry');
+    expect(body.posture.bridgeChainOfRecordTruth).toBe('no_bridge_chain_of_record');
+    expect(body.posture.allNonAdmitted).toBe(true);
+    expect(body.posture.records).toHaveLength(5);
+    expect(body.terminalJournalEntry.exchangeSequence).toBe('19');
+  });
+
   it('returns JSON-safe deployment readiness settlements and persists telemetry or upgrades', async () => {
     const insertCryptoTelemetryEvent = jest.fn(async (row) => ({
       event: row.event,

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

@@ -13,6 +13,8 @@ import {
   type BtdAssetPackExchangeSettlement,
   type BtdAssetPackLedgerAnchorInput,
   type BtdAssetPackLedgerAnchorSettlement,
+  type BtdBridgeReadinessResearchInput,
+  type BtdBridgeReadinessResearchSettlement,
   type BtdBtcFeeTransactionInput,
   type BtdBtcFeeTransactionSettlement,
   type BtdDeploymentReadinessInput,
@@ -40,6 +42,7 @@ import {
   buildBtdAncestryReviewSettlement,
   buildBtdAssetPackExchangeSettlement,
   buildBtdAssetPackLedgerAnchorSettlement,
+  buildBtdBridgeReadinessResearchSettlement,
   buildBtdBtcFeeTransactionSettlement,
   buildBtdDeploymentReadinessSettlement,
   buildBtdLedgerDatabaseReconciliationSettlement,
@@ -62,6 +65,7 @@ export {
   buildBtdAncestryReviewSettlement,
   buildBtdAssetPackExchangeSettlement,
   buildBtdAssetPackLedgerAnchorSettlement,
+  buildBtdBridgeReadinessResearchSettlement,
   buildBtdBtcFeeTransactionSettlement,
   buildBtdDeploymentReadinessSettlement,
   buildBtdLedgerDatabaseReconciliationSettlement,
@@ -601,6 +605,39 @@ export function buildPostBtdSourceToSharesProofRoute(options: BtdRouteOptions =
   });
 }
 
+export function buildPostBtdBridgeReadinessResearchRoute(options: BtdRouteOptions = {}) {
+  return traceRoute('/btd/bridge-readiness-research', async (request: Request) => {
+    const user = await (options.resolveAuthenticatedUser ?? defaultResolveAuthenticatedUser)(
+      request,
+    );
+    if (!user) {
+      return createJsonResponse({ error: 'Unauthorized' }, 401);
+    }
+
+    let body: Omit<BtdBridgeReadinessResearchInput, 'actorId' | 'exchangeSequence'> & {
+      exchangeSequence: string | number;
+    };
+    try {
+      body = await request.json();
+    } catch {
+      return createJsonResponse({ error: 'Invalid JSON body' }, 400);
+    }
+
+    let settlement: BtdBridgeReadinessResearchSettlement;
+    try {
+      settlement = buildBtdBridgeReadinessResearchSettlement({
+        ...body,
+        actorId: user.userId,
+        exchangeSequence: parseBtdRequiredBigInt(body.exchangeSequence, 'exchangeSequence'),
+      });
+    } catch (error) {
+      return createJsonResponse({ error: toBadRequestMessage(error) }, 400);
+    }
+
+    return createJsonResponse(toJsonSafe(settlement));
+  });
+}
+
 export function buildPostBtdDeploymentReadinessRoute(options: BtdRouteOptions = {}) {
   return traceRoute('/btd/deployment-readiness', async (request: Request) => {
     const user = await (options.resolveAuthenticatedUser ?? defaultResolveAuthenticatedUser)(
@@ -661,6 +698,7 @@ export const postBtdTerminalJournal = buildPostBtdTerminalJournalRoute();
 export const postBtdLedgerDatabaseReconciliation =
   buildPostBtdLedgerDatabaseReconciliationRoute();
 export const postBtdSourceToSharesProof = buildPostBtdSourceToSharesProofRoute();
+export const postBtdBridgeReadinessResearch = buildPostBtdBridgeReadinessResearchRoute();
 export const postBtdDeploymentReadiness = buildPostBtdDeploymentReadinessRoute();
 
 function toBadRequestMessage(error: unknown): string {

packages/btd/README.md

@@ -19,6 +19,10 @@ This package owns:
   largest-remainder share weights, BTD range slices, exact BTC fee allocation,
   settlement conservation, zero-cell/refit tail posture, ancestry evidence, and
   no-overpayment/no-underpayment theorem verdicts
+- bridge-readiness research boundaries for Taproot, BitVM, BSC/opBNB,
+  Binance Web3 Wallet, and future distribution paths; every bridge posture is
+  research-only and cannot become current `$BTD` chain-of-record truth without
+  explicit future proof and policy admission
 - ledger/database/object-storage projection reconciliation, including
   deterministic repair classes, source-safe object artifact roots,
   secret-free Supabase staging-testnet readback receipts, quarantine/retry
@@ -54,6 +58,7 @@ import {
   buildBtdRegistrySnapshot,
   buildSupabaseStagingTestnetProjectionReadback,
   buildSourceToSharesProof,
+  buildBridgeReadinessResearchPosture,
   reconcileLedgerDatabaseProjection,
   sourceToSharesProofToSettlementConservationCheck,
   toBtdJsonSafe,