V30 Gate 9: Prove interface integration regression

Add package-owned BTD interface integration contracts and regression proof builders, including source-safe coverage for Terminal, API, MCP, ChatGPT App, Auxillaries hooks, and Exchange hooks.

Expose the JSON-safe API admission route, wire Terminal/MCP/ChatGPT adapter records, and update V30 spec, parity, notes, README, gate workflow, and checker coverage.

Proof: BTD/API/MCP/ChatGPT/Terminal focused tests, touched typechecks, V30 Gate 1-9 checkers, spec-family/canonical-input/posture checks, and diff hygiene passed locally.

Author: geraldarthurdavis

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

@@ -87,6 +87,7 @@ jobs:
             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
             node scripts/check-v30-gate8-protocol-telemetry-proof-hooks.mjs --skip-branch-check
+            node scripts/check-v30-gate9-interface-integration-regression-proof.mjs --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1
@@ -131,6 +132,8 @@ jobs:
             tests/terminalDepositReadWorkbench.test.ts \
             tests/terminalTransactionQuery.test.ts \
             tests/terminalTransactionReadModel.test.ts \
+            tests/terminalProtocolProjection.test.ts \
+            tests/terminalInterfaceIntegrationRegression.test.ts \
             tests/terminalWalletBtcOperation.test.ts \
             tests/terminalJournalReconciliation.test.ts \
             tests/terminalOrganizationAuthority.test.ts \

BITCODE_SPEC_V30.md

@@ -349,6 +349,28 @@ The focused Playwright spec proves the cockpit in a real browser in deterministi
 Gate 9 acceptance does not change Reading law, source disclosure law, settlement law, or organization authority law.
 It makes the current V30 Terminal cockpit commercially operable enough that later local/staging promotion readiness can debug failures from the UI rather than from browser network logs alone.
 
+### Gate 9 interface integration regression proof
+
+Gate 9 adds a package-owned proof that current interface surfaces consume the
+Protocol/BTD rails instead of duplicating them:
+
+- `BtdInterfaceIntegrationRegressionProof` covers Terminal, API, MCP,
+  ChatGPT App, Auxillaries hook, and Exchange hook surfaces.
+- `BtdInterfaceIntegrationRecordInput` and
+  `@bitcode/btd/interface-integration-contract` give browser-facing
+  interfaces a client-safe contract for surface and object-family coverage.
+- `/btd/interface-integration-regression` wraps the package proof in a
+  source-safe Terminal journal `proof_admission` boundary.
+- The proof covers BTD registry, read access, BTD receipts, BTC fee operation,
+  ledger projection, source-to-shares proof, Protocol telemetry,
+  organization authority, and Terminal journal object families.
+- Every record must set `packageOwned: true`,
+  `routeLocalReimplementation: false`, `sourceSafeLowDetailIntact: true`, and
+  `transactionCockpitRegression: false`.
+- The proof fails closed on missing surfaces, missing object families,
+  protected source, secrets, route-local policy copies, or low-detail cockpit
+  regression.
+
 ## V30 local and staging promotion readiness canon
 
 V30 promotion is admissible only when the version branch can prove both source

BITCODE_SPEC_V30_DELTA.md

@@ -305,6 +305,20 @@ Closure acceptance:
 - low-detail source-safe UX remains intact;
 - focused regression tests prove no V29 transaction cockpit behavior regresses.
 
+Gate 9 implementation centers on:
+
+- `packages/btd/src/interface-integration-contract.ts` for client-safe
+  surface and object-family contracts;
+- `packages/btd/src/interface-integration.ts` for
+  `BtdInterfaceIntegrationRegressionProof` and source-safe fail-closed
+  record validation;
+- `buildBtdInterfaceIntegrationRegressionSettlement` and
+  `/btd/interface-integration-regression` for JSON-safe API admission;
+- Terminal, MCP, and ChatGPT App adapter records proving package-owned
+  consumption without route-local BTD policy copies;
+- focused BTD, API, MCP, ChatGPT App, and Terminal tests for source-safe
+  low-detail regression closure.
+
 ### Gate 10: V30 Promotion Readiness
 
 Gate 10 owns final local/staging proof, generated artifacts, and V30 promotion workflow support.

BITCODE_SPEC_V30_NOTES.md

@@ -251,6 +251,22 @@ boundary exposes `/btd/protocol-telemetry` as a JSON-safe proof-admission route;
 it does not commit source-bearing artifacts, and it does not replace existing
 crypto telemetry rows used for deployment readiness health.
 
