Metering & Rate Card
Every metered surface flows through the gateway (the single chokepoint) and settles against the caller's prepaid wallet. This page is the shared vocabulary the surfaces were missing: for each one, who pays, at what rate, and by which mechanism. Rates are configurable via environment variables; the values below are the defaults.
Mechanisms#
Two settlement mechanisms, chosen by op size:
- Escrow (per-op). High-value or unbounded-duration ops place a hold that
bounds the spend before running, then capture the actual cost on completion
(
placeHold→captureHold/releaseHold,packages/ledger/src/escrow.ts). A crash releases the hold via the periodic sweeper. Used by AI completions and file uploads. - Accumulate-and-flush (sub-threshold). Costs too small to justify a ledger
write per op accrue in memory per
(payer, app, opType)and flush one transaction when they crossDB_USAGE_FLUSH_THRESHOLD_MICRO(default $0.01) or on the periodic sweep (meterUsage,packages/ledger/src/usage.ts). Used by DB ops and file egress.
Rate card#
| Surface | Op | Payer | Rate (default) | Mechanism | Env override |
|---|---|---|---|---|---|
| AI | chat completion | caller | OpenRouter's own per-token rates (prompt + completion) × 1.25 margin | escrow (ai_call) | — (upstream) |
| Database | read / write | private → user; resource-owned → resource payer policy; creator-owned → actor | per-op micro-USD (see pricing.ts) | accumulate-and-flush (db_usage) | — |
| Storage | upload (at-rest) | private → uploader; resource bucket with payer:"owner" → resource owner; else uploader | 0.0001 micro-USD/byte, one-time at upload | escrow (storage_write) | OSGARDEN_STORAGE_WRITE_MICRO_PER_BYTE |
| Storage | download (egress) | the fetching session | 0.00009 micro-USD/byte | accumulate-and-flush (storage_egress) | OSGARDEN_STORAGE_EGRESS_MICRO_PER_BYTE |
At-rest storage: the v1 model#
Object storage has an ongoing at-rest cost (bytes sitting on disk cost money
every month), but osgarden currently charges it once, at upload time, as a
per-byte storage_write capture. The write rate is padded so it amortizes the
expected retention cost of a stored object.
The recurring GB-month sweep is deferred (post-v1). A correct recurring
accrual needs machinery that does not exist yet: a periodic sweep sizing every
owner's stored bytes, pro-rating partial months, crediting deletions, and
re-pointing the payer when ownership transfers (retain/account-deletion). Until
that lands, the padded one-time charge is the whole story. The storage_write
and storage_egress ledger op types already exist, so adding the sweep later is
additive — no schema change.
Invariants (from ROADMAP.md)#
- Single chokepoint — no resource is reachable except through the metered gateway, or metering leaks.
- Escrow before use — every escrowed op holds funds before running and captures on completion.
- Stripe only at top-up — usage never touches Stripe; it settles against the prepaid balance.