V29 Gate 6: Close settlement reconciliation repair

Specify and implement settlement reconciliation repair as a first-class V29 Terminal workflow. BTD reports now classify projection drift, emit repair actions, surface proof roots, and block settlement conservation drift. The API, Sandbox harness, Terminal journal projection, and detail card now carry that evidence through to operator-visible repair actions and proof roots.

Add focused API, BTD, harness, and Terminal tests plus the Gate 6 checker and gate-quality workflow wiring.

Author: geraldarthurdavis

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

@@ -67,6 +67,7 @@ jobs:
           node scripts/check-v29-gate3-wallet-signer-btc-operations.mjs --skip-branch-check
           node scripts/check-v29-gate4-reading-pipeline-observability.mjs --skip-branch-check
           node scripts/check-v29-gate5-assetpack-disclosure-rights.mjs --skip-branch-check
+          node scripts/check-v29-gate6-settlement-reconciliation-repair.mjs --skip-branch-check
 
       - name: Validate source casing and imports
         run: |
@@ -76,6 +77,7 @@ jobs:
       - name: Type-check gate packages
         run: |
           pnpm --filter @bitcode/btd typecheck
+          pnpm --filter @bitcode/api build
           pnpm --filter @bitcode/pipeline-asset-pack typecheck
           pnpm --filter @bitcode/pipeline-hosts typecheck
 
@@ -84,6 +86,8 @@ jobs:
           pnpm --filter @bitcode/btd test
           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/api exec jest --config jest.config.cjs --runTestsByPath src/routes/__tests__/btd-crypto.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 --runInBand
           pnpm --filter @bitcode/pipeline-asset-pack exec jest --config jest.config.cjs --runTestsByPath src/__tests__/asset-pack-disclosure.test.ts src/__tests__/postprocess.test.ts src/__tests__/read-need.test.ts --runInBand
@@ -99,6 +103,8 @@ jobs:
             tests/terminalTransactionQuery.test.ts \
             tests/terminalTransactionReadModel.test.ts \
             tests/terminalWalletBtcOperation.test.ts \
+            tests/terminalJournalReconciliation.test.ts \
+            tests/terminalTransactionDetailCards.test.tsx \
             tests/pipelineExecutionLogHeader.test.tsx \
             --runInBand
 

BITCODE_SPEC_V29.md

@@ -225,6 +225,43 @@ The Terminal Wallet/BTC section is source-safe before settlement.
 It may reveal quote roots, state labels, txids, and readiness blockers.
 It may not expose protected AssetPack source, wallet secrets, provider tokens, or private signing material.
 
+## V29 settlement reconciliation repair canon
+
+Settlement reconciliation is an ordinary Terminal workflow, not an after-action database debug task.
+The canonical report is produced from:
+
+- ledger observed facts: fee receipts, ledger anchors, journal entries, BTD ranges, ownership events, read licenses, and finality state;
+- database projected facts: the Supabase readback rows that claim those ledger facts are durable in the application projection;
+- private metaphysical canonical facts: protected source metadata, need/fit context, access policy documents, encrypted storage pointers, disputes, and telemetry context represented only by roots;
+- settlement conservation checks: BTC debit/credit and fee/payment roots that must conserve before unlock;
+- delivery evidence: post-settlement pull-request visibility and recovery posture.
+
+Drift is classified before repair:
+
+- `missing_database_projection`: the ledger has a fact that the database projection has not read back;
+- `ledger_root_mismatch`: the database projection points at a different root than the ledger observation;
+- `ledger_finality_mismatch`: the projected finality differs from the observed finality;
+- `database_orphan_projection`: the database projects a fact that has no matching ledger observation;
+- `settlement_conservation_drift`: BTC debit/credit or fee/payment accounting does not conserve.
+
+Repair actions are canonical and auditable:
+
+- `retry_database_readback`;
+- `project_ledger_fact`;
+- `update_finality_state`;
+- `quarantine_database_projection`;
+- `pause_settlement_unlock`;
+- `recover_delivery`.
+
+The reconciliation state is one of aligned, retryable, repairable, approval required, or blocked.
+Confirmed ledger facts that are missing from the database require operator-approved projection repair.
+Reorged or failed finality, database-only orphan projection, or settlement conservation drift blocks unlock and delivery.
+Delivery recovery is allowed only when settlement is otherwise aligned and the full AssetPack delivery target is not visible.
+
+Terminal must show drift classes, blockers, repair actions, proof roots, observed facts, projected facts, canonical facts, journal entries, and repair receipts before raw payloads.
+The Vercel Sandbox harness must store the reconciliation report as settlement evidence when it claims ledger readback.
+The API may persist schema-compatible repair receipts while richer repair actions and proof roots remain report evidence until the registry schema is formally expanded.
+
 ## V29 canonical subsystem surfaces
 
 ### Depositing and asset supply

