[design] The usage ledger records value, not charge — add payer attribution

[serge-ivo]

The confusion this exists to end

A delegation was refused with "the $50.00 daily spend limit has been hit". The user went to
platform.claude.com to see the $50 — and found nothing, because no money had been spent. The
engine had been running on their Claude subscription.

Chasing that took an hour and produced a wrong first answer from me, twice. The reason it was
hard is not a bug in one function. It is that the ledger has no column for who pays.

The model we have

ai_usage records tokens and one cost_micros, plus cost_source (migration 0080): 'reported'
when Claude Code computed the figure, NULL when we did.

That axis answers "whose arithmetic produced this number?" — a minor provenance detail. It was
then used everywhere as if it answered "is this number money?", which it does not, and which
nothing in the schema answers at all.

What the vendor documentation actually says

From Manage costs effectively (Anthropic, current):

Claude Code computes the dollar figure locally from token counts priced at standard list
rates, so it doesn't reflect promotional pricing or contracted discounts and may differ from
your actual bill. For authoritative billing, see the Usage page in the Claude Console.

Claude Max and Pro subscribers have usage included in their subscription, so the session cost
figure isn't relevant for billing purposes.

So total_cost_usd is the same kind of object as our own estimate — tokens × list price. It is
not a measurement of money, in any auth mode. And on a subscription it corresponds to no charge
at all.

Note also that subscription limits are not denominated in dollars: they are a rolling 5-hour
window and a weekly window, shared across Claude chat, Claude Code and Cowork. There is no
subscription number a dollar ceiling could ever be comparing against.

The model we should have

Three distinct facts, currently collapsed into one column:

Fact	Always true?	Have it?
Consumption — input / output / cache-read / cache-write tokens	yes	✅ stored
Notional value — tokens × list price, "what this would cost on the API"	yes, as an estimate	✅ cost_micros
Charge — money someone actually owes	depends on the payer	❌ missing

The missing thing is not a better cost number. It is payer.

payer:
  byok-api      — the user's own provider API key. Real money, their provider account.
  subscription  — a Claude/ChatGPT subscription. No marginal charge; draws a plan allowance.
  platform      — PAGS pays (Workers AI, platform models).
  unknown       — we could not determine it. Say so; never guess.

provider (anthropic / openai / platform) is the vendor, not the payer, and cannot
substitute: the same vendor is reached both ways.

With payer present, everything downstream becomes correct by construction rather than by
special-case:

