V31 Gate 7: Add interface admission catalog (#50)

Deepens AuxillariesInterfaceAdmission with supported actions, current admitted actions, policy requirements, source-safety classes, blockers, deferred-product depth, and required proof roots across Terminal, API, MCP, ChatGPT App, Exchange, Conversations, and future hooks.

Renders the package-owned catalog in the Interfaces pane, carries interfaceAdmissions through user data, documents the source-safe boundaries, and adds the Gate 7 checker plus workflow coverage.

Validation: pnpm run check:v31-gate1 && pnpm run check:v31-gate2 && pnpm run check:v31-gate3 && pnpm run check:v31-gate4; pnpm run check:v31-gate5 && pnpm run check:v31-gate6 && pnpm run check:v31-gate7; pnpm --filter @bitcode/api build; pnpm -C uapi exec tsc --noEmit --pretty false; pnpm --filter @bitcode/api exec jest --config jest.config.cjs --runTestsByPath src/routes/__tests__/auxillaries-contract.test.ts --runInBand; pnpm -C uapi exec jest --runTestsByPath tests/orbitalsInterfacesPane.test.tsx tests/userDataRoute.test.ts --runInBand; git diff --check; strict changed-file secret sweep.

Author: geraldarthurdavis

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

@@ -101,6 +101,7 @@ jobs:
             node scripts/check-v31-gate4-connects-provider-readiness.mjs --skip-branch-check
             node scripts/check-v31-gate5-wallet-btd-pane-readiness.mjs --skip-branch-check
             node scripts/check-v31-gate6-organization-team-role-policy-authority.mjs --skip-branch-check
+            node scripts/check-v31-gate7-interfaces-pane-admission-cross-surface-contracts.mjs --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1

BITCODE_SPEC_V31.md

@@ -268,6 +268,10 @@ Gate 7 Interfaces precision:
 
 - Interface admission records enumerate surface id, auth mode, supported actions, required policy, source-safety class, and current readiness.
 - Interfaces may point to Terminal, API, MCP, ChatGPT App, Exchange, or future hooks, but V31 does not implement deferred Exchange market law or Conversations product depth.
+- `AuxillariesInterfaceAdmission` now distinguishes `supportedActions` from the currently admitted `allowedActions`, so a surface can advertise the product action family it understands while remaining blocked or degraded for the current user/account posture.
+- Each admission record carries `policyRequirements`, legacy-compatible `policyConstraints`, blockers, `deferredProductDepth`, source-safety class, and `interfaceAdmissionRoot`.
+- The required V31 admission catalog contains `terminal`, `api`, `mcp`, `chatgpt-app`, `exchange-hook`, `conversations-hook`, and `future-interface-hooks`.
+- Exchange and Conversations records are present as source-safe hooks only; they remain blocked with explicit deferred-product blockers until later versions implement market law or Conversations product depth.
 
 Gate 8 UX precision:
 
@@ -359,6 +363,7 @@ V31 adds a package-owned proof that interface surfaces consume admitted Auxillar
 - Terminal, API, MCP, and ChatGPT App may read interface admission to gate source-safe actions and protected actions.
 - Exchange and Conversations remain deferred product-depth hooks, not admitted market or conversation implementation.
 - The proof fails closed on missing auth mode, unsupported action, protected source, secrets, route-local policy copies, stale readiness, or missing policy root.
+- The Auxillaries Interfaces pane renders the same admission records as a catalog: surface, auth mode, readiness, source-safety class, supported actions, currently admitted actions, policy requirements, blockers, and proof root. It does not recalculate policy locally.
 
 ## V31 local and staging promotion readiness canon
 

BITCODE_SPEC_V31_DELTA.md

@@ -179,6 +179,14 @@ Closure acceptance:
 - each record names auth mode, supported actions, source-safety class, policy requirements, blockers, and readiness;
 - V31 does not implement deferred Exchange market law or Conversations product depth.
 
+Gate 7 implementation centers:
+
+- `packages/api/src/routes/auxillaries-contract.ts` deepens `AuxillariesInterfaceAdmission` with `policyRequirements`, legacy-compatible `policyConstraints`, `supportedActions`, current `allowedActions`, `sourceSafetyClass`, `deferredProductDepth`, blockers, readiness, and proof roots;
+- `buildAuxillariesInterfaceAdmissions` emits the required catalog for Terminal, API, MCP, ChatGPT App, Exchange hook, Conversations hook, and future interface hooks, keeping Exchange and Conversations blocked as deferred product-depth hooks;
+- `validateAuxillariesContractSnapshot` now fails malformed snapshots that omit required interface ids or the required admission fields;
+- `uapi/hooks/useUserData.ts` and `.js` carry `interfaceAdmissions` into UI read models, and `AuxillariesInterfacesPane.tsx` renders the source-safe catalog without deriving policy locally;
+- focused API and Interfaces pane tests assert supported actions, admitted actions, policy requirements, source-safety classes, deferred blockers, proof roots, and autosaved interface defaults.
+
 ### Gate 8: Auxillaries UX Accessibility And Responsive Proof
 
 Gate 8 proves the user experience.

BITCODE_SPEC_V31_NOTES.md

@@ -57,7 +57,7 @@ V31 owns deeper Auxillaries:
 
 - Profile and account completeness become typed, persisted, projected, and recoverable.
 - Connects show provider readiness, credential posture without secrets, repair actions, retry semantics, and readback evidence.
-- Interfaces enumerate admitted commercial surfaces with auth modes, action boundaries, readiness, and source-safety posture.
+- Interfaces enumerate admitted commercial surfaces with auth modes, supported actions, currently admitted actions, policy requirements, blockers, readiness, source-safety posture, deferred-product boundaries, and proof roots. The V31 catalog includes Terminal, API, MCP, ChatGPT App, Exchange hook, Conversations hook, and future interface hooks; Exchange market law and Conversations product depth remain explicitly blocked.
 - Wallet and BTD panes consume V30 wallet, signer, BTD range, read-right, treasury, settlement, and no-custody primitives.
 - Organization, team, member role, multi-sig readiness, explicit grants, policy decisions, denial reasons, and recovery routes become package-owned and UI-visible.
 - Readiness diagnostics and recovery runs are executions with source-safe before/after evidence.

BITCODE_SPEC_V31_PARITY_MATRIX.md

@@ -129,18 +129,18 @@ No `_legacy/` source is active source truth.
 
 | Requirement | Source evidence | Current V31 judgment |
 | --- | --- | --- |
-| Organization authority is package-owned | `BtdOrganizationPolicyAuthority` and `buildBtdOrganizationPolicyAuthority` in `packages/btd/src/authority.ts`; `OrganizationPolicyAuthority` aliases that object in `packages/api/src/routes/auxillaries-contract.ts` | drafted |
-| Role, grants, policy, wallet binding, and denial reasons are typed | BTD tests cover allowed settlement-adjacent policy authority and protected-source denial; API tests assert organization/team/member/grant/policy/multi-sig route emission; Profile pane tests render the shared authority object | drafted |
-| Protected actions fail closed unless all authority inputs admit them | `packages/btd/__tests__/btd.test.ts` covers missing grant, wallet, policy, interface admission, multi-sig, settlement, read access, and confirmation denial reasons with blocked source visibility | drafted |
-| Terminal and Auxillaries consume one authority object | `uapi/hooks/useUserData.ts`, `uapi/app/auxillaries/components/AuxillariesSurface.tsx`, `uapi/app/auxillaries/components/AuxillariesProfilePane.tsx`, and `uapi/app/terminal/terminal-organization-authority.ts` consume/project `organizationAuthority` without route-local policy rederivation | drafted |
+| Organization authority is package-owned | `BtdOrganizationPolicyAuthority` and `buildBtdOrganizationPolicyAuthority` in `packages/btd/src/authority.ts`; `OrganizationPolicyAuthority` aliases that object in `packages/api/src/routes/auxillaries-contract.ts` | closed |
+| Role, grants, policy, wallet binding, and denial reasons are typed | BTD tests cover allowed settlement-adjacent policy authority and protected-source denial; API tests assert organization/team/member/grant/policy/multi-sig route emission; Profile pane tests render the shared authority object | closed |
+| Protected actions fail closed unless all authority inputs admit them | `packages/btd/__tests__/btd.test.ts` covers missing grant, wallet, policy, interface admission, multi-sig, settlement, read access, and confirmation denial reasons with blocked source visibility | closed |
+| Terminal and Auxillaries consume one authority object | `uapi/hooks/useUserData.ts`, `uapi/app/auxillaries/components/AuxillariesSurface.tsx`, `uapi/app/auxillaries/components/AuxillariesProfilePane.tsx`, and `uapi/app/terminal/terminal-organization-authority.ts` consume/project `organizationAuthority` without route-local policy rederivation | closed |
 
 ## Gate 7 Parity
 
 | Requirement | Source evidence | Current V31 judgment |
 | --- | --- | --- |
-| Interfaces pane exposes admitted surfaces | Interfaces pane records and tests | pending |
-| Each surface names auth, actions, policy, source-safety, blockers, and readiness | package/API/MCP/ChatGPT App contract tests | pending |
-| Deferred Exchange and Conversations remain explicitly out of scope | specs, checker, and UI labels | pending |
+| Interfaces pane exposes admitted surfaces | `AuxillariesInterfaceAdmission` records in `packages/api/src/routes/auxillaries-contract.ts` enumerate Terminal, API, MCP, ChatGPT App, Exchange hook, Conversations hook, and future interface hooks; `uapi/app/auxillaries/components/AuxillariesInterfacesPane.tsx` renders the catalog | drafted |
+| Each surface names auth, actions, policy, source-safety, blockers, and readiness | `packages/api/src/routes/__tests__/auxillaries-contract.test.ts` asserts auth mode, `supportedActions`, current `allowedActions`, `policyRequirements`, `sourceSafetyClass`, blockers, readiness, and roots | drafted |
+| Deferred Exchange and Conversations remain explicitly out of scope | Exchange and Conversations hook records are blocked with `deferredProductDepth` values and deferred blockers; `uapi/tests/orbitalsInterfacesPane.test.tsx` reads those blockers in the catalog | drafted |
 
 ## Gate 8 Parity
 

SPECIFICATIONS_ROADMAP.md

@@ -5,7 +5,7 @@
 - Current active canonical pointer: `BITCODE_SPEC.txt` -> `V30`
 - Current active canon: `BITCODE_SPEC_V30.md`
 - Current draft target: `BITCODE_SPEC_V31.md`
-- Current working gate: V31 Gate 6 Organization Team Role Policy Authority, which binds account, organization, team, member, role, explicit grants, wallet binding, policy id/hash, multi-sig readiness, policy decision, denial reason, and recovery route into one package-owned authority object consumed by Auxillaries and Terminal.
+- Current working gate: V31 Gate 7 Interfaces Pane Admission And Cross-Surface Contracts, which turns the Interfaces pane into the source-safe admission catalog for Terminal, API, MCP, ChatGPT App, Exchange, Conversations, and future hooks with auth mode, supported actions, current admitted actions, policy requirements, source-safety class, blockers, readiness, deferred-product boundaries, and proof roots.
 - Purpose: concise running index of Bitcode/ENGI specification history, current work, and planned work.
 
 This roadmap is not an active system specification.

package.json

@@ -70,6 +70,7 @@
     "check:v31-gate4": "node scripts/check-v31-gate4-connects-provider-readiness.mjs",
     "check:v31-gate5": "node scripts/check-v31-gate5-wallet-btd-pane-readiness.mjs",
     "check:v31-gate6": "node scripts/check-v31-gate6-organization-team-role-policy-authority.mjs",
+    "check:v31-gate7": "node scripts/check-v31-gate7-interfaces-pane-admission-cross-surface-contracts.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

@@ -58,6 +58,16 @@ denial reasons, source visibility, recovery route, and proof root. API
 responses must expose only the source-safe authority object shared by
 Auxillaries and Terminal.
 
+Interface admission state is package-owned in `AuxillariesInterfaceAdmission`.
+The catalog emitted by `buildAuxillariesInterfaceAdmissions` covers Terminal,
+API, MCP, ChatGPT App, Exchange hook, Conversations hook, and future interface
+hooks. Each record carries auth mode, `supportedActions`, current
+`allowedActions`, policy requirements, legacy-compatible policy constraints,
+source-safety class, blockers, readiness, deferred-product depth, and an
+interface-admission root. Exchange market law and Conversations product depth
+remain blocked/deferred in V31; route and UI code may display the source-safe
+record but must not implement those product laws locally.
+
 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__/auxillaries-contract.test.ts

@@ -223,6 +223,105 @@ describe('Auxillaries package route contracts', () => {
     expect(payload.organizationAuthority.policy.policyHash).toMatch(/^[0-9a-f]{64}$/);
     expect(payload.organizationAuthority.actionDecision?.decision).toBe('allowed');
     expect(payload.organizationAuthority.authorityRoot).toMatch(/^btd-proof-root:organization-policy-authority:/);
+    expect(payload.interfaceAdmissions.map((admission) => admission.interfaceId)).toEqual([
+      'terminal',
+      'api',
+      'mcp',
+      'chatgpt-app',
+      'exchange-hook',
+      'conversations-hook',
+      'future-interface-hooks',
+    ]);
+    expect(payload.interfaceAdmissions).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          interfaceId: 'terminal',
+          surface: 'terminal',
+          authMode: 'session',
+          readiness: 'ready',
+          policyRequirements: expect.arrayContaining([
+            'session_required',
+            'organization_policy_required_for_protected_actions',
+          ]),
+          supportedActions: expect.arrayContaining([
+            'request_read',
+            'review_need',
+            'request_finding_fits',
+            'pay_btc_fee',
+            'deliver_asset_pack',
+          ]),
+          allowedActions: expect.arrayContaining([
+            'request_read',
+            'review_need',
+            'request_finding_fits',
+          ]),
+          sourceSafetyClass: 'source_safe',
+          deferredProductDepth: 'none',
+        }),
+        expect.objectContaining({
+          interfaceId: 'api',
+          surface: 'api',
+          authMode: 'api_key',
+          readiness: 'ready',
+          sourceSafetyClass: 'secret_free_summary',
+          policyRequirements: expect.arrayContaining(['api_key_required', 'provider_scope_required']),
+          supportedActions: expect.arrayContaining(['read_support_state', 'deliver_asset_pack']),
+        }),
+        expect.objectContaining({
+          interfaceId: 'mcp',
+          surface: 'mcp',
+          authMode: 'provider_oauth',
+          readiness: 'ready',
+          sourceSafetyClass: 'secret_free_summary',
+          policyRequirements: expect.arrayContaining([
+            'provider_oauth_required',
+            'wallet_binding_required_for_delivery',
+            'organization_policy_required_for_protected_actions',
+          ]),
+        }),
+        expect.objectContaining({
+          interfaceId: 'chatgpt-app',
+          surface: 'chatgpt_app',
+          authMode: 'session',
+          readiness: 'ready',
+          sourceSafetyClass: 'protected_source_redacted',
+          policyRequirements: expect.arrayContaining([
+            'protected_source_never_embedded_before_paid_unlock',
+          ]),
+        }),
+        expect.objectContaining({
+          interfaceId: 'exchange-hook',
+          surface: 'exchange',
+          authMode: 'wallet_signature',
+          readiness: 'blocked',
+          allowedActions: [],
+          blockers: ['exchange.market_depth_deferred_to_future_version'],
+          deferredProductDepth: 'exchange_market_law',
+        }),
+        expect.objectContaining({
+          interfaceId: 'conversations-hook',
+          surface: 'future_hook',
+          authMode: 'not_admitted',
+          readiness: 'blocked',
+          allowedActions: [],
+          blockers: ['conversations.product_depth_deferred_to_future_version'],
+          deferredProductDepth: 'conversations_product_depth',
+        }),
+        expect.objectContaining({
+          interfaceId: 'future-interface-hooks',
+          surface: 'future_hook',
+          authMode: 'not_admitted',
+          readiness: 'blocked',
+          allowedActions: [],
+          blockers: ['future_hooks.interface_contract_unregistered'],
+          deferredProductDepth: 'future_interface_contract',
+        }),
+      ]),
+    );
+    for (const admission of payload.interfaceAdmissions) {
+      expect(admission.interfaceAdmissionRoot).toMatch(/^[0-9a-f]{64}$/);
+      expect(admission.policyConstraints).toEqual(admission.policyRequirements);
+    }
     expect(payload.auxillariesContract.contractVersion).toBe(AUXILLARIES_CONTRACT_VERSION);
     expect(validateAuxillariesContractSnapshot(payload.auxillariesContract)).toEqual({
       valid: true,