[shovon]

Closes #117.

What changed

The record format and its reading rules (packages/ledger/records.ts, new):

• encode, decode, LogEvent and Hlc move here from ledger.ts, unchanged.
• readRecords(buf, start, last, suspectAfter) is the per-segment loop that was inside #readSegments, as a pure fold over the segment's newline-ended lines. It returns:
  • accepted: the records taken, in order
  • last: the seq of the last one taken
  • end: just past the last good record, taken or a duplicate, where the next read resumes; undefined if there was none
  • suspect: the latest hlc.l among taken records dated past suspectAfter
  • stall: { at, why }, with at as an offset in the segment
• It reads no file and no clock: suspectAfter is handed in.
• records.ts is not exported from the package (exports is still ./ledger.ts). ledger.ts re-exports encode, LogEvent and Hlc, so the public surface doesn't change.

#readSegments (ledger.ts) keeps the directory listing, opening and reading each segment, and moving on to the next. For each segment it calls readRecords and applies the result to the cursor: last, suspect, and seg/offset when end is set. The cursor still moves into a new segment only once one of its records is accepted or skipped, as before.

multi-writer.md: one paragraph under "Reading foreign logs" says which rows of the table are readRecords, and that a rule changes in both places together.

For the reviewer

• The format, and every rule in the spec's table, are unchanged. The loop moved as it was. The jump message, the offsets, and the "intact records follow it" and "torn tail" reasons are byte-for-byte the same.
• Two small differences:
  • The too-far-ahead check uses the scan's own wall clock (at.wall, already taken once per scan) instead of calling Date.now() per record. The threshold can differ by however long the read took, and every record in one scan is now judged against the same time.
  • Accepted records are pushed in a loop, not push(...accepted). A full 16 MiB segment can hold more records than a call accepts as arguments.
• Found while testing, not changed here: with a mutation that folds past a seq gap, the existing ledger.test.ts hangs instead of failing, and had to be stopped. Some test waits on an iterator for a state that never comes and isn't bounded by its timeout. Worth a look on its own.

Tests

• records.test.ts (12 tests, new), over records built with encode:
  • one per row of the table: a clean run, nothing to read, duplicate deliveries (alone and mixed in), a seq that jumps (after a record, and as the first one), a bad record with intact records after it, a checksum mismatch, a torn tail (bad, unterminated, several bad lines), offsets counted from a non-zero start, and records dated too far ahead (taken, the latest reported, a duplicate not counted)
  • a valid run with multi-byte text, cut at every byte: taken up to the last whole record, never past the cut, and stalled at the start of the split record exactly when one is split
  • the same run read up to each cut and then on from end with the last it gave: every record taken once, ending past the run
  • a bad line at every position in the run: everything before it taken, nothing after, with the matching reason
• Mutation checks: folding past a gap fails the jump test, and skipping a bad line fails 4 tests.
• The existing ledger.test.ts and open-writer.test.ts (29 tests) pass unchanged.
• End to end, in a scratch instance, on a copy of a ledger an earlier build wrote:
  • it folded the same pages, with all 7 records read and the writer ok
  • with half of an eighth record appended, the writer stalled at byte 2376 (where the record starts) with "torn tail" and the pages unchanged
  • with the rest appended, it healed by itself: 8 records read, back to ok
• npm test (213 tests across all workspaces), and the app's npm run typecheck (which covers the ledger) and npm run lint pass.

🤖 Generated with Claude Code