Merge pull request #107 from engineeredsoftware/v36/gate-8-exchange-ux-terminal-integration

V36 Gate 8: Exchange UX And Terminal Navigation Integration

Author: geraldarthurdavis

.bitcode/v36-exchange-ux-proof.json

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

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

@@ -219,6 +219,9 @@ jobs:
               if [ -f scripts/check-v36-gate7-exchange-dispute-repair-revenue-route.mjs ]; then
                 node scripts/check-v36-gate7-exchange-dispute-repair-revenue-route.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v36-gate8-exchange-ux-proof.mjs ]; then
+                node scripts/check-v36-gate8-exchange-ux-proof.mjs --skip-branch-check
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
@@ -242,7 +245,7 @@ jobs:
 
       - name: Test gate packages
         run: |
-          pnpm --filter @bitcode/btd test
+          pnpm --filter @bitcode/btd exec jest --config jest.config.cjs --runInBand --forceExit
           pnpm --filter @bitcode/btd test -- --runTestsByPath __tests__/btc-fee-operation.test.ts
           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
@@ -280,6 +283,7 @@ jobs:
           pnpm --dir packages/protocol exec node --test --test-force-exit test/v36-exchange-pricing-quote.test.js
           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 --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
@@ -311,6 +315,8 @@ jobs:
             tests/terminalDepositReadWorkbench.test.ts \
             tests/terminalTransactionQuery.test.ts \
             tests/terminalTransactionReadModel.test.ts \
+            tests/exchangePageClient.test.tsx \
+            tests/exchangeTerminalHandoff.test.ts \
             tests/terminalProtocolProjection.test.ts \
             tests/terminalInterfaceIntegrationRegression.test.ts \
             tests/terminalWalletBtcOperation.test.ts \

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

@@ -205,6 +205,26 @@ wallet private material, provider tokens, protected prompts, protected model
 responses, private payment credentials, private buyer repository payloads,
 object-storage private bytes, raw disputed source bytes, or secret values.
 
+## V36 Gate 8 ExchangeUxProof canon
+
+Gate 8 implements `ExchangeUxProof` as the package-owned contract binding the
+Exchange route, Terminal handoff, and source-safe review surfaces to generated
+proof.
+
+`ExchangeUxProof` covers market-wide master-detail, filters, order history, rights-transfer review, pricing quote, settlement state, and repair state.
+It proves that Terminal can hand off to Exchange without losing transaction context.
+It also proves that collapsed UI gives readable status and expanded UI exposes source-safe detail.
+Exchange telemetry dashboards remain source-safe and proof-rooted.
+
+Gate 8 emits `.bitcode/v36-exchange-ux-proof.json` with
+`source-safe-exchange-ux-proof-metadata`.
+The artifact may expose route ids, transaction ids, filter ids, order state,
+rights-transfer preview state, quote roots, settlement state, repair state,
+proof roots, event ids, and source-safe UI detail metadata; it must not expose
+protected source, unpaid AssetPack source, wallet private material, 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

@@ -151,6 +151,9 @@ Closure acceptance:
 - `/exchange` exposes market-wide master-detail, filters, order history, rights-transfer review, pricing quote, settlement state, and repair state;
 - 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.
+- `.bitcode/v36-exchange-ux-proof.json` is generated from the package-owned `ExchangeUxProof` builder with `source-safe-exchange-ux-proof-metadata`;
+- `pnpm run check:v36-gate8` validates package source, artifact freshness, package tests, route handoff tests, docs, workflow wiring, master-detail UX, filters, order history, rights-transfer review, pricing quote, settlement state, repair state, Terminal handoff, collapsed/expanded disclosure, telemetry binding, proof roots, and event ids.
 
 ### Gate 9: Local Staging Exchange Rehearsal And Proof Coverage
 

BITCODE_SPEC_V36_DELTA.md

@@ -153,6 +153,22 @@ principal ids, status, commands, routes, and proof posture, not protected source
 unpaid AssetPack source, private payment credentials, or wallet private
 material.
 
+## Gate 8 closure notes
+
+Gate 8 closes when `ExchangeUxProof` is package-owned and generated through
+`.bitcode/v36-exchange-ux-proof.json`.
+The generated artifact carries `source-safe-exchange-ux-proof-metadata`.
+`ExchangeUxProof` covers market-wide master-detail, filters, order history, rights-transfer review, pricing quote, settlement state, and repair state.
+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.
+Exchange UX artifacts remain source-safe: they expose route state, filter state,
+transaction identity, order history, rights-transfer preview, pricing quote,
+settlement state, repair state, proof roots, event ids, and redaction posture,
+not protected source, unpaid AssetPack source, wallet private material, 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

