Position read model — proposed for #248
Position read model — proposed for #248
Decision boundary
Status: first-screen scope and visual direction approved by the owner on 2026-10-22; orchestration and acceptance proposal for #248/#249. Position opens with All books, grouped by entity, and supports entity or individual-book scope. Each row is an independently authorized, explicit-date report. This does not approve live-entity policy, change SQL/HTTP, classify an account as cash, or calculate spendable funds. The existing financial reporting, reporting SQL, HTTP, and pinned journal contracts remain authoritative for implemented report arithmetic and access. Evidence records review depth, inference and alternatives.
The approved first screen shows entity/book, functional currency, Assets, Liabilities, Book equity, and signed Equity change against an explicit earlier date. Position · Ledger · Reports remain directly available at the top. Clean sans-serif text, aligned amounts and alternating faint-gray/unshaded book rows provide structure; no column tint. Equity increases/decreases may use restrained green/red with explicit signs, never a claim of spendability, reconciliation, or favorable/adverse movement in every account category. Direct equity and unclosed earnings remain report detail. Cash classification, spendability and attention status are deferred extensions, not first-screen fields.
All-books orchestration and independent snapshots
Use the current authorized workspace membership list for visible entity/book rows. Apply all-books, entity or individual-book selection to that list; do not obtain scope from cached financial responses or caller-provided actor identity. Every balance-sheet request still authenticates and authorizes its exact entity/book. The membership list is discovery, never a durable grant. If access changes, clear that row's prior amounts before rendering its denied/unavailable state. A global identity failure stops scheduling further reads and clears financial results.
The browser orchestrates existing per-book balance-sheet comparison requests with at most four in flight. Four is an initial UI concurrency bound, not a measured capacity claim. No new SQL, API route, bulk response, arithmetic or aggregation is authorized. Queue books beyond the bound and show their pending state honestly; do not silently truncate the selected scope. Scope/date changes cancel obsolete work where supported and generation-guard every result so a late old response cannot overwrite the current selection. Reuse no rows across scope refreshes.
One response provides current/prior totals and their exact signed change for one
book revision. Each row retains its own accounting/comparison dates,
snapshot_revision, generated_at, currency code/version/minor units and status.
Expose those details accessibly for that row. A shared date control expresses the
requested cutoff, not a shared transaction. Books read before/after concurrent
postings can have different revisions and generation times: label the overview
Independent book snapshots and never assign a common report revision.
Successful rows remain visible when another book fails; pending, valid zero, denied, stale and unsupported rows are distinct. An unavailable row contains no current, prior or change substitute zero and no retained stale amounts. Each row is either a complete accepted comparison response or unavailable; do not splice totals from separate responses. Explicit refresh rereads the selected scope and replaces row snapshots. Reading one book successfully does not imply all books were read.
Entity headings organize rows only. No entity subtotal, portfolio grand total, cross-book sum, FX conversion, eliminations or claim of consolidation is permitted, even when two rows use USD. Books can represent overlapping economic activity. #59 owns any future consolidated/presentation-currency model. Unsupported book policies, including functional currencies beyond today's synthetic USD profile, remain unavailable rather than fabricated multi-currency support. Original transaction currencies remain accessible in the ledger under existing authority.
Top navigation preserves explicit selected scope and date intent. Ledger/Reports may require choosing a book within that scope before using their single-book endpoints; they must not silently choose one or imply a cross-book report. Evidence for a Position row carries that row's entity/book/date/revision.
Selection, exact arithmetic and trace
Request exactly one verified, currently readable entity/book, an inclusive
through_date, and an explicit earlier comparison through_date if movement is
shown. Dates are accounting dates in the book's supported UTC policy, independent
of browser time and journal posted_at. A Position line is a point balance,
not a period flow. Change since is current point balance minus earlier point
balance, preserving a signed result. It does not claim cash flow, profitability,
or the cause of change. The balance-sheet comparison uses one authorized book
revision for both dates. Do not fill a failed or missing comparison with zero.
For eligible posted lines through the selected date, N(account)=Σ(functional debit−functional credit) as an exact decimal. Preserve unexpected signs and
contra balances. The existing unclassified balance-sheet categories define:
| Position line | Exact functional-currency expression | Existing evidence |
|---|---|---|
| Assets | Σ N(asset) | Balance-sheet totals.assets, account rows and selectors |
| Liabilities | −Σ N(liability) | totals.liabilities |
| Direct equity | −Σ N(equity) | totals.direct_equity |
| Unclosed earnings | −Σ [N(revenue)+N(expense)] over eligible history | totals.unclosed_earnings; derived, never a journal |
| Book equity | Direct equity + unclosed earnings | totals.total_equity; comparison change is server-supplied |
| Cash | Σ N(a) for a reviewed, versioned set of asset account IDs C | Extension required; no existing cash classification |
| Other assets | Total assets − Cash | Extension required after C is approved |
Total assets = Liabilities + Total equity is an invariant, not an adjustment.
Never take absolute values to force a pleasant presentation. Account code/name,
provider type and source account links cannot substitute for reviewed cash
membership. A credit-balance cash account stays negative. Inactive historical
accounts remain in totals. Empty valid books return exact zero statement totals;
this is not an unavailable read. Zero totals or an empty report selection cannot
prove that no journals were posted: offsetting entries can have the same result.
The existing balance-sheet API has no authoritative journal-count flag. Display
exact zero without a No posted entries claim. Such a status requires separately
owned authoritative metadata before it can be shown.
Deferred cash and evidence extensions
The server must own cash membership and calculation, not browser-selected rows or
client-side arithmetic. A proposed position-v1 read extension can return a
versioned cash_account_ids policy reference, cash, other_assets, and their
comparisons, computed with the existing balance-sheet authority and same
revision/transaction. It should reject missing, foreign, non-asset, ambiguous or
unsupported classifications and never silently omit an account. Its eventual
policy storage and update workflow require a reviewed decision before DDL.
Until then, Position omits Cash; a future dedicated cash view must show Not configured without reviewed membership, never relabel total assets as cash.
Initial Position can show current and prior point totals from the existing comparison response; a single
server response is required for consistent movement.
All amounts remain canonical signed decimal strings, at most 29 integer and
9 fractional digits; zero is "0". No float or JavaScript financial arithmetic.
Functional currency ISO 4217 code, pinned version ID and minor units accompany
each total. UI padding is display only. A book's original amounts/currency versions
and immutable rate IDs survive in the supporting GL and journal; original units
are never summed across currencies. No cross-book/entity consolidation or
aggregation in this overview. A policy or functional-currency transition without approved mapping returns
unsupported_policy, never a converted total. The first implemented report
profile is synthetic accrual/UTC/USD functional currency; future functional
currencies require their own approved policy and tests.
Each account/derived line uses its server-generated selector to show contributing
accounts. A selected account opens scoped GL with the same snapshot_revision,
date bounds and exact amounts; a selected GL row opens the existing pinned
journal endpoint in the same revision. The current journal endpoint proves one
selected GL-line inclusion, not arbitrary subtotal-to-journal membership.
For subtotal evidence, the UI must expose the contributing account list and then
GL; a direct subtotal journal list needs a bounded server contract and tests.
For point balances, GL must cover opening history through through_date, not
only a convenient recent window. An empty account selection shows an explicit
zero and no journals. Original and reversal journals remain immutable on their
own accounting dates; the view never erases the original when corrected.
Truthful state and attention
Position has three independent clocks: (1) the accounting cutoff
through_date, (2) the book snapshot snapshot_revision and
generated_at, and (3) source freshness from separately authorized
acquisition/status reads. A source being current does not prove its observations
were reviewed or posted. A posted balance does not prove reconciliation,
completeness or availability to spend. generated_at is computation time,
not a posting cutoff. Pending/failed commands may need attention but are not
included in balances until posted.
A future Needs attention tool requires a separate, typed, server-supported feed of
actionable items with scope, source/status ID, observed timestamp, state and
direct task target. Candidate kinds: unreviewed source observations, failed or
stale acquisition, and a pending/failed command requiring terminal
acknowledgement. Each kind needs its owning contract, authorization and a
reviewed freshness threshold. Until such a feed exists, render Attention status unavailable or omit the list, not All clear. Do not infer a reconciled
state from an empty list. Source-only observations and drafts never enter the
posted Position. The attention feed may fail independently; its failure must not
change a valid posted balance into zero or imply a complete review.
| Condition | Required result |
|---|---|
| No readable books / valid authorized book returning zero totals | Empty workspace state / exact-zero row; no inference about posted-entry count |
| Unknown or inaccessible scope | 404 with no totals or existence hint |
| Missing credentials / read grant denied | 401 / 403 with no financial body |
| Revision changed between views | 409 report_snapshot_changed; discard old evidence and offer explicit refresh |
| Unsupported policy, overflow or timeout | 422 / 503, no partial totals or substitute zero |
| Stale source status | Keep posted Position labelled by revision/date; show separately sourced freshness warning only |
Every report request reauthorizes current read permission before revision
comparison. Responses are no-store; no financial rows, tokens or requests in
browser persistence, analytics URLs or shared caches. A later page or drill must
not silently switch revisions. The existing report bounds (4,096 selected rows,
2 MiB response, bounded execution) may make Position unavailable for a larger
book; scale work needs measured evidence, not client truncation.
Standards and decisions
This is an internal book-query response, not a selected bank-to-bank exchange. ISO 20022 FAQ and message catalogue R01–R02 were reviewed at public overview depth; no applicable registered message/version or counterparty usage profile has been identified for this internal read. The extension therefore uses a versioned local contract without an ISO designation. Reassess for an actual financial exchange. ISO 4217 R03 applies to currency identity and versioned metadata, not FX valuation or account classification. The existing reporting currency mapping is retained. ISO 21378:2019 R04 and ISO 21926:2026 R05 are relevant to future audit extraction/semantics; public abstract/preview only was reviewed, so no field-level mapping or conformance is claimed. The proposed Position response is not an audit export. No purchased normative text, external usage profile or live accounting framework was reviewed for this slice.
| Open decision | Owner and condition |
|---|---|
| Cash account membership and change control, including restricted cash and cash equivalents | Owner/accountant under #1; approve policy/version and tests before a Cash total ships |
| Real entity basis, opening balances, FX/close semantics | Owner/accountant #1/#10/#59 before live use |
| Attention sources, thresholds and priority | Owning acquisition/command contracts plus owner workflow review |
| Position labels, scope and first-screen order | Owner approved the all-books overview and gray zebra rows on 2026-10-22; browser evidence remains required for #249 |
Alternative considered: derive Cash from account codes or linked bank accounts. It is easy to display but misclassifies noncash or restricted balances and is not stable under renamed accounts. Alternative: aggregate all account rows in the browser. It duplicates SQL sign/currency/policy rules and can mix pages or revisions. The proposed server-owned classified subset preserves the existing ledger/report boundary, at the cost of a policy workflow and extension.
Named acceptance evidence
The fixed independent values in Position sources
are review fixtures, not generated expectations. First-slice acceptance in #249
must name tests for: exact server-string totals and comparison mapping
(PositionOverview fixed values); max-four scheduling and queued completeness;
current membership and per-request denied/global identity results; independent
book revision/date/currency metadata; partial failure without zero substitution;
valid zero versus unsupported policy, without inferring no posted entries;
stale/scope-change late-response rejection;
no cross-book total or client financial arithmetic; and direct top navigation
with explicit scope/date handoff. Browser screenshots at desktop and 390px must
show approved type, row bands, keyboard labels and readable signed changes.
These are required acceptance cases, not claims of existing test coverage.
Deferred extension tests are TestPositionCashPolicy (membership/version and
classification), TestPositionSourceExclusion (unposted observations/commands),
and TestPositionBounds (policy, precision and response caps). Existing reporting
SQL/HTTP tests remain the authority for exact totals, single-book comparison,
revision checks and current authorization. Owner visual approval does not approve
cash policy, real-book accounting, FX, consolidation, or live use; #1/#59 remain
separate dependencies for those operations.