schemas: specs

Code: schemas/cost.py (C-), schemas/check.py (C-sum, C-cache-ttl bound, S-). Constants named in each spec live at the top of those files.

C-tokens: disjoint token counts

Definition: every event carries tokens{input, output, cache_read, cache_write, reasoning}, ints >= 0, disjoint, so their sum is the billed token count. - input = uncached input only (excludes cache reads and cache writes). - output = visible output only (excludes reasoning). - When a harness reports inclusive counts, subtract: input = input_reported - cache_read - cache_write (flag input_includes_cache), output = output_reported - reasoning (flag output_includes_reasoning). - Edge: missing count = 0; a subtraction below 0 (inconsistent harness report) is clamped to 0. - user_prompt and tool_decision events carry all-zero tokens and cost (enforced by S-event-kind). Worked example: harness reports input 13000 incl. cache, cache_read 10000, cache_write 2000, output 250 incl. reasoning 50 → {input:1000, output:200, cache_read:10000, cache_write:2000, reasoning:50}. Test: 02-measure/tests/test_schemas.py Cost.test_c_tokens (also the clamp: input 5 incl. cache_read 10 → 0).

C-price-match: price lookup

schemas/prices.json maps a model substring to USD per million tokens (PER_TOKENS) for input, output, cache_read, cache_write. Lookup lowercases the model id and takes the first key (file order) that is a substring of it. More specific keys come first (opus-5-5 before opus). No match or null model → no price (no default). Seeded from the price table of the earlier from-transcripts.py. Estimated rows: gpt and gemini are one family-level price for all versions seen locally, with cache_write 0 (not billed separately); fable is a list price as recorded there, not re-checked. opus-5-5 is fitted from Claude Code OTel cost_usd (input 4, output 20, cache_read 0.2, cache_write_5m 5, cache_write_1h 8; flat cache_write = 5m rate); sonnet-5-5 (2/10/0.1/2.5/4) is a guess from one sample. Rows may carry a string basis saying where the numbers come from; cost code ignores it. Formula: price = prices[first k in prices if k in lower(model)], else None. Edge cases: null model → None; case-insensitive (Claude-HAIKU-5 → haiku-5); dated ids match their base (claude-opus-5-5-20260901 → opus-5-5, not opus); no match → None, cost then falls to C-cost rule 4. Worked example: claude-opus-5-5 → key opus-5-5 (output 20); Claude-Opus-4-1 → key opus (output 25); mystery-1 → None. Test: 02-measure/tests/test_schemas.py Cost.test_c_price_match.

C-list: list-price cost

cost.input = input * p.input / PER_TOKENS, cost.output = (output + reasoning) * p.output / PER_TOKENS, cost.cache_read = cache_read * p.cache_read / PER_TOKENS, cost.cache_write = cache_write * p.cache_write / PER_TOKENS, cost.total = sum of the four. Unit USD, unrounded floats. Reasoning is billed at the output rate and has no cost field of its own. Edge cases: zero tokens → all parts 0.0; no rounding or cap on huge counts (Python floats, ~1e-16 relative error); no price → C-list does not apply (C-cost rule 4). Worked example: model claude-sonnet-4 (sonnet: 3, 15, 0.3, 3.75), tokens from C-tokens → input 0.003, output 0.00375, cache_read 0.003, cache_write 0.0075, total 0.01725. Test: 02-measure/tests/test_schemas.py Cost.test_c_list.

C-allocate: reported total only

When the harness reports one USD total and no per-type split: weights = C-list parts if the model is priced and their total > 0; else token counts per type (reasoning added to output); part = total * weight / sum(weights). If all weights are 0 the whole total goes to input. cost.total = the reported total exactly; parts match it within SUM_TOL. Worked example: same tokens and model, reported total 0.0345 → input 0.006, output 0.0075, cache_read 0.006, cache_write 0.015. Edge cases: unpriced model with tokens input 1, output 3, total 1.0 → input 0.25, output 0.75; all-zero tokens, total 1.0 → input 1.0. Test: 02-measure/tests/test_schemas.py Cost.test_c_allocate.

C-cost: event cost and cost_basis

First that applies: 1. harness reports per-type USD → those values (reasoning cost already inside output), total = sum, cost_basis:"reported". 2. harness reports only a total → C-allocate, "reported_total_allocated". 3. model priced (C-price-match) → C-list, "list_price". 4. else all five cost fields 0.0, "unknown"; analyze counts these calls in coverage.<harness>.unpriced_calls. Never a guessed price. Edge cases: zero tokens with a price → all zeros, "list_price"; reported split with missing types → those types 0.0; null model → rule 4. Worked example: reported {input:0.1, output:0.2} → cost {0.1, 0.2, 0, 0, total 0.3}, "reported"; same tokens, model mystery-1, nothing reported → all 0.0, "unknown". Test: 02-measure/tests/test_schemas.py Cost.test_c_cost_reported_unknown (rules 1, 4), test_c_allocate (2), test_c_list (3).

C-cache-ttl: cache writes by TTL

