nx_balance.nx

nx_balance.nx -- per-account balance cache for the ledger. module: nishi-core.finance.balance depends: nishi-core.finance.ledger, nishi-core.io.iso8601 disk_kb: 5 capability: MARKETPLACE license_tier: PUBLIC_NISHI_SUBSTRATE genealogy_id: standard_accounting_running_balance_pattern + cardinal_13_additive_only + nishi_pillar_4_bits_up_sovereign_2026 Per-account running-balance cache. The ledger (`nx_ledger.nx`) is the authoritative event log; this primitive maintains O(1) balance lookups by listening to each posted transaction and updating per-account totals. Per Cardinal 13 (additive-only): cache entries are append-only snapshots. Each transaction post creates a new BalanceSnapshot row stamped with the post_ts. Querying current balance returns the latest is_current=1 snapshot; querying historical balance at time T returns the latest snapshot with post_ts <= T. ===== Why a cache when we have the ledger? ======================= Walking the ledger for every balance query is O(N) in transaction count. At 100k+ transactions/year, that's prohibitive for UI dashboards + dunning + fraud-detection workflows. The cache is a denormalized projection that maintains the invariant: sum(line.amount where account_id = A and is_debit = 1) - sum(line.amount where account_id = A and is_debit = 0) == BalanceSnapshot.balance_minor_q10 for A's latest snapshot Substrate periodically asserts this invariant via nx_balance_reconcile_against_ledger (queued).