Merge pull request #105 from engineeredsoftware/v36/gate-6-exchange-settlement-reconciliation

V36 Gate 6: Exchange Settlement Ledger Database Reconciliation

Author: geraldarthurdavis

.bitcode/v36-exchange-settlement-reconciliation.json

@@ -85,6 +85,9 @@ jobs:
               if [ -f scripts/check-v36-gate5-exchange-pricing-quote.mjs ]; then
                 node scripts/check-v36-gate5-exchange-pricing-quote.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v36-gate6-exchange-settlement-reconciliation.mjs ]; then
+                node scripts/check-v36-gate6-exchange-settlement-reconciliation.mjs --skip-branch-check
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

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

@@ -213,6 +213,9 @@ jobs:
               if [ -f scripts/check-v36-gate5-exchange-pricing-quote.mjs ]; then
                 node scripts/check-v36-gate5-exchange-pricing-quote.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v36-gate6-exchange-settlement-reconciliation.mjs ]; then
+                node scripts/check-v36-gate6-exchange-settlement-reconciliation.mjs --skip-branch-check
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
@@ -272,6 +275,7 @@ jobs:
           pnpm --dir packages/protocol exec node --test --test-force-exit test/v36-exchange-intent-order-contracts.test.js
           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 --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

@@ -149,6 +149,34 @@ Ledger journal state remains stronger than database projection state for quote
 roots, settlement admission, payment matching, route allocation, and network
 posture.
 
+## V36 Gate 6 ExchangeSettlementReceipt canon
+
+Gate 6 implements `ExchangeSettlementReceipt` as the package-owned settlement
+and reconciliation contract for Exchange completion.
+`ExchangeSettlementReceipt` binds payment observation, finality state, rights
+transfer receipt, ledger root, database projection root, object storage root,
+delivery state, repair id, observer jobs, reconciliation decision, proof roots,
+and event ids before source-bearing delivery can be trusted.
+
+Gate 6 emits `.bitcode/v36-exchange-settlement-reconciliation.json` with
+`source-safe-exchange-settlement-reconciliation-metadata`.
+The settlement binding is payment observation, finality state, rights transfer receipt, ledger root, database projection root, object storage root, delivery state, and repair id.
+The source-safe receipt may expose settlement identity, payment observation,
+finality state, rights-transfer receipt identity, ledger root, database
+projection root, object storage root, delivery state, repair id, observer jobs,
+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, or secret values.
+
+observers and repair jobs reconcile database projections to ledger truth.
+The ledger journal remains stronger than database and object-storage
+projections; repair jobs may rewrite projections toward ledger truth but cannot
+rewrite ledger truth toward projection convenience.
+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.
+
 ## 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

@@ -126,7 +126,9 @@ Closure acceptance:
 
 - `ExchangeSettlementReceipt` binds payment observation, finality state, rights transfer receipt, ledger root, database projection root, object storage root, delivery state, and repair id;
 - observers and repair jobs reconcile database projections to ledger truth;
-- settlement finality and delivery are auditable.
+- settlement finality and delivery are auditable;
+- `.bitcode/v36-exchange-settlement-reconciliation.json` is generated from the package-owned builder with `source-safe-exchange-settlement-reconciliation-metadata`;
+- `pnpm run check:v36-gate6` validates package source, artifact freshness, package tests, docs, workflow wiring, payment observation, finality state, rights transfer receipt, ledger root, database projection root, object storage root, delivery state, repair id, observer jobs, repair jobs, projection reconciliation to ledger truth, delivery auditability, source-safety, proof roots, and event ids.
 
 ### Gate 7: Dispute Repair Revenue Route Operations
 

BITCODE_SPEC_V36_DELTA.md

@@ -126,6 +126,18 @@ the BTD range ledger journal remains the ownership and range identity record.
 underpayment, overpayment, stale quote, or unsupported network posture fails closed so settlement cannot continue with mismatched payment, expired price,
 or unsupported network state.
 
+## Gate 6 closure notes
+
+Gate 6 closes when `ExchangeSettlementReceipt` is package-owned and generated
+through `.bitcode/v36-exchange-settlement-reconciliation.json`.
+The generated artifact carries
+`source-safe-exchange-settlement-reconciliation-metadata` and binds payment observation, finality state, rights transfer receipt, ledger root, database projection root, object storage root, delivery state, and repair id.
+observers and repair jobs reconcile database projections to ledger truth.
+settlement finality and delivery are auditable.
+Delivery remains blocked until paid finality, rights-transfer receipt,
+projection synchronization, object-storage projection, and delivery state are
+all source-safe and proof-rooted.
+
 ## Accepted boundaries
 
 - V36 owns deeper Exchange.

