V40 Gate 4: Close API route integration contracts

Adds the package-backed V40ApiIntegrationContracts artifact, generator, checker, protocol exports, workflow wiring, and documentation for source-safe API/UAPI/MCP/ChatGPT App route contract coverage.

Hardens API and MCP integration test runners by wiring missing package dependency resolution, fixing Supabase insert/select mocks, aligning MCP asset-pack tool contract expectations, and normalizing MCP performance metrics from CPU deltas.

Proof: pnpm run check:v40-gate1; pnpm run check:v40-gate2; node scripts/check-v40-gate3-unit-coverage.mjs --skip-package-tests; pnpm run check:v40-gate4; pnpm --filter @bitcode/api build; pnpm --dir packages/executions-mcp/src/mcp-server run type-check; pnpm --filter @bitcode/protocol typecheck; node --test --test-force-exit packages/protocol/test/v40-test-inventory-coverage-matrix.test.js packages/protocol/test/v40-unit-coverage-inventory.test.js packages/protocol/test/v40-api-integration-contracts.test.js; git diff --check.

Author: geraldarthurdavis

.bitcode/v40-api-integration-contracts.json

@@ -565,7 +565,7 @@
       "passed": true
     },
     {
-      "id": "roadmap-advanced-to-gate3",
+      "id": "roadmap-advanced-through-gate3",
       "sourcePath": "SPECIFICATIONS_ROADMAP.md",
       "passed": true
     },

.bitcode/v40-unit-coverage-inventory.json

@@ -229,6 +229,9 @@ jobs:
               if [ -f scripts/check-v40-gate3-unit-coverage.mjs ]; then
                 node scripts/check-v40-gate3-unit-coverage.mjs --skip-branch-check --skip-package-tests
               fi
+              if [ -f scripts/check-v40-gate4-api-integration-contracts.mjs ]; then
+                node scripts/check-v40-gate4-api-integration-contracts.mjs --skip-branch-check --skip-integration-tests
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

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

@@ -358,6 +358,9 @@ jobs:
               if [ -f scripts/check-v40-gate3-unit-coverage.mjs ]; then
                 node scripts/check-v40-gate3-unit-coverage.mjs --skip-branch-check --skip-package-tests
               fi
+              if [ -f scripts/check-v40-gate4-api-integration-contracts.mjs ]; then
+                node scripts/check-v40-gate4-api-integration-contracts.mjs --skip-branch-check --skip-integration-tests
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

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

@@ -113,6 +113,13 @@ The package-owned `V40UnitCoverageInventory` emits `.bitcode/v40-unit-coverage-i
 Rows bind package names, source roots, test paths, command ids, verdicts, and closure requirements.
 Gate 3 permits no missing, blocked, or exempt critical unit surface in the artifact; any later discovered critical package unit without a direct test must reopen Gate 3 or be explicitly closed by a later V40 artifact.
 
+## V40 Gate 4 API And Route Integration Contracts
+
+Gate 4 closes API and route integration contract coverage beneath later browser, pipeline, synchronization, and rehearsal gates.
+The package-owned `V40ApiIntegrationContracts` emits `.bitcode/v40-api-integration-contracts.json` with source-safe rows for UAPI Reading and pipeline routes, execution stream routes, Conversation routes, Auxillaries and Orbitals routes, VCS/wallet/webhook routes, public activity/template routes, package API route orchestration, package API Conversation and pipeline routes, MCP execution interface contracts, and ChatGPT App action contracts.
+Rows bind route families, source roots, test paths, command ids, verdicts, and closure requirements.
+Gate 4 permits no missing, blocked, or exempt critical contract row; the artifact must prove route contract coverage while withholding secrets, protected source, raw protected prompts, raw provider responses, wallet private material, and unpaid AssetPack source.
+
 ## V40 canonical subsystem surfaces
 
 ### Depositing and asset supply
@@ -372,6 +379,8 @@ V40 inherits operator-quality artifact expectations for readable proof and repai
 | `.bitcode/v40-spec-family-report.json` | protocol canonical package | draft spec family validation |
 | `.bitcode/v40-canonical-input-report.json` | protocol canonical package | draft canonical input accounting |
 | `.bitcode/v40-test-inventory-coverage-matrix.json` | protocol canonical package | Gate 2 source-safe test inventory and coverage matrix |
+| `.bitcode/v40-unit-coverage-inventory.json` | protocol canonical package | Gate 3 source-safe unit coverage inventory |
+| `.bitcode/v40-api-integration-contracts.json` | protocol canonical package | Gate 4 source-safe API and route integration contract inventory |
 | `.bitcode/v40-promotion-readiness-report.json` | future V40 promotion gate | promotion readiness |
 
 ### V40 specifying generated artifacts

BITCODE_SPEC_V40.md

@@ -43,6 +43,7 @@ Gate 3 closes with package-backed `V40UnitCoverageInventory`, deterministic `.bi
 ### Gate 4: API And Route Integration Contracts
 
 Close API, UAPI, public route, MCP API, ChatGPT App, persistence, and authorization contract suites.
