Merge pull request #67 from engineeredsoftware/v33/gate-2-interface-contract-catalog

V33 Gate 2: Interface Contract Catalog

Author: geraldarthurdavis

.bitcode/v33-interface-contract-catalog.json

@@ -0,0 +1,293 @@
+{
+  "artifactId": "v33-interface-contract-catalog",
+  "catalogRoot": "v33-interface-contract-catalog:7d2e48f799f989b43084ee81",
+  "closureCommand": "pnpm run check:v33-gate2",
+  "coverage": {
+    "activeContractCount": 5,
+    "credentialsSerialized": false,
+    "deferredBlockedCount": 2,
+    "deferredSurfacesHidden": false,
+    "missingInterfaceIds": [],
+    "observedInterfaceIds": [
+      "terminal_handoff",
+      "public_api",
+      "mcp_api",
+      "chatgpt_app",
+      "package_consumer",
+      "exchange_hook",
+      "conversations_hook"
+    ],
+    "protectedSourceVisible": false,
+    "routeLocalReimplementation": false
+  },
+  "currentTarget": "V32",
+  "deferredInterfaceIds": [
+    "exchange_hook",
+    "conversations_hook"
+  ],
+  "generatedAt": "2026-05-22T00:00:00.000Z",
+  "passed": true,
+  "requiredInterfaceIds": [
+    "terminal_handoff",
+    "public_api",
+    "mcp_api",
+    "chatgpt_app",
+    "package_consumer",
+    "exchange_hook",
+    "conversations_hook"
+  ],
+  "requiredRowFields": [
+    "ownerPackage",
+    "actionId",
+    "schemaId",
+    "authPolicyId",
+    "sourceSafetyClass",
+    "exampleFixturePath",
+    "validationCommand",
+    "compatibilityStatus",
+    "failureMode",
+    "repairPosture",
+    "telemetryProofHookId"
+  ],
+  "rows": [
+    {
+      "actionId": "terminal.reading.handoff",
+      "authPolicyId": "interface.authorization.reader-session",
+      "bindingKind": "terminal_handoff",
+      "compatibilityStatus": "compatible",
+      "exampleFixturePath": "uapi/tests/terminalInterfaceIntegrationRegression.test.ts",
+      "failureMode": "terminal-handoff-denies-protected-assetpack-source-before-settlement",
+      "interfaceId": "terminal_handoff",
+      "ownerPackage": "uapi/app/terminal",
+      "repairPosture": "review-source-safe-preview-and-settle-before-full-delivery",
+      "rowRoot": "v33-interface-contract-catalog-row:acde7c4f416938c39cf71669",
+      "schemaId": "bitcode.interface.terminalReadingHandoff.v1",
+      "sourceSafetyClass": "protected-source-locked",
+      "status": "active_contract",
+      "telemetryProofHookId": "interface.telemetry.terminal-reading-handoff",
+      "validationCommand": "pnpm --dir uapi exec jest --runTestsByPath tests/terminalInterfaceIntegrationRegression.test.ts --runInBand"
+    },
+    {
+      "actionId": "api.reading.interface",
+      "authPolicyId": "interface.authorization.authenticated-route",
+      "bindingKind": "api_route",
+      "compatibilityStatus": "compatible",
+      "exampleFixturePath": "packages/api/src/routes/__tests__/btd-crypto.test.ts",
+      "failureMode": "public-api-denies-missing-auth-or-stale-read-license",
+      "interfaceId": "public_api",
+      "ownerPackage": "packages/api/src/routes",
+      "repairPosture": "authenticate-refresh-license-or-request-source-safe-preview",
+      "rowRoot": "v33-interface-contract-catalog-row:0f44cfae6fc12a5ce519fa20",
+      "schemaId": "bitcode.interface.publicApiReading.v1",
+      "sourceSafetyClass": "source-safe-internal",
+      "status": "active_contract",
+      "telemetryProofHookId": "interface.telemetry.public-api-reading",
+      "validationCommand": "pnpm --filter @bitcode/api exec jest --config jest.config.cjs --runTestsByPath src/routes/__tests__/btd-crypto.test.ts --runInBand"
+    },
+    {
+      "actionId": "mcp.reading.pipeline",
+      "authPolicyId": "interface.authorization.pipeline-permission",
+      "bindingKind": "mcp_tool",
+      "compatibilityStatus": "compatible",
+      "exampleFixturePath": "packages/executions-mcp/src/mcp-server/src/__tests__/unit/pipeline-ingress-contract.test.ts",
+      "failureMode": "mcp-tool-denies-missing-pipelines-create-permission",
+      "interfaceId": "mcp_api",
+      "ownerPackage": "packages/executions-mcp/src/mcp-server",
+      "repairPosture": "grant-pipeline-permission-or-use-source-safe-readonly-tool",
+      "rowRoot": "v33-interface-contract-catalog-row:d9c30910e339a7c701ee16d8",
+      "schemaId": "bitcode.interface.mcpReadingTool.v1",
+      "sourceSafetyClass": "source-safe-internal",
+      "status": "active_contract",
+      "telemetryProofHookId": "interface.telemetry.mcp-reading-tool",
+      "validationCommand": "pnpm --dir packages/executions-mcp/src/mcp-server run test:mcp -- --runTestsByPath src/__tests__/unit/pipeline-ingress-contract.test.ts --runInBand"
+    },
+    {
+      "actionId": "chatgpt.reading.action",
+      "authPolicyId": "interface.authorization.confirmed-connected-write",
+      "bindingKind": "chatgpt_action",
+      "compatibilityStatus": "compatible",
+      "exampleFixturePath": "packages/chatgptapp/src/__tests__/tools.test.ts",
+      "failureMode": "chatgpt-action-denies-missing-confirmation-read-access-or-authority",
+      "interfaceId": "chatgpt_app",
+      "ownerPackage": "packages/chatgptapp",
+      "repairPosture": "confirm-action-refresh-read-access-or-repair-organization-authority",
+      "rowRoot": "v33-interface-contract-catalog-row:1a33b4a6b38368cdfa1417be",
+      "schemaId": "bitcode.interface.chatGptReadingAction.v1",
+      "sourceSafetyClass": "source-safe-internal",
+      "status": "active_contract",
+      "telemetryProofHookId": "interface.telemetry.chatgpt-reading-action",
+      "validationCommand": "pnpm --dir packages/chatgptapp exec jest --runTestsByPath src/__tests__/tools.test.ts --runInBand"
+    },
+    {
+      "actionId": "package.interface.contract-catalog",
+      "authPolicyId": "interface.authorization.package-consumer-source-safe",
+      "bindingKind": "package_export",
+      "compatibilityStatus": "compatible",
+      "exampleFixturePath": "packages/btd/__tests__/interface-contract-catalog.test.ts",
+      "failureMode": "package-consumer-denies-route-local-contract-reimplementation",
+      "interfaceId": "package_consumer",
+      "ownerPackage": "packages/btd",
+      "repairPosture": "consume-package-export-and-regenerate-contract-artifact",
+      "rowRoot": "v33-interface-contract-catalog-row:53c71c3b4eea4e590a65285e",
+      "schemaId": "bitcode.interface.packageConsumerCatalog.v1",
+      "sourceSafetyClass": "source-safe-public",
+      "status": "active_contract",
+      "telemetryProofHookId": "interface.telemetry.package-contract-catalog",
+      "validationCommand": "pnpm --filter @bitcode/btd test -- --runTestsByPath __tests__/interface-contract-catalog.test.ts"
+    },
+    {
+      "actionId": "exchange.reading.hook",
+      "authPolicyId": "interface.authorization.deferred-not-admitted",
+      "bindingKind": "deferred_hook",
+      "compatibilityStatus": "deferred_not_admitted",
+      "deferredReason": "Exchange product depth is deferred beyond V33 interface cataloging.",
+      "exampleFixturePath": "uapi/tests/terminalInterfaceIntegrationRegression.test.ts",
+      "failureMode": "exchange-hook-remains-blocked-until-exchange-product-depth-gate",
+      "interfaceId": "exchange_hook",
+      "ownerPackage": "uapi/app/exchange",
+      "repairPosture": "wait-for-exchange-depth-gate-before-interface-admission",
+      "rowRoot": "v33-interface-contract-catalog-row:48e0e1303fcd41f9869cc8c0",
+      "schemaId": "bitcode.interface.exchangeHook.v1",
+      "sourceSafetyClass": "deferred-blocker",
+      "status": "deferred_blocked",
+      "telemetryProofHookId": "interface.telemetry.exchange-hook-blocker",
+      "validationCommand": "pnpm --dir uapi exec jest --runTestsByPath tests/terminalInterfaceIntegrationRegression.test.ts --runInBand"
+    },
+    {
+      "actionId": "conversations.reading.hook",
+      "authPolicyId": "interface.authorization.deferred-not-admitted",
+      "bindingKind": "deferred_hook",
+      "compatibilityStatus": "deferred_not_admitted",
+      "deferredReason": "Website Conversations product depth is deferred beyond V33 interface cataloging.",
+      "exampleFixturePath": "uapi/tests/api/conversationsRouteRead.test.ts",
+      "failureMode": "conversations-hook-remains-blocked-until-conversations-product-depth-gate",
+      "interfaceId": "conversations_hook",
+      "ownerPackage": "uapi/app/conversations",
+      "repairPosture": "wait-for-conversations-depth-gate-before-interface-admission",
+      "rowRoot": "v33-interface-contract-catalog-row:bca048866c37837b5a5d7200",
+      "schemaId": "bitcode.interface.conversationsHook.v1",
+      "sourceSafetyClass": "deferred-blocker",
+      "status": "deferred_blocked",
+      "telemetryProofHookId": "interface.telemetry.conversations-hook-blocker",
+      "validationCommand": "pnpm --dir uapi exec jest --runTestsByPath tests/api/conversationsRouteRead.test.ts --runInBand"
+    }
+  ],
+  "schemaId": "bitcode.v33.interfaceContractCatalog.v1",
+  "sharedFixtureFiles": [
+    "packages/btd/src/interface-contract-catalog.ts",
+    "packages/btd/src/index.ts",
+    "BITCODE_SPEC_V33.md",
+    "BITCODE_SPEC_V33_DELTA.md",
+    "BITCODE_SPEC_V33_PARITY_MATRIX.md",
+    "packages/btd/__tests__/interface-contract-catalog.test.ts",
+    "scripts/check-v33-gate2-interface-contract-catalog.mjs"
+  ],
+  "sourceEvidence": [
+    {
+      "digest": "sha256:36110f21b7743a3642d6ea38760b56cf2141fdad1007d8379e46ddd73d43bd0e",
+      "relativePath": "packages/btd/src/interface-contract-catalog.ts",
+      "requiredTokens": [
+        {
+          "present": true,
+          "token": "buildBtdInterfaceContractCatalog"
+        },
+        {
+          "present": true,
+          "token": "terminal_handoff"
+        },
+        {
+          "present": true,
+          "token": "public_api"
+        },
+        {
+          "present": true,
+          "token": "mcp_api"
+        },
+        {
+          "present": true,
+          "token": "chatgpt_app"
+        },
+        {
+          "present": true,
+          "token": "package_consumer"
+        },
+        {
+          "present": true,
+          "token": "conversations_hook"
+        },
+        {
+          "present": true,
+          "token": "deferred_not_admitted"
+        }
+      ]
+    },
+    {
+      "digest": "sha256:c8df35e424491484dcd72b26044ed53cef54c30d35d40dd089ea4e25bd6e4bda",
+      "relativePath": "packages/btd/src/index.ts",
+      "requiredTokens": [
+        {
+          "present": true,
+          "token": "interface-contract-catalog"
+        }
+      ]
+    },
+    {
+      "digest": "sha256:ba4069d85192fa7b62a3c393baf5a2ebd38f9a661b19f81a01793cd09414852c",
+      "relativePath": "BITCODE_SPEC_V33.md",
+      "requiredTokens": [
+        {
+          "present": true,
+          "token": "InterfaceContractCatalog"
+        },
+        {
+          "present": true,
+          "token": ".bitcode/v33-interface-contract-catalog.json"
+        }
+      ]
+    }
+  ],
+  "sourceSafetyVerdict": "source-safe-interface-contract-catalog-metadata",
+  "testEvidence": [
+    {
+      "digest": "sha256:fc7643fec28d633c907038164c3ad2eb49418a03d5217d989f3e8475f8130010",
+      "relativePath": "packages/btd/__tests__/interface-contract-catalog.test.ts",
+      "requiredTokens": [
+        {
+          "present": true,
+          "token": "catalogs Terminal handoff, public API, MCP API, ChatGPT App, package consumers, and deferred hooks"
+        },
+        {
+          "present": true,
+          "token": "fails closed when a required interface catalog row is missing"
+        },
+        {
+          "present": true,
+          "token": "fails closed when deferred hooks are accidentally admitted as compatible active contracts"
+        },
+        {
+          "present": true,
+          "token": "fails closed on secret-shaped or protected-source catalog text"
+        }
+      ]
+    },
+    {
+      "digest": "sha256:dfa6c8231a615b5f078f2f4e85ff1a7003946ef80284d84c05b29291eb29f5ae",
+      "relativePath": "scripts/check-v33-gate2-interface-contract-catalog.mjs",
+      "requiredTokens": [
+        {
+          "present": true,
+          "token": "check:v33-interface-contract-catalog"
+        },
+        {
+          "present": true,
+          "token": "interface-contract-catalog.test.ts"
+        },
+        {
+          "present": true,
+          "token": "Gate 2 interface contract catalog"
+        }
+      ]
+    }
+  ],
+  "version": "V33"
+}

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