@@ -60,7 +60,7 @@ No `_legacy/` source is active source truth.
 | Pricing quote | Gate 5 | `ExchangePricingQuote`, `.bitcode/v36-pricing-liquidity-fee-quote.json`, package source, tests, and `check:v36-gate5` | closed | BTC price, measurement weight, measurement volume, liquidity band, wrapper analysis, treasury/depositor/reader routes, quote roots, and fail-closed payment/network posture are deterministic. |
 | 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 | `/exchange`, Terminal handoff, public docs, telemetry dashboards, `.bitcode/v36-exchange-ux-proof.json`, and `check:v36-gate8` | draft-required | Master-detail UX, source-safe expanded detail, order history, and Terminal navigation are validated. |
+| 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. |
 | 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. |
 
@@ -173,6 +173,18 @@ No `_legacy/` source is active source truth.
 | Dispute and revenue payloads are source-safe | `source-safe-exchange-dispute-repair-revenue-route-metadata`; protected source, unpaid AssetPack source, private wallet material, private payment credentials, raw disputed source bytes, provider tokens, protected prompts, protected model responses, private buyer payloads, object-storage private bytes, and secret values are forbidden | closed |
 | Workflow and package tests are wired | `packages/protocol/test/v36-exchange-dispute-repair-revenue-route.test.js`, `scripts/check-v36-gate7-exchange-dispute-repair-revenue-route.mjs`, `.github/workflows/bitcode-gate-quality.yml` | closed |
 
+## Gate 8 Parity
+
+| Requirement | Source evidence | Current V36 judgment |
+| --- | --- | --- |
+| `ExchangeUxProof` is package-owned | `packages/protocol/src/canonical/exchange-ux-proof.js`, `packages/protocol/src/index.js`, `packages/protocol/src/index.d.ts` | closed |
+| Generated Exchange UX artifact exists | `.bitcode/v36-exchange-ux-proof.json`, `scripts/generate-v36-exchange-ux-proof.mjs`, `pnpm run check:v36-exchange-ux-proof` | closed |
+| Exchange route exposes market review | `/exchange` exposes market-wide master-detail, filters, order history, rights-transfer review, pricing quote, settlement state, and repair state | closed |
+| Terminal handoff preserves context | `buildExchangeHref`, `TerminalTransactionDetailHero`, and `uapi/tests/exchangeTerminalHandoff.test.ts`; Terminal can hand off to Exchange without losing transaction context | closed |
+| Collapsed and expanded disclosure is source-safe | collapsed UI gives readable status and expanded UI exposes source-safe detail | closed |
+| 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 |
+
 ## V36 accepted boundaries
 
 - V36 owns deeper Exchange.

BITCODE_SPEC_V36_PARITY_MATRIX.md

@@ -55,6 +55,14 @@ generated artifact `.bitcode/v36-exchange-dispute-repair-revenue-route.json`.
 `ExchangeRevenueRoute` covers depositor, reader, treasury, fee, BTC route, BTD right route, and conservation proof.
 The source-safe verdict is
 `source-safe-exchange-dispute-repair-revenue-route-metadata`; runbooks and repair commands are source-safe and proof-rooted.
+V36 Gate 8 anchors Exchange route usability through package-owned
+`ExchangeUxProof` and the source-safe generated artifact
+`.bitcode/v36-exchange-ux-proof.json`.
+`ExchangeUxProof` covers market-wide master-detail, filters, order history, rights-transfer review, pricing quote, settlement state, and repair state.
+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`.
 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 8 Exchange UX And Terminal Navigation Integration, following V36 Gate 7 dispute repair revenue route closure.
+- Current working gate: V36 Gate 9 Local Staging Exchange Rehearsal And Proof Coverage, following V36 Gate 8 Exchange UX and Terminal navigation 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`.
@@ -34,6 +34,7 @@
 - V36 Gate 5 closure anchor: Exchange depth now owns package-backed `ExchangePricingQuote` source, deterministic `.bitcode/v36-pricing-liquidity-fee-quote.json`, `source-safe-exchange-pricing-quote-metadata`, BTC amount, measurement weight, measurement volume, liquidity band, wrapper analysis, treasury route, depositor route, reader route, quote root, proof roots, event ids, ledger/database projection refs, package tests, workflow wiring, and `check:v36-gate5`; wrapper analysis cannot make BTD range cells fungible chain-of-record assets, and underpayment, overpayment, stale quote, or unsupported network posture fails closed.
 - 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`.
 - 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

@@ -203,6 +203,9 @@
     "generate:v36-exchange-dispute-repair-revenue-route": "node scripts/generate-v36-exchange-dispute-repair-revenue-route.mjs",
     "check:v36-exchange-dispute-repair-revenue-route": "node scripts/generate-v36-exchange-dispute-repair-revenue-route.mjs --check",
     "check:v36-gate7": "node scripts/check-v36-gate7-exchange-dispute-repair-revenue-route.mjs",
+    "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",
     "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",