perf(telemetry): the ledger is kept by day, so an ingest costs what it adds

[blafourcade]

🎯 What & why

One ingested call used to cost the whole ledger: every partition read and refolded, and its month rewritten (#1001). The ledger is now kept by UTC day, and an ingest reads, folds and rewrites only the days around its calls. One call into a 265k-call ledger: ~1.65 s → 58-64 ms, flat as history grows.

🛠️ How it works

• Partitions ledger/<YYYY-MM-DD>.jsonl replace <YYYY-MM>.jsonl. The mechanism is unchanged: canonical order, a changed partition rewritten whole by rename, one call per line (usage-ledger-adapter.ts).
• Ingest window: each call's day plus the days on each side (stored-usage.ts:43, ledger-upkeep.ts:15).
  • Measured read-only on a real history: 262,631 calls. A call's snapshots are 0.3 h apart at most, 3 straddle midnight, none spans a day.
• Report settles (ledger-upkeep.ts:30, under the lock at report-usage-use-case.ts:61). It already reads everything. When it finds a call in two places, a leftover monthly file or a damaged line, it rewrites those partitions canonically.
  • After any report, the bytes are identical whatever the history of ingests.
  • Between reports, a call seen outside the window would sit twice, never observed in practice. Fold-at-read still counts it once.
• Migration: monthly files are still read. The first ingest touching a month splits it into days and removes the month last (usage-ledger-adapter.ts:102), so a crash mid-split loses nothing.
• Times: an at without a zone or outside four-digit years is now unusable, so a day never depends on the machine's TZ. Incoming calls like that count as undated; stored lines like that are dropped as damage. Claude always writes Z: 1.83M local timestamps checked, none without it.
• Alternative set aside: append-only plus compaction. About 0.1 s faster, but a compaction rule, torn-line handling and a fold in every reader. Frame: contract.md.

🧪 How to verify

• cd cli && pnpm test: 6495 passed.
• pnpm test:mutation:telemetry: 96.14 (floor 96).
• Determinism: ledger-upkeep.property.integration.test.ts. Any grouping or order of ingests, from monthly files or not, with damage, gives canonical bytes after a settle, and a second settle is a no-op. The reviewer also swept 5 seeds × 1000 runs and replayed 3,617 crash states of a split; all converged.
• node scripts/check-claude-tokens-end-to-end.cjs (and --attended): 2 calls, 393 tokens, all on task demo, ticket T-1.
• Review rounds: review.md.

⚠️ Heads-up

• report still reads the whole ledger (~2.8 s on a 265k-call month). That is out of scope here.
• First ingest after upgrade splits the current month once: 1.6-1.7 s at 265k calls.
• IngestResult.skippedLedgerLines now counts damage inside the ingest's window. The report's figure covers everything.
• If AIDD_TELEMETRY_DIR points at ledger/ itself, forget would list day files as files from the earlier version. This is a pre-existing oddity.

🔗 Linked issue

Closes #1001

✅ I certify

• I DO CERTIFY I READ EACH LINE OF THE PULL REQUEST BECAUSE I AM A SOFTWARE ENGINEER, NOT A AI PUPPY.

🤖 Generated with Claude Code