V33 Gate 4: Harden ChatGPT App action contracts

Add package-owned ChatGPT App Reading action contracts covering Read, Need, Finding Fits, preview, fee, settlement, and delivery actions with source-safe renderers, proof roots, denied-state repair posture, generated artifact checks, workflow wiring, and ChatGPT App registry integration.

Validate with V33 Gate 1-4 checkers, V33 strict spec quality, BTD typecheck/full Jest, ChatGPT App typecheck/full Jest, protocol tests, canon posture/canonical-input checks, V32 promotion readiness, and diff/secret hygiene.

Author: geraldarthurdavis

.bitcode/v33-chatgpt-app-action-contracts.json

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

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

@@ -132,6 +132,7 @@ jobs:
             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
+            node scripts/check-v33-gate4-chatgpt-app-action-contracts.mjs --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1
@@ -161,13 +162,14 @@ jobs:
           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__/chatgpt-app-action-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 --dir packages/chatgptapp exec jest --runTestsByPath src/__tests__/chatgpt-action-contract.test.ts 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
           pnpm --filter @bitcode/pipeline-asset-pack exec jest --config jest.config.cjs --runTestsByPath src/__tests__/reading-pipeline-observability.test.ts src/__tests__/reading-pipeline-contract.test.ts src/__tests__/v32-reading-pipeline-proof-coverage.test.ts --runInBand

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

@@ -534,12 +534,14 @@ V33 inherits the V20 operator-quality expectation that interface-facing proof is
 | `.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 |
+| `.bitcode/v33-chatgpt-app-action-contracts.json` | `scripts/generate-v33-chatgpt-app-action-contracts.mjs` | `check:v33-chatgpt-app-action-contracts` and `check:v33-gate4` | source-safe-chatgpt-app-action-contract-metadata | Gate 4 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.
+Gate 4 adds `.bitcode/v33-chatgpt-app-action-contracts.json`, which serializes source-safe `ChatGptAppActionContract` metadata for `bitcode_request_read`, `bitcode_review_read_need`, `bitcode_request_finding_fits`, `bitcode_review_asset_pack_preview`, `bitcode_quote_asset_pack_fee`, `bitcode_settle_asset_pack`, and `bitcode_deliver_asset_pack`, including package-owned schemas, source-safe response renderers, proof-root projection, readable denial states such as `READ_LICENSE_REQUIRED`, and repair actions.
 Later gates may add authorization policy, schema compatibility, telemetry replay, and promotion readiness artifacts.
 
 ### Shared generated-artifact fields
@@ -564,7 +566,7 @@ V33 promotion must fail closed when generated artifacts are missing, stale, sour
 
 ## Appendix D. Validation and checking gate catalog
 
-V33 validation includes `check-bitcode-spec-family`, `check-bitcode-canonical-inputs`, `check-bitcode-canon-posture-drift`, `check:v33-gate1`, later gate-specific checkers, package tests, interface contract tests, and promotion workflow checks.
+V33 validation includes `check-bitcode-spec-family`, `check-bitcode-canonical-inputs`, `check-bitcode-canon-posture-drift`, `check:v33-gate1`, `check:v33-gate2`, `check:v33-gate3`, `check:v33-gate4`, later gate-specific checkers, package tests, interface contract tests, and promotion workflow checks.
 
 ## Appendix E. Current canonical source map
 

BITCODE_SPEC_V33.md

@@ -111,6 +111,15 @@ Implementation centers:
 
 Gate 4 hardens ChatGPT App contracts.
 
+Implementation centers:
+
+- `packages/btd/src/chatgpt-app-action-contract.ts` owns `ChatGptAppActionContract`, `BTD_CHATGPT_APP_ACTION_CONTRACT_IDS`, and source-safe response rendering through `renderBtdChatGptAppSourceSafeResponse`;
+- `packages/chatgptapp/src/tools.ts` derives Reading action tool names, descriptions, schemas, source-safe metadata, and denial repair posture from `buildBtdChatGptAppActionContractRegistry`;
+- the package-owned action ids are `bitcode_request_read`, `bitcode_review_read_need`, `bitcode_request_finding_fits`, `bitcode_review_asset_pack_preview`, `bitcode_quote_asset_pack_fee`, `bitcode_settle_asset_pack`, and `bitcode_deliver_asset_pack`;
+- denied states include `SCHEMA_VALIDATION_FAILED`, `MISSING_READER_SESSION`, `READ_NEED_REQUIRED`, `FINDING_FITS_REQUIRED`, `ASSET_PACK_PREVIEW_REQUIRED`, `FEE_QUOTE_REQUIRED`, `SETTLEMENT_REQUIRED`, `READ_LICENSE_REQUIRED`, `ORGANIZATION_AUTHORITY_REQUIRED`, and `CONFIRMATION_REQUIRED`;
+- `.bitcode/v33-chatgpt-app-action-contracts.json` records source-safe Gate 4 action metadata, proof-root coverage, source-safe renderer coverage, denial repair coverage, and credential non-serialization;
+- `check:v33-gate4` validates source, tests, docs, workflow, generated artifact freshness, and ChatGPT App source-safe action posture.
+
 Closure acceptance:
 
 - ChatGPT App actions use package-owned schemas and source-safe response renderers;

BITCODE_SPEC_V33_DELTA.md

@@ -78,6 +78,15 @@ Denied states are explicit and include `SCHEMA_VALIDATION_FAILED`, `PROVIDER_BIN
 The MCP server consumes the package-owned contract through `getBtdMcpToolContract` for tool discovery, including tool id and description, while pre-settlement protected source remains invisible.
 The generated source-safe artifact is `.bitcode/v33-mcp-api-tool-contracts.json`, checked by `check:v33-mcp-api-tool-contracts` and `check:v33-gate3`.
 
