Demo 3.15: Ledger Consistency & Integrity Verification

Functional Objective: Verifies that the primary distributed ledger (TigerBeetle) and the localized Postgres General Ledger projection maintain exact parity and eventual consistency, ensuring zero data loss even during network partitions or catastrophic worker crashes.

---

🎥 Video Walkthrough & Feature Tour

Ledger Integrity, Chaos Monkey & Zero Data Loss

Demonstrates a system chaos test where the outbox relay worker is terminated mid-transaction. Proves that the system enters a partition state securely, and instantly reconciles the Postgres read-model with the immutable TigerBeetle write-model once the worker recovers.

---

📋 Core Functional Capabilities

• Immutable Ledger Verification: Dual-write verification ensuring the high-performance book_keeper.ledger_transfers table in TigerBeetle matches the relational financialglentry projection in PostgreSQL. (Note: Immutability and ledger integrity guarantees are currently provided natively by TigerBeetle. The PostgreSQL projection acts purely as a read-model without row-level cryptographic signing, although Meta.dual_sign hash-chaining is planned for a future release).
• Worker Crash Resilience (Chaos Testing): Simulated partition scenarios where the JetStream Outbox worker (SIGKILL) is crashed during a live Journal Entry submission.
• Eventual Consistency & Auto-Recovery: Once the background worker is restored, pending transactions in the Outbox are instantly replicated to the Postgres read-model without any lost updates or duplicate transactions.
• Voucher Isolation: UUID-based ledger isolation per test run to prevent data pollution on shared enterprise databases.

---

🏗️ Technical Architecture & DocType Mapping

In Business M and Framework M, this domain is powered by native, metadata-driven DocTypes, async controllers, and distributed ledger adapters:

Active Business M DocTypes

JournalEntry, FinancialGLEntry, Company, Account

graph LR
    User["Stakeholder Portal / Desk"] --> Gateway["API Gateway"]
    Gateway --> Controller["Journal Entry Controller"]
    Controller --> TB[("TigerBeetle Immutable Ledger (Write)")]
    Controller --> Outbox["JetStream Outbox Queue"]
    Outbox -. "Crashes / Recovers" .-> Worker["Outbox Relay Worker"]
    Worker --> DB[("PostgreSQL GL Projection (Read)")]

---

🧪 Verifiable Test Script (Human Review Flow)

Follow these steps in the running Business M instance to replicate the live PoC demonstration:

1. Perform Baseline Transaction: Create and submit a baseline Journal Entry. Verify that TigerBeetle and Postgres balances match exactly.

• ✅ Action: Submit Document

2. Simulate Outbox Partition: Terminate the Finance outbox background worker (SIGKILL) to simulate a catastrophic failure.
3. Process Offline Transaction: Submit a new Journal Entry. The transaction writes instantly to TigerBeetle (sync mode) but is queued in the Outbox for Postgres projection.

• ✅ Action: Submit Document

4. Verify Imbalance: Check the ledgers. TigerBeetle reflects the updated balance immediately, while Postgres retains the delayed read-state.
5. Restore & Recover: Restart the background worker. Verify that the Outbox drains instantly and both databases match perfectly, proving Zero Audit Trail Loss.