BITCODE_SPEC_V29_DELTA.md

@@ -140,6 +140,16 @@ Closure acceptance:
 
 Gate 6 owns ledger/database/metaphysical separation, journal diffing, reconciliation repair actions, proof-root surfacing, settlement conservation drift handling, and delivery recovery.
 
+Closure acceptance:
+
+- `@bitcode/btd` reconciliation reports carry `state`, `driftKindCounts`, `repairActions`, deterministic proof roots, and settlement conservation status while preserving private metaphysical canonical facts.
+- Projection repair receipts classify missing database projections, ledger-root mismatches, ledger-finality mismatches, database-only orphan projections, and settlement conservation drift.
+- Repair actions use canonical action kinds: retry database readback, project ledger fact, update finality state, quarantine database projection, pause settlement unlock, and recover delivery.
+- The Vercel Sandbox pipeline harness records `ledgerDatabaseReconciliation` evidence after settlement/readback and emits reconciliation state plus repair-action counts in telemetry.
+- Terminal journal detail renders drift classes, blocking reasons, ledger observed facts, database projected facts, metaphysical canonical facts, Terminal journal entries, repair actions, proof roots, and repair receipts without requiring browser-network inspection.
+- Focused BTD, API, pipeline-harness, and Terminal tests prove repair classification, conservation drift blocking, delivery recovery visibility, and proof-root projection.
+- `check:v29-gate6` and the gate-quality workflow fail closed when Gate 6 specification, implementation, tests, or workflow wiring is missing.
+
 ### Gate 7: Organization Permissions And Interface Authority
 
 Gate 7 owns organization holdings, roles, read-license usage, registry-derived permission decisions, MCP/ChatGPT action authority alignment, and Terminal permission explainers.

BITCODE_SPEC_V29_NOTES.md

@@ -151,6 +151,23 @@ Accepted Gate 5 posture:
 - Gate pull request titles must carry the uppercase version and gate prefix so gate closure can be audited from GitHub history.
 - Gate 5 does not implement reconciliation repair, organization authority, full settlement UI depth, or browser proof; later V29 gates own those slices.
 
+## Gate 6 working notes
+
+Gate 6 hardens the settlement truth boundary after source-safe preview and before paid unlock/delivery are treated as admissible.
+
+Implementation notes:
+
+- Reconciliation must always separate ledger-observed facts from database-projected facts and private metaphysical canonical facts.
+- Metaphysical facts remain private root commitments; they are not rendered as protected source.
+- Repair receipts classify drift, while repair actions describe the operational next step.
+- Settlement conservation drift is not a warning; it blocks unlock because BTC debit/credit truth must conserve before BTD rights are transferred or source is delivered.
+- Delivery recovery is surfaced only after settlement is aligned and delivery evidence exists but the pull-request shippable is not visible in the transaction read model.
+
+Operator notes:
+
+- Terminal journal detail is the ordinary repair cockpit for this gate: drift classes, blockers, repair actions, proof roots, journal entries, and repair receipts must be visible without opening network logs.
+- Raw payload remains audit material, not the primary operator interface.
+
 ## Later-version boundaries
 
 - V30 remains reserved for Protocol/BTD hardening that is not necessary to close Terminal transaction depth.

BITCODE_SPEC_V29_PARITY_MATRIX.md

@@ -53,7 +53,7 @@ No `_legacy/` source is active source truth.
 | Wallet signer/BTC operations | Gate 3 | `packages/btd/src/btc-fee-operation.ts`, BTC fee route, Terminal Wallet/BTC detail section, BTD and UAPI tests, Gate 3 checker | drafted | Signer session, PSBT, broadcast/finality/reorg/replacement/failure states are ordinary Terminal states. |
 | Reading pipeline observability | Gate 4 | `packages/pipelines/asset-pack/src/reading-pipeline-observability.ts`, `packages/pipeline-hosts/src/asset-pack-harness.ts`, Terminal stream components, Gate 4 checker | drafted | Pipeline/phase/PTRR/ThricifiedGeneration/tool/prompt/raw-output/parsed-output telemetry is contract-projected, complete, and readable. |
 | AssetPack disclosure rights | Gate 5 | `asset-pack-disclosure.ts`, AssetPack postprocess, sandbox harness, BTD access tests, Terminal disclosure review UI, Gate 5 checker | drafted | Source-safe preview and paid unlock are proven without protected-source leakage. |