@@ -130,6 +130,7 @@ jobs:
             fi
             node scripts/check-v32-gate10-promotion-readiness.mjs --promotion-mode --skip-branch-check
             node scripts/check-v33-gate1-interface-roadmap-opening.mjs --skip-branch-check
+            node scripts/check-v33-gate2-interface-contract-catalog.mjs --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1
@@ -157,6 +158,7 @@ jobs:
           pnpm --filter @bitcode/btd test -- --runTestsByPath __tests__/btd.test.ts
           pnpm --filter @bitcode/btd test -- --runTestsByPath __tests__/v32-ledger-btd-settlement-failure-states.test.ts
           pnpm --filter @bitcode/btd test -- --runTestsByPath __tests__/v32-interface-contract-regression.test.ts
+          pnpm --filter @bitcode/btd test -- --runTestsByPath __tests__/interface-contract-catalog.test.ts
           pnpm --filter @bitcode/btd test -- --runTestsByPath __tests__/v32-testnet-mainnet-readiness-rehearsal.test.ts
           pnpm --dir packages/protocol exec node --test --test-force-exit test/v32-promotion-proof-generation.test.js
           pnpm --filter @bitcode/api exec jest --config jest.config.cjs --runTestsByPath src/routes/__tests__/btd-crypto.test.ts --runInBand

