ADR-0062: Cost by tag — aggregated at query time from live rows
Context and Problem Statement
Homer prices every Claude attempt onto processes.cost_usd (ADR-0061) and runs carry key:value subject tags in process_tags (ADR-0060), but the two are never joined: there is no way to ask what everything carrying one tag value, such as one ticket, cost. Operators want cost broken down by the values of one or more tag keys, with the tracked keys declared in server config rather than open to any key a caller names.
Decision Drivers
- No new persistence.
cost_entries(ADR-0035/ADR-0007) is an append-only ledger with noprocess_idcolumn, backingCostMeter's throttle windows; adding one to correlate spend with tags is a migration and a second source of truth for a valueprocesses.cost_usdalready holds. - Runtime tags must count. A tag declared mid-run via
POST /api/v1/callback/tags(ADR-0060) must be reflected even though the Claude attempts that produced the run's cost were recorded before the tag existed. - §12 rule 7 / CWE-203 (ADR-0060's existing screen). A tag whose value is currently secret must never surface as a breakdown key — the same constraint
getAll's?tag=filter and its response already enforce. - §12 rule 4. The candidate row set is bounded by the same
MAX_TAG_SCREENED_ROWScap the tag-filtered branch ofgetAlluses, not a new, separately-tuned bound. - TagValidation.KEY_PATTERN allows
_. A SQL single-character wildcard, so a prefix match built asLIKE 'key:%'from a config-declared key would also match an unrelated look-alike key (ticket_id:vsticketXid:). - Trust boundary: no new one.
/costs,/costs/monthly,/costs/totalsare alreadyauthorizer.isAdmin403 gates; the new endpoint answers the same question (aggregate spend) and should sit behind the same gate.
Considered Options
- Option A — aggregate at query time. Join
process_tagstoprocessesby tag-key prefix, keep only tags whose key is configured, screen for secrets, group by tag value and sumprocesses.cost_usd. No schema change. - Option B — snapshot the tag value onto each Claude spend entry at
accountAttempttime, and sumcost_entriesgrouped by that column. - Option C — reuse Langfuse trace tags (ADR-0050) and pull cost from Langfuse's own aggregation.
Decision Outcome
Chosen option: "Option A — aggregate at query time". Option B needs a cost_entries migration and would systematically undercount: a tag declared after some of a run's Claude attempts already posted their entries would never be attached to those entries, so the run's earlier spend would be missing from any tag-scoped total. Query-time aggregation always reads a run's current tag set against its current running total, so it is correct regardless of when a tag was declared relative to the spend that produced it. Option C fails for the same reason ADR-0060 rejected it for subject-tag search: a telemetry-OFF run has no trace, and Homer's spend figures (session-endpoint-priced, ADR-0061) are not necessarily what Langfuse reports.
Specifics:
ProcessRepository.costByTag(key, screenTags): Map<String, Double>(since the 2026-09-29 amendment: returnsCostByTagResult, which addstruncated) — candidate rows areProcessesfiltered by a correlatedEXISTSagainstProcessTags(carriesTagPrefix, mirroringcarriesAllTags's shape from ADR-0060), not aLIKE. The prefix test is a range bound: every characterTagValidation.KEY_PATTERNpermits in a key or a value sorts strictly between:(0x3A) and;(0x3B), sotag >= "key:" AND tag < "key;"matches exactly the tags whose key portion equalskey— no_/%wildcard ambiguity, and noESCAPEclause to get right. The existing(tag, process_id)index onProcessTagssupports the range scan. (2026-09-29 amendment: the correlatedEXISTSplanned as a scan ofprocesses; the candidate query is nowid IN (…)driven by that index,process_tags_tag_process_id.)- Bounded the same way
getAll's tag-filtered branch is. The candidate query is capped withMAX_TAG_SCREENED_ROWS(10,000) — the same constant, not a second bound to keep in sync. (2026-09-29 amendment: the constant is unchanged, but the query orders byid DESCand fetches one row past it to reporttruncated, so the shape differs fromgetAll's tag branch.) - Secret screening happens after the SQL, never in it, for the same reason ADR-0060's
?tag=filter does: a value that is currently secret (an input flipped tosecret: truesince the tag was written, or afromInputstag derived from asecretinput) must not become a breakdown key. Candidate rows are hydrated intoProcessInfo(batchedtagsByProcessTx, chunked bySQLITE_PARAM_CHUNK) and every tag is passed through the caller-suppliedscreenTagsbefore it can contribute — the same callback signature and the samescreenTags(tags, inputParams, agent, secretInputKeys)function the/status/allroute already builds. A route calling this method without a real screen cannot compile past the required, non-nullable parameter — the same fail-closed shape ADR-0060 established forgetAll. - Grouping happens in the application, not
GROUP BY, because the screen must run per row before a value is allowed to become (or contribute to) a group key; a SQLGROUP BYwould group on the raw, unscreened value first. - Route:
GET /api/v1/costs/by-tag/{key},authorizer.isAdmin-gated (403, matching its siblings) — spend data is treated as an admin-only surface regardless of the axis it's sliced on, the same posture/costs,/costs/monthly, and/costs/totalsalready take, so this endpoint introduces no new principal boundary.keymust be a member ofcostTrackedTagKeysor the route answers 400 — the config list is what's queryable, not any key a caller can name, which is also what keeps the response's cardinality bounded at deploy time rather than at request time. AppConfig.costTrackedTagKeys: List<String>is validated at config load againstTagValidation.KEY_PATTERN(same charset as a tag key) and capped atTagValidation.MAX_TAG_QUERY_PARAMSentries — reusingTagValidation's existing constants rather than declaring new ones.- Accepted tradeoff: a run can be counted once per value under a shared key.
process_tags' primary key is(process_id, tag), so nothing stops a run from carrying two different values under the same configured key (e.g. a workflow that re-tags itself). Such a run'scost_usdcontributes to both values' totals. This is accepted rather than engineered around: the endpoint is informational (§2 — no billing or enforcement reads it), and a run legitimately carrying two subject values for the same key arguably did incur cost attributable to both.
Trust boundary touched: none new — /costs/by-tag/{key} reuses the existing admin-only gate the sibling cost endpoints already enforce. Secrets are excluded via the same post-SQL screenTags application ADR-0060's ?tag= filter uses, with the same fail-closed (non-nullable callback) shape. Availability is bounded by the pre-existing MAX_TAG_SCREENED_ROWS cap and by restricting queryable keys to costTrackedTagKeys.
Consequences
- Good: no new table, no new column, no migration —
cost_entriesandCostMeterare untouched. - Good: a tag declared at any point in a run's life is reflected correctly, because aggregation reads the run's current tag set and current
cost_usd, not a value frozen at spend-record time. - Good: reuses
MAX_TAG_SCREENED_ROWS,carriesAllTags'sEXISTSpattern (since the 2026-09-29 amendment, its index-drivenid IN (…)form instead), and thescreenTagscallback verbatim — no parallel security surface to keep in sync with ADR-0060's. - Neutral: the queryable key space is deploy-time, not request-time — an operator who wants to slice by a new tag key must add it to
costTrackedTagKeysand restart/reload rather than querying it ad hoc. - Bad: a run carrying two values under one configured key has its cost counted once per value (accepted above).
- Bad: like
getAll's screened branch, cost scales with the rows the candidate query admits (up toMAX_TAG_SCREENED_ROWS), not with the number of distinct values returned.
More Information
- Write path (unchanged, from ADR-0060):
process_tagsinserts atobtainProcessIdand viaPOST /api/v1/callback/tags. - Read path:
ProcessRepository.costByTag(range-bound candidate query — since the 2026-09-29 amendment an index-drivenid IN (SELECT process_id …),hasTagPrefix, instead of the originalEXISTS— +screenTags+ application-side grouping),ProcessManager.costByTag(delegates),SecuredRoutes.ktGET /api/v1/costs/by-tag/{key},CostByTagResponse(withtruncated). - Config:
AppConfig.costTrackedTagKeys, validated againstTagValidation.KEY_PATTERN/MAX_TAG_QUERY_PARAMS. - Related: ADR-0060 (tag storage, screening, the
EXISTS/range-bound pattern this ADR reuses); ADR-0061 (cost_usd,cost_entries); ADR-0035 (the ledger this ADR deliberately does not extend); ADR-0047 (§12).
Amendments
2026-09-29: the
MAX_TAG_SCREENED_ROWSbound stays — the secret screen must decode every candidate row (ProcessInfo+screenTags), so raising or removing it is unbounded work per §12 rule 4, not a size the endpoint can absorb. Aggregating the sum in SQL (GROUP BYovercost_usd, no row cap) was considered and rejected for the same reason ADR-0060 rejected it for the?tag=filter: the screen needs each run'sinputParams,secretInputKeysand current agent definition, none of which aGROUP BYcan evaluate — grouping has to happen after every row is hydrated and screened, in the application.Instead,
costByTagnow reports when the bound cut the candidate set short: it fetchesMAX_TAG_SCREENED_ROWS + 1rows ordered byid DESCand drops the extra one, soCostByTagResponse.truncatedistrueexactly when more runs carried the key than fit the bound. TheLIMITbounds the rows returned, not the query's work: that is bounded by thekey:range of the tag index, at mostmaxProcesses× the per-run tag cap entries. Kept end: the newestMAX_TAG_SCREENED_ROWSruns by process id — the same endgetAll's tag-filtered branch already keeps for its default descending order, so a truncated total silently drops the oldest matches, never the most recent activity. The endpoint is admin-only, so exposing the flag discloses nothing across principals.Adding the
ORDER BYalso fixed the candidate query's shape: the previous correlatedEXISTS(Processesfiltered row-by-row againstprocess_tags) plans as a fullSCAN processes, probing the(process_id, tag)primary key once per row instead of driving from an index. It is replaced with the sameid IN (SELECT process_id FROM process_tags WHERE …)formcarriesAllTags's index-driven branch already uses (ADR-0060) — planned onprocess_tags_tag_process_id, withprocessesfetched by primary key and noTEMP B-TREEfor the sort, checked at 150k rows with and withoutsqlite_stat1(DatabaseMigrationTest).