The units
| Unit | What it is | Typical id |
|---|---|---|
| Span | One metered event | minted on capture |
| Turn | One sealed transcript line | minted on capture |
| Task | One unit of intent (often one human turn) | task_id |
| Session / sitting | One harness conversation | session_id — the spine |
| Episode | A range of turns inside one sitting, with one primary on the tree | an objective window |
principal is who directed. It is a dimension. It is never the join. Joins use session_id, then task_id, then the exact span.
The span
Written once. No update. No delete. It carries:- Attribution — principal, session, task, optional parent span, optional tool name, optional project (seating: where the harness was pointed)
- Model — provider, model, lane (
frontier/offload/local) - Tokens by phase — input, cache read, cache write, output, reasoning, tool I/O
- Cost — integer micro-USD when priced; absent when not
- Producer ref — the idempotency key
The turn
One conversation line: human, agent, reasoning, or tool. Almost every column is readable without the key: time, session, sequence, kind, tool, counts, the link to the span. Exactly one column is sealed: the message text. A shredded principal keeps the rows. The text is gone. Surfaces say[shredded], not an empty message.
Overlays
Overlays are extra rows. They point at a span or a sitting. They never edit the original.| Overlay | Claim |
|---|---|
| Classification | Span work-type (mechanical, tooling, routing, reasoning, generation) |
| Valuation | A value score on a span |
| Cost correction | A later, versioned cost — original stays |
| Outcome attribution | This outcome was produced by this spend |
| Product attribution | Path mentions in the sitting’s own documents |
| Session annotation | Type — kind of work |
| Objective window | Episode — this stretch of turns was for this tree node |
| Objective touch | This sitting also affected that node — no dollars |
| Scope window | Writes landed in repo:<slug> |
Outcomes
Atask_outcome is a result: something happened, optionally with a declared dollar value.
ROI joins outcomes to spend through the attribution overlay. Missing declared value means ROI is undefined, not −100%.
How a dollar finds a sentence
- Capture writes spans and turns for the same sitting.
- A turn may carry
span_refto the span that paid for it. assay turnsand the session page print cost on that join.- Labels on the sitting (type, episode, product) group those dollars.