[Juliusolsson05]

Fixes #1276. Related: #1299 (the recorder that ran 33 h, filed separately as P1).

Plan: docs/plans/2026-09-25-dictation-journal-cap.md (first commit; updated to match the code).

Evidence

One press produced a 1.196 GB dictation-debug file. By event, 96 % of it is per-chunk and per-sample: recorder:dataavailable, the CHUNK layer, deepgram:chunk:*, deepgram:message and AUDIO_LEVEL sample. Only 17 lifecycle events appear in the whole file. The only cleanup was a 14-day prune, and DictationDebugJournalRegistry.dispose had no callers.

Merged behaviour

• Per-file budget of 16 MiB. Past it, high-frequency events (chunks, recorder data, Deepgram chunk and message events, audio samples, interim previews) are not written one by one. Instead they are counted into one journal:high-frequency-summary row per minute. Each row has per-kind counts, per-source last chunk indexes, maxPeak and nonZeroPeaks. A kept event (lifecycle, error, outcome, stop, final transcript) first closes the open summary window, so ordering around it is preserved. This keeps a Dictation can keep the microphone open for hours: no max duration, no silence stop (33 h recorded) #1299-style tail visible at minute resolution.
• The registry keeps at most 64 journals and evicts the oldest. An evicted writer is flushed. flushAll() (the shutdown drain) waits for eviction flushes and for a drain already in flight.
• Re-creating a writer for an evicted press keeps the budget. It starts from the larger of the on-disk size and every in-flight evicted writer's accounted bytes. It also keeps the press clock: tMs is anchored to the file's first {"ts","tMs"} line.
• Known caveat: if the press is reopened before its first evicted writer has written anything, there is no file line to anchor on, and tMs restarts from the new writer's clock. ts and the byte budget are unaffected.

Tests

src/main/dictationJournal.test.ts covers:

• every suppressed classification, and ERROR/OUTCOME preservation;
• summary counts, peaks and minute cadence on disk, and lifecycle ordering;
• oldest-versus-newest eviction, and eviction and shutdown with delayed writes;
• in-flight evicted budgets and the clock anchor.

The new tests were red on main. npx tsc -b is clean. Review dispositions are in the comments.

🤖 Generated with Claude Code

[Juliusolsson05]

Final disposition (posted after merge; steering q35 correction). I merged this PR at 54287d90 without first posting this comment, which is a process miss. From now on, the disposition is a pre-merge gate.

Tested head: 3d1fb302, which contains main 3c12bb73. quality-gate passed in run 36152352034.

Reviewer	Round 1	Round 2	Final
A (correctness)	FIX-BEFORE-MERGE	FIX-BEFORE-MERGE	fixed in 503ef71a, 2cd778e2
B (tests)	FIX-BEFORE-MERGE	FIX-BEFORE-MERGE	fixed in 23557fa1, 503ef71a
C (debuggability/privacy)	FIX-BEFORE-MERGE	MERGE-READY (one minor)	minor fixed in 2cd778e2

Material fixes from review:

• Per-minute summaries replace the one-shot marker (b555c9eb, C1/A3). Past the 16 MiB budget, high-frequency events (chunks, audio samples, interim previews, Deepgram messages) are counted into journal:high-frequency-summary rows. Each row carries per-kind counts, maxPeak and nonZeroPeaks. A kept lifecycle event closes the open window first, so the Dictation can keep the microphone open for hours: no max duration, no silence stop (33 h recorded) #1299 tail stays visible.
• The budget survives eviction (A1, b555c9eb / 23557fa1). A re-created writer starts from the on-disk size.
• Each in-flight evicted writer counts (A-r2, steering q30, 503ef71a). A reopened press starts at the MAX of the in-flight writers' accounted bytes, so a write not yet on disk cannot reset the budget.
• Shutdown joins eviction and in-flight drains (A2/B1, both rounds, b555c9eb / 23557fa1). flush() awaits a running drain and then drains the rest; flushAll() waits for writers still being disposed.
• Per-source chunk indexes (A-r2 minor, 23557fa1). The summary no longer mixes the zero-based renderer/main indexes with the one-based Deepgram ones.
• The press clock is kept (C-r2 minor, 2cd778e2). A re-created writer reads the original {"ts","tMs"} anchor from the file's first line, so summary tMs stays on the press clock.
• Tests now cover:
  • every high-frequency classification, and ERROR/OUTCOME preservation;
  • exactly one summary per window, minute-scale timing on disk before the final flush, and repeated-event and multi-peak aggregation;
  • lifecycle-boundary ordering;
  • oldest-versus-newest eviction and the in-flight eviction and shutdown races.

Known caveat (confirmed by reading 54287d90): a press reopened before its first evicted writer has written anything to disk cannot find the original clock anchor. existingStartedAt reads only the file, and the in-flight ledger carries bytes, not the start time. That writer's tMs then restarts from its own clock. The byte budget still holds, because the in-flight bytes are counted. Timestamps (ts) stay absolute. This is not worth a follow-up unless a real journal shows it.

Not addressed: B-r1 minor 5 (no sanitized recorded *.dictation.jsonl fixture). The event shapes follow the current emitters.

🤖 Generated with Claude Code