feat(usage): add the Plane-A token-usage store (RIG-2872)

[rigel-mintaka]

This PR is part of a stack containing 3 PRs:

1. main
2. "feat(usage): add the Plane-A token-usage store (RIG-2872)" (this PR)
3. feat(usage): record compute-usage intervals with the session binding (RIG-2872) #1509
4. feat(usage): derive compute-usage rollups and prune the raw compute log (RIG-2872) #1513

Summary

Adds the Plane-A token-usage store that the LLM gateway's usage events will be written into. This is the token-usage half of the observability record's T1. The compute-usage (billing) event is left out until its unit is decided (RIG-4046).

• go/internal/usage:
  • TokenUsageEvent (the gateway record's field set, with micro-USD money).
  • The Store interface: append, series, rebuild and prune.
  • NewMemory, the in-memory reference.
  • usagetest.Run, one contract suite that runs against both backends.
• Postgres (new migration 0002_token_usage.sql; 0001_init.sql is frozen because migrations are append-only per RIG-4077):
  • token_usage_events is append-only, keyed (tenant_id, id). A retried batch is ignored.
  • token_usage_rollups_hourly and _daily are incremented only from newly inserted rows, and can be rebuilt from the log.
  • All three tables are under the tenant_isolation RLS policy. 0002 repeats 0001's RLS, grant and trigger loop bodies for these tables.
• Migration number: fix(auth): scope bearer callers to their token's tenant (RIG-4066) #1375 also adds a 0002. The runner rejects a gap or a duplicate, so whichever PR merges second renumbers to the next free version.
• Retention:
  • A daily sweeper deletes raw events older than --usage-event-retention (or $COMPASS_USAGE_EVENT_RETENTION). The default is 90 days, and 0 disables the sweeper. The rollups are kept.
  • A global prune horizon, which only moves forward, stops a rebuild from wiping rollups for days whose events were pruned.
  • The prune advances the horizon, then deletes each tenant's events in that tenant's own RLS-scoped transaction. It does not use the BYPASSRLS system role, so DL-315's list of loops is unchanged.

Tests

• usagetest (11 cases) passes on memory and on Postgres. The cases cover: re-append counts once, mixed batches, UTC hour and day boundaries, filters, empty range, ordering, rebuild after cleared rollups, prune keeps rollups, tenant isolation, and invalid events and queries.
• The suite was red against a stub backend before the implementation.
• TestRetentionSweeper*: prune at start and then daily, a failed prune is retried, and a 0 window disables the sweeper.
• TestOpenUpgradesV1DatabaseToTokenUsage opens a database that stopped at v1 and checks that Open migrates it to v2 with RLS forced, the horizon row seeded, and tenant-scoped reads. It fails without 0002.
• Store RLS and updated_at pgtests, and the serve boot and shutdown pgtests, all pass. squawk and sqruff pass on 0002.
• Lint, vet and sqlc-drift are clean.

Refs RIG-2872

[trunk-io]

😎 Merged successfully - details.

[linear-code]

RIG-2872

[github-actions]

Compass engineering docs preview: https://compass-server-rig-2872-toke.compass-eng-docs.pages.dev

Deployed from compass-server/rig-2872-token-usage-store at 95edbd7.

Changed pages:

• docs/self-host.md