BITCODE_SPEC_V33.md

@@ -7,8 +7,8 @@
 - Current canonical/latest target: `V32`
 - Prior canonical anchor: `BITCODE_SPEC_V32.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V32_PROVEN.md`
-- Generated structured artifact inventory: draft V33 specifying artifacts `.bitcode/v33-spec-family-report.json` and `.bitcode/v33-canonical-input-report.json`; later V33 gates may add source-safe interface proof artifacts
-- Source parity state: Gate 1 opens source parity tracking for interface-depth work; implementation begins only through scoped V33 gates
+- Generated structured artifact inventory: draft V33 specifying artifacts `.bitcode/v33-spec-family-report.json`, `.bitcode/v33-canonical-input-report.json`, and Gate 2 `.bitcode/v33-interface-contract-catalog.json`; later V33 gates may add additional source-safe interface proof artifacts
+- Source parity state: Gate 2 adds package-owned `InterfaceContractCatalog` source and generated proof coverage for active and deferred interface surfaces
 - Active canonical pointer during draft opening: `BITCODE_SPEC.txt` -> `V32`
 - Notes companion: `BITCODE_SPEC_V33_NOTES.md`
 - Delta companion: `BITCODE_SPEC_V33_DELTA.md`
@@ -224,7 +224,7 @@ The V33 operator chain keeps V32 behavior and adds interface consistency:
 - Current invariants and fail-closed conditions: invalid deposit, missing source proof, unsupported provider, policy denial, or protected-source leakage blocks interface projection.
 - Current proof obligations: deposit measurement proof, source-safety class, and interface projection test.
 - Current source-bearing implementation basis: commercial package and `uapi` routes, not `protocol-demonstration`.
