Finance Data, API, Roles, and Controls

Authority boundary

The browser presents state and submits intent. The Partner API and database own authorization, partner/event scope, current version, lifecycle transition, exact-money calculation, journal posting, locks, idempotency, leases, and audit time. Hidden controls are not authorization.

Reads and writes use authenticated partner scope. Each mutation rechecks its capability and validates identifiers belong to the same partner and, where required, event. High-risk actions can require recent authentication. Service-role database routines are not callable by ordinary browser roles.

Role and capability matrix

Role	Typical reads	Typical commands	Prohibited by default
Finance viewer	Overview, events, permitted details	None	Create, approve, pay, close, configure, export sensitive data
Finance operator/maker	Operational registers	Draft/create, submit, import preview, match, count	Approve own request, close, provider admin
Finance approver/checker	Submitted records and evidence	Approve/reject within threshold	Approve own work, alter posted journal
Payer	Approved/scheduled outflows	Mark paid/settle with evidence	Approve own request unless policy explicitly permits and is independently reviewed
Reconciler	Statements, journal candidates	Match/classify/commit	Reconcile own unsupported adjustment without checker
Custody participant	Assigned sessions	Acknowledge, count, handover/return	Act as both required parties
Finance administrator	Settings, automation, integrations	Configure within policy and version	Read back secrets; bypass journal/lock/audit controls
Auditor	Broad receipts and exports	Integrity/export operations	Operational mutation
Platform administrator	Platform support projections	Controlled recovery/configuration	Use platform status to impersonate an accountable finance actor

Actual capability names and thresholds come from the server contract. Least privilege, event scope, sensitive-field redaction, and prohibited combinations must be reviewed during deployment.

Exact money and currencies

Canonical commands use an exact decimal string or integer minor units as defined by the endpoint. Every amount carries ISO currency. Negative values are limited to named correction/credit contexts. Authoritative aggregates remain grouped by currency unless a response includes conversion source, rate, timestamp, and rounding policy.

Core formulas:

Value	Formula
Book cash	Opening cash + posted cash debits − posted cash credits
Available cash	Book cash − restricted cash − approved pending outflows
Event book net	Posted event inflow − posted event outflow
Payable outstanding	max(0, gross − credits − valid payments)
Receivable outstanding	max(0, gross − credits − collections − approved write-off)
Budget available	Original + revisions + transfers in − transfers out − actual − commitments
Custody expected	Opening + paid in + positive adjustments − paid out − safe drops − negative adjustments
Custody difference	Counted − expected
Statement difference	Statement closing − cleared book balance

Every displayed KPI must disclose scope, included/excluded states, source, cutoff, timezone, currency, rounding, and freshness. See the certification handbook for the full oracle and test evidence.

Journal and lifecycle integrity

Posted entries and lines are immutable. Reversal/correction creates a linked balanced journal with a reason and actor. Domain records retain their own lifecycle while posting through one accounting boundary. Period close blocks later posting until an authorized audited reopen/correction path succeeds.

Maker-checker, threshold, custody dual control, optimistic version, active lease, and idempotency rules are enforced transactionally. Valid retry with the same idempotency key and payload returns the original canonical result; reuse with a different payload is a conflict.

Evidence and privacy

Uploaded evidence is stored in Sanity only. Postgres retains operational metadata such as opaque asset reference, checksum, media type, scan/quarantine state, retention class, supersession, and audit links. Clients receive an opaque artifact ID or authorized proxy path. Raw Sanity URLs, Supabase Storage paths, arbitrary external evidence URLs, provider secrets, bank credentials, and internal SQL errors must not appear in browser responses, exports, logs, or docs.

Access to evidence is purpose-bound, short-lived, redacted by role, and audited. Quarantined, unscanned, expired, or wrong-partner evidence blocks use.

API behavior

Current Finance coverage includes 54 API contracts. The corrective slice adds authoritative event/currency snapshots and audited cash-account administration. Complete strict runtime schemas, generated OpenAPI, uniform Problem Details, router decomposition, saved views, and asynchronous exports remain part of API TASK038 and are not represented as finished here.

Every mature endpoint should document:

• method/path and authenticated partner/event scope;
• required capability and recent-auth requirement;
• path/query/body schema, unknown-field behavior, limits, and cursor sort binding;
• exact money, currency, date/time, cutoff, version/ETag, and idempotency semantics;
• canonical success, field error, conflict, lock, denial, unavailable, and retry responses;
• journal, audit, evidence, notification, integration, and export side effects.

Error and recovery contract

Condition	Required response	Operator action
Validation	Field-specific error; no partial write	Correct named fields and submit again
Missing capability/scope	Denial without sensitive existence leak	Confirm active partner/role; request authorized help
Stale version	Conflict with current safe projection	Refresh, compare, and intentionally reapply
Locked period	Lock owner/period and permitted correction path	Stop posting; request controlled reopen/correction
Maker-checker conflict	Required independent role/action	Assign a different authorized checker
Duplicate/idempotency replay	Original result or payload-conflict response	Inspect receipt; do not create a second record
Provider failure/revocation	Redacted provider class and retryability	Reauthorize or retry from job detail when safe
Evidence quarantine/expiry	Opaque state; no provider URL	Replace/review evidence through authorized flow
Lease conflict	Current safe job/session state	Wait, reclaim after expiry, or escalate stale lease
Rate/unavailable	Retry timing and correlation ID	Preserve intent/idempotency; retry after guidance

Unexpected errors require a stable correlation ID and safe generic detail. Secrets, stack traces, SQL, and raw provider bodies stay server-side.

Current local evidence and open gates

Local certificates pass 14 routes, 18 modal controls, five workflows, six screenshots, 13 dialog families, eight accessibility contracts, 29 calculations, 10 mutations, deterministic 16-way contention, one-million-row aggregation, logical restore digest, 40,000 API property cases, provider contract fixtures, operational lifecycle checks, security-hardening checks, and TypeScript.

Still required: disposable linked database/Worker execution, additive migrations and RLS/query plans, hosted authenticated mutation/readback/cleanup, real Telegram/Discord and bank/accounting sandboxes, native restore, 390 px and additional-browser evidence, deployment receipts, and named independent review.