Reconciliation

The ledger continuously proves its own totals. A background scheduler runs integrity checks and raises when anything drifts.

The four categories

Cat	What it checks	Cadence
A — internal integrity	Does the trial balance sum to zero? Does every transaction have journal lines? Are source_txn_ids unique?	every cycle (default 1h)
B — derivation	Does each customer's wallet balance equal the sum of their journal lines? Do account totals match aggregated lines? Do snapshot balances match a replayed history?	every cycle
C — external	Does the ledger's cash match the broker's cash? Do share counts match the broker's positions? Does the LRS side match the ViewTrade side?	longer cadence (default daily)
D — lifecycle	Are any pending / in-transit flows older than the tolerance?	every cycle

A + B are cheap — SQL-only. C hits the live brokers, so it's throttled to daily by default. D is cheap.

What each check returns

For every check, per run:

• Status — ok / warn / fail.
• Metrics — arbitrary payload (totals, counts).
• Variances — a list of the SPECIFIC rows that broke it. If a check fails, this is where you look first.

Alerts

If a check moves to warn or fail:

• Optionally POSTs to an external ops webhook (fire-and-forget).
• Optionally persists the variances to a history table.

Both are opt-in via config.

The "degrade to OK on the wrong book" pattern

Every India-only check is also registered on the UAE book. When it runs on UAE, the query against India-only tables comes back empty and the check returns ok. No exceptions, no noise. This means adding India checks never breaks the UAE recon.

Running a check on demand

Ops can trigger any category from the Reconciliation page in the UI, or programmatically via POST /v1/reconciliation/run with an optional category filter.

When a check fails

1. Look at the variances. The specific rows are named on the run detail.
2. Trace to a transaction. Variances almost always name a txn_id or a source_txn_id.
3. Decide the class:
   • Data issue upstream → reverse, fix ingest, re-sync.
   • Ledger bug → fix the rule, migrate the data if needed, add a test.
   • Timing → often self-heals on the next cycle.
4. Confirm. Re-run the check.

The three on-demand India recon reports

Complement the scheduled checks:

• Ledger ↔ ViewTrade cash — per customer, ledger cash+securities vs live ViewTrade balance.
• Holdings — per (customer, instrument) share-count tie-out.
• LRS ↔ ViewTrade — per customer, remitted (GlomoPay) vs funded (ViewTrade).

All three are read-only, fetch live broker data, and isolate per-customer failures. See the Valuation section for detail.