+Gate 4 closes with package-backed `V40ApiIntegrationContracts`, deterministic `.bitcode/v40-api-integration-contracts.json`, protocol exports, source-safe rows for every critical API/interface contract surface, and `check:v40-gate4`.
 
 ### Gate 5: Reading Pipeline Integration Coverage
 

BITCODE_SPEC_V40_DELTA.md

@@ -74,3 +74,10 @@ Gate 3 is closed by `V40UnitCoverageInventory`.
 Its generated `.bitcode/v40-unit-coverage-inventory.json` artifact binds critical unit surfaces to package names, source roots, test paths, commands, and covered verdicts.
 The covered surfaces include protocol report builders, BTD ledger/settlement/right primitives, prompt composition, PTRR agents, registry-backed tools, execution lineage, generic pipelines, Reading AssetPack units, pipeline hosts, isolated interface helpers, utility packages, and the demonstration/commercial boundary.
 No missing, blocked, or exempt critical unit surface is allowed in the Gate 3 artifact.
+
+## Gate 4 implementation notes
+
+Gate 4 is closed by `V40ApiIntegrationContracts`.
+Its generated `.bitcode/v40-api-integration-contracts.json` artifact binds critical API route integration contracts to route families, source roots, test paths, command ids, and covered verdicts.
+The covered surfaces include UAPI Reading/pipeline routes, execution stream routes, Conversation routes, Auxillaries/Orbitals routes, VCS/wallet/webhook routes, public activity/template routes, package API route orchestration, package API Conversation/pipeline routes, MCP execution interface contracts, and ChatGPT App action contracts.
+No missing, blocked, or exempt critical API route integration contract surface is allowed in the Gate 4 artifact.

BITCODE_SPEC_V40_NOTES.md

@@ -32,7 +32,7 @@ This matrix records the V40 testing surfaces that must become promotion-grade be
 | Canon workflow | Canon quality knows active V39 and draft V40 | `.github/workflows/bitcode-canon-quality.yml` | drafted |
 | Browser E2E | Critical website flows have browser proof | future V40 artifacts | not yet implemented |
 | Visual proof | Screenshot comparisons are deterministic and reviewable | future V40 artifacts | not yet implemented |
-| API integration | Route and API contracts are parseable and source-safe | future V40 artifacts | not yet implemented |
+| API integration | Route and API contracts are parseable and source-safe | `.bitcode/v40-api-integration-contracts.json` | implemented |
 | Pipeline integration | Primitive and real Reading pipeline implementations are tested | future V40 artifacts | not yet implemented |
 | Unit coverage | Packages, primitives, isolated implementations, and real implementations have unit coverage | future V40 artifacts | not yet implemented |
 | Prompt benchmark smoke | Prompt and PromptPart benchmarks run before V41 | future V40 artifacts | not yet implemented |
@@ -44,7 +44,7 @@ This matrix records the V40 testing surfaces that must become promotion-grade be
 | Gate 1 | Open V40 family and check script | drafted |
 | Gate 2 | Test inventory artifact and coverage matrix | implemented |
 | Gate 3 | Unit coverage closure artifact | implemented |
