V36 Gate 9: Prove local staging Exchange rehearsal

Add package-owned ExchangeRehearsal canon, deterministic source-safe artifact generation, Gate 9 checker, protocol tests, workflow wiring, and V36 spec/docs parity for local and staging-testnet Exchange rehearsal coverage.

Validation: pnpm run check:v36-exchange-rehearsal; pnpm run check:v36-gate1..check:v36-gate9; pnpm --filter @bitcode/protocol typecheck; pnpm --filter @bitcode/protocol test; V36 spec family and canon posture checks; git diff --check.

Author: geraldarthurdavis

.bitcode/v36-exchange-rehearsal.json

@@ -94,6 +94,9 @@ jobs:
               if [ -f scripts/check-v36-gate8-exchange-ux-proof.mjs ]; then
                 node scripts/check-v36-gate8-exchange-ux-proof.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v36-gate9-exchange-rehearsal.mjs ]; then
+                node scripts/check-v36-gate9-exchange-rehearsal.mjs --skip-branch-check
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

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

@@ -222,6 +222,9 @@ jobs:
               if [ -f scripts/check-v36-gate8-exchange-ux-proof.mjs ]; then
                 node scripts/check-v36-gate8-exchange-ux-proof.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v36-gate9-exchange-rehearsal.mjs ]; then
+                node scripts/check-v36-gate9-exchange-rehearsal.mjs --skip-branch-check
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
@@ -284,6 +287,7 @@ jobs:
           pnpm --dir packages/protocol exec node --test --test-force-exit test/v36-exchange-settlement-reconciliation.test.js
           pnpm --dir packages/protocol exec node --test --test-force-exit test/v36-exchange-dispute-repair-revenue-route.test.js
           pnpm --dir packages/protocol exec node --test --test-force-exit test/v36-exchange-ux-proof.test.js
+          pnpm --dir packages/protocol exec node --test --test-force-exit test/v36-exchange-rehearsal.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

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

@@ -225,6 +225,25 @@ protected source, unpaid AssetPack source, wallet private material, provider
 tokens, protected prompts, protected model responses, buyer private repository
 payloads, or secret values.
 
+## V36 Gate 9 ExchangeRehearsal canon
+
+Gate 9 implements `ExchangeRehearsal` as the package-owned contract binding
+local and staging-testnet Exchange rehearsals to generated proof.
+
+`ExchangeRehearsal` proves that local and staging-testnet rehearsals exercise list, bid, ask, cancel, accept, settle, repair, and history flows.
+It proves that rehearsal logs/screenshots are source-safe.
+It also proves that ledger/database synchronization and value-bearing mainnet blocking are visible.
+
+Gate 9 emits `.bitcode/v36-exchange-rehearsal.json` with
+`source-safe-exchange-rehearsal-metadata`.
+The artifact may expose rehearsal ids, lane ids, flow ids, event ids, proof
+roots, ledger/database synchronization checks, validation commands, redacted
+log/screenshot roots, source evidence, and summary counts; it must not expose
+protected source, unpaid AssetPack source, wallet private material, private
+payment credentials, object-storage private bytes, provider tokens, protected
+prompts, protected model responses, buyer private repository payloads, or secret
+values.
+
 ## Canonical Bitcode executive summary
 
 Bitcode measures technical knowledge, finds deposits that fit reviewed Reads, synthesizes source-bearing AssetPacks, and settles read rights in BTC with BTD range and rights receipts.

BITCODE_SPEC_V36.md

@@ -161,9 +161,12 @@ Gate 9 proves Exchange locally and in staging-testnet.
 
 Closure acceptance:
 
+- `ExchangeRehearsal` is package-owned by `@bitcode/protocol`;
 - local and staging-testnet rehearsals exercise list, bid, ask, cancel, accept, settle, repair, and history flows;
 - rehearsal logs/screenshots are source-safe;
-- ledger/database synchronization and value-bearing mainnet blocking are visible.
+- ledger/database synchronization and value-bearing mainnet blocking are visible;
+- `.bitcode/v36-exchange-rehearsal.json` is generated from the package-owned `ExchangeRehearsal` builder with `source-safe-exchange-rehearsal-metadata`;
+- `pnpm run check:v36-gate9` validates package source, artifact freshness, package tests, docs, workflow wiring, local lane flow coverage, staging-testnet lane flow coverage, source-safe logs/screenshots, ledger/database synchronization checks, proof roots, and blocked value-bearing mainnet posture.
 
 ### Gate 10: V36 Promotion Readiness
 

BITCODE_SPEC_V36_DELTA.md

@@ -169,6 +169,22 @@ not protected source, unpaid AssetPack source, wallet private material, provider
 tokens, protected prompts, protected model responses, buyer private repository
 payloads, or secret values.
 
