ADR-0030: Event Store as Source of Truth for the TigerBeetle Ledger
ADR-0030: Event Store as Source of Truth for the TigerBeetle Ledger
Section titled “ADR-0030: Event Store as Source of Truth for the TigerBeetle Ledger”- Status: Proposed
- Date: 2026-09-21
- Deciders: @revant.one
- Supersedes: N/A
- Superseded by: N/A
Context
Section titled “Context”TigerBeetle is a deterministic financial state machine. It persists only fixed-size structs — Account, Transfer — and the materialized balances derived from them. There is no event log, no audit history, no arbitrary metadata, no key-value store, and no query language. A bare TigerBeetle cluster answers “what is the current balance”, never “why”, “when”, “who approved it”, or “what was the ledger at a point in time”.
Regulatory/audit bookkeeping and disaster recovery require an immutable, replayable record of every mutation. The ledger must be provably reconstructible from that record alone.
Decision
Section titled “Decision”- KurrentDB is the canonical event log behind the
EventStorePort(libs/ledger-core/ledger_core/interfaces.py). Postgresevent_store_eventsis the fallback behind the same port. TigerBeetle becomes a projection of the log, not a record of it. - Every ledger mutation dual-writes: the domain event is appended and the resulting state lands in the ledger. This dual-write already exists in
FinanceLedgerServiceandStockLedgerService. - Replay is a port-to-port hydrator implemented once in
ledger_core.replay, fed byEventStorePort.read_all(global ordered reads) and writing through a sharedLedgerSink— a real ledger (LedgerPortSink), a JSONL file (FileSink), or an in-memory mirror used for--verify. - The commands live in the domain libs, not in
apps/business-m:m replay-finance(registered bylibs/finance) andm replay-stock(registered bylibs/wms), each dispatching through its own bootstrap adapter and translator. Macroservices deploy finance/wms standalone (INSTALLED_APPS=finance,INSTALLED_APPS=wms) withoutbusiness-m-shell, so a command registered only in the shell would be absent there. Distinct names keep both commands available in the monolith (both libs installed) without aCommandCollisionErrorin the CLI plugin loader. - The external script
files/new/replay_hydration.pyis deprecated; its deterministic-ID and verify ideas carry intoledger_core.replay/--verify.
Design notes
Section titled “Design notes”- Postgres
positionis per-tenant. The real-Postgresevent_store_eventstable is hash-partitioned ontenant_id(ledger_core/ddl/postgres.py), which forbidsIDENTITYcolumns and requires any unique constraint to include the partition key. A globalBIGSERIAL UNIQUEis therefore impossible; the replay cursor isUNIQUE (tenant_id, position). Ordering still matches Kurrent within a tenant — the only scope replay needs. - Replay keeps an in-run
original→freshtransfer-ID remap and an event index. Pending/void/reversal events reference the original run’s transfer IDs (PendingTransferCommitted.transfer_id,StockTransferVoided.pending_id, reversaloriginal_transfer_id). A clean rebuild mints fresh UUIDs, so the hydrator remaps each created transfer back to its original ID (viaTransferCommand.replay_key) and resolves reversals through an index of events keyed bytransfer_id. Without this, post/void/reverse replay would fail and balances would not reconcile.
Consequences
Section titled “Consequences”Positive
Section titled “Positive”- Full audit history and point-in-time reconstruction:
read_alldoubles as the audit-export (--outputJSONL) and verification (--verifyvsLedgerPort.get_balance) path. - TigerBeetle stays a lean projection — it is rebuilt, not queried.
- Usable in every topology: finance-only, wms-only, and the monolith each get exactly the commands they ship.
- Original IDs are preserved in event data even though rebuilt ledgers mint fresh UUIDs.
Negative
Section titled “Negative”- One extra durable write per transfer — the event append after each ledger commit.
- Event schema must be forward-compatible; translators can only replay event types they know.
- Rebuilt transfer UUIDs differ from the original run (documented and accepted).
- The transfer-ID remap is in-memory per run; cross-run idempotency without a checkpoint is not addressed yet (deterministic transfer IDs are the documented upgrade path).
DR-Drill Runbook
Section titled “DR-Drill Runbook”- Wipe the ledger backend (TigerBeetle or Postgres projection).
- Rebuild from the event log:
m replay-finance --reset --verify/m replay-stock --reset --verify. --verifyrecomputes expected per-account balances fromread_alland compares them againstLedgerPort.get_balance, exiting non-zero on any mismatch.- Rerun the verify on a recurring cadence (scheduled) so drift is caught early, not at recovery time.