Rating v1: turn metered token counts into money (the revenue path)

[hhuuggoo]

What

The rating system — turns raw billing_event token counts into money. This is the piece between "we metered tokens" and "a neocloud can send an invoice." Per Wendy's PM assessment, this was the #1 revenue blocker (Phoebe metered but did not bill).

Mechanism only — Hugo sets the actual prices later, as data, not code. The rating system is reversible and buildable now; the prices are the one-way commercial door, decoupled.

Money correctness (treated like auth — go deep, it's expensive to be wrong)

• Integer micro-USD everywhere, never float. cost_micro_usd int64 (1e-6 USD). 1 Atlas hourly_usage_record unit = 100 micro-USD.
• The billable-prompt formula (the highest-risk line): vLLM's prompt_tokens is the TOTAL, cached_tokens the cache-hit SUBSET. Each prompt token is charged exactly once: billable_prompt = prompt_tokens - cached_tokens at the prompt rate, cached_tokens at the (discounted) cached rate. Charging the naive prompt*prompt_rate + cached*cached_rate would overbill every cache hit — guarded + tested by name.
• Effective-dated prices — an event rates at the price effective at its event_ts; rating "now" never retroactively reprices old traffic.
• Idempotent — rollups upsert on (auth_id, model, window_start); re-rating a window reconciles, never doubles.
• Fail loud, never $0 — a model with no price → ErrNoPrice, counted, logged ERROR, dropped from rollups (not silently $0-billed). Rater exits 2 so a CronJob alerts.
• Unattributable rows are counted, not silently dropped — billing_event rows with NULL auth_id/model are counted + surfaced + trigger exit-2 (a nonzero count means an upstream billing-gate leak). This closed a silent-loss gap found in review.

Schema

• model_price — effective-dated price book (prompt/cached/completion micro-USD per token). Tables only; no prices in the migration.
• rated_usage — hourly rollups per (auth_id, model, window_start), unique-keyed for idempotent upsert.
• migrations/seed_example_prices.sql — clearly NON-BINDING placeholder prices (do not ship to prod).
• Alembic chained after billing_event (down_revision = b1f0c2d3e4a5), following the drainer's migration-ownership pattern.

Code

• internal/rating: pure Rate() money core, effective-dated PriceBook, Rater.Run(window), Store (+ Postgres impl).
• cmd/rater: one-shot batch job (run by a k8s CronJob), --since/--until, default = last complete hour. Exit 0 / 1 (fatal) / 2 (rated but anomaly: unpriced or unattributable).

Base

Targets postgres-drainer (reads its billing_event table). ~36 tests, every money rule named, race/lint/fmt clean, zero new deps.