Merge pull request #106 from engineeredsoftware/v36/gate-7-dispute-repair-revenue-route

V36 Gate 7: Exchange Dispute Repair Revenue Routes

Author: geraldarthurdavis

.bitcode/v36-exchange-dispute-repair-revenue-route.json

@@ -88,6 +88,9 @@ jobs:
               if [ -f scripts/check-v36-gate6-exchange-settlement-reconciliation.mjs ]; then
                 node scripts/check-v36-gate6-exchange-settlement-reconciliation.mjs --skip-branch-check
               fi
+              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
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

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

@@ -216,6 +216,9 @@ jobs:
               if [ -f scripts/check-v36-gate6-exchange-settlement-reconciliation.mjs ]; then
                 node scripts/check-v36-gate6-exchange-settlement-reconciliation.mjs --skip-branch-check
               fi
+              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
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
@@ -276,6 +279,7 @@ jobs:
           pnpm --dir packages/protocol exec node --test --test-force-exit test/v36-exchange-rights-transfer-review.test.js
           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 --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

@@ -177,6 +177,34 @@ settlement finality and delivery are auditable.
 Delivery stays blocked while finality, rights-transfer receipt, database
 projection, or object-storage projection is missing, stale, or drifted.
 
+## V36 Gate 7 ExchangeDisputeRepairCase and ExchangeRevenueRoute canon
+
+Gate 7 implements `ExchangeDisputeRepairCase` and `ExchangeRevenueRoute` as the
+package-owned operational contracts for Exchange failures, repairs, operator
+runbooks, and revenue conservation.
+`ExchangeDisputeRepairCase` covers stale owner, cancelled order replay, underpayment, overpayment, projection drift, source leakage, and delivery mismatch.
+Each case binds affected order identity, affected settlement receipt identity,
+affected projection roots, source-safe repair command, verification command,
+proof-rooted runbook, escalation path, proof roots, and event ids.
+
+`ExchangeRevenueRoute` covers depositor, reader, treasury, fee, BTC route, BTD right route, and conservation proof.
+Each route binds public principal ids, BTC debit/credit amounts, BTD range
+identity, rights-transfer receipt identity, source-to-shares proof root, and a
+conservation proof that reader debit equals depositor credit plus treasury
+credit plus fee credit plus reader refund.
+
+Gate 7 emits `.bitcode/v36-exchange-dispute-repair-revenue-route.json` with
+`source-safe-exchange-dispute-repair-revenue-route-metadata`.
+runbooks and repair commands are source-safe and proof-rooted.
+The artifact may expose dispute identities, incident classes, affected order and
+settlement ids, projection roots, source-safe repair commands, verification
+commands, runbook ids, escalation status, revenue accounts, BTC amounts, BTD
+right-route metadata, source-to-shares roots, conservation proofs, proof roots,
+and event ids; it must not expose protected source, unpaid AssetPack source,
+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.
+
 ## 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

@@ -139,6 +139,8 @@ Closure acceptance:
 - `ExchangeDisputeRepairCase` covers stale owner, cancelled order replay, underpayment, overpayment, projection drift, source leakage, and delivery mismatch;
 - `ExchangeRevenueRoute` covers depositor, reader, treasury, fee, BTC route, BTD right route, and conservation proof;
 - runbooks and repair commands are source-safe and proof-rooted.
+- `.bitcode/v36-exchange-dispute-repair-revenue-route.json` is generated from the package-owned builder with `source-safe-exchange-dispute-repair-revenue-route-metadata`;
+- `pnpm run check:v36-gate7` validates package source, artifact freshness, package tests, docs, workflow wiring, dispute coverage, revenue route coverage, repair commands, verification commands, proof-rooted runbooks, escalation paths, conservation proofs, source-safety, proof roots, and event ids.
 
 ### Gate 8: Exchange UX And Terminal Navigation Integration
 

BITCODE_SPEC_V36_DELTA.md

@@ -138,6 +138,21 @@ Delivery remains blocked until paid finality, rights-transfer receipt,
 projection synchronization, object-storage projection, and delivery state are
 all source-safe and proof-rooted.
 
+## Gate 7 closure notes
+
+Gate 7 closes when `ExchangeDisputeRepairCase` and `ExchangeRevenueRoute` are
+package-owned and generated through
+`.bitcode/v36-exchange-dispute-repair-revenue-route.json`.
+The generated artifact carries
+`source-safe-exchange-dispute-repair-revenue-route-metadata`.
+`ExchangeDisputeRepairCase` covers stale owner, cancelled order replay, underpayment, overpayment, projection drift, source leakage, and delivery mismatch.
+`ExchangeRevenueRoute` covers depositor, reader, treasury, fee, BTC route, BTD right route, and conservation proof.
+runbooks and repair commands are source-safe and proof-rooted.
+Dispute and revenue artifacts remain source-safe: they expose roots, public
+principal ids, status, commands, routes, and proof posture, not protected source,
+unpaid AssetPack source, private payment credentials, or wallet private
+material.
+
 ## Accepted boundaries
 
 - V36 owns deeper Exchange.

