A08 — Risk and held-liability analytics API

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

Issues and acceptance covered

#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

A01/A03 and #55 durable evaluation/hold/resolution/recovery contracts; #59 allocation status to distinguish held/reserved. Policy D-01/D-02 resolved by owners where necessary.

Repository and expected files

Backend: proposed src/utils/analytics/risk.ts, dedicated protected risk analytics router/tests; read #55 facts and A03 positions; narrow existing payout-review read integration only.

Existing behavior and verified gap

PayoutItem badges and manual decisions exist but automatic badges do not block bulk approval. No durable evaluation/hold table exists. Current FLAGGED can mean tracking failure, not fraud (E12).

Proposed implementation boundary

Count unresolved signals and affected submissions/creators separately from unique held amount; breakdown by rule/version/platform/campaign, resolution history and unknown input coverage. Include uncertain payout operation counts through payout producer without interpreting uncertainty as proven fraud. No rule execution or hold mutation.

Expected API / data contract

Risk DTO with bounded evidence references, reason categories, rule version, open/resolved counts, exact unique held liability, recovery overview if permitted, scope/asOf. Exclude raw provider payloads and unrestricted account data.

Required tests

Two holds on one entry count signals twice but money once; partial entry held; resolved then re-evaluated; unknown metric; reserved-versus-held precedence from producer; postpaid recovery separate; no badge-to-hold fallback; authorization/redaction.

Suggested agent tier

Smart model owns money/signal distinctness and security review. Lower-cost agent may wire endpoint/serializers and expand decided rule fixtures.

Expected PR boundary and reason

One risk aggregate read PR, stacked on A03/#55/#59. Unlocks A15. Fraud workflow/rules and transfer gates remain separate prerequisites. 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

Preserve existing payout-review/moderation protection according to mounted resource; no weaker combined guard. TODO(RBAC): Require approved fraud-evidence and cross-creator held-finance access for these reads; reasons and compensation are sensitive internal data.

Completion and reconciliation checks

Risk held amount equals A03 held positions for same scope; signal count can differ and is labelled. Resolving one of several blocking holds does not release all held liability in the read projection.

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.