[nicolasburtey]

Cross-repository financial report experiment

Paired Lana draft: https://github.com/GaloyMoney/lana-bank/pull/9972

Adds a bounded account/currency/range grid read in one indexed SQL statement, with shared cumulative checkpoints and CALA-owned BalanceRange construction. Opening dates remain exclusive, closing dates inclusive, and range versions use all_time_version, not per-date snapshot versions.

Also exposes executor-bound entry hydration and a read-only batch ancestor-ID lookup so Lana can project identified closing transfers on the same database snapshot. The API does not wait for EC rollups or claim a posting-time frontier.

Compatibility / current integration state

This PR targets current CALA main (0.33). The identical additive APIs were initially cherry-picked onto feat/effective-balance-grid-0.32; the tested Lana draft pins immutable revision cd602a309a42d8e64e9d79fc72162f1382e52096, without local paths or Cargo registry patches.

During implementation Lana main merged #9879, upgrading to CALA 0.33/es-entity 0.20. The Lana rebase hit manifest/lockfile conflicts and was aborted per repository policy. Next step is to integrate the Lana draft onto that migration and consume this current-main PR revision, not downgrade main or merge the compatibility pin as-is. Both PRs remain draft for architecture review.

Local validation

• Current-main cargo check -p cala-ledger --test effective_balance_grid: passed.
• Grid value-object tests: passed (3), including 1/4/12/24-bucket checkpoint sharing and invalid/work-limited requests.
• Current-main real-Postgres integration: passed. Compares every bound/counter/version with existing range reads, including backdating, missing IDs/currencies, empty openings, duplicate effective dates, pending balances and negative pending reversals. Also checks batch ancestry, journal isolation and executor-bound entry hydration.
• 0.32 compatibility grid integration: passed; the paired Lana draft's closed-year/visibility integrations also exercise those backported APIs.
• The grid repository consumes one IntoOneTimeExecutor and makes one statement. Twelve adjacent months share thirteen checkpoints. Result/probe volume remains proportional to accounts × currencies × boundaries.

CI status

Security audit and typos passed. Nix-based jobs fail before running code because the Nix installer/Magic Nix Cache actions time out on network requests; one retry reproduced the infrastructure failure. No CI-green or release readiness claim is made.

Draft for architecture review, not a release/merge request.

[github-actions]

📊 Performance Report

Commit: 972c5df
Updated: 2026-10-22 21:58:00 UTC

Cala Performance Benchmark Results (non-representative)

Criterion Benchmark Results (single-threaded)

Benchmark	Time per Run	Throughput	% vs Baseline
post_simple_transaction	2.145ms	466 tx/s	0 (baseline)
post_backdated_transaction_with_effective_balances_365_days	14.427ms	69 tx/s	-572.0%
post_multi_layer_transaction	3.584ms	278 tx/s	-67.0%
post_simple_transaction_with_effective_balances	2.093ms	477 tx/s	+2.0%
post_simple_transaction_with_skipped_velocity	2.277ms	439 tx/s	-6.0%
post_simple_transaction_with_velocity	2.147ms	465 tx/s	-0.0%
post_simple_transaction_with_hit_velocity	.837ms	1193 tx/s	+60.0%
post_simple_transaction_with_one_account_set	3.236ms	308 tx/s	-50.0%
post_simple_transaction_with_five_account_sets	2.423ms	412 tx/s	-12.0%
post_simple_transaction_with_ec_account_set	1.597ms	626 tx/s	+25.0%

Load Testing Results (parallel-execution)

Scenario	tx/s
1 parallel	360.28
2 parallel	589.04
5 parallel	834.57
10 parallel	523.58
20 parallel	872.03
2 contention	394.22
5 contention	262.23
2 acct_sets	293.82
5 acct_sets	292.53

---

Note: Performance results may vary based on system resources and database state.

Last updated by commit 972c5df