audit: document and lock Claude transcript usage deduplication semantics #92

Problem

Claude JSONL transcripts are not a one-row-per-model-call ledger. Summing every row containing message.usage can substantially overstate usage.

In an anonymized historical corpus:

• 23,516 usage rows represented 9,632 unique message/request identities.
• 6,907 identities appeared more than once.
• 760 identities had changing token vectors; all 760 were monotonic.
• No non-monotonic group suggesting independent calls was found.
• Raw-row totals were approximately 2.15× the current deduplicated total.

Controlled experiment

A fresh Claude Code 2.1.228 session was run for exactly three short turns, then resumed for one additional turn.

Each model response produced two assistant transcript rows:

• one thinking block;
• one text block;
• identical message ID and request ID;
• identical complete usage vector.

The first three responses therefore produced six usage rows but only three billable response identities. Raw summation was exactly 2× the max-per-identity total.

Normal resume appended one new response to the existing file. The previous byte prefix remained unchanged and no previous usage identity was appended again.

Historical cross-file duplicates were limited to two highly overlapping transcript clone/fork pairs. Their shared rows had identical identities, timestamps and token vectors, so they do not represent separate calls.

Proposed resolution

• Keep the existing maximum-token-vector-per-message/request identity behavior.
• Add regression fixtures for:
  • identical thinking/text usage rows;
  • monotonic partial/final usage snapshots;
  • cross-file transcript clones;
  • distinct request IDs that must remain separately counted.
• Update comments and documentation to explain why deduplicated totals can be lower than Claude Code local statistics.
• Do not calibrate against stats-cache or introduce correction factors.

No conversation content, raw identifiers, project names or filesystem paths are included in this audit.

🤖 Generated with OpenAI Codex