A03 — Shared financial projection readers

Status: blocked. Updated: 2026-09-06. Assigned agent: unassigned. Implementation PR: none.

Issues and acceptance covered

#51. The acceptance boundary is the implementation scope and completion checks below; see the issue acceptance matrix for parent coverage. Shared definitions: financial contract; proof anchors: evidence index.

Dependencies and blockers

A01 and accepted #31/#33/#37/#53/#54/#55/#56/#59 source contracts, plus #58 success/release event semantics. Provider production enablement is separate; source models/fixtures must exist. D-02/D-03/D-05 constrain affected amounts/backfill.

Repository and expected files

Backend: proposed src/utils/analytics/financial.ts, legacyCoverage.ts, contracts/tests. Read landed upstream services/tables; do not create or rename their schema. Read existing Payout/PayoutItem only through compatibility adapter.

Existing behavior and verified gap

No funding/earning/hold/allocation ledger exists. Mutable calculator results, legacy paid flags, approved items and Float totals mix in routes. Sponsor has a bounded recorded-gross adapter with limited legacy detection (E01/E03/E06/E10).

Proposed implementation boundary

Build exact shared read projections for creator/submission/campaign and balances at one snapshot; funding receipts versus allocations; CPM spend versus RPM expense; disjoint positions; confirmed gross/net paid and recovery. Aggregate facts before one-to-many joins. Legacy adapter exposes provable actual records and unattributed/undated coverage, never reconstructed earnings.

Expected API / data contract

Internal versioned projection result used by later routes: exact named fields from financial-contract, source watermark/asOf and component coverage. No HTTP or money-writer behavior changes; no cache yet unless scope/isolation demonstrated.

Required tests

A01 fixture against real disposable source records; sums across creator/submission/campaign; multiple operations/holds/attempts without fanout; signed corrections/recovery; same rate edit after posting; deleted/denied historic source; legacy missing allocations/date; large exact values; RepeatableRead concurrency snapshot.

Suggested agent tier

Smart model owns all calculations, source choices, query isolation, schema interface acceptance and integration review. Lower-cost fixture loading only after expected totals are fixed.

Expected PR boundary and reason

One backend domain/read-adapter PR, stacked on source schema/services and A01. No route or frontend bundle. Unlocks A04/A05/A06/A08/A09/A10. Keep compatibility additive, avoid unrelated cleanup, and list exact stacked commits and later units unlocked in the PR. If observed scope grows beyond this boundary, update the plan before splitting or adding work.

RBAC requirements / TODOs

Caller must pass server-validated scope; return a deliberately narrow projection. TODO(RBAC): Cross-creator financial readers may be called only behind the approved financial-view boundary; preserve existing guards at every later adapter.

Completion and reconciliation checks

Exact sums and state conservation pass; no raw views/current rate determines an amount. Unknown legacy coverage remains visible. Queries never mutate facts, reserve money, invoke a provider or treat approval as success.

Record actual tests, source schema/contract versions, PR/merge SHA, manual evidence and residual coverage before changing status to review/complete. Any unexpected migration must first satisfy the migration gates; never bundle upstream financial writer work into this analytics unit.