+## Gate 9 closure notes
+
+Gate 9 closes when `ExchangeRehearsal` is package-owned and generated through
+`.bitcode/v36-exchange-rehearsal.json`.
+The generated artifact carries `source-safe-exchange-rehearsal-metadata`.
+`ExchangeRehearsal` proves that local and staging-testnet rehearsals exercise list, bid, ask, cancel, accept, settle, repair, and history flows.
+It proves that rehearsal logs/screenshots are source-safe.
+It also proves that ledger/database synchronization and value-bearing mainnet blocking are visible.
+Exchange rehearsal artifacts remain source-safe: they expose rehearsal ids,
+lane ids, flow ids, event ids, proof roots, ledger/database synchronization
+checks, validation commands, redacted log/screenshot roots, source evidence,
+and summary counts, not protected source, unpaid AssetPack source, wallet
+private material, private payment credentials, object-storage private bytes,
+provider tokens, protected prompts, protected model responses, buyer private
+repository payloads, or secret values.
+
 ## Accepted boundaries
 
 - V36 owns deeper Exchange.

BITCODE_SPEC_V36_NOTES.md

@@ -61,7 +61,7 @@ No `_legacy/` source is active source truth.
 | Settlement reconciliation | Gate 6 | `ExchangeSettlementReceipt`, `.bitcode/v36-exchange-settlement-reconciliation.json`, observers, repair tests, and `check:v36-gate6` | closed | Payment observation, finality state, rights-transfer receipt, ledger root, database projection root, object storage root, delivery state, repair id, observer jobs, and repair jobs reconcile. |
 | Dispute repair revenue routes | Gate 7 | `ExchangeDisputeRepairCase`, `ExchangeRevenueRoute`, `.bitcode/v36-exchange-dispute-repair-revenue-route.json`, tests, and `check:v36-gate7` | closed | Disputes, repairs, revenue routes, conservation proofs, runbooks, and escalation paths exist. |
 | Exchange UX and Terminal integration | Gate 8 | `ExchangeUxProof`, `/exchange`, Terminal handoff, public docs, telemetry dashboards, `.bitcode/v36-exchange-ux-proof.json`, tests, and `check:v36-gate8` | closed | Master-detail UX, filters, order history, rights-transfer review, pricing quote, settlement state, repair state, Terminal navigation, collapsed status, and source-safe expanded detail are validated. |
-| Local staging rehearsal | Gate 9 | `.bitcode/v36-exchange-rehearsal.json`, local/staging logs, proof roots, and `check:v36-gate9` | draft-required | Local and staging-testnet list/bid/ask/cancel/accept/settle/repair/history flows are rehearsed. |
+| Local staging rehearsal | Gate 9 | `.bitcode/v36-exchange-rehearsal.json`, local/staging logs, proof roots, and `check:v36-gate9` | closed | Local and staging-testnet list/bid/ask/cancel/accept/settle/repair/history flows are rehearsed. |
 | Promotion readiness | Gate 10 | `.bitcode/v36-promotion-readiness-report.json`, promotion workflow, generated proof support, and `check:v36-gate10` | draft-required | V36 can promote only after all Exchange gates pass and generated canon remains source-safe. |
 
 ## V36 implementation checklist
@@ -185,6 +185,17 @@ No `_legacy/` source is active source truth.
 | Telemetry binding is source-safe | `source-safe-exchange-ux-proof-metadata`; Exchange telemetry dashboards remain source-safe and proof-rooted | closed |
 | Workflow, package, and UI tests are wired | `packages/protocol/test/v36-exchange-ux-proof.test.js`, `uapi/tests/exchangePageClient.test.tsx`, `uapi/tests/exchangeTerminalHandoff.test.ts`, `scripts/check-v36-gate8-exchange-ux-proof.mjs`, `.github/workflows/bitcode-gate-quality.yml` | closed |
 
+## Gate 9 Parity
+
+| Requirement | Source evidence | Current V36 judgment |
+| --- | --- | --- |
+| `ExchangeRehearsal` is package-owned | `packages/protocol/src/canonical/exchange-rehearsal.js`, `packages/protocol/src/index.js`, `packages/protocol/src/index.d.ts` | closed |
+| Generated Exchange rehearsal artifact exists | `.bitcode/v36-exchange-rehearsal.json`, `scripts/generate-v36-exchange-rehearsal.mjs`, `pnpm run check:v36-exchange-rehearsal` | closed |
+| Local and staging-testnet flows are complete | local and staging-testnet rehearsals exercise list, bid, ask, cancel, accept, settle, repair, and history flows | closed |
+| Rehearsal evidence is source-safe | rehearsal logs/screenshots are source-safe through redacted screenshot/log roots and `source-safe-exchange-rehearsal-metadata` | closed |
+| Ledger/database synchronization is visible | ledger/database synchronization and value-bearing mainnet blocking are visible through sync checks, projection roots, and blocked mainnet row posture | closed |
+| Workflow and package tests are wired | `packages/protocol/test/v36-exchange-rehearsal.test.js`, `scripts/check-v36-gate9-exchange-rehearsal.mjs`, `.github/workflows/bitcode-gate-quality.yml`, `.github/workflows/bitcode-canon-quality.yml` | closed |
+
 ## V36 accepted boundaries
 
 - V36 owns deeper Exchange.

BITCODE_SPEC_V36_PARITY_MATRIX.md

