# Billing Architectural Invariants v1

## Purpose

This is the short PR review checklist for billing changes. The full domain model
lives in `doc/architecture/Billing_Platform_Overhaul_v1.md`.

## Invariants

1. Ledger entries are immutable. Corrections are new entries.
2. Balance is derived from ledger entries; never add or update a mutable balance
   source of truth.
3. Usage capture, rating, ledger posting, invoicing, payment collection, refunds,
   disputes, budgets, and delinquency are separate concerns.
4. Rating outputs are not ledger entries until an explicit posting step.
5. Pricing mode, unit price, currency, region, service/SKU context, and pricing plan
   version are snapshotted onto the billable runtime or rated line.
6. Historical charges are not re-rated by mutable catalog or policy changes.
7. Money uses integer minor units plus ISO-4217 currency. No floating point money.
8. Cross-currency presentation requires an FX snapshot. Historical entries are not
   revalued when FX rates change.
9. Tax/VAT context is snapshotted onto invoice evidence. Tax corrections are additive.
10. Every billable record resolves to tenant, project, resource, usage unit, region,
    and correlation context; app and managed-ingress usage also preserve their
    domain-specific attribution anchors.
11. Shared resources bill to the owning tenant/project while preserving submitter
    identity for chargeback where known.
12. Reseller/channel billing is a rating/invoice layer above raw tenant usage, not
    tenant impersonation.
13. Privileged finance mutations write audit with correlation ID.
14. Idempotency is mandatory for billing, payment, refund, rating, and posting retry
    paths.
15. Budget and delinquency decisions are policy-driven and visible; destructive
    enforcement must not be hidden inside worker loops.
16. Provider payment, refund, dispute, and webhook handling is idempotent by provider
    event/session/reference identity.
17. Workers expose lag, queue depth, failed item count, and oldest unprocessed item.
18. Raw high-volume usage may be compacted only after invoice/dispute evidence
    requirements are satisfied.

## Review Questions

1. Does this change touch money, rating, ledger, payment, refund, invoice, budget, or
   delinquency behavior?
2. Does the OpenAPI contract change first where API behavior changes?
3. Does the change preserve immutable ledger and additive correction behavior?
4. Are currency, tax, and pricing snapshots explicit?
5. Are tenant/project/resource/submitter attribution fields preserved?
6. Are retries idempotent and tested?
7. Are privileged mutations audited?
8. Are real Postgres tests present where JSON metadata, numeric precision, or
   polymorphic bind typing could fail?