BITCODE_SPEC_V36_NOTES.md

@@ -58,7 +58,7 @@ No `_legacy/` source is active source truth.
 | Exchange intent and order contracts | Gate 3 | `ExchangeIntent`, `ExchangeOrder`, `.bitcode/v36-exchange-intent-order-contracts.json`, package source, tests, and `check:v36-gate3` | closed | Buy, sell, bid, ask, cancel, accept, settle, and history transitions are typed, authorized, idempotent, policy-gated, source-safe, and replayable. |
 | 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` | draft-required | Ledger, database, object storage, finality, delivery, and rights-transfer roots reconcile. |
+| 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. |
 | 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. |
@@ -147,6 +147,18 @@ No `_legacy/` source is active source truth.
 | Ledger/database projection posture is explicit | ledger journal refs outrank database projection refs for quote roots, settlement admission, route allocation, and network posture | closed |
 | Workflow and package tests are wired | `packages/protocol/test/v36-exchange-pricing-quote.test.js`, `scripts/check-v36-gate5-exchange-pricing-quote.mjs`, `.github/workflows/bitcode-gate-quality.yml` | closed |
 
+## Gate 6 Parity
+
+| Requirement | Source evidence | Current V36 judgment |
+| --- | --- | --- |
+| `ExchangeSettlementReceipt` is package-owned | `packages/protocol/src/canonical/exchange-settlement-reconciliation.js`, `packages/protocol/src/index.js`, `packages/protocol/src/index.d.ts` | closed |
+| Generated settlement artifact exists | `.bitcode/v36-exchange-settlement-reconciliation.json`, `scripts/generate-v36-exchange-settlement-reconciliation.mjs`, `pnpm run check:v36-exchange-settlement-reconciliation` | closed |
+| Required settlement fields are covered | payment observation, finality state, rights transfer receipt, ledger root, database projection root, object storage root, delivery state, and repair id | closed |
+| Projection reconciliation is explicit | observers and repair jobs reconcile database projections to ledger truth | closed |
+| Finality and delivery are auditable | settlement finality and delivery are auditable | closed |
+| 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 |
+
 ## V36 accepted boundaries
 
 - V36 owns deeper Exchange.

BITCODE_SPEC_V36_PARITY_MATRIX.md

@@ -42,6 +42,12 @@ source-safe generated artifact `.bitcode/v36-pricing-liquidity-fee-quote.json`.
 The quote covers BTC amount, measurement weight, measurement volume, liquidity band, wrapper analysis, treasury route, depositor route, reader route, and
 quote root. The source-safe verdict is
 `source-safe-exchange-pricing-quote-metadata`; 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 anchors settlement through package-owned `ExchangeSettlementReceipt`
+and the source-safe generated artifact
+`.bitcode/v36-exchange-settlement-reconciliation.json`.
+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.
 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 6 Exchange Settlement Ledger Database Reconciliation, following V36 Gate 5 Exchange pricing/liquidity quote closure.
+- Current working gate: V36 Gate 7 Dispute Repair Revenue Route Operations, following V36 Gate 6 Exchange settlement reconciliation 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`.
@@ -32,6 +32,7 @@
 - V36 Gate 3 closure anchor: Exchange depth now owns package-backed `ExchangeIntent` and `ExchangeOrder` source, deterministic `.bitcode/v36-exchange-intent-order-contracts.json`, `source-safe-exchange-intent-order-contract-metadata`, buy, sell, bid, ask, cancel, accept, settle, and history transition rows, actor principals, organization roles, wallet posture, authority proofs, idempotency keys, policy decisions, fail-closed results, proof roots, event ids, ledger journal refs, database projection refs, package tests, workflow wiring, and `check:v36-gate3`; order history is replayable without private wallet material or secrets.
 - 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.
 - 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

@@ -197,6 +197,9 @@
     "generate:v36-exchange-pricing-quote": "node scripts/generate-v36-exchange-pricing-quote.mjs",
     "check:v36-exchange-pricing-quote": "node scripts/generate-v36-exchange-pricing-quote.mjs --check",
     "check:v36-gate5": "node scripts/check-v36-gate5-exchange-pricing-quote.mjs",
+    "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",
     "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",