Build backend financial intelligence engine

[danbuildss]

Summary

Implements the backend financial intelligence layer on top of the conservative truth foundation merged in PR #200.

Economic action reconstruction

• Groups source classification events by agent, chain, and transaction.
• Reconstructs direct payments, internal transfers, swaps, bridges, refunds, owner funding, loans, collateral activity, protocol income, expenses, and unknown actions.
• Excludes swaps, bridges, internal transfers, funding, loans, and collateral from revenue recognition.

Commercial evidence and recognition

• Adds commercial events and deterministic payment allocations.
• Adds an authenticated endpoint for linking an economic action to an invoice, task, API request, subscription, settlement, deliverable, refund, or dispute.
• Requires a customer reference and completed delivery before service revenue is recognized.
• Treats undelivered payments as deferred revenue and unsupported wallet inflows as candidates/unresolved.

Double-entry accounting

• Adds journals and journal lines.
• Posts cash/revenue, cash/deferred-revenue, and refund reversal entries.
• Enforces balanced journals in application code and through a Postgres assertion function.
• Avoids duplicate journal posting when the processor is rerun.

Evidence, anomaly detection, and publication

• Separates evidence grades A/B/C/D/U from recognition status.
• Flags related-party payments, material unresolved flows, and refunds for review.
• Produces deterministic SHA-256 financial snapshot hashes.
• Publishes only explicitly published snapshots through the public financial-intelligence API.

APIs

• POST /api/admin/financial-intelligence/process
• POST /api/admin/financial-intelligence/commercial-events
• GET /api/v1/financial-intelligence/[slug]

Database

Adds:

• economic_actions
• commercial_events
• payment_allocations
• financial_journals
• financial_journal_lines
• financial_anomalies
• financial_snapshots

Migration: supabase/migrations/20260724000001_financial_intelligence_engine.sql

Validation

• 12 focused financial truth tests pass.
• TypeScript typecheck completed successfully and proceeded to the production build.
• Production build was started after typecheck; final build status was still pending when the PR was opened.

Rollout

1. Apply the included Supabase migration.
2. Deploy the backend.
3. Run the financial processor for each agent and reporting period with publish: false.
4. Submit commercial evidence for candidate payments.
5. Reprocess and inspect journals/anomalies.
6. Publish approved snapshots with publish: true.

Scope

Backend only. No frontend or existing product UI changes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
zetta	Ready	Preview, Comment	Jul 24, 2026 3:51pm