Skip to content

Add append-only double-entry ledger (monitoring-only)#3880

Draft
TaprootFreak wants to merge 4 commits into
developfrom
feat/accounting-ledger
Draft

Add append-only double-entry ledger (monitoring-only)#3880
TaprootFreak wants to merge 4 commits into
developfrom
feat/accounting-ledger

Conversation

@TaprootFreak

Copy link
Copy Markdown
Collaborator

Summary

Introduces a pure-observer double-entry journal as a reconciliation source of truth for all value movements.

  • New ledger_account / ledger_tx / ledger_leg tables — the migration creates new tables only, no ALTER or data change on any existing table
  • Chart-of-accounts bootstrap (custody assets, transit routes, liabilities, P&L, equity, suspense) and idempotent booking consumers that translate settled source rows (bank, exchange, payin, payout, buy/sell, liquidity, trading) into balancing journal entries
  • Books balance by construction: integer-cent CHF check enforced in the service layer and via DB check constraint; append-only with explicit reversal transactions
  • Valuation reuses already-persisted CHF fields and snapshot marks — no new external or pricing calls (enforced by a static isolation gate and a DB-write isolation test)
  • One-time cutover opening, daily mark-to-market, and per-account reconciliation against persisted feeds with staleness guards, transit-age and suspense alarms
  • Read-only ADMIN endpoints for account balances, ledger detail, reconciliation status, suspense and realized-margin reporting
  • All ledger crons are gated by dedicated process flags (kill switch); existing financial log, safety module and dashboards remain unchanged and authoritative

Test plan

  • npm run format:check, npm run type-check, npm run lint clean
  • Full jest run green (100 suites / 1353 tests, incl. 24 new ledger suites / 332 tests)
  • Synthetic evidence-week integration tests (liability hold until bank booking, no imbalance during status-sync windows, staleness/placeholder guards, untracked sweeps to suspense, trade booking via symbol/side, cutover idempotency, global balance invariant)
  • Isolation self-tests: static write/pricing gate and DB-write isolation
  • Enable ledger processes on DEV, run cutover, verify reconciliation results and journal-vs-log parity

- new ledger_account/ledger_tx/ledger_leg tables (new-tables-only migration,
  integer-cent balance check, append-only with explicit reversals)
- chart-of-accounts bootstrap and idempotent booking engine with consumers
  for bank, exchange, payin, payout, buy/sell, liquidity and trading sources
- valuation from already-persisted CHF fields and snapshot marks, no new
  external or pricing calls (static isolation gate + DB write isolation test)
- one-time cutover opening, daily mark-to-market and per-account
  reconciliation with staleness guards, transit-age and suspense alarms
- read-only ADMIN endpoints for account balances, ledger detail,
  reconciliation status, suspense and realized-margin reporting
- all crons gated by dedicated process flags (kill switch); existing
  financial log and safety module remain unchanged and authoritative
- bound cutover opening queries with lookback window and settled filters
- correct check-constraint name to match TypeORM naming strategy
- paginate mark-to-market candidate selection across all open accounts
- align cutover watermark init with per-consumer settled semantics
- harden isolation gates and fix vacuous setting stub in isolation test
- drop unused imports in cutover spec, use synthetic source id in mapper spec
- add multi-page pagination test for mark-to-market candidate selection
- scope isolation-gate allowlist marker to write blocks only, with self-test
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant