Merge pull request #68 from engineeredsoftware/v33/gate-3-mcp-api-tool-registry-contracts

V33 Gate 3: MCP API Tool Registry Contracts

Author: geraldarthurdavis

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

@@ -222,7 +222,7 @@
       ]
     },
     {
-      "digest": "sha256:c8df35e424491484dcd72b26044ed53cef54c30d35d40dd089ea4e25bd6e4bda",
+      "digest": "sha256:43b65036a542f5a329aec530008d3faabf404f7e9cd4082b69e59aa49bd6495c",
       "relativePath": "packages/btd/src/index.ts",
       "requiredTokens": [
         {
@@ -232,7 +232,7 @@
       ]
     },
     {
-      "digest": "sha256:ba4069d85192fa7b62a3c393baf5a2ebd38f9a661b19f81a01793cd09414852c",
+      "digest": "sha256:7b1a6d74f640a1a5d263f6863b7ed12c5bb1a12c45dd1ade2f5b9a878d3ae2d2",
       "relativePath": "BITCODE_SPEC_V33.md",
       "requiredTokens": [
         {

.bitcode/v33-mcp-api-tool-contracts.json

@@ -0,0 +1,252 @@
+{
+  "artifactId": "v33-mcp-api-tool-contracts",
+  "closureCommand": "pnpm run check:v33-gate3",
+  "contracts": [
+    {
+      "authPolicyId": "interface.authorization.pipeline-permission",
+      "category": "pipelines",
+      "contractRoot": "v33-mcp-api-tool-contract:d37acb48606663faf222a539",
+      "deniedStates": [
+        "MISSING_API_KEY",
+        "INSUFFICIENT_PERMISSIONS",
+        "PROVIDER_BINDING_REQUIRED",
+        "SCHEMA_VALIDATION_FAILED",
+        "RATE_LIMITED",
+        "UNKNOWN_TOOL"
+      ],
+      "examples": [
+        {
+          "exampleId": "mcp-asset-pack-create-success-queued",
+          "fixturePath": "packages/executions-mcp/src/mcp-server/src/__tests__/unit/pipeline-ingress-contract.test.ts",
+          "posture": "success_queued"
+        },
+        {
+          "exampleId": "mcp-asset-pack-create-denied-permission",
+          "fixturePath": "packages/executions-mcp/src/mcp-server/src/__tests__/unit/pipeline-ingress-contract.test.ts",
+          "posture": "denied_permission"
+        },
+        {
+          "exampleId": "mcp-asset-pack-create-denied-auth",
+          "fixturePath": "packages/executions-mcp/src/mcp-server/src/__tests__/unit/auth.test.ts",
+          "posture": "denied_auth"
+        },
+        {
+          "exampleId": "mcp-asset-pack-create-denied-provider-binding",
+          "fixturePath": "packages/executions-mcp/src/mcp-server/src/__tests__/unit/pipeline-ingress-contract.test.ts",
+          "posture": "denied_provider_binding"
+        }
+      ],
+      "inputSchemaId": "bitcode.mcp.assetPackCreate.input.v1",
+      "outputSchemaId": "bitcode.mcp.assetPackCreate.output.v1",
+      "proofRootFields": [
+        "toolId",
+        "inputSchemaId",
+        "outputSchemaId",
+        "authPolicyId",
+        "requestRoot",
+        "responseRoot",
+        "writeAdmission"
+      ],
+      "protectedSourcePolicy": "source-safe-preview-and-metadata-before-settlement",
+      "requestRootFields": [
+        "task",
+        "repository",
+        "attachments",
+        "connections",
+        "subtype",
+        "streaming"
+      ],
+      "requiredPermissions": [
+        "pipelines.create"
+      ],
+      "responseRootFields": [
+        "runId",
+        "assetPackEvidenceId",
+        "status",
+        "interfaceSurface",
+        "writeAdmission",
+        "outputMeaning",
+        "monitoringUrl"
+      ],
+      "sourceSafetyClass": "protected-source-locked",
+      "toolId": "bitcode://pipelines/asset-pack/create",
+      "validationCommands": [
+        "pnpm --filter @bitcode/btd test -- --runTestsByPath __tests__/mcp-tool-contract.test.ts",
+        "pnpm --dir packages/executions-mcp/src/mcp-server run test:mcp -- --runTestsByPath src/__tests__/unit/mcp-tool-contract.test.ts src/__tests__/unit/pipeline-ingress-contract.test.ts --runInBand"
+      ]
+    }
+  ],
+  "coverage": {
+    "credentialsSerialized": false,
+    "deniedStateCoverage": true,
+    "missingToolIds": [],
+    "observedToolIds": [
+      "bitcode://pipelines/asset-pack/create"
+    ],
+    "proofRootCoverage": true,
+    "protectedSourceVisible": false,
+    "toolDiscoveryPackageDerived": true
+  },
+  "currentTarget": "V32",
+  "generatedAt": "2026-05-22T00:00:00.000Z",
+  "passed": true,
+  "requiredDeniedStates": [
+    "MISSING_API_KEY",
+    "INSUFFICIENT_PERMISSIONS",
+    "PROVIDER_BINDING_REQUIRED",
+    "SCHEMA_VALIDATION_FAILED",
+    "RATE_LIMITED",
+    "UNKNOWN_TOOL"
+  ],
+  "requiredProofRootFields": [
+    "toolId",
+    "inputSchemaId",
+    "outputSchemaId",
+    "authPolicyId",
+    "requestRoot",
+    "responseRoot",
+    "writeAdmission"
+  ],
+  "requiredToolIds": [
+    "bitcode://pipelines/asset-pack/create"
+  ],
+  "schemaId": "bitcode.v33.mcpApiToolContracts.v1",
+  "sharedFixtureFiles": [
+    "packages/btd/src/mcp-tool-contract.ts",
+    "packages/btd/src/index.ts",
+    "packages/executions-mcp/src/mcp-server/src/tools/pipeline-tools.ts",
+    "packages/executions-mcp/src/mcp-server/src/types/index.ts",
+    "packages/executions-mcp/src/mcp-server/src/server.ts",
+    "packages/btd/__tests__/mcp-tool-contract.test.ts",
+    "packages/executions-mcp/src/mcp-server/src/__tests__/unit/mcp-tool-contract.test.ts",
+    "packages/executions-mcp/src/mcp-server/src/__tests__/unit/pipeline-ingress-contract.test.ts",
+    "packages/executions-mcp/src/mcp-server/src/__tests__/unit/auth.test.ts",
+    "scripts/check-v33-gate3-mcp-api-tool-contracts.mjs"
+  ],
+  "sourceEvidence": [
+    {
+      "digest": "sha256:ed7ff68bb55bd47afc9c538b346a3df3b4559c4278f21f5551cb00a212d98c03",
+      "relativePath": "packages/btd/src/mcp-tool-contract.ts",
+      "requiredTokens": [
+        {
+          "present": true,
+          "token": "buildBtdMcpToolContractRegistry"
+        },
+        {
+          "present": true,
+          "token": "bitcode://pipelines/asset-pack/create"
+        },
+        {
+          "present": true,
+          "token": "SCHEMA_VALIDATION_FAILED"
+        },
+        {
+          "present": true,
+          "token": "PROVIDER_BINDING_REQUIRED"
+        },
+        {
+          "present": true,
+          "token": "source-safe-preview-and-metadata-before-settlement"
+        }
+      ]
+    },
+    {
+      "digest": "sha256:7ebd19411892562e1dacc38ba2187bd56ef62e95be89c0b9419d85b70331ae7e",
+      "relativePath": "packages/executions-mcp/src/mcp-server/src/tools/pipeline-tools.ts",
+      "requiredTokens": [
+        {
+          "present": true,
+          "token": "getBtdMcpToolContract"
+        },
+        {
+          "present": true,
+          "token": "assetPackCreateContract.toolId"
+        },
+        {
+          "present": true,
+          "token": "assetPackCreateContract.description"
+        },
+        {
+          "present": true,
+          "token": "AssetPackPipelineToolSchema"
+        }
+      ]
+    },
+    {
+      "digest": "sha256:7780b32086b7ae3f6bbd10b98b2b69e16b0fa7e7547076725723182111e03dec",
+      "relativePath": "packages/executions-mcp/src/mcp-server/src/types/index.ts",
+      "requiredTokens": [
+        {
+          "present": true,
+          "token": "AssetPackPipelineToolSchema"
+        },
+        {
+          "present": true,
+          "token": "PipelineNameValues"
+        },
+        {
+          "present": true,
+          "token": "PipelineConnectionInputSchema"
+        }
+      ]
+    }
+  ],
+  "sourceSafetyVerdict": "source-safe-mcp-api-tool-contract-metadata",
+  "testEvidence": [
+    {
+      "digest": "sha256:27ef7ecf25bdbcb8420466d898b28b5808ef30121ae24d5378a906573607c585",
+      "relativePath": "packages/btd/__tests__/mcp-tool-contract.test.ts",
+      "requiredTokens": [
+        {
+          "present": true,
+          "token": "publishes the package-owned AssetPack create tool contract"
+        },
+        {
+          "present": true,
+          "token": "carries proof-root fields, request roots, response roots, denied states, and examples"
+        },
+        {
+          "present": true,
+          "token": "fails closed when the required MCP tool id is missing"
+        }
+      ]
+    },
+    {
+      "digest": "sha256:b6a65ab71085aa0218109c207a5c079076aea59c4e7c531f25d51b4a1b58f428",
+      "relativePath": "packages/executions-mcp/src/mcp-server/src/__tests__/unit/mcp-tool-contract.test.ts",
+      "requiredTokens": [
+        {
+          "present": true,
+          "token": "discovers the AssetPack create tool from the package-owned BTD contract"
+        },
+        {
+          "present": true,
+          "token": "rejects invalid MCP tool input before execution"
+        },
+        {
+          "present": true,
+          "token": "declares source-safe output fields and proof roots for MCP responses"
+        }
+      ]
+    },
+    {
+      "digest": "sha256:c09f752e418c23b85c4bb583aab39a5e36037602d10ffbcde0ca58def6343144",
+      "relativePath": "packages/executions-mcp/src/mcp-server/src/__tests__/unit/pipeline-ingress-contract.test.ts",
+      "requiredTokens": [
+        {
+          "present": true,
+          "token": "rejects MCP pipeline writes without pipelines.create permission"
+        },
+        {
+          "present": true,
+          "token": "rejects incoherent repository/provider ingress before queueing MCP work"
+        },
+        {
+          "present": true,
+          "token": "returns asset-pack-normalized results for completed MCP writes"
+        }
+      ]
+    }
+  ],
+  "version": "V33"
+}

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

@@ -131,6 +131,7 @@ jobs:
             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
+            node scripts/check-v33-gate3-mcp-api-tool-contracts.mjs --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1
@@ -159,11 +160,13 @@ jobs:
           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__/mcp-tool-contract.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
           pnpm --filter @bitcode/api exec jest --config jest.config.cjs --runTestsByPath src/routes/__tests__/auxillaries-contract.test.ts --runInBand
           pnpm --dir packages/executions-mcp/src/mcp-server run test:mcp -- --runTestsByPath src/__tests__/unit/auth.test.ts --runInBand
+          pnpm --dir packages/executions-mcp/src/mcp-server run test:mcp -- --runTestsByPath src/__tests__/unit/mcp-tool-contract.test.ts src/__tests__/unit/pipeline-ingress-contract.test.ts --runInBand
           pnpm --dir packages/chatgptapp exec jest --runTestsByPath src/__tests__/tools.test.ts --runInBand
           pnpm --filter @bitcode/pipeline-hosts exec jest --config jest.config.cjs --runTestsByPath src/__tests__/asset-pack-harness.test.ts --runInBand
           pnpm --filter @bitcode/pipeline-asset-pack exec jest --config jest.config.cjs --passWithNoTests --forceExit

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`, `.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
+- Generated structured artifact inventory: draft V33 specifying artifacts `.bitcode/v33-spec-family-report.json`, `.bitcode/v33-canonical-input-report.json`, Gate 2 `.bitcode/v33-interface-contract-catalog.json`, and Gate 3 `.bitcode/v33-mcp-api-tool-contracts.json`; later V33 gates may add additional source-safe interface proof artifacts
+- Source parity state: Gate 3 adds package-owned `McpToolContract` source and generated proof coverage for MCP API tool discovery, schema, auth, denial, and proof-root contracts
 - Active canonical pointer during draft opening: `BITCODE_SPEC.txt` -> `V32`
 - Notes companion: `BITCODE_SPEC_V33_NOTES.md`
 - Delta companion: `BITCODE_SPEC_V33_DELTA.md`
@@ -148,6 +148,7 @@ Layer boundaries:
 - Ledger records and journals are source-of-truth for settlement/finality; Supabase/PostgreSQL projections must not contradict them.
 - Source-safe previews may expose measurements, roots, score bands, policy ids, fee quote roots, settlement posture, and denial reasons; they may not expose protected source before payment.
 - Interface responses may expose proof roots and repair instructions; they must not expose secrets, service-role keys, wallet private material, provider tokens, raw protected prompts, or pre-settlement AssetPack source.
+- MCP API tools must derive tool ids, descriptions, schema ids, proof-root fields, auth policy ids, denied states, examples, and source-safety posture from the package-owned `McpToolContract` registry, starting with `bitcode://pipelines/asset-pack/create`.
 
 ## V33 proof/test package API and inherited support canon
 
@@ -175,7 +176,7 @@ V33 adds interface-facing contract objects over V32 protocol truth:
 
 - `InterfaceContractCatalog`: active interface ids, owners, actions/tools/routes, schemas, source-safety classes, examples, proof roots, and compatibility status.
 - `InterfaceAuthorizationPolicy`: auth mode, issuer, organization/team/role requirements, wallet requirement, license requirement, protected-source policy, denial reason, and repair posture.
-- `McpToolContract`: MCP tool id, input schema, output schema, auth policy, source-safety class, ledger/database proof bindings, and denied-state rendering.
+- `McpToolContract`: MCP tool id, input schema, output schema, auth policy, source-safety class, ledger/database proof bindings, denied-state rendering, proof-root field set, package-derived examples, and pre-settlement protected-source lock.
 - `ChatGptAppActionContract`: ChatGPT App action id, UI response family, source-safe summary, structured result schema, repair instructions, and proof-root projection.
 - `PublicApiRouteContract`: route id, method, schema, auth policy, idempotency, versionless path, rate/security posture, and example set.
 - `ReadLicenseInterfaceContract`: Read request, reviewed ReadNeed, Finding Fits admission, source-safe preview, fee quote, license posture, unpaid denial, paid unlock, and proof root.
@@ -191,7 +192,7 @@ V33 closes through ten gates:
 
 1. **Gate 1: V33 Interface Roadmap And Spec Opening** opens the V33 family, makes `SPECIFICATIONS_ROADMAP.md` truthful after V32 promotion, and wires V33 Gate 1 checks.
 2. **Gate 2: Interface Inventory And Contract Catalog** inventories active and deferred interface surfaces and creates the package-owned `InterfaceContractCatalog`.
-3. **Gate 3: MCP API Tool And Registry Contracts** hardens MCP tool schemas, action discovery, policy denial, proof-root surfacing, and example replay.
+3. **Gate 3: MCP API Tool And Registry Contracts** hardens MCP tool schemas, action discovery, policy denial, proof-root surfacing, and example replay through `McpToolContract` and `.bitcode/v33-mcp-api-tool-contracts.json`.
 4. **Gate 4: ChatGPT App Action And Tool Contracts** hardens ChatGPT App action schemas, source-safe response rendering, denial readability, and examples.
 5. **Gate 5: Interface Authorization Policy Fail-Closed** centralizes auth, organization, wallet, read-license, rights, and protected-source policy denials.
 6. **Gate 6: Read License And AssetPack Rights Interface Contracts** proves source-safe preview, paid settlement, BTD rights, and delivery contracts across interfaces.
@@ -492,6 +493,11 @@ The required row ids are `terminal_handoff`, `public_api`, `mcp_api`, `chatgpt_a
 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.
 
+Gate 3 `McpToolContract` rows are package-owned source-safe MCP API metadata.
+The required first tool id is `bitcode://pipelines/asset-pack/create`.
+The contract binds `bitcode.mcp.assetPackCreate.input.v1`, `bitcode.mcp.assetPackCreate.output.v1`, `interface.authorization.pipeline-permission`, `pipelines.create`, `protected-source-locked`, `source-safe-preview-and-metadata-before-settlement`, proof-root fields, request/response roots, and denied states including `SCHEMA_VALIDATION_FAILED` and `PROVIDER_BINDING_REQUIRED`.
+MCP discovery must consume this contract instead of repeating tool ids or descriptions locally.
+
 ## Appendix B. Proof family closure catalog
 
 The V33 proof-family catalog is the nine-family catalog in `V33 proof-family canon`.
@@ -527,11 +533,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 |
+| `.bitcode/v33-mcp-api-tool-contracts.json` | `scripts/generate-v33-mcp-api-tool-contracts.mjs` | `check:v33-mcp-api-tool-contracts` and `check:v33-gate3` | source-safe-mcp-api-tool-contract-metadata | Gate 3 required |
 
 ### V33 specifying generated artifacts
 
 V33 starts with `.bitcode/v33-spec-family-report.json` and `.bitcode/v33-canonical-input-report.json`.
 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`.
+Gate 3 adds `.bitcode/v33-mcp-api-tool-contracts.json`, which serializes source-safe `McpToolContract` metadata for `bitcode://pipelines/asset-pack/create`, including schema ids, denied states, proof-root fields, examples, package-derived discovery posture, and protected-source invisibility.
 Later gates may add authorization policy, schema compatibility, telemetry replay, and promotion readiness artifacts.
 
 ### Shared generated-artifact fields