@@ -63,6 +63,13 @@ Terminal can hand off to Exchange without losing transaction context.
 collapsed UI gives readable status and expanded UI exposes source-safe detail.
 Exchange telemetry dashboards remain source-safe and proof-rooted.
 The source-safe verdict is `source-safe-exchange-ux-proof-metadata`.
+V36 Gate 9 anchors Exchange rehearsal through package-owned
+`ExchangeRehearsal` and the source-safe generated artifact
+`.bitcode/v36-exchange-rehearsal.json`.
+`ExchangeRehearsal` proves that local and staging-testnet rehearsals exercise list, bid, ask, cancel, accept, settle, repair, and history flows.
+It proves that rehearsal logs/screenshots are source-safe.
+It also proves that ledger/database synchronization and value-bearing mainnet blocking are visible.
+The source-safe verdict is `source-safe-exchange-rehearsal-metadata`.
 Promoted V35 closure owns telemetry and documentation depth over promoted V34:
 internal codebase docs, public `/docs`, telemetry taxonomy, dashboards, alert
 runbooks, incident response, operator escalation, documentation QA, developer

README.md

@@ -5,7 +5,7 @@
 - Current active canonical pointer: `BITCODE_SPEC.txt` -> `V35`
 - Current active canon: `BITCODE_SPEC_V35.md`
 - Current draft target: `BITCODE_SPEC_V36.md`
-- Current working gate: V36 Gate 9 Local Staging Exchange Rehearsal And Proof Coverage, following V36 Gate 8 Exchange UX and Terminal navigation closure.
+- Current working gate: V36 Gate 10 Promotion Readiness, following V36 Gate 9 local/staging Exchange rehearsal closure.
 - Latest closed version: V35 Telemetry And Documentation Depth, which promoted documentation surfaces, telemetry taxonomy, public docs, dashboards, alert runbooks, incident response, operator escalation, documentation QA, onboarding, local/staging telemetry rehearsal, and V35 promotion readiness.
 - Recent V35 closure anchor: V35 Gate 10 Promotion Readiness generated V35 proof support, promoted `BITCODE_SPEC.txt` to `V35`, prepared V35 active / V36 draft runtime posture, and closed telemetry/documentation-depth canon.
 - 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`.
@@ -35,6 +35,7 @@
 - V36 Gate 6 closure anchor: Exchange depth now owns package-backed `ExchangeSettlementReceipt` source, deterministic `.bitcode/v36-exchange-settlement-reconciliation.json`, `source-safe-exchange-settlement-reconciliation-metadata`, payment observation, finality state, rights transfer receipt, ledger root, database projection root, object storage root, delivery state, repair id, observer jobs, repair jobs, proof roots, event ids, package tests, workflow wiring, and `check:v36-gate6`; observers and repair jobs reconcile database projections to ledger truth, and settlement finality and delivery are auditable.
 - V36 Gate 7 closure anchor: Exchange depth now owns package-backed `ExchangeDisputeRepairCase` and `ExchangeRevenueRoute` source, deterministic `.bitcode/v36-exchange-dispute-repair-revenue-route.json`, `source-safe-exchange-dispute-repair-revenue-route-metadata`, stale owner, cancelled order replay, underpayment, overpayment, projection drift, source leakage, delivery mismatch, depositor, reader, treasury, fee, BTC route, BTD right route, conservation proof, source-safe proof-rooted runbooks, repair commands, verification commands, escalation paths, proof roots, event ids, package tests, workflow wiring, and `check:v36-gate7`.
 - V36 Gate 8 closure anchor: Exchange depth now owns package-backed `ExchangeUxProof` source, deterministic `.bitcode/v36-exchange-ux-proof.json`, `source-safe-exchange-ux-proof-metadata`, market-wide master-detail, filters, order history, rights-transfer review, pricing quote, settlement state, repair state, Terminal context handoff, collapsed readable status, expanded source-safe detail, source-safe proof-rooted telemetry dashboards, route preservation tests, package tests, workflow wiring, and `check:v36-gate8`.
+- V36 Gate 9 closure anchor: Exchange depth now owns package-backed `ExchangeRehearsal` source, deterministic `.bitcode/v36-exchange-rehearsal.json`, `source-safe-exchange-rehearsal-metadata`, local and staging-testnet rehearsals exercise list, bid, ask, cancel, accept, settle, repair, and history flows, rehearsal logs/screenshots are source-safe, ledger/database synchronization and value-bearing mainnet blocking are visible, package tests, workflow wiring, and `check:v36-gate9`.
 - 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

@@ -206,6 +206,9 @@
     "generate:v36-exchange-ux-proof": "node scripts/generate-v36-exchange-ux-proof.mjs",
     "check:v36-exchange-ux-proof": "node scripts/generate-v36-exchange-ux-proof.mjs --check",
     "check:v36-gate8": "node scripts/check-v36-gate8-exchange-ux-proof.mjs",
+    "generate:v36-exchange-rehearsal": "node scripts/generate-v36-exchange-rehearsal.mjs",
+    "check:v36-exchange-rehearsal": "node scripts/generate-v36-exchange-rehearsal.mjs --check",
+    "check:v36-gate9": "node scripts/check-v36-gate9-exchange-rehearsal.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",