+## Gate 9 interface integration notes
+
+Gate 9 makes interface reuse explicit. The accepted package shape is
+`BtdInterfaceIntegrationRegressionProof` plus the browser-safe
+`@bitcode/btd/interface-integration-contract` subpath. Terminal uses the
+contract without importing storage-backed BTD entry points into the client.
+API uses `buildBtdInterfaceIntegrationRegressionSettlement` and exposes
+`/btd/interface-integration-regression` as a JSON-safe proof-admission route.
+MCP and ChatGPT App expose small adapter records that name their package-owned
+BTD object consumption.
+
+The proof is not a new user journey. It is regression evidence that the V30
+rails can be consumed by current interfaces without losing low-detail source
+safety, reintroducing route-local BTD policy copies, or changing the selected
+Terminal transaction behavior promoted in V29.
+
 ## 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

@@ -62,7 +62,7 @@ No `_legacy/` source is active source truth.
 | 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 | `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 | `packages/btd/src/telemetry.ts`, API route boundary, focused BTD/API tests, gate checker | drafted | Receipts, fee states, projections, source-to-shares proofs, and bridge-readiness posture 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. |
+| Interface integration regression | Gate 9 | `packages/btd/src/interface-integration.ts`, `packages/api/src/routes/btd-crypto.ts`, Terminal/MCP/ChatGPT adapters and tests, gate checker | drafted | 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. |
 
 ## V30 implementation checklist
@@ -229,6 +229,25 @@ No `_legacy/` source is active source truth.
 - Gate 8 may expose telemetry/proof hooks to Terminal/API callers for operator review.
 - Gate 8 does not promote V30 or change the active canon pointer.
 
+## Gate 9 Parity
+
+| Requirement | Source evidence | Current V30 judgment |
+| --- | --- | --- |
+| Interface integration proof is package-owned | `packages/btd/src/interface-integration.ts`, `packages/btd/src/interface-integration-contract.ts`, `packages/btd/src/index.ts` | drafted |
+| Terminal can consume client-safe package contracts | `uapi/app/terminal/terminal-interface-integration-regression.ts`, `uapi/app/terminal/terminal-protocol-projection.ts` | drafted |
+| API exposes JSON-safe proof admission | `buildBtdInterfaceIntegrationRegressionSettlement`, `buildPostBtdInterfaceIntegrationRegressionRoute`, `uapi/app/api/btd/interface-integration-regression/route.ts` | drafted |
+| MCP and ChatGPT App declare package-owned object records | `packages/executions-mcp/src/mcp-server/src/interface-integration.ts`, `packages/chatgptapp/src/interface-integration.ts` | drafted |
+| Source-safe low-detail and transaction cockpit regression are tested | BTD interface-integration tests, BTD crypto route tests, Terminal projection tests, MCP auth test, ChatGPT tools test | drafted |
+| Gate checker protects interface integration boundaries | `scripts/check-v30-gate9-interface-integration-regression-proof.mjs`, `pnpm run check:v30-gate9`, gate-quality workflow | drafted |
+
+## Gate 9 accepted boundaries
+
+- Gate 9 does not redesign Reading, settlement, source disclosure, organization authority, MCP, ChatGPT App, Auxillaries, or Exchange.
+- Gate 9 does not expose protected AssetPack source, prompts, raw source, private keys, service keys, model keys, JWT-looking secrets, or database passwords.
+- Gate 9 admits only source-safe interface integration records and a proof-admission route; it does not commit ledger state or deliver AssetPacks.
+- Gate 9 proves current interfaces consume package-owned BTD object families without route-local policy copies.
+- Gate 9 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

@@ -62,6 +62,7 @@
     "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:v30-gate8": "node scripts/check-v30-gate8-protocol-telemetry-proof-hooks.mjs",
+    "check:v30-gate9": "node scripts/check-v30-gate9-interface-integration-regression-proof.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

@@ -21,6 +21,7 @@ import {
   buildBtdBtcFeeTransactionSettlement,
   buildBtdBridgeReadinessResearchSettlement,
   buildBtdDeploymentReadinessSettlement,
+  buildBtdInterfaceIntegrationRegressionSettlement,
   buildBtdLedgerDatabaseReconciliationSettlement,
   buildBtdLicensedReadRevenueSettlement,
   buildBtdMintDraft,
@@ -41,6 +42,7 @@ import {
   buildPostBtdBtcFeeTransactionRoute,
   buildPostBtdBridgeReadinessResearchRoute,
   buildPostBtdDeploymentReadinessRoute,
+  buildPostBtdInterfaceIntegrationRegressionRoute,
   buildPostBtdLedgerDatabaseReconciliationRoute,
   buildPostBtdLicensedReadRevenueRoute,
   buildPostBtdMintDraftRoute,
@@ -49,6 +51,7 @@ import {
   buildPostBtdReadAccessRoute,
   buildPostBtdSourceToSharesProofRoute,
   buildPostBtdTerminalJournalRoute,
+  postBtdInterfaceIntegrationRegression,
 } from '../btd-crypto';
 
 const issuedAt = '2026-05-06T00:00:00.000Z';
@@ -259,6 +262,86 @@ function protocolTelemetryBody(overrides: Record<string, unknown> = {}) {
   };
 }
 
+function interfaceIntegrationRegressionBody(overrides: Record<string, unknown> = {}) {
+  const recordBase = {
+    packageOwned: true,
+    routeLocalReimplementation: false,
+    sourceSafeLowDetailIntact: true,
+    transactionCockpitRegression: false,
+    notes: ['package-owned object consumed source-safely'],
+    issuedAt,
+  };
+
+  return {
+    records: [
+      {
+        ...recordBase,
+        surface: 'terminal',
+        consumerId: 'terminal-transaction-cockpit',
+        packageExport: '@bitcode/btd/interface-integration-contract',
+        adapterPath: 'uapi/app/terminal/terminal-interface-integration-regression.ts',
+        objectFamilies: ['btd_registry', 'read_access', 'terminal_journal'],
+        proofRoot: 'terminal-interface-proof-root',
+      },
+      {
+        ...recordBase,
+        surface: 'api',
+        consumerId: 'btd-api-route-boundary',
+        packageExport: '@bitcode/btd',
+        adapterPath: 'packages/api/src/routes/btd-crypto.ts',
+        objectFamilies: [
+          'btd_receipts',
+          'btc_fee_operation',
+          'ledger_projection',
+          'protocol_telemetry',
+        ],
+        proofRoot: 'api-interface-proof-root',
+      },
+      {
+        ...recordBase,
+        surface: 'mcp',
+        consumerId: 'bitcode-mcp-interface',
+        packageExport: '@bitcode/btd/interface-integration-contract',
+        adapterPath: 'packages/executions-mcp/src/mcp-server/src/interface-integration.ts',
+        objectFamilies: ['source_to_shares_proof', 'organization_authority'],
+        proofRoot: 'mcp-interface-proof-root',
+      },
+      {
+        ...recordBase,
+        surface: 'chatgpt_app',
+        consumerId: 'bitcode-chatgpt-app-interface',
+        packageExport: '@bitcode/btd/interface-integration-contract',
+        adapterPath: 'packages/chatgptapp/src/interface-integration.ts',
+        objectFamilies: ['read_access', 'organization_authority'],
+        proofRoot: 'chatgpt-app-interface-proof-root',
+      },
+      {
+        ...recordBase,
+        surface: 'auxillaries_hook',
+        consumerId: 'auxillaries-interface-hook',
+        packageExport: '@bitcode/btd/interface-integration-contract',
+        adapterPath: 'uapi/app/terminal/terminal-interface-integration-regression.ts',
+        objectFamilies: ['btd_registry', 'organization_authority'],
+        proofRoot: 'auxillaries-interface-proof-root',
+      },
+      {
+        ...recordBase,
+        surface: 'exchange_hook',
+        consumerId: 'exchange-interface-hook',
+        packageExport: '@bitcode/btd/interface-integration-contract',
+        adapterPath: 'uapi/app/terminal/terminal-interface-integration-regression.ts',
+        objectFamilies: ['btd_receipts', 'btc_fee_operation', 'ledger_projection'],
+        proofRoot: 'exchange-interface-proof-root',
+      },
+    ],
+    lowDetailProofRoot: 'terminal-low-detail-source-safe-proof-root',
+    transactionCockpitProofRoot: 'terminal-transaction-cockpit-regression-proof-root',
+    exchangeSequence: '21',
+    issuedAt,
+    ...overrides,
+  };
+}
+
 describe('BTD crypto API builders', () => {
   it('builds a deterministic mint draft from accepted Read-Fit semantic units', () => {
     const draft = buildBtdMintDraft(mintDraftInput());
@@ -1682,6 +1765,59 @@ describe('BTD crypto API builders', () => {
     expect(body.terminalJournalEntry.exchangeSequence).toBe('20');
   });
 
+  it('returns JSON-safe interface integration regression proof from the route boundary', async () => {
+    const direct = buildBtdInterfaceIntegrationRegressionSettlement({
+      ...(interfaceIntegrationRegressionBody() as any),
+      exchangeSequence: 21n,
+      actorId: 'user-1',
+    });
+    const route = buildPostBtdInterfaceIntegrationRegressionRoute({
+      resolveAuthenticatedUser: async () => ({ userId: 'user-1' }),
+    });
+    const response = await route(
+      new Request('https://bitcode.test/api/btd/interface-integration-regression', {
+        method: 'POST',
+        body: JSON.stringify(interfaceIntegrationRegressionBody()),
+      }),
+    );
+    const body = await response.json();
+
+    expect(direct.kind).toBe('btd_interface_integration_regression_settlement');
+    expect(postBtdInterfaceIntegrationRegression).toBeDefined();
+    expect(response.status).toBe(200);
+    expect(body.kind).toBe('btd_interface_integration_regression_settlement');
+    expect(body.committed).toBe(false);
+    expect(body.proof.coverage.surfaces.missing).toEqual([]);
+    expect(body.proof.coverage.objectFamilies.missing).toEqual([]);
+    expect(body.proof.packageOwned).toBe(true);
+    expect(body.proof.routeLocalReimplementation).toBe(false);
+    expect(body.proof.sourceSafeLowDetailIntact).toBe(true);
+    expect(body.proof.transactionCockpitRegression).toBe(false);
+    expect(body.terminalJournalEntry.exchangeSequence).toBe('21');
+  });
+
+  it('fails interface integration regression when source-safe low detail is not proven', async () => {
+    const route = buildPostBtdInterfaceIntegrationRegressionRoute({
+      resolveAuthenticatedUser: async () => ({ userId: 'user-1' }),
+    });
+    const body = interfaceIntegrationRegressionBody({
+      records: (interfaceIntegrationRegressionBody().records as any[]).map((record, index) => ({
+        ...record,
+        sourceSafeLowDetailIntact: index === 0 ? false : record.sourceSafeLowDetailIntact,
+      })),
+    });
+    const response = await route(
+      new Request('https://bitcode.test/api/btd/interface-integration-regression', {
+        method: 'POST',
+        body: JSON.stringify(body),
+      }),
+    );
+    const payload = await response.json();
+
+    expect(response.status).toBe(400);
+    expect(payload.error).toContain('source-safe low-detail UX');
+  });
+
   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

@@ -19,6 +19,8 @@ import {
   type BtdBtcFeeTransactionSettlement,
   type BtdDeploymentReadinessInput,
   type BtdDeploymentReadinessSettlement,
+  type BtdInterfaceIntegrationRegressionInput,
+  type BtdInterfaceIntegrationRegressionSettlement,
   type BtdLedgerDatabaseReconciliationInput,
   type BtdLedgerDatabaseReconciliationSettlement,
   type BtdLicensedReadRevenueInput,
@@ -47,6 +49,7 @@ import {
   buildBtdBridgeReadinessResearchSettlement,
   buildBtdBtcFeeTransactionSettlement,
   buildBtdDeploymentReadinessSettlement,
+  buildBtdInterfaceIntegrationRegressionSettlement,
   buildBtdLedgerDatabaseReconciliationSettlement,
   buildBtdLicensedReadRevenueSettlement,
   buildBtdMintDraft,
@@ -71,6 +74,7 @@ export {
   buildBtdBridgeReadinessResearchSettlement,
   buildBtdBtcFeeTransactionSettlement,
   buildBtdDeploymentReadinessSettlement,
+  buildBtdInterfaceIntegrationRegressionSettlement,
   buildBtdLedgerDatabaseReconciliationSettlement,
   buildBtdLicensedReadRevenueSettlement,
   buildBtdMintDraft,
@@ -675,6 +679,39 @@ export function buildPostBtdProtocolTelemetryRoute(options: BtdRouteOptions = {}
   });
 }
 
+export function buildPostBtdInterfaceIntegrationRegressionRoute(options: BtdRouteOptions = {}) {
+  return traceRoute('/btd/interface-integration-regression', async (request: Request) => {
+    const user = await (options.resolveAuthenticatedUser ?? defaultResolveAuthenticatedUser)(
+      request,
+    );
+    if (!user) {
+      return createJsonResponse({ error: 'Unauthorized' }, 401);
+    }
+
+    let body: Omit<BtdInterfaceIntegrationRegressionInput, 'actorId' | 'exchangeSequence'> & {
+      exchangeSequence: string | number;
+    };
+    try {
+      body = await request.json();
+    } catch {
+      return createJsonResponse({ error: 'Invalid JSON body' }, 400);
+    }
+
+    let settlement: BtdInterfaceIntegrationRegressionSettlement;
+    try {
+      settlement = buildBtdInterfaceIntegrationRegressionSettlement({
+        ...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)(
@@ -737,6 +774,8 @@ export const postBtdLedgerDatabaseReconciliation =
 export const postBtdSourceToSharesProof = buildPostBtdSourceToSharesProofRoute();
 export const postBtdBridgeReadinessResearch = buildPostBtdBridgeReadinessResearchRoute();
 export const postBtdProtocolTelemetry = buildPostBtdProtocolTelemetryRoute();
+export const postBtdInterfaceIntegrationRegression =
+  buildPostBtdInterfaceIntegrationRegressionRoute();
 export const postBtdDeploymentReadiness = buildPostBtdDeploymentReadinessRoute();
 
 function toBadRequestMessage(error: unknown): string {