• Dollar ceilings sum only byok-api. A circuit breaker for money stops counting things that
  are not money. (→ [bug] The $50 circuit breaker is denominated in dollars for work nobody is billed for — subscription engine usage blocks delegations #343)
• Subscription work gets bounded in its own unit — tokens over a rolling window — with its own
  message. Different resource, different number, different sentence. (→ [bug] The $50 circuit breaker is denominated in dollars for work nobody is billed for — subscription engine usage blocks delegations #343)
• Usage shows two figures that are never added together: "Billed to your API key (estimated)"
  and "Drawn from your Claude subscription". (→ [bug] The platform calls engine cost "measured" — Anthropic's docs say it is a list-price estimate #347)
• cost_source shrinks back to what it is: a provenance note about whose arithmetic ran, with
  no authority attached. Both values are list-price estimates.

Determining the payer honestly

resolveEngineAuth (packages/browser-runner/src/coding/engine-auth.ts:63) already derives
api-key / subscription / machine-login from the merged spawn env, and authResolved already
reaches the cloud on the capture snapshot (workers/api/src/routes/coding.ts:734) and in
diagnostics (:1680). It is displayed and then discarded — recordEngineUsage
(workers/api/src/lib/usage.ts:147) never receives it and the ledger row has nowhere to put it.
Persisting it is most of the mechanical work.

The honest gap: machine-login does not mean "subscription". It means neither credential was
in the env and the CLI used whatever login it has stored — which could be either. Mapping it to
subscription would be the same species of confident-but-unfounded inference this ticket exists
to remove, so it must map to unknown.

Which leaves a genuine design decision, and it should be taken deliberately:

• Treating unknown as billable is fail-safe against a surprise bill, but machine-login is the
  most common resolution (it is what auto produces), so this preserves today's bug for most
  users.
• Treating it as non-billable removes the false block but could let real API spend run unbounded.

Recommended: stop inferring and ask. A one-time per-machine declaration — "Claude Code on this
machine signs in with: ( ) my Claude subscription ( ) an API key" — is a fact the user knows for
certain and we cannot derive. Keep the env-derived signal as a cross-check and warn on
conflict, exactly as engineAuthWarning already does for mode-vs-resolved. Until it is answered,
unknown bounds by tokens (never blocked over money) and the Usage page says "payer not
established" rather than picking one.

One caveat to state in the UI rather than model: a subscriber drawing on usage credits is
being charged. We cannot detect that, so we should say we cannot, not imply we can.

Scope

1. Migration: ai_usage.payer TEXT (NULL = unknown, no backfill — pre-existing rows genuinely are
   unknown).
2. Thread authResolved → recordEngineUsage → the row. Platform-paid rows get platform; rows
   made on a vault provider key get byok-api (those we know for certain — we injected the key).
3. Per-machine payer declaration + conflict warning.
4. Consumers read payer, not cost_source.

Verification

• A row's payer is never inferred from machine-login; that resolves to unknown in the ledger.
• Summing cost_micros without filtering on payer is not done anywhere after this lands — a
  test asserting the dollar aggregate filters is worth more than the aggregate itself.
• A user with no declaration and a machine-login engine session is never blocked by a money
  limit, and can see on the Usage page that the payer is unestablished and why.

Related

• [bug] The $50 circuit breaker is denominated in dollars for work nobody is billed for — subscription engine usage blocks delegations #343 — the incident: the circuit breaker firing on non-money.
• [bug] The platform calls engine cost "measured" — Anthropic's docs say it is a list-price estimate #347 — the platform asserting engine cost is "measured" when the vendor docs say it is an estimate.
• [3P] Cost governance & abuse controls (gates the public open) #56 (cost governance), [3P] Metering → payout-ready (payouts built behind a flag, launch deferred) #57 (metering → payouts). Both consume this column; both are wrong
  without it. Payouts in particular must never pay out against notional subscription value.

[serge-ivo]

Assessment: mostly served by 6141dad + a9f4cd7. Not closing — two of the six verification points fail, and one of the four scope items should be dropped rather than built.

What already serves each acceptance criterion

Scope item	Served by	Where
1. ai_usage.payer TEXT, NULL = unknown, no backfill	✅	migrations/0092_ai_usage_payer.sql (+ idx_ai_usage_user_payer)
2. Thread authResolved → recordEngineUsage → the row; platform rows platform, vault-key rows byok-api	⚠️ partly	lib/usage.ts:187 maps it; recordPlatformUsage hardcodes 'platform', recordUsage hardcodes 'byok-api' with the right justification ("a payer we injected the credential for is one we know"). But only 1 of 4 engine call sites passes the observation — see below
3. Per-machine payer declaration + conflict warning	❌ not built	and should not be — see "What I would not build"
4. Consumers read payer, not cost_source	⚠️ partly	The two controls do (CHARGED_SQL in usage.ts:537,580,625; DAILY_TOKEN_CEILING beside DAILY_CEILING_MICROS). Five readouts still don't — see below

Verification	Result
A row's payer is never inferred from machine-login	✅ payerForEngineAuth returns null; usage-payer.test.ts pins it
Nothing sums cost_micros without filtering on payer; a test asserts it	❌ five unfiltered aggregates remain, and no such test exists
An undeclared machine-login user is never blocked by a money limit	✅ NULL ∉ CHARGED_PAYERS, and the token ceiling gives it a bound in its own unit
…and can see on Usage that the payer is unestablished, and why	✅ Usage.tsx:288-294 renders byPayer with the unknown note

Also worth recording, because it was the other half of the confusion: a9f4cd7/engine-metering.ts
makes an unmetered drive read as unmetered instead of as $0. Between the two commits the ledger
now distinguishes value from charge in both directions, which is the ticket's thesis. What is left
is smaller and different from what the ticket asks for.

Tested: the payer column is populated on one of four engine writes

recordEngineUsage has four call sites. Only routes/coding.ts:698 passes authResolved.
workflows/coding-session.ts:379 and :663 both drain /coding/capture, and the runner puts
authResolved on every capture snapshot regardless of drainUsage
(browser-runner/src/coding/runtime.ts:190) — so they hold the value and drop it one line before
the write. lib/usage.ts:164 justifies the optional parameter by naming "the Pilot's own capture"
as a path with no observation to pass; that is true of /coding/end and false of the Pilot.

The drain's own comment calls it "the only path collecting the Engine's own spend for the longest
and most expensive sessions the platform has" — i.e. the sessions shaped exactly like #343 record
payer = NULL. It does not re-open the incident (NULL is excluded from CHARGED_SQL), so this is
a defect rather than a design gap. Filed as #356; it is a two-line change and does not belong
in this design ticket.

Tested: the aggregate-filter criterion is unmet, but the fix is naming, not filtering

Dollar aggregates over ai_usage that still sum everything:

• lib/admin.ts:97 — per-user spend_30d_micros in the admin user list. Named "spend".
• lib/admin.ts:452 — platform-wide 30-day total. (:453 filters provider='platform', which is the vendor axis and only coincidentally tracks payer='platform'.)
• lib/external-usage.ts:134 — the external-vs-operator usage report.
• lib/stats-sources.ts:314 — the usageCost stat source agents publish to their own dashboards.
• routes/admin-instance-detail.ts:113 — the per-instance 30-day rollup.

The interesting part is that most of these should not filter. Sum-of-notional-value is a real
and useful quantity — "how much AI did this instance consume, in comparable units" — and filtering
it to charged rows would make an admin's view of a subscription-heavy user read as near-zero
activity, which is the mirror-image of #343's error. The rule that actually holds is narrower:

An aggregate that gates or pays must filter to CHARGED_SQL. An aggregate that displays
may sum everything, but then it may not be called spend, cost or bill.

By that rule the only one that is currently wrong on its own terms is lib/admin.ts:97
(spend_30d_micros), and the only one that is dangerous is lib/external-usage.ts:134, because
that report is the natural input to #57 (metering → payouts) and #56 (cost governance). Paying a
creator, or charging a tenant, against value drawn from somebody's Claude subscription is precisely
the failure the ticket says must never happen — and today nothing in that file mentions payer at
all, so the next person to wire it up inherits an unfiltered sum with an innocent name.

So the residual work is: rename the display aggregates to say value, filter the two that gate or
pay, and add the guard. The guard should be a naming ratchet in the shape of usage-claims.test.ts
— which already exists and already works this way — asserting that any SQL summing cost_micros
either contains CHARGED_SQL or is not bound to an identifier matching /spend|cost|bill|charge/.
That is enforceable by grep, and grep is the right instrument for a defect that regenerates by
being re-typed in a new file.

What I would not build: the per-machine payer declaration (scope item 3)

The ticket's recommendation is "stop inferring and ask" — a one-time per-machine declaration with
the env-derived signal kept as a cross-check. I'd drop it, for three reasons.

1. The control it proposes already exists, one level down. The engine preset's auth mode is
already auto | machine | subscription | api-key (lib/coding-engines.ts, console EnginesModal).
Choosing subscription injects CLAUDE_CODE_OAUTH_TOKEN and strips ANTHROPIC_API_KEY; choosing
api-key injects the vault key. Either resolves observably, so the payer stops being unknown —
not because the user asserted it, but because the platform changed what the process gets and then
watched the outcome. machine-login is what auto produces when the user has not used that
control. A declaration would be a second, weaker copy of a setting we already have: same question,
unverifiable answer.

2. Nothing load-bearing depends on the answer any more. That is what 6141dad bought. Unknown
is excluded from the money ceiling and bounded by the token ceiling, so a declaration changes one
label on the Usage page and no decision anywhere. Asking a user a question to improve a label is a
poor trade against the surface it costs — storage, an editor, a conflict-warning path, and the
support burden of a warning that fires on a mismatch the user cannot act on.

3. Where it would become load-bearing, self-report is worse than NULL. Under #57 the person
declaring "I'm on a subscription" is the person whose usage is being metered, and under #56 the
person declaring is the one being budgeted. A field the beneficiary supplies about their own bill
looks authoritative and is not; NULL is honest and forces the consumer to handle the case. The
ticket's own principle — "never guess" — cuts against accepting someone else's guess and storing it
in the same column as an observation.

The cheaper version of the same benefit, if the "Payer not established" label is judged too weak:
say on the Usage page and in the engine-auth report what to do about it — "set this engine's
sign-in to your Claude subscription or an API key and we'll be able to tell". engineAuthReport
already carries note and warning per session and already words the machine-login case
correctly; the missing sentence is the remedy, not a new fact.

Recommended remaining scope

1. lib/external-usage.ts:134 and lib/admin.ts:97 — decide charged-vs-value explicitly, and name
   the column accordingly. These are the two that feed money decisions.
2. The naming-ratchet guard test described above.
3. Drop scope item 3; add the remedy sentence to the Usage page / engineAuthReport instead.
4. recordEngineUsage drops the payer observation it is already holding on the Pilot's drains #356 handles the dropped observation.

With 1–3 done, this ticket is finished and #343/#347 stay shut.

_{Footnote, unrelated: there are two migrations numbered 0092 (0092_ai_usage_payer.sql,
0092_coder_repo_engine_copy.sql). wrangler d1 migrations apply keys on the full filename and
sorts lexically, so both apply, in that order — harmless today, but there is no test asserting
prefix uniqueness and the next collision may not sort so kindly.}

[serge-ivo]

Done — the five aggregates, judged one at a time, plus the guard

Landed as d3a8b68/b69c7f8, cf96dac/b35f80b, 2ffee3e/e4d4c89 and c805829 (rebased onto
main; CI green on each).

Taking the design comment's rule rather than the ticket's literal wording: an aggregate that
gates or pays must filter to CHARGED_SQL; one that displays may sum everything, but then it may
not be called spend. Filtering a display is the same error as #343 pointed the other way — it
would show an operator near-zero activity for a subscriber who is in fact using the platform hard.

Per-site verdicts

Site	What it is	Verdict
admin.ts:97 per-user spend_30d_micros	display an operator acts on	both. value_30d_micros (all rows — who is using the platform) + charged_30d_micros (CHARGED_SQL — the cost-governance one), side by side in the Users list and on User detail
admin.ts:452 platform-wide 30-day total	display	renamed. value30dMicros, alias AS value_micros. Sums everything, says so
admin.ts:453 platformSpend30dMicros	money the platform owes	filtered, and moved onto the right axis. provider = 'platform' answered which vendor; it is now payer = 'platform', with pre-0092 NULL-payer rows still attributed by vendor — for our own Workers AI binding that states the same fact rather than inferring it
external-usage.ts:134	the dangerous one	split. See below
stats-sources.ts:314 usageCost	subscriber's own dashboard	display, renamed. usageValue, alias AS value_micros. Filtering would show $0.00 on a Coder whose engine runs on the owner's subscription — an agent that plainly did a lot of work. The usage.cost source id stays (it is stored in every agent's stats schema); its label is now "AI value (list price)" and the caveat says why
admin-instance-detail.ts:113	operator drill-down	both. value_micros + charged_micros in one statement

One extra, found while doing the above and fixed in c805829: the operator dashboard's "BYOK
spend" was aggregateAdminUsage's provider-based split total — i.e. an unfiltered sum of every
non-Workers-AI row, which is anthropic reached both by a metered key and by a subscription.
The guard cannot see it (it aggregates in TypeScript, not SQL). BucketTotals now carries
chargedMicros, and the two "BYOK spend" stats read it.

What external-usage.ts now feeds payouts

ExternalUsageReport carries two figures everywhere (totals, per-agent, operator), and neither
is named so that a consumer can use it without choosing:

• valueMicros — list price on every row. This is what [Strategy] Focus bet — 10 external users on ONE runtime agent before expanding #68 wants: "is anyone but the operator
  here?" filtered to charged rows would read a subscription-heavy external user as no user at all.
• chargedMicros — SUM(CASE WHEN payer IN ('byok-api','platform') THEN cost_micros ELSE 0 END).
  This is the only one [3P] Metering → payout-ready (payouts built behind a flag, launch deferred) #57 metering→payouts or [3P] Cost governance & abuse controls (gates the public open) #56 governance may read.

Before this the file did not mention payer anywhere; whoever wired the payout up would have
inherited one unfiltered sum under the name cost_micros and paid a creator out of value drawn
from somebody else's Claude subscription. A unit test pins it: a 48.76 subscription row and a 1.00
BYOK row give valueMicros: 49_760_000, chargedMicros: 1_000_000.

The guard

lib/usage-aggregates.ts + usage-aggregates.test.ts. Every SQL sum over cost_micros in
workers/api/src must either take a position on the payer or alias itself as value.

Positive naming rather than the blacklist the comment proposed, because a blacklist of
/spend|cost|bill|charge/ is satisfied by calling the number n — which is literally how
getOverviewStats shipped an unfiltered sum into a field named spend30dMicros. Requiring the
word where the number is created, in SQL, puts the decision in front of the next person who
writes a consumer.

Pointed at the tree before any fix, it named all five sites at the line numbers above, plus
:453. Mutation check after the fixes — renaming external-usage's alias back to total_spend_micros:

lib/external-usage.ts:166  sums cost_micros with no payer predicate and calls it "total_spend_micros"
                           — either filter it (payer IN ('byok-api', 'platform')) or alias it as value

It needed a lexer position none of the four existing scanners had: keep the contents of every
string literal of all three kinds and nothing else. source-guard.ts blanks strings (its subject
is code), prompt-claims.ts inverts that, sql.ts needed the boundary between the two — and SQL
here is written as a template, as a double-quoted one-liner (admin.ts:452, the shape that
actually shipped the bug), and as a multi-line prepare argument. Comments are blanked first,
which makes this the fifth scanner in the repo to hit that: every file explaining this
correction has to quote the wording it retired.

Scope items

1. ✅ payer column — was already served by 6141dad.
2. ✅ Now fully served: 4b7e57f closed the fourth recordEngineUsage call site (recordEngineUsage drops the payer observation it is already holding on the Pilot's drains #356).
3. ⛔ Dropped, per the design comment — the engine preset's auth mode already resolves the
   payer observably, nothing load-bearing depends on the answer any more, and where it would
   become load-bearing ([3P] Metering → payout-ready (payouts built behind a flag, launch deferred) #57/[3P] Cost governance & abuse controls (gates the public open) #56) a self-report from the beneficiary is worse than NULL.
4. ✅ Consumers read payer. Both remaining verification points now hold.