-| Settlement reconciliation repair | Gate 6 | BTD journal/reconciliation, Supabase readback, Terminal repair UI | pending | Ledger, database, and metaphysical state drift is visible and repairable. |
+| Settlement reconciliation repair | Gate 6 | BTD journal/reconciliation, Supabase readback, sandbox harness settlement evidence, Terminal repair UI, Gate 6 checker | drafted | Ledger, database, and metaphysical state drift is classified, proof-rooted, repair-actioned, and visible. |
 | Organization permission authority | Gate 7 | access policy, org holdings, MCP/ChatGPT gates, Terminal permission UI | pending | Registry-derived roles, holdings, and read-license authority govern actions. |
 | Commercial formalization | Gate 8 | packages/protocol, package tests, import scans, docs | pending | Demonstration-origin commercial internals are package-native and no runtime demo imports remain. |
 | Terminal UX quality | Gate 9 | Playwright/Jest/a11y/responsive/browser QA | pending | Complete transaction cockpit is usable by default and inspectable in detail. |
@@ -182,6 +182,31 @@ Gate 4 is complete when Reading pipeline observability is package-owned, stream
 
 - Gate 5 does not reveal protected AssetPack source before settlement.
 - Gate 5 does not perform settlement reconciliation repair; Gate 6 owns ledger/database drift and repair.
+
+## Gate 6 Parity
+
+Gate 6 closes the settlement reconciliation slice by making drift ordinary data instead of hidden operator guesswork.
+
+Accepted surfaces:
+
+- `packages/btd/src/reconciliation.ts` is the canonical reconciliation primitive for ledger observed facts, database projected facts, private metaphysical canonical facts, settlement conservation checks, projection repair receipts, repair actions, drift-kind counts, report state, and proof roots.
+- `packages/api/src/routes/btd-crypto.ts` accepts settlement conservation checks and binds reconciliation proof roots into the Terminal journal entry for reconciliation settlements.
+- `packages/pipeline-hosts/src/asset-pack-harness.ts` stores `asset-pack/settlement.ledgerDatabaseReconciliation`, includes it in evidence, and streams reconciliation state/repair-action count after ledger readback.
+- `uapi/app/terminal/terminal-journal-reconciliation.ts` projects the selected transaction into observed facts, projected facts, canonical facts, drift classes, blocking reasons, repair actions, proof roots, and repair receipts.
+- `uapi/app/terminal/TerminalTransactionJournalReconciliationCard.tsx` renders the above as a low-detail operator surface with raw payload still available behind expansion.
+
+Accepted failure states:
+
+- Confirmed ledger facts missing from database projection require operator-approved projection repair.
+- Reorged or failed fee/anchor finality blocks settlement unlock.
+- Database-only orphan projection blocks until quarantined or matched to a ledger observation.
+- BTC fee settlement conservation drift blocks unlock and delivery.
+- Post-settlement missing pull-request delivery produces a delivery recovery action without exposing protected source.
+
+Gate 6 completion condition:
+
+- `pnpm run check:v29-gate6` passes.
+- Focused BTD, API, pipeline-hosts, and UAPI tests prove repair classification, conservation drift, proof roots, and Terminal repair visibility.
 - Gate 5 does not implement organization authority beyond read-right state distinctions; Gate 7 owns registry-derived roles and holdings.
 - Gate 5 does not add browser proof or full UX polish; Gate 9 owns that surface.
 - Gate 5 does not add versioned API routes or source identifiers.

package.json

@@ -49,6 +49,7 @@
     "check:v29-gate3": "node scripts/check-v29-gate3-wallet-signer-btc-operations.mjs",
     "check:v29-gate4": "node scripts/check-v29-gate4-reading-pipeline-observability.mjs",
     "check:v29-gate5": "node scripts/check-v29-gate5-assetpack-disclosure-rights.mjs",
+    "check:v29-gate6": "node scripts/check-v29-gate6-settlement-reconciliation-repair.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",

packages/api/jest.config.cjs

