A01 — Financial contracts and reconciliation fixtures

Status: in review. Updated: 2026-09-06. Assigned agent: smart analytics owner, with bounded fixture/test agents. Implementation PR: backend #78.

Issues and acceptance covered

#51, #52. 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

Existing exact rate domain is verified. No external producer must land to write pure fixture contracts. D-01/D-02 policy values remain parameters, not guessed defaults.

Repository and expected files

Backend: proposed src/utils/analytics/contracts.ts, fixtures.ts, focused *.test.ts; reuse src/utils/rates/domain.ts without rewriting it. Update this project folder with agreed producer interfaces.

Existing behavior and verified gap

Rates exist, but no shared financial read contract or cross-view reference fixture exists. Current routes disagree on amount basis and status meaning (E01–E08).

Proposed implementation boundary

Define exact money/scope/coverage/time DTOs and pure reconciliation functions over synthetic facts. Encode the hand-calculated two-campaign fixture, state partitions, gross/net distinction and group union semantics. No Prisma models, route wiring, new writers or provider calls.

Expected API / data contract

Propose contractVersion: 2, decimal-string amounts, scope/window/timeBasis/asOf, per-measure coverage and distinct financial components. Publish interfaces for funding, observations, earnings, holds, allocations and review events; no production endpoint changes.

Required tests

Independent expected constants for campaign 100/30/70, 40/12/28 and expense/state totals; exact rate/cumulative rounding, partial allocation, multi-hold de-duplication, post-payment recovery separation and scope mismatches. Add consumer-shape assertions without mirroring implementation arithmetic.

Suggested agent tier

Smart architecture owner implements/reviews contracts and financial fixtures. A lower-cost agent may expand already-decided fixture combinations and documentation links.

Expected PR boundary and reason

One contract/test-only PR. A narrow foundation can merge independently and unlocks A02–A17 and upstream interface agreement. Refs #51/#52; no issue-closing keywords. 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

No new routes. TODO(RBAC): Carry explicit caller/creator/campaign scope in read contracts so cross-creator finance requires its separately approved capability; a caller-supplied creator ID alone is not authority.

Completion and reconciliation checks

All fixture totals reconcile independently; no unresolved product value becomes a default. Mark interfaces stable with date and reviewer; later producer mismatch returns to this contract rather than a route-local workaround.

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.

Implementation evidence

• Branch/commit: feature/analytics-financial-contracts at b554f973b05d09306597a89b59640b41321a29bd, based directly on backend dev at 226381b.
• Frozen v2 implementation: src/utils/analytics/contracts.ts; independent reference fixture: src/utils/analytics/fixtures.ts. Contract version 2, USD six-scale decimal strings, explicit scope/window/as-of, per-measure coverage, and persisted producer interfaces are reviewable in PR #78.
• Reconciliation evidence: 13 contract tests and 10 fixture tests passed. Existing rate domain/history/migration suites passed. Targeted strict TypeScript validation passed; full npm run build passed after refreshing the ignored generated Prisma client from the sibling main worktree, whose schema and package lock hashes matched exactly.
• Covered variants: A 100/30/70, B 40/12/28, creator/campaign/platform agreement, cross-campaign payout allocation, unknown reservation, released history, multi-hold de-duplication, gross/net fee and withholding, referral exclusion, post-payment recovery, overlap union, partial/unavailable coverage, source replay rejection, exact rate provenance, segment rounding, and a named synthetic sub-cent policy fixture.
• Compatibility/security: additive contract only; no route, schema, migration, writer, provider, or central RBAC change. The contract carries an authorized caller and target scope with the required TODO(RBAC) attachment marker.
• Residual gate: do not mark complete until PR #78 is reviewed/merged. A02 may stack pure reader/legacy-adapter work on #78; authoritative observation time/status modes still require #37/#41/#42.