feat: cc.billing — exact, cache-tier, per-call token attribution (OPIK-6873)

[jverre]

Summary

Rebuilds the plugin's spend attribution around one product schema, cc.billing: per-LLM-call, cache-tier-aware token attribution that is exact against API usage at every level (span → trace → any SUM across traces). This is the data contract for Opik's AI Spend dashboard (OPIK-6870): lane values, breakdowns, stacked definition/usage bars, counts and FE-side pricing all come from this block.

cc.billing:
  llm_calls: 3
  model: claude-fable-5
  totals: {total, input, cache_read, cache_creation, output}   # == Σ original_usage.* exactly
  lanes:
    <laneKey>:                                                 # fixed JSON path per lane
      total, input, cache_read, cache_creation, output
      items: [{name, kind: definition|usage, count, total, input, cache_read, cache_creation, output}]
    unattributed: {...}                                        # explicit remainder — what makes sums exact

How it works

Anthropic's prompt caching is prefix-based, so each call's usage splits the request positionally: [0,R) cache_read, [R,R+W) cache_creation, tail fresh input. Per call, the request is laid out as ordered pieces (static config prefix, then the conversation in transcript order), reconciled to the call's measured usage (usage-derived pieces never rescaled; undershoot lands in unattributed, placed at the tail where unobserved content actually sits), and cut by position. Output is booked from per-block attributed tokens. Tier tokens are therefore per-call billing events: plain SUM aggregation reproduces the API bill exactly — no cumulative weighting, no scale factors.

Also in this PR

• Bug fix — 2x usage double-count: the transcript repeats message.usage on every entry of a multi-block message; two summary paths summed per entry. Found via a three-way audit (transcript vs span aggregation vs /context); reproduced on fresh production data (logged 202 for a true 101, exactly 2x). Fixed by counting once per message.id.
• count_tokens anchoring: exact piece sizes via the free endpoint, authenticated with Claude Code's own OAuth credential (keychain / .credentials.json). Persistent (model, sha256) cache → static config is measured once ever; budgeted, detached at turn end. Live measurement showed ratio estimates running 25–55% under on table/code-heavy content — exactly the mass previously stuck in unattributed.
• Static overhead itemization: the dynamic environment block (cwd, platform, git status) is reconstructed locally and carved out as its own item — repos with long git status visibly pay for it per request; deferred-catalog names split built-in vs MCP; optional per-release Components table + capture procedure in docs/builtin-calibration.md.
• Payload consolidation: the per-lane composition emitters (skills/tools/memory/agents summaries, user_prompts, tool_results, file_attachments, prior_assistant, thinking, assistant_text, output_tokens) are removed — every UI surface they fed now reads cc.billing. Net −900 lines. Trace metadata is identity + git + billing + cc_builtin (+ context_runtime).
• Skill load identity: one loaded[] event per load with stable unique ids (slash:<idx> for slash commands) so repeat loads count correctly.
• Removed after validation: a call-1 residual self-calibration for the bundled system prompt — it absorbed all unobserved request content and inflated static overhead 3.6x vs /context ground truth (commit history documents the dead end).

Validation

Invariant	Where
Σ lanes (incl. unattributed) == input/cache_read/cache_creation/output per call & per trace	billing_test.go + two real sessions, exact to the token
Cache-prefix chain: read(k+1) == read(k) + write(k)	real-session audit (850k-context session, token-perfect)
Usage booked once per message.id (the 2x regression)	cumulative_test.go
Skill bodies never leak into user_prompts; repeat loads keep distinct ids	cumulative_test.go
by_size/by_content-style partitions sum to lane totals	billing_test.go
Anchoring budget/baseline mechanics, cache merge, anchor preference	count_tokens_test.go

Full suite green. Consumer-side queries (Opik BE) are documented on OPIK-6870.

🤖 Generated with Claude Code