Add revenue usage reconciliation

[Arthurescc]

Issue

Closes #20

@algora-pbc /claim #20

Summary

Adds a focused revenue usage reconciliation module for issue #20. This is distinct from the existing billing/ledger/entitlement submissions: it validates whether subscription quotas, top-ups, compute usage, invoice totals, and analytics licensing exports reconcile cleanly before a billing cycle is closed.

Demo

• Demo GIF: revenue-usage-reconciliation/docs/demo.gif
• Text demo transcript: revenue-usage-reconciliation/docs/demo-transcript.md
• CLI demo: cd revenue-usage-reconciliation && npm run demo

The CLI demo shows one clean lab account, one undercharged institution, one unsafe analytics export, high-risk account reporting, and a stable audit hash.

Acceptance criteria mapping

• Tiered subscriptions: plan quota, included price, and overage rates are modeled.
• AI compute billing: usage is aggregated by capability with billable and non-billable units.
• Top-ups and quotas: top-up units are applied before overage calculation.
• Institutional invoices: invoice totals are reconciled against expected entitlement and usage charges, including undercharge and overcharge/refund-risk paths.
• Licensing APIs/analytics: anonymized export safety checks flag private fields and unsafe exports.
• Revenue health reporting: totals, anomaly counts, high-risk accounts, audit hash, and entitlement regression matrix are produced.

Detailed mapping: revenue-usage-reconciliation/docs/issue-20-requirement-map.md

Verification

cd revenue-usage-reconciliation
npm run check
npm test
npm run demo
cd ..
git diff --check origin/main...HEAD

Local results:

• npm run check passed
• npm test passed: 7 revenue reconciliation tests
• npm run demo produced needs-revenue-ops-review, anomaly count 2, and audit hash 0a6048212d3a7a4bfd089d785abb47846b2181a37845d43dae3cb20ee45db8cb
• git diff --check origin/main...HEAD passed

AI-Assisted Disclosure

This contribution was produced with AI assistance and manually reviewed/verified before submission.