BITCODE_SPEC_V36_NOTES.md

@@ -59,7 +59,7 @@ No `_legacy/` source is active source truth.
 | Rights-transfer review | Gate 4 | `ExchangeRightsTransferPreview`, `.bitcode/v36-exchange-rights-transfer-review.json`, package source, tests, and `check:v36-gate4` | closed | BTD range identity, ownership, buyer, rights scope, disclosure boundary, settlement unlock, owner-read, licensed-read, and blocked transfer states are source-safe. |
 | 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` | draft-required | Disputes, repairs, revenue routes, conservation proofs, runbooks, and escalation paths exist. |
+| 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. |
 | 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. |
@@ -159,6 +159,20 @@ No `_legacy/` source is active source truth.
 | Settlement payloads are source-safe | `source-safe-exchange-settlement-reconciliation-metadata`; protected source, unpaid AssetPack source, private wallet material, provider tokens, protected prompts, protected model responses, private payment credentials, object-storage private bytes, private buyer payloads, and secret values are forbidden | closed |
 | Workflow and package tests are wired | `packages/protocol/test/v36-exchange-settlement-reconciliation.test.js`, `scripts/check-v36-gate6-exchange-settlement-reconciliation.mjs`, `.github/workflows/bitcode-gate-quality.yml` | closed |
 
+## Gate 7 Parity
+
+| Requirement | Source evidence | Current V36 judgment |
+| --- | --- | --- |
+| `ExchangeDisputeRepairCase` and `ExchangeRevenueRoute` are package-owned | `packages/protocol/src/canonical/exchange-dispute-repair-revenue-route.js`, `packages/protocol/src/index.js`, `packages/protocol/src/index.d.ts` | closed |
+| Generated dispute and revenue artifact exists | `.bitcode/v36-exchange-dispute-repair-revenue-route.json`, `scripts/generate-v36-exchange-dispute-repair-revenue-route.mjs`, `pnpm run check:v36-exchange-dispute-repair-revenue-route` | closed |
+| Required dispute classes are covered | stale owner, cancelled order replay, underpayment, overpayment, projection drift, source leakage, and delivery mismatch | closed |
+| Required revenue route fields are covered | depositor, reader, treasury, fee, BTC route, BTD right route, and conservation proof | closed |
+| Repair operations are source-safe | runbooks and repair commands are source-safe and proof-rooted | closed |
+| Escalation and verification are explicit | repair commands, verification commands, escalation paths, proof roots, and event ids are present for every dispute case | closed |
+| Revenue conservation is explicit | every revenue route proves BTC debits equal credits while BTD rights and source-to-shares roots remain conserved | closed |
+| 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 |
+
 ## V36 accepted boundaries
 
 - V36 owns deeper Exchange.

BITCODE_SPEC_V36_PARITY_MATRIX.md

@@ -48,6 +48,13 @@ and the source-safe generated artifact
 The receipt binds payment observation, finality state, rights transfer receipt, ledger root, database projection root, object storage root, delivery state, and repair id.
 The source-safe verdict is
 `source-safe-exchange-settlement-reconciliation-metadata`; observers and repair jobs reconcile database projections to ledger truth, and settlement finality and delivery are auditable.
+V36 Gate 7 anchors dispute repair and revenue routing through package-owned
+`ExchangeDisputeRepairCase`, `ExchangeRevenueRoute`, and the source-safe
+generated artifact `.bitcode/v36-exchange-dispute-repair-revenue-route.json`.
+`ExchangeDisputeRepairCase` covers stale owner, cancelled order replay, underpayment, overpayment, projection drift, source leakage, and delivery mismatch.
+`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.
 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 7 Dispute Repair Revenue Route Operations, following V36 Gate 6 Exchange settlement reconciliation closure.
+- Current working gate: V36 Gate 8 Exchange UX And Terminal Navigation Integration, following V36 Gate 7 dispute repair revenue route 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`.
@@ -33,6 +33,7 @@
 - V36 Gate 4 closure anchor: Exchange depth now owns package-backed `ExchangeRightsTransferPreview` source, deterministic `.bitcode/v36-exchange-rights-transfer-review.json`, `source-safe-exchange-rights-transfer-review-metadata`, BTD range identity, current owner, requested buyer, rights scope, settlement unlock condition, disclosure limit, owner-read, licensed-read, and blocked transfer preview states, proof roots, event ids, ledger/database projection refs, package tests, workflow wiring, and `check:v36-gate4`; AssetPack source is hidden until paid settlement and rights transfer are complete.
 - 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`.
 - 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

@@ -200,6 +200,9 @@
     "generate:v36-exchange-settlement-reconciliation": "node scripts/generate-v36-exchange-settlement-reconciliation.mjs",
     "check:v36-exchange-settlement-reconciliation": "node scripts/generate-v36-exchange-settlement-reconciliation.mjs --check",
     "check:v36-gate6": "node scripts/check-v36-gate6-exchange-settlement-reconciliation.mjs",
+    "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",
     "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",