+## Gate 4 closure note
+
+Gate 4 introduces `ChatGptAppActionContract` in `packages/btd/src/chatgpt-app-action-contract.ts`.
+The required ChatGPT App Reading action ids are `bitcode_request_read`, `bitcode_review_read_need`, `bitcode_request_finding_fits`, `bitcode_review_asset_pack_preview`, `bitcode_quote_asset_pack_fee`, `bitcode_settle_asset_pack`, and `bitcode_deliver_asset_pack`.
+Each action binds package-owned input/output schemas, `interface.authorization.chatgpt-reading-action`, `chatgpt.reading.invoke`, a source-safe response renderer, proof-root projection, and readable repair posture.
+Denied states include `SCHEMA_VALIDATION_FAILED`, `READ_NEED_REQUIRED`, `FINDING_FITS_REQUIRED`, `ASSET_PACK_PREVIEW_REQUIRED`, `FEE_QUOTE_REQUIRED`, `SETTLEMENT_REQUIRED`, `READ_LICENSE_REQUIRED`, `ORGANIZATION_AUTHORITY_REQUIRED`, and `CONFIRMATION_REQUIRED`.
+The ChatGPT App tool registry consumes the package-owned contracts through `buildBtdChatGptAppActionContractRegistry`, while `renderBtdChatGptAppSourceSafeResponse` keeps locked AssetPack contents invisible.
+The generated source-safe artifact is `.bitcode/v33-chatgpt-app-action-contracts.json`, checked by `check:v33-chatgpt-app-action-contracts` and `check:v33-gate4`.
+
 ## Carryforward from V32
 
 V33 inherits these V32 truths:

BITCODE_SPEC_V33_NOTES.md

@@ -53,7 +53,7 @@ No `_legacy/` source is active source truth.
 | Roadmap truth | Gate 1 | `SPECIFICATIONS_ROADMAP.md`, README, PR template, workflow posture | drafted | Roadmap states V32 active, V33 draft, and coherent V34-V37 responsibilities. |
 | Interface contract catalog | Gate 2 | `packages/btd/src/interface-contract-catalog.ts`, `packages/btd/__tests__/interface-contract-catalog.test.ts`, `.bitcode/v33-interface-contract-catalog.json`, `check:v33-gate2` | drafted | Active and deferred interface surfaces have package-owned rows. |
 | MCP API contracts | Gate 3 | `packages/btd/src/mcp-tool-contract.ts`, `packages/btd/__tests__/mcp-tool-contract.test.ts`, `packages/executions-mcp/src/mcp-server/src/tools/pipeline-tools.ts`, `packages/executions-mcp/src/mcp-server/src/__tests__/unit/mcp-tool-contract.test.ts`, `.bitcode/v33-mcp-api-tool-contracts.json`, `check:v33-gate3` | drafted | MCP tool discovery, schemas, auth, denied states, and proof roots are package-derived. |
-| ChatGPT App contracts | Gate 4 | planned ChatGPT App action contract tests and examples | pending | ChatGPT App actions match package-owned Read, Need, Finding Fits, preview, fee, settlement, and delivery contracts. |
+| ChatGPT App contracts | Gate 4 | `packages/btd/src/chatgpt-app-action-contract.ts`, `packages/btd/__tests__/chatgpt-app-action-contract.test.ts`, `packages/chatgptapp/src/tools.ts`, `packages/chatgptapp/src/__tests__/chatgpt-action-contract.test.ts`, `.bitcode/v33-chatgpt-app-action-contracts.json`, `check:v33-gate4` | drafted | ChatGPT App actions match package-owned Read, Need, Finding Fits, preview, fee, settlement, and delivery contracts. |
 | Interface authorization policy | Gate 5 | planned `InterfaceAuthorizationPolicy` fixtures and tests | pending | Interface auth and license denials fail closed with repair posture. |
 | Read license and AssetPack rights contracts | Gate 6 | planned `ReadLicenseInterfaceContract` and `AssetPackRightsInterfaceContract` tests | pending | Source-safe preview, paid settlement, BTD rights, and delivery contracts are consistent across interfaces. |
 | API schema compatibility | Gate 7 | planned `APISchemaCompatibilityMatrix` artifact and tests | pending | Schemas, examples, compatibility status, and validation commands are source-safe and versionless. |