@@ -0,0 +1,17 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  rootDir: '.',
+  roots: ['<rootDir>/src'],
+  testMatch: ['<rootDir>/src/**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  transform: {
+    '^.+\\.tsx?$': [
+      'ts-jest',
+      {
+        tsconfig: '<rootDir>/tsconfig.json',
+        diagnostics: false,
+      },
+    ],
+  },
+};

packages/api/package.json

@@ -6,7 +6,7 @@
   "types": "src/index.ts",
   "scripts": {
     "build": "tsc --noEmit",
-    "test": "jest",
+    "test": "jest --config jest.config.cjs",
     "dev": "tsc --watch"
   },
   "dependencies": {

packages/api/src/routes/__tests__/btd-crypto.test.ts

@@ -762,9 +762,15 @@ describe('BTD crypto API builders', () => {
     });
 
     expect(settlement.report.blocking).toBe(true);
+    expect(settlement.report.state).toBe('approval_required');
     expect(settlement.report.repairs[0].repairKind).toBe('ledger_finality_state');
+    expect(settlement.report.repairs[0].repairActionKind).toBe('update_finality_state');
+    expect(settlement.report.proofRoots.repairPlanRoot).toMatch(/^btd-proof-root:repair-plan:/);
     expect(settlement.report.metaphysicalFacts[0].canonicalRoot).toBe('private-source-root');
     expect(settlement.terminalJournalEntry.transactionKind).toBe('ledger_database_reconciliation');
+    expect(settlement.terminalJournalEntry.receiptRoots).toContain(
+      settlement.report.proofRoots.repairPlanRoot,
+    );
   });
 
   it('builds deployment readiness, telemetry, and upgrade settlements', () => {
@@ -1230,6 +1236,15 @@ describe('BTD crypto API builders', () => {
               private: true,
             },
           ],
+          settlementConservationChecks: [
+            {
+              checkId: 'settlement-conservation-api-1',
+              expectedDebitSats: 1000,
+              observedDebitSats: 1000,
+              expectedCreditSats: 1000,
+              observedCreditSats: 900,
+            },
+          ],
           commitToRegistry: true,
           issuedAt,
         }),
@@ -1240,6 +1255,8 @@ describe('BTD crypto API builders', () => {
     expect(response.status).toBe(200);
     expect(body.kind).toBe('btd_ledger_database_reconciliation_settlement');
     expect(body.report.blocking).toBe(true);
+    expect(body.report.state).toBe('blocked');
+    expect(body.report.driftKindCounts.settlement_conservation_drift).toBe(1);
     expect(body.report.metaphysicalFacts[0].canonicalRoot).toBe('private-source-root');
     expect(body.committed).toBe(true);
     expect(insertReconciliationRepair).toHaveBeenCalledWith(

packages/api/src/routes/btd-crypto.ts

@@ -302,6 +302,7 @@ export interface BtdLedgerDatabaseReconciliationInput {
   ledgerFacts: LedgerObservedFact[];
   databaseFacts: DatabaseProjectedFact[];
   metaphysicalFacts?: MetaphysicalCanonicalFact[];
+  settlementConservationChecks?: Parameters<typeof reconcileLedgerDatabaseProjection>[0]['settlementConservationChecks'];
   commitToRegistry?: boolean;
   actorId?: string;
   issuedAt?: string;
@@ -926,6 +927,7 @@ export function buildBtdLedgerDatabaseReconciliationSettlement(
     ledgerFacts: input.ledgerFacts,
     databaseFacts: input.databaseFacts,
     metaphysicalFacts: input.metaphysicalFacts,
+    settlementConservationChecks: input.settlementConservationChecks,
     issuedAt: input.issuedAt,
   });
   const terminalJournalEntry = buildTerminalJournalEntry({
@@ -950,6 +952,10 @@ export function buildBtdLedgerDatabaseReconciliationSettlement(
       report.reconciliationId,
       ...report.repairs.map((repair) => repair.repairId),
       ...report.metaphysicalFacts.map((fact) => fact.receiptRoot ?? fact.canonicalRoot),
+      report.proofRoots.ledgerObservedRoot,
+      report.proofRoots.databaseProjectionRoot,
+      report.proofRoots.repairPlanRoot,
+      report.proofRoots.settlementConservationRoot,
     ],
     ledgerAnchorIds: input.ledgerFacts.map((fact) => fact.factId),
     exchangeSequence: BigInt(Math.max(1, input.ledgerFacts.length + input.databaseFacts.length)),