Specification · 001-cash-snapshot
Point-in-time cash-account snapshots
One cash account, two truthful balances: what has traded, and what has actually settled — as of any instant.
A cash account has more than one correct balance at a single instant. Traded cash (the
investment book, IBOR) counts every fill executed by the as-of time; settled cash (the accounting
book, ABOR) counts only trades whose cash has actually settled. The gap between them is cash in flight across the
settlement lag. This feature computes both, as of any point in time, deriving each trade's settlement date from the
standard cycle in force on that trade's trade date — so a historical snapshot is settled under the rule that
governed it, not today's. It is realised by the std-only Rust settlement crate.
- I Independent
- Depends only on a trade record and a business-day calendar. Knows nothing about positions, P&L, or tax lots.
- N Negotiable
- Outcome (two edition-correct balances as of an instant), not a named language or storage engine.
- V Valuable
- Unlocks SC-001 — a front office and an accounting team reading one account and each seeing their own truthful balance.
- E Estimable
- Settlement-date arithmetic, an as-of filter, and a two-book sum are well-understood; the edition cutover is the one subtlety and it is pinned.
- S Small
- One entity, one function, four functional requirements; refresh cadence is a product knob, not core math.
- T Testable
- Settlement dates, the IBOR/ABOR split, and the double-settlement-day edge are all mechanically checkable against fixed fixtures.
- Exec / PM
- §Context, §User scenarios, §Success criteria.
- Reviewer
- §Requirements, §Assumptions, §Open questions.
- Implementer
- §Requirements, §Data model, §Conformance index.
1 · Context
Cash reconciliation breaks when a single account is asked for "the balance" as if there were only one. The front-office desk works trade-date: the moment a fill executes, that cash is committed and must show. The accounting team works settlement-date: cash is real only once it has settled, because that is what NAV and the books are struck on. Between the two sits the settlement lag — for US equities, one or two business days — during which the same account legitimately holds two different balances.
The users are the investment desk (needs traded cash now) and the fund-accounting team (needs settled cash as of a close). Both read one cash account; each needs its own basis to be correct, and correct as of a chosen instant, not just live.
2 · User scenarios & testing
Each story MUST be independently testable.
US1 · Settled cash across the lag P1
As a fund accountant, I want the settled-cash balance as of a close date, so NAV is struck on cash that has actually settled and not on trades still in flight.
Acceptance: given a book of trades and an as-of date, the settled (ABOR) balance includes exactly those trades whose settlement date — trade date + the cycle in force on that trade date — is on or before the as-of date.
US2 · Traded vs settled at one instant P2
As an investment-desk operator, I want traded cash and settled cash for the same account as of the same instant, so I can see committed cash immediately and the in-flight gap explicitly.
Acceptance: a snapshot returns both the traded (IBOR) and settled (ABOR) balances; their difference equals the net cash of trades executed but not yet settled as of that instant.
US3 · Edition-correct historical snapshot P3
As a reconciliation analyst, I want a snapshot as of a past date to settle each trade under the cycle that was in force when it was struck, so a re-run of an old close reproduces the books exactly.
Acceptance: a trade dated before the T+1 compliance date settles T+2; a trade dated on or after it settles T+1; a snapshot spanning the cutover applies each rule to the trades it governs.
Edge cases
- Double settlement day. The last T+2 trade date and the first T+1 trade date can settle on the same calendar day; both must be recognised on that day, neither early nor late.
- Holiday in the lag. A market holiday between trade and settlement extends the settlement date by a business day; weekends and holidays are never settlement dates.
- As-of before any settlement. An as-of instant before every trade has settled yields a settled balance equal to the opening balance, with all trade cash still in flight.
3 · Requirements
Conformance keywords (
Functional
The settlement date of a US-equity trade
Rationale
Point-in-time correctness across the compliance-date cutover: the cycle length is
read from standard_cycle(trade_date), grounded on KB-0001@2024-05-28, which supersedes the T+2
edition without rewriting how a pre-cutover trade settled.
A snapshot as of an instant
For a trade with two currency legs, the snapshot
The snapshot service
Out of scope (deferred)
- Available cash — settled cash net of holds, collateral, and pending withdrawals — a later slice; this spec computes traded and settled only.
- Corporate-action cash entitlements (dividends across the ex/record/pay dates); adjacent domain, not part of the snapshot math here.
- Multi-currency NAV translation and FX rate sourcing — owned by the fund-accounting platform, never this slice.
4 · Data model
The feature owns the snapshot computation and the settlement calendar; it borrows the trade record.
Entities
Trade- A fill: ticker, side (buy/sell), quantity, price in exact cents, and a trade date. Its cash effect is a buy paying out and a sell bringing cash in.
SettlementCalendar- Weekends plus a set of US market holidays; answers is-business-day and add-N-business-days, and derives a trade's settlement date via the edition-correct cycle.
Snapshot{ ibor_cents, abor_cents }— traded cash and settled cash as of an instant; their difference is cash in flight.
Invariant: money is exact integer cents — never floating point — and a settlement date is always a business day. The IBOR and ABOR balances converge once every trade in the book has settled.
5 · Success criteria
Technology-agnostic, measurable outcomes.
For a fixed book of trades and a given as-of date, the reported settled balance equals the opening balance plus the net cash of exactly the trades whose edition-correct settlement date is on or before that date — reproducible to the cent.
A snapshot taken on the last day trades remain unsettled and again on the day they settle shows the traded balance unchanged and the settled balance rising by exactly the settling trades' net cash, closing the in-flight gap to zero.
6 · Assumptions
Trades are US-equity single-currency fills except where FR-003's two-legged FX case applies; other asset classes are out of scope for this slice.
The settlement calendar's holiday set is supplied and correct for the window being snapshotted; sourcing the holiday calendar is not this spec's concern.
7 · Open questions
None outstanding — the two-book contract and the edition-correct settlement rule are fixed here; available cash and corporate actions are explicitly deferred rather than left open, and the refresh interval is a product knob, not an unresolved question.
8 · Conformance index
Auto-built from every <spec-requirement> in this document.
9 · Change log
- Initial draft. Point-in-time cash snapshots across the investment (IBOR) and accounting (ABOR) books: edition-correct settlement-date derivation (FR-001, T+2 in this edition), the two-book as-of snapshot (FR-002), FX exposure on principal with a PvP flag (FR-003), and an optional refresh interval (FR-004). Realised by the std-only Rust
settlementcrate. - Applied 2024-05-28-usd-t1-settlement: USD equities T+2 → T+1 (SEC Rule 15c6-1, 28 May 2024).