Claude bills 5-minute cache writes at 1.25x input and 1-hour writes at 2x input (matched Claude Code OTel cost to 1e-6). Optional token keys cache_write_5m, cache_write_1h (ints >= 0) are subsets of cache_write, which stays the total, so C-tokens disjointness and every sum over TOKEN_TYPES are unchanged. Optional price keys of the same names in prices.json (Claude rows: 1.25x / 2x input). Formula: rest = cache_write - cache_write_5m - cache_write_1h (missing key = 0); cost.cache_write = (rest * p.cache_write + cache_write_5m * p.get(cache_write_5m, p.cache_write) + cache_write_1h * p.get(cache_write_1h, p.cache_write)) / PER_TOKENS. Used by C-list and so by C-allocate weights. Edge cases: no split keys → flat cache_write price (unchanged behavior; the flat Claude values are kept as before and are inconsistent: opus = 1h rate, others = 5m rate, so readers with the split should always pass it); model without TTL prices (gpt, gemini) → flat rate; make_tokens raises cache_write to the split sum if smaller; check.py rejects cache_write_5m + cache_write_1h > cache_write at any depth. Worked example: sonnet (input 3 → 5m 3.75, 1h 6), cache_write 3500, cache_write_5m 1000, cache_write_1h 2000 → (500·3.75 + 1000·3.75 + 2000·6)/1e6 = 0.017625. Test: 02-measure/tests/test_schemas.py Cost.test_c_cache_ttl.

C-basis-worst: session cost_basis

BASIS_ORDER = reported < reported_total_allocated < list_price < unknown. A session's (or any aggregate's) basis is the latest in that order among its api_call events; no events → unknown. Worked example: [reported, list_price, reported] → list_price. Formula: basis = max(bases, key=BASIS_ORDER.index), unknown if empty. Edge: only api_call events count (user_prompt/tool_decision bases are ignored). Test: 02-measure/tests/test_schemas.py Cost.test_c_basis_worst.

C-sum: cost parts add up

For every object with numeric total, input, output, cache_read, cache_write (event, session, totals): |input + output + cache_read + cache_write - total| <= SUM_TOL (1e-6 USD). Checked by check.py at any depth. Worked example: {input:0.1, output:0.2, cache_read:0, cache_write:0, total:0.3} passes; total 0.31 fails. Edge cases: an object missing any of the five fields, or with a non-numeric one, is not a cost object for C-sum and is skipped (the schema reports the missing/bad field itself); 5e-7 off passes, 1e-5 fails. Test: 02-measure/tests/test_schemas.py Broken.test_session_analysis_decision_impact (session, analysis totals), Fixtures.test_cli_rejects_broken_copy (event via CLI).

S-event-kind

Rules (event rows): - decision and decision_source are non-null only on tool_decision; a tool_decision has non-null tool and decision. - user_prompt and tool_decision (ZERO_KINDS in check.py) have every tokens and cost value 0: any(tokens.values()) or any(cost.values()) → error. - No text field anywhere (the event schema allows no extra keys). Edge cases: their cost_basis is free (use "unknown"); an api_call with zero tokens is valid. Worked example: {kind:"tool_decision", tool:"Bash", decision:"accept", tokens:all 0, cost:all 0} passes; same with tokens.input:5 or cost.input:0.5,total:0.5 fails; api_call with decision_source:"user" fails. Test: 02-measure/tests/test_schemas.py Semantic.test_s_event_kind.

S-decision-choice

Rule: set(probabilities) ⊆ set(options) and choice in options or choice == "unsure". Edge cases: empty probabilities is valid; empty options allows only choice:"unsure"; probabilities need not sum to 1 (vendor scores). Worked example: options {a, b}, probabilities {a:0.7, b:0.3}, choice a passes; choice unsure passes; probability key zzz fails; choice maybe fails. Test: 02-measure/tests/test_schemas.py Semantic.test_s_decision_choice, Broken.test_session_analysis_decision_impact.

S-session-order

Rule: parse(end) >= parse(start), both parsed as aware datetimes (Z or ±HH:MM offset, optional fraction), so offsets compare correctly. Writers should still emit UTC Z. Edge cases: end == start passes (single-event session); unparseable ts → no S-session-order error (the ts pattern reports it). Worked example: start 2026-10-01T12:00:00+02:00 (10:00Z), end 2026-10-01T10:30:00Z passes; start 10:30:00Z, end 12:00:00+02:00 fails. Test: 02-measure/tests/test_schemas.py Semantic.test_s_session_order.

S-raw-payload

Rule: a v1 raw line (has v) has exactly one of data (parsed JSON), undecoded (summary of a dropped body: bytes, sha256, content_type, reason) and data_b64 (raw body, base64, only with KEEP_RAW_UNDECODED). Legacy lines (no v) are not checked. Edge cases: neither or both → error. v must be the integer 1 (const is type-strict: 1.0 or true fail). Worked example: {v:1, recv_ts, path:"/v1/logs", content_type, harness_hint:null, data_b64:"AA=="} passes; same without payload, or with both, fails. Test: 02-measure/tests/test_schemas.py Semantic.test_s_raw_payload, Semantic.test_const_strict.