-| Gate 4 | API/route integration artifact | not yet implemented |
+| Gate 4 | API/route integration artifact | implemented |
 | Gate 5 | Reading pipeline integration artifact | not yet implemented |
 | Gate 6 | Conversation/Terminal integration artifact | not yet implemented |
 | Gate 7 | Browser/visual/accessibility/responsive artifact | not yet implemented |
@@ -55,6 +55,7 @@ This matrix records the V40 testing surfaces that must become promotion-grade be
 
 Gate 2 implementation evidence: package-backed `V40TestInventoryCoverageMatrix` emits `.bitcode/v40-test-inventory-coverage-matrix.json` and is wired through `check:v40-gate2`.
 Gate 3 implementation evidence: package-backed `V40UnitCoverageInventory` emits `.bitcode/v40-unit-coverage-inventory.json` and is wired through `check:v40-gate3`.
+Gate 4 implementation evidence: package-backed `V40ApiIntegrationContracts` emits `.bitcode/v40-api-integration-contracts.json` and is wired through `check:v40-gate4`.
 
 ## V40 accepted boundaries
 

BITCODE_SPEC_V40_PARITY_MATRIX.md

@@ -534,6 +534,11 @@ V40 Gate 3 adds the package-backed `V40UnitCoverageInventory`, generated
 `.bitcode/v40-unit-coverage-inventory.json`, and `check:v40-gate3` to close
 critical unit coverage for packages, primitives, isolated implementations,
 Reading AssetPack units, interface helpers, and demonstration boundary tests.
+V40 Gate 4 adds the package-backed `V40ApiIntegrationContracts`, generated
+`.bitcode/v40-api-integration-contracts.json`, and `check:v40-gate4` to close
+source-safe API, UAPI, MCP, ChatGPT App, persistence, authorization, and
+response-schema route integration contract coverage before later browser and
+pipeline gates.
 V38 Gates 1 through 11 are wired through `pnpm run check:v38-gate1`,
 `pnpm run check:v38-gate2`, `pnpm run check:v38-gate3`,
 `pnpm run check:v38-gate4`, `pnpm run check:v38-gate5`,

README.md

@@ -5,8 +5,8 @@
 - Current active canonical pointer: `BITCODE_SPEC.txt` -> `V39`
 - Current active canon: `BITCODE_SPEC_V39.md`
 - Current draft target: `BITCODE_SPEC_V40.md`.
-- Current working gate: V40 Gate 3 Unit Coverage For Packages And Primitives.
-- Next queued gate after V40 Gate 3 closure: V40 Gate 4 API And Route Integration Contracts.
+- Current working gate: V40 Gate 4 API And Route Integration Contracts.
+- Next queued gate after V40 Gate 4 closure: V40 Gate 5 Reading Pipeline Integration Coverage.
 - Latest closed version: V39 Commercial Reading Readiness, which promoted Depository supply indexing, enterprise five-step Reading UX, ReadNeed review/resynthesis, ReadFitsFinding many-candidate runtime, source-safe AssetPack preview and deterministic BTC quote, settlement rights delivery, operational telemetry/repair readback, interface parity, local/staging rehearsal, and V39 promotion readiness.
 - Recent V39 closure anchor: V39 canonical promotion updated `BITCODE_SPEC.txt` to `V39`, generated `BITCODE_SPEC_V39_PROVEN.md`, preserved active V39 / draft V40 runtime posture, and closed commercial Reading readiness canon.
 - V39 Gate 9 closure anchor: commercial Reading readiness now owns package-backed `ReadingInterfaceProductParity`, deterministic `.bitcode/v39-interface-conversation-product-parity.json`, Terminal/Conversation/API/MCP/ChatGPT/package-consumer no-bypass rows, source-safe contract readback, BTD interface root composition, focused package/interface tests, and workflow wiring through `check:v39-gate9`.
