feat(telemetry): report envelope v2 keeps the figures apart from the run - #1048

🎯 What & why

aidd telemetry report --json printed its figures next to facts about the read that produced them, such as files read, calls not stored and the oldest transcript. So two reports over the same data were not byte-identical: the second reads 0 files where the first read 2. Envelope v2 keeps the figures apart from a run object. This PR also adds a guard that runs the telemetry tests under a far time zone and a non-English locale, locally and in CI.

🛠️ How it works

• The figures are every top-level field except run: period, axis, filters, rows, totals, coverage.records and coverage.left_out. They depend only on the ledger's records, its left-out file, the declarations, the identity, the period, the filters and the axis. run, always last, holds what this read found. The definition lives in one place, envelope.md, and the usage contract and the CLI memory link to it.
• unknown_records is no longer at the top level. It only copied totals.total.unknown_records, so v2 keeps it once, in the totals.
• Each field was decided on its own. The reasons are in the v1 to v2 table. Two moves are less obvious:
  • skipped_ledger_lines really changes on a re-run, because the report's own settle keeps each damaged line once. A test proves it, 2 then 1.
  • consent_log_damaged says whether this read could store anything, not anything about the figures.
• The CLI makes the same split in ReportResult (coverage and run). The text report prints exactly what it printed before.
• Properties:
  • P1 (fast-check) checks that the figures' bytes are the same across storage order and batching, monthly partitions, the zone the calls were stored in, no-op stores, a second report, and TZ in UTC, Kiritimati (UTC+14) and Adak (UTC−10), while run carries random facts. The envelope is built inside the zone being tested.
  • P2 runs the built CLI on one sandbox and checks that the figures are identical across 3 zones × 3 locales (C, fr_FR, ar_SA), where run.files_read goes from 2 to 0.
• Guard: pnpm test:foreign-clock first has a child Node write a number and a date, and requires both to differ from en-US, with a non-zero offset. It exits 1 otherwise, for example on a bogus locale or zone. It then runs the telemetry tests under UTC+14 and ar_SA. CI runs it as one step in the existing cli-coverage job (cli-ci.yml:303). Two hand mutations prove it is a guard (see the evidence):
  • The ledger day in local time. On origin/next, 1493 tests in scope pass it under UTC. The guard fails 36 of them.
  • Counts grouped by the default locale. The default suite passes it. The guard fails 24.
• Readers updated: the 01-usage skill (answer and envelope reference), the usage contract, the CLI telemetry memory, and check-claude-tokens-end-to-end.cjs, which now calls itself broken on any version other than 2.

🧪 How to verify

• cd cli && pnpm test
• cd cli && pnpm test:foreign-clock
• cd cli && pnpm exec vitest run tests/contexts/telemetry/application/report/report-figures.property.integration.test.ts tests/e2e/telemetry-report-figures.e2e.test.ts
• node scripts/check-claude-tokens-end-to-end.cjs cli/dist/cli.js (and --attended)

⚠️ Heads-up

• Envelope v2, no v1 shape.
  • coverage.files_read, unrecognised_shapes, not_stored, consent_log_damaged, oldest_transcript_at and skipped_ledger_lines moved to run.
  • version is 2.
  • The refusal is {"version": 2, "refused": "AIDD_TELEMETRY=0"}.
  • unknown_records is no longer at the top level: read totals.total.unknown_records.
  • Plugin and CLI must move together. On a version mismatch, the skill gives no figure and names the fix: update the CLI if the envelope is below 2, the plugin if it is above.
• Release impact: ships as a minor, by the maintainer's decision. The project is in beta, so the envelope change is not marked breaking.
  • The squash-merge message carries no ! and no BREAKING CHANGE: footer. release-please reads only that message.
  • Merge by squash only. The branch history keeps d25f7ca7 feat(telemetry)!. A merge commit would carry it to main and ship this as breaking.
• Limits:
  • Node applies a runtime TZ change only on a main thread. Under Stryker's worker threads, P1 does not vary the zone (report-figures test:218).
  • The locale is fixed when a process starts. So locale identity is checked across processes only on the fixed e2e sandbox. P1 under the guard compares against itself.
  • The guard runs on ubuntu only. Windows ICU ignores LC_ALL, and this was not run on Windows locally.
• Mutation: telemetry 96.7 (floor 96) at 25c9f857, with every changed-line mutant killed. The rerun after review round 1 was stopped by the machine running low on memory and has not been redone. Bundle: 712,713 B, 696.0 KB of 709 KB, not raised.

🔗 Linked issue

None. Found by the R1 telemetry audit (M5, M9).

✅ 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

https://claude.ai/code/session_01VWNxk63AGKkqE8HRqHLjGp