feat(framework): the metrics contract a pricing service consumes

[blafourcade]

Outcome

A consumer outside this repository — the governor, or anything else — receives a session's metrics complete enough to price and attribute them, without knowing how any tool writes its files.

The gap, measured

Run today against a real 5134-record session, a stored record carries:

{"kind":"request","vendor_id":"2c21d903-…","vendor_field":"sessionId",
 "turn_id":"req_011Ce4ccjP8oZQNsyQ6iKpQi","turn_field":"requestId",
 "model":"claude-opus-5","effort":"high","agent_name":"general-purpose",
 "input_tokens":2,"output_tokens":1,"cache_read_tokens":12127,
 "cache_creation_tokens":19232,"event_timestamp":"…",
 "sink_schema_version":2,"provenance":"local-read"}

Good enough to price. Two things are missing, and both are needed by anyone aggregating across a team.

Which tool produced it. There is no tool field. The only clue is vendor_field, which reads sessionId for a locally-read Claude Code record, session.id for an exported one, session_meta.id for Codex — a leaky proxy that encodes the route as much as the tool, and that a consumer would have to reverse-engineer. The run journal has carried tool since its first line; the sink never did, because when it was written there was only one tool.

Which step was running. step_start lives in the run journal and is never joined into the stored record. So the figures know the agent (agent_name separates aidd-dev:executor from the main loop — measured, 2543 calls against 1611 on one session) but not the skill. That join is the entire point of #663, and nothing performs it yet.

Scope

• Includes: the tool on every stored record, as a fact rather than something inferred from a field name.
• Includes: joining the run journal's step boundaries onto the cost records they cover, so a shipped figure carries the step it belongs to.
• Includes: a stated contract for what a consumer receives — the field set, what each field means, which are always present and which are conditional, and what a missing one signifies.
• Includes: the two double-count rules stated in the contract rather than left for a consumer to rediscover — kind: "request" and kind: "session" measure the same quantities differently and are never summed; a re-read is matched on turn_id.
• Excludes: pricing. The rates live in the governor.
• Excludes: transport. Getting the payload out is feat(framework): upload out of band, never at the session's expense #662, and redacting it on the way is feat(framework): redact again on the upload path #655.
• Excludes: presenting anything to a human, which is feat(framework): a skill that reports cost per task and per step #629.

Done When

• Every stored record names the tool that produced it, without a consumer parsing vendor_field.
• A record produced during a step carries that step, joined from the run journal rather than inferred from a timestamp.
• The contract is written down, and a consumer implementing against it needs nothing from this repository's source.
• A field that is conditional says under what condition, and what its absence means — an absent counter and a zero counter are different facts.
• The contract states the two double-count rules explicitly.
• A tool whose figures cannot be attributed to a step says so, rather than presenting an unattributed figure as attributed.

Why this is the prerequisite

Anything downstream — pricing, per-person aggregation, per-epic reporting — reads this contract. Building those on a shape that cannot name its own tool means every consumer re-derives it, differently, and one of them gets it wrong.

Relations

Field	Value
parent	#631
related	#629, #662, #655, #663, #685

[blafourcade]

Claude Code writes the skill into its own transcript, and it is better than the journal for that path

Measured 2026-08-20 across the 40 most recent transcripts on one machine.

An assistant message line carries attributionSkill and attributionPlugin beside requestId, sessionId, isSidechain and message.usage:

messages with usage: 18585   attributed to a skill: 2267 (12.2%)   distinct skills: 25
   aidd-dev:05-review      x641      aidd-dev:02-implement   x180
   impeccable:impeccable   x380      aidd-dev:01-plan        x153
   xeval-memory            x360      aidd-dev:11-browser-qa  x127

Real names, per message, with the counters already on the same line. No OTEL_LOG_TOOL_DETAILS, no journal join, no interval inference, and no sticky attribution — the three problems #663 exists to work around are all absent here.

Two measured limits that shape how it can be used

It arrived around 2.1.220. Across twelve versions on this machine, 2.1.217 carries it nowhere; it appears from 2.1.220 and is common from 2.1.223.

It is omitted entirely, never null, when no skill is running. Zero null values across all twelve versions — the key is either present with a name or absent.

Those two together mean absence is ambiguous: it says either "no skill was running" or "this Claude Code does not report it", and nothing on the record separates them. So a report may say a figure is unattributed. It may not say the work happened outside a skill. That distinction is the difference between a fact and a false figure, and it has to survive into the output format.

What this changes

Per tool, the best available source is not the same one:

Path	Skill comes from	Quality
Claude Code, local read	attributionSkill on the transcript line	exact, per message
Claude Code, export	nothing — the vendor attribute reads third-party	via the journal, by interval
Codex, Cursor, Copilot	no equivalent measured	via the journal, by interval
OpenCode	no equivalent measured	not joinable yet (#676)

So #663's journal boundaries are not wasted — they remain the only route for four tools out of five and for Claude Code's export path. But this ticket should read the exact source where one exists rather than inferring an interval beside it, and a record must say which of the two produced its attribution. An exact attribution and an interval-inferred one are not the same claim.

Cross-referenced from #663, whose mechanism this narrows rather than replaces.

[blafourcade]

Delivered and committed, not merged. Three commits on blafourcade/brainstorm-telemetry, gate green throughout: 2435 CLI tests, tsc, biome, the layering check and the markdown link check all exit 0.

• 43f35a81 a stored record names the tool that produced it
• 6957d9fe a record carries the step that was running, and how it knows
• b404c268 the contract a service outside this repository consumes

What shipped beyond the ticket body.

The step has two sources and they are not the same kind of claim, so every record says which answered: stated by the tool, derived from an interval, or unattributed. Claude Code's own attributionSkill is exact per message where the journal's is a half-open interval, and collapsing the two would let a consumer read an inference as a measurement.

Three things found while building, none of them in the brief:

• A journal boundary with an unparseable moment let the previous step's interval swallow everything after it — silent attribution to the wrong skill. Unparseable boundaries are now dropped before pairing.
• The export path is deliberately not journal-attributed. The mapper runs at receive time while the journal is still being written: the live turn has no end yet, so its last boundary would read as an open interval and claim whatever arrived next. Inferring once, from an incomplete file, into a permanent record is worse than leaving it unattributed. Raised by an executor against my own brief, and correct.
• A Codex record carried no moment at all, so no interval could ever reach it — and the journal is Codex's only step source. The rollout carries one on turn_context; it is now taken, deliberately the turn's start rather than a moment from a counted event inside it, since the record covers the whole turn.

The document cannot drift. A test parses field names from the interface and from the document's own headings, neither list hand-copied, and fails in both directions naming the offending field — proven by renaming one heading and watching it name both the stale entry and the missing field. The worked examples' totals are recomputed from their samples.

One claim was flagged unsourced by its author and is now sourced. Copilot's cost is denominated in premium requests, not currency: across fourteen local sessions it reads 0.33 for every single-request claude-haiku-4.5 session while consumption ranges from 2.04 to 2.95 billion nano-AIU, and 0 for a five-request gpt-5-mini one. Request count times a per-model multiplier, invariant to consumption.

Next on the sequence in #631: #629, the reader.