@@ -15,7 +15,8 @@
 - V40 Gate 1 opening anchor: exhaustive commercial application testing opens over promoted V39 with V40 SPEC, DELTA, NOTES, and PARITY files, `check:v40-gate1`, active V39 / draft V40 posture, and an eleven-gate plan for test inventory, unit coverage, API/route integrations, Reading pipeline integrations, Conversation/Terminal integrations, browser/visual/accessibility/responsive proof, ledger/database/storage/wallet/delivery synchronization, local/staging rehearsal, prompt benchmark smoke, and promotion readiness.
 - V40 Gate 2 closure anchor: exhaustive testing now owns package-backed `V40TestInventoryCoverageMatrix` source, deterministic `.bitcode/v40-test-inventory-coverage-matrix.json`, ten source-safe inventory surfaces covering unit, API/route, Reading pipeline, Conversation/Terminal, browser/visual/accessibility/responsive, ledger/database/storage/wallet/delivery, local/staging, prompt benchmark smoke, demonstration, and CI/promotion quality, protocol exports, package tests, workflow wiring, and `check:v40-gate2`.
 - V40 Gate 3 closure anchor: exhaustive testing now owns package-backed `V40UnitCoverageInventory` source, deterministic `.bitcode/v40-unit-coverage-inventory.json`, twelve source-safe covered unit surfaces for protocol report builders, BTD ledger/settlement/right primitives, prompt composition, PTRR agents, registry-backed tools, execution lineage/events/metrics, generic pipeline primitives, Reading AssetPack implementation units, pipeline hosts, isolated interface helpers, utility/security packages, and demonstration boundary coverage, protocol exports, package tests, workflow wiring, and `check:v40-gate3`.
-- Forward planning note: V41 should focus singularly on Prompt and PromptPart implementation quality: prompts as programs. V38's inference correctness hardening and V40's testing/benchmark depth should empower V41 to examine every raw PromptPart, every Prompt composition, every benchmark, semantic partition, title, template, interpolation contract, registry binding, and inference callsite; then repartition, retitle, rewrite, catalogue, and validate them across Reading pipelines and conversational interactions. V41 should primarily harden `ReadNeedComprehensionSynthesis` and `ReadFitsFindingSynthesis` prompt surfaces while also covering conversational and other inference prompts with the same catalogue-and-benchmark discipline.
+- V40 Gate 4 closure anchor: exhaustive testing now owns package-backed `V40ApiIntegrationContracts` source, deterministic `.bitcode/v40-api-integration-contracts.json`, ten source-safe covered API integration surfaces for UAPI Reading/pipeline routes, execution stream routes, Conversation routes, Auxillaries/Orbitals routes, VCS/wallet/webhook routes, public activity/template routes, package API route orchestration, package API Conversation/pipeline routes, MCP execution interface contracts, and ChatGPT App action contracts, protocol exports, package tests, workflow wiring, and `check:v40-gate4`.
+- Forward planning note: V41 should focus singularly on Prompt and PromptPart implementation quality: prompts as programs. V38's inference correctness hardening and V40's testing/benchmark depth should empower V41 to examine every raw PromptPart, every Prompt composition, every benchmark, meaningfully benchmarkable semantic part, title, template, interpolation contract, registry binding, and inference callsite; then repartition, retitle, rewrite, catalogue, and validate them across Reading pipelines and conversational interactions. V41 should primarily harden `ReadNeedComprehensionSynthesis` and `ReadFitsFindingSynthesis` prompt surfaces while also covering conversational and other inference prompts with the same catalogue-and-benchmark discipline.
 - V34 Gate 2 closure anchor: deployment-depth now owns package-backed `DeploymentHostCapabilityCatalog` and `EnvironmentLaneContract` source, deterministic `.bitcode/v34-deployment-host-capability-catalog.json` and `.bitcode/v34-environment-lane-contracts.json`, and visible `value-bearing-mainnet` blocking through `blocked_future_canon_required`.
 - V34 Gate 3 closure anchor: deployment-depth now owns package-backed `DistributedExecutionRuntimeReceipt` source, deterministic `.bitcode/v34-distributed-execution-runtime-receipts.json`, `request_response_not_required` long-running work posture, and source-safe roots for pipeline, PTRR agent, ThricifiedGeneration, tool, ledger, wallet, proof, object-storage, and repair work.
 - V34 Gate 4 closure anchor: deployment-depth now owns package-backed `DeploymentStoragePosture` source, deterministic `.bitcode/v34-deployment-storage-posture.json`, ledger/database/object-storage drift repair fixtures, retention/encryption/backup/rollback/audit posture, and source-bearing AssetPack storage remains locked before settlement.