-- Current validating commands and parity basis: V32 canonical proofs plus V33 Gate 2 interface catalog checks.
+- Current validating commands and parity basis: V32 canonical proofs plus V33 Gate 2 interface catalog checks, including `.bitcode/v33-interface-contract-catalog.json`.
 - Current accepted boundaries: V33 does not change deposit ownership law.
 
 ### Reading and prompt/inference ownership
@@ -487,6 +487,11 @@ V33 is complete when all ten gates are closed, source-safe interface contracts a
 Primary V33 types: `InterfaceContractCatalog`, `InterfaceAuthorizationPolicy`, `McpToolContract`, `ChatGptAppActionContract`, `PublicApiRouteContract`, `ReadLicenseInterfaceContract`, `AssetPackRightsInterfaceContract`, `APISchemaCompatibilityMatrix`, and `InterfaceTelemetryProofHook`.
 Primary surfaces: MCP API, ChatGPT App, public API, Terminal handoff, package consumers, ledger projection, database projection, object-storage projection, and proof replay.
 
+Gate 2 `InterfaceContractCatalog` rows are package-owned source-safe metadata.
+The required row ids are `terminal_handoff`, `public_api`, `mcp_api`, `chatgpt_app`, `package_consumer`, `exchange_hook`, and `conversations_hook`.
+Each row names an owner package, action/tool/route id, schema id, auth policy id, source-safety class, example fixture path, validation command, compatibility status, failure mode, repair posture, telemetry proof hook id, and deterministic proof root.
+The `exchange_hook` and `conversations_hook` rows are visible as `deferred_not_admitted` rather than hidden.
+
 ## Appendix B. Proof family closure catalog
 
 The V33 proof-family catalog is the nine-family catalog in `V33 proof-family canon`.
