Service layer for detailed (per-security) balance accounts:
- findOrCreateSecurity (UPSERT on normalized UPPER(TRIM) symbol, callable
in-txn via an executor), listSecurities, getSecurity, updateSecurity.
- saveSnapshotAtomic / upsertSnapshotLines: a detailed account (line carrying
a holdings array) writes its aggregated line (value = rounded-cent SUM,
qty/price NULL) AND its holdings in the SAME BEGIN/COMMIT; the line id is
captured, existing holdings DELETEd, each security find-or-created and each
holding INSERTed. A holding-insert failure rolls the whole save back. Simple
/ legacy-priced scalar path is unchanged. upsertSnapshotLines is now wrapped
in an explicit transaction for the same atomicity.
- validateDetailedSnapshot: detailed+holdings => line qty/price NULL and
value === rounded-cent SUM(holdings) compared EXACTLY (no float tolerance);
detailed without holdings => pre-pivot aggregated tolerated.
validateLineKindInvariants stays byte-for-byte for the scalar path.
- roundToCent helper; detailed path uses per-holding cent rounding then exact
comparison to avoid N-holding rounding accumulation (decision 2026-06-03).
- Service backstop in updateBalanceAccount: detailed->simple rejected with a
typed error (account_kind_detailed_has_holdings) when holdings exist; adds
kind/detailed_since to the account input + SELECT.
- getHoldingsForLatestSnapshot (prefill; excludes quantity-0 positions),
listHoldingsBySnapshotLine (drill-down).
- computeUnrealizedGain: per-holding and aggregated value - book_cost and %;
book_cost = 0 OR NULL => gain % null (no divide-by-zero); NULL book_cost
excluded from the aggregate and flagged.
Existing aggregators (getSnapshotTotalsBy*) and computeAccountReturn untouched.
Unit tests for every new function incl. casing dedup, N>=20 holdings rounding,
book_cost=0/NULL, detailed->simple guard, atomic save + rollback. Existing
upsertSnapshotLines/updateBalanceAccount tests updated for the BEGIN/COMMIT
wrapping and the kind/detailed_since columns.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