@@ -135,7 +136,7 @@ They are referenced here for specification history only; active implementation w
 | V38 | `BITCODE_SPEC_V38.md` | promoted historical Bitcode canon | Inference correctness after V37: pipeline execution call stack, PTRR agents, FailsafeGenerationSequence over ThricifiedGeneration, prompt registry composition, PromptPart and Prompt benchmarking, Reading pipeline inference, ReadFitsFindingSynthesis depository search and embeddings, source-safe inference telemetry, local/staging rehearsal, and promotion readiness. |
 | V39 | `BITCODE_SPEC_V39.md` | active canon | Commercial Reading readiness after V38: Depository supply indexing, enterprise five-step Reading UX, ReadNeed review/resynthesis, ReadFitsFinding many-candidate runtime and replay, source-safe AssetPack preview and deterministic BTC quote, settlement, BTD rights transfer, post-settlement delivery, ledger/database/storage synchronization, operational telemetry/repair, interface parity, local/staging rehearsal, and promotion readiness. |
 | V40 | `BITCODE_SPEC_V40.md` | active draft target | Exhaustive commercial application testing depth after V39: rich browser E2E for all website interactions and state possibilities, visual/screenshot comparison coverage, API and integration suites for pipelines, conversations, routes, ledger/database/storage synchronization, and unit coverage for packages, primitives, isolated implementations, and real commercial implementations. |
-| V41 | future draft target after V40 | planned | Prompt and PromptPart excellence, treating prompts as programs: audit every raw PromptPart and composed Prompt, run and harden benchmarks, repartition prompts into benchmarkable semantic parts, retitle and rewrite PromptParts/Prompts where optimal, catalogue registry bindings and interpolation contracts, and elevate all Reading and Conversation inference points after V38 inference scaffolding and V40 testing depth make that work measurable. The primary surface is Reading, especially `ReadNeedComprehensionSynthesis` and `ReadFitsFindingSynthesis`; conversations and other inference prompts follow with the same benchmarkable catalogue discipline. |
+| V41 | future draft target after V40 | planned | Prompt and PromptPart excellence, treating prompts as programs: audit every raw PromptPart and composed Prompt, run and harden benchmarks, repartition prompts into meaningfully benchmarkable semantic parts, retitle and rewrite PromptParts/Prompts where optimal, catalogue registry bindings and interpolation contracts, and elevate all Reading and Conversation inference points after V38 inference scaffolding and V40 testing depth make that work measurable. The primary surface is Reading, especially `ReadNeedComprehensionSynthesis` and `ReadFitsFindingSynthesis`; conversations and other inference prompts follow with the same benchmarkable catalogue discipline. |
 
 ## Current Planning Spine
 
@@ -154,7 +155,7 @@ They are referenced here for specification history only; active implementation w
 13. V38 promoted inference correctness, Reading pipeline search, prompt benchmarking, source-safe inference telemetry, and the practical PTRR/Failsafe/Thricified call stack.
 14. V39 promoted commercial Reading readiness: Depository supply indexing, enterprise Reading UX, accepted-Need-gated Finding Fits, AssetPack preview/quote, settlement, rights transfer, delivery, telemetry/repair, interface parity, local/staging rehearsal, and promotion readiness.
 15. V40 is the current draft target and hardens exhaustive testing for the rich commercial application: E2E, visual, screenshot comparison, interaction/state matrices, integration, and unit coverage across the website, APIs, pipelines, conversations, packages, primitives, and real implementations.
-16. V41 is the planned prompts-as-programs target after V40: every PromptPart, Prompt composition, benchmark, semantic division, title, template, interpolation contract, registry binding, and inference callsite should be examined and improved across Reading and Conversation inference, using V38's inference correctness scaffolding and V40's testing/benchmarking depth as the measurement base.
+16. V41 is the planned prompts-as-programs target after V40: every PromptPart, Prompt composition, benchmark, meaningfully benchmarkable semantic division, title, template, interpolation contract, registry binding, and inference callsite should be examined and improved across Reading and Conversation inference, using V38's inference correctness scaffolding and V40's testing/benchmarking depth as the measurement base.
 
 ## Boundary Rules