@@ -100,6 +100,19 @@ No `_legacy/` source is active source truth.
 | Tests fail closed | BTD and MCP tests cover contract discovery, proof roots, denied states, invalid schema arguments, and protected-source invisibility | drafted |
 | Workflow and spec-family wiring exists | `check:v33-gate3`, `.github/workflows/bitcode-gate-quality.yml`, and `packages/protocol/src/canonical/v21-specifying.js` include the Gate 3 contract | drafted |
 
+## Gate 4 Parity
+
+| Requirement | Source evidence | Current V33 judgment |
+| --- | --- | --- |
+| Package-owned ChatGPT action contract builder exists | `packages/btd/src/chatgpt-app-action-contract.ts` exports `buildBtdChatGptAppActionContractRegistry`, `BTD_CHATGPT_APP_ACTION_CONTRACT_IDS`, and `renderBtdChatGptAppSourceSafeResponse` | drafted |
+| Reading action sequence is canonical | `bitcode_request_read`, `bitcode_review_read_need`, `bitcode_request_finding_fits`, `bitcode_review_asset_pack_preview`, `bitcode_quote_asset_pack_fee`, `bitcode_settle_asset_pack`, and `bitcode_deliver_asset_pack` are required action ids | drafted |
+| Schemas and auth are bound | every `ChatGptAppActionContract` carries input/output schema ids, `interface.authorization.chatgpt-reading-action`, `chatgpt.reading.invoke`, and source-safe renderer id | drafted |
+| Denied states are explicit and repairable | `SCHEMA_VALIDATION_FAILED`, `READ_NEED_REQUIRED`, `FINDING_FITS_REQUIRED`, `ASSET_PACK_PREVIEW_REQUIRED`, `FEE_QUOTE_REQUIRED`, `SETTLEMENT_REQUIRED`, `READ_LICENSE_REQUIRED`, `ORGANIZATION_AUTHORITY_REQUIRED`, and `CONFIRMATION_REQUIRED` are readable repair states | drafted |
+| ChatGPT App consumes package contract | `packages/chatgptapp/src/tools.ts` uses `buildBtdChatGptAppActionContractRegistry`, derives tool schemas, and returns `renderBtdChatGptAppSourceSafeResponse` metadata | drafted |
+| Generated artifact is source-safe and deterministic | `.bitcode/v33-chatgpt-app-action-contracts.json` is produced by `generate:v33-chatgpt-app-action-contracts` and checked by `check:v33-chatgpt-app-action-contracts` | drafted |
+| Tests fail closed | BTD and ChatGPT tests cover action registration, schemas, proof roots, accepted source-safe render output, denied repair actions, and secret-shaped source text rejection | drafted |
+| Workflow and spec-family wiring exists | `check:v33-gate4`, `.github/workflows/bitcode-gate-quality.yml`, and `packages/protocol/src/canonical/v21-specifying.js` include the Gate 4 contract | drafted |
+
 ## Gate 1 Parity
 
 | Requirement | Source evidence | Current V33 judgment |

BITCODE_SPEC_V33_PARITY_MATRIX.md

@@ -5,7 +5,7 @@
 - Current active canonical pointer: `BITCODE_SPEC.txt` -> `V32`
 - Current active canon: `BITCODE_SPEC_V32.md`
 - Current draft target: `BITCODE_SPEC_V33.md`
-- Current working gate: V33 Gate 3 MCP API Tool And Registry Contracts, which makes MCP tool discovery package-derived and source-safe, binds `bitcode://pipelines/asset-pack/create` to `McpToolContract`, proves schema/auth denial states such as `SCHEMA_VALIDATION_FAILED` and `PROVIDER_BINDING_REQUIRED`, and generates `.bitcode/v33-mcp-api-tool-contracts.json`.
+- Current working gate: V33 Gate 4 ChatGPT App Action And Tool Contracts, which makes ChatGPT App Reading actions package-derived and source-safe, binds Read, Need, Finding Fits, preview, fee, settlement, and delivery action ids to `ChatGptAppActionContract`, proves denial repair states such as `READ_LICENSE_REQUIRED` and `SETTLEMENT_REQUIRED`, and generates `.bitcode/v33-chatgpt-app-action-contracts.json`.
 - Purpose: concise running index of Bitcode/ENGI specification history, current work, and planned work.
 
 This roadmap is not an active system specification.

SPECIFICATIONS_ROADMAP.md

@@ -107,6 +107,9 @@
     "generate:v33-mcp-api-tool-contracts": "node scripts/generate-v33-mcp-api-tool-contracts.mjs",
     "check:v33-mcp-api-tool-contracts": "node scripts/generate-v33-mcp-api-tool-contracts.mjs --check",
     "check:v33-gate3": "node scripts/check-v33-gate3-mcp-api-tool-contracts.mjs",
+    "generate:v33-chatgpt-app-action-contracts": "node scripts/generate-v33-chatgpt-app-action-contracts.mjs",
+    "check:v33-chatgpt-app-action-contracts": "node scripts/generate-v33-chatgpt-app-action-contracts.mjs --check",
+    "check:v33-gate4": "node scripts/check-v33-gate4-chatgpt-app-action-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",