Docs

justin-napolitano/jayburd-bookkeeping / docs/contracts/position-read-model.md

Position read model — proposed for #248

Synced 2026-11-04 · Updates are made in the source repository.

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 lineExact functional-currency expressionExisting 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 historytotals.unclosed_earnings; derived, never a journal
Book equityDirect equity + unclosed earningstotals.total_equity; comparison change is server-supplied
CashΣ N(a) for a reviewed, versioned set of asset account IDs CExtension required; no existing cash classification
Other assetsTotal assets − CashExtension 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.

ConditionRequired result
No readable books / valid authorized book returning zero totalsEmpty workspace state / exact-zero row; no inference about posted-entry count
Unknown or inaccessible scope404 with no totals or existence hint
Missing credentials / read grant denied401 / 403 with no financial body
Revision changed between views409 report_snapshot_changed; discard old evidence and offer explicit refresh
Unsupported policy, overflow or timeout422 / 503, no partial totals or substitute zero
Stale source statusKeep 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 decisionOwner and condition
Cash account membership and change control, including restricted cash and cash equivalentsOwner/accountant under #1; approve policy/version and tests before a Cash total ships
Real entity basis, opening balances, FX/close semanticsOwner/accountant #1/#10/#59 before live use
Attention sources, thresholds and priorityOwning acquisition/command contracts plus owner workflow review
Position labels, scope and first-screen orderOwner 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.