@@ -521,11 +526,13 @@ V33 inherits the V20 operator-quality expectation that interface-facing proof is
 | --- | --- | --- | --- | --- |
 | `.bitcode/v33-spec-family-report.json` | spec-family report builder | `check-bitcode-spec-family` | source-safe-generated-proof | draft-required |
 | `.bitcode/v33-canonical-input-report.json` | canonical-input report builder | `check-bitcode-canonical-inputs` | source-safe-generated-proof | draft-required |
+| `.bitcode/v33-interface-contract-catalog.json` | `scripts/generate-v33-interface-contract-catalog.mjs` | `check:v33-interface-contract-catalog` and `check:v33-gate2` | source-safe-interface-contract-catalog-metadata | Gate 2 required |
 
 ### V33 specifying generated artifacts
 
 V33 starts with `.bitcode/v33-spec-family-report.json` and `.bitcode/v33-canonical-input-report.json`.
-Later gates may add interface catalog, authorization policy, schema compatibility, telemetry replay, and promotion readiness artifacts.
+Gate 2 adds `.bitcode/v33-interface-contract-catalog.json`, which serializes source-safe `InterfaceContractCatalog` metadata for `terminal_handoff`, `public_api`, `mcp_api`, `chatgpt_app`, `package_consumer`, `exchange_hook`, and `conversations_hook` with deferred hooks marked `deferred_not_admitted`.
+Later gates may add authorization policy, schema compatibility, telemetry replay, and promotion readiness artifacts.
 
 ### Shared generated-artifact fields