# Revenue metrics: the contract

Every revenue number Bucker returns names the definition it was computed under. The definitions
are data, published as versioned files with a sha256 and an effective date, in
`@bucker/shared/analytics/metric-contracts`:

| File | Defines |
| --- | --- |
| `revenue-v1.json` | MRR, ARR, the MRR bridge, active customers, customer and revenue churn, ARPU, LTV, gross revenue, refunds, fees, net revenue, deferred revenue, and the currency policy |
| `web-v1.json` | pageviews, visitors, sessions, bounce rate, conversion rate |

A published contract is **immutable**. Changing a word changes its sha256, which a test pins, so a
change is a new file (`revenue-v2.json`) with a new effective date. Every read states the contract
name, version and sha256 beside its figures. A contract is exportable in MetricFlow's
semantic-model shape (`toSemanticModelYaml`); a converter for other formats is not built.

## The definitions that are easy to get wrong

- **MRR** is each account's recurring charge normalised to one month (annual / 12, quarterly / 3),
  net of recurring discounts, excluding tax, one-off charges and usage overage. ARR is 12 x MRR.
- **The bridge** splits a month's change in MRR, per account, into five movements:

  ```
  start + new + expansion + reactivation - contraction - churn = end
  ```

  `new` is an account with no MRR ever before; `reactivation` one that had MRR earlier, none at the
  start of the month and some at the end. The identity is checked for every month in integer minor
  units and a residual other than zero is refused with an error naming the month, never rounded.
- **Churn** is a rate of accounts (customers lost over customers at the start) or of revenue
  ((churn + contraction) over start MRR). Both are null when the start is empty, not zero.
- **LTV** is ARPU divided by customer churn. It is **null below 30 customers** at the start of
  the month and **null at zero churn**; a number there would be believed and is noise or infinity.
- **Net revenue** is gross minus refunds minus fees. A source that reports no fees yields
  `feesKnown: false`, not a zero fee.
- **Currency.** Amounts convert at the rate of the day they occurred and the rate version used is
  stored. An amount with no rate for its day is **excluded and counted** (`unconvertible`, with
  the currencies), never read as zero.

## Reading it

`readMrrBridge` (`domain/src/modules/web/revenue/bridge.ts`) reads `account_revenue_days` and returns
at most 24 months, each with its identity checked, plus an optional breakdown by plan and the
unconvertible count. It is **aggregate-only**: no account key leaves it. It is an end-user read, so
it refuses with `analytics_not_enabled` (422) and touches no table while the project's PA-01 gate is
shut. A month's opening and closing figures are snapshots: the latest row on or before the month
boundary, so an account the daily rollup did not touch keeps its last known MRR, and a churn is a row
with zero MRR. The running month's end is the day of the read and is marked `closed: false`.

## What is and is not stored

Stored: keyed pseudonyms of the paying account and subject, a hashed vendor customer reference,
amounts in minor units with currency, the base-currency amount and the rate version, product and
plan ids, service period, timestamps. Not stored: a name, an email, an address, a card number, last
four digits or brand, or any raw vendor identifier. A test scans the revenue tables' columns for
these.
