8000 fix(blocks): round-trip an unparseable header instead of blanking it by simon-inkie · Pull Request #6 · simon-inkie/inkie-deck · GitHub
[go: up one dir, main page]

Skip to content

fix(blocks): round-trip an unparseable header instead of blanking it - #6

Merged
simon-inkie merged 1 commit into
mainfrom
header-roundtrip-guarantee
Aug 18, 2026
Merged

simon-inkie merged 1 commit into
mainfrom
header-roundtrip-guarantee

Conversation

@simon-inkie
Copy link
Copy Markdown
Owner

The bug

serializeHeader's own docstring promises HEADER_RE-matching output. It did not deliver it, and the gap corrupted data.

When parseHeader failed, parseBlock substituted a blank header (empty timestamp/from/subject, status read). serializeHeader then interpolated those blanks and produced:

##  - from:  - status: read - subject:

which no parser can read. So reading a file and writing it back destroyed the header permanently, and because the re-blanked line fails parse again on the next read, the damage compounded on every read-write cycle, with nobody sending anything malformed. This is a data-corruption class defect, not a missing feature.

Any block whose header cannot be cleanly re-serialised is affected: an ordinary markdown heading that happens to start a block, a header with an unparseable timestamp, a truncated header, a heading containing header-ish words.

The fix

parseBlock now carries the original header line on BlockHeader.rawHeader whenever parseHeader fails, and serializeHeader emits it verbatim when present. A re-serialise of a header we cannot parse becomes a no-op rather than a lossy rewrite.

rawHeader is set only on the failure path. Carrying it on the success path too would break the counter-property: a legitimate status flip (sent to read) would serialise the OLD line and never persist.

Two alternatives were rejected:

  • Making serializeHeader throw pushes the decision onto every caller, and one of them gets it wrong quietly.
  • Deleting the parse fallback also fixes the blanking, but that fallback exists to stop unparseable blocks nagging as permanently unread.

Tests

New packages/deck/test/blocks/header-roundtrip.test.ts, 10 cases.

The load-bearing detail is that the already-blanked string is a fixed point of the broken code: blanking it again yields the same string, so a round-trip test using only that input passes without the fix. Every case meant to exercise the fix therefore uses input that is not a fixed point. Verified by revert-to-red: with the guard line removed, 6 of the 10 fail.

Two cases go through the production seam (parseBlock then serializeBlock) rather than calling serializeHeader directly, because parse.ts is the exact place a regression would attach rawHeader to both arms. A counter-property test that cannot reach the code it guards does not guard anything.

Checks

  • pnpm test: 89 files, 1829 passed, 11 skipped, green
  • pnpm typecheck: exit 0
  • pnpm check:boundaries: no dependency violations (484 modules, 859 dependencies)
  • node scripts/leak-gate.mjs --self-test: all 30 rules fire
  • node scripts/leak-gate.mjs: clean, 367 files scanned
  • node scripts/leak-gate.mjs --messages: this branch's commit is clean. The two findings the scan reports are pre-existing and belong to other refs, not to this change.

🤖 Generated with Claude Code

serializeHeader's docstring promised HEADER_RE-matching output and did not
deliver it. When parseHeader failed, parseBlock substituted a blank header
(empty timestamp/from/subject, status "read"), and serializeHeader then
interpolated those blanks into "##  - from:  - status: read - subject: ",
which no parser can read. Reading a file and writing it back therefore
destroyed the header permanently, and because the re-blanked line fails
parse again, the damage compounded on every subsequent read-write cycle.

parseBlock now carries the ORIGINAL header line on BlockHeader.rawHeader
whenever parseHeader fails, and serializeHeader emits it verbatim when
present. A re-serialise of a header we cannot parse becomes a no-op rather
than a lossy rewrite.

rawHeader is set ONLY on the failure path. Carrying it on the success path
too would break the counter-property: a legitimate status flip (sent to
read) would serialise the OLD line and never persist. The new test pins
that through the production seam, parseBlock then serializeBlock, because
parse.ts is the exact place a regression would attach it to both arms.

Not fixed by throwing (that pushes the decision onto every caller and one
gets it wrong quietly), and not by deleting the parse fallback (that
fallback exists to stop unparseable blocks nagging as permanently unread).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@simon-inkie
simon-inkie merged commit c7c4896 into main Aug 18, 2026
1 of 4 checks passed
simon-inkie added a commit that referenced this pull request Aug 18, 2026
)

serializeHeader's docstring promised HEADER_RE-matching output and did not
deliver it. When parseHeader failed, parseBlock substituted a blank header
(empty timestamp/from/subject, status "read"), and serializeHeader then
interpolated those blanks into "##  - from:  - status: read - subject: ",
which no parser can read. Reading a file and writing it back therefore
destroyed the header permanently, and because the re-blanked line fails
parse again, the damage compounded on every subsequent read-write cycle.

parseBlock now carries the ORIGINAL header line on BlockHeader.rawHeader
whenever parseHeader fails, and serializeHeader emits it verbatim when
present. A re-serialise of a header we cannot parse becomes a no-op rather
than a lossy rewrite.

rawHeader is set ONLY on the failure path. Carrying it on the success path
too would break the counter-property: a legitimate status flip (sent to
read) would serialise the OLD line and never persist. The new test pins
that through the production seam, parseBlock then serializeBlock, because
parse.ts is the exact place a regression would attach it to both arms.

Not fixed by throwing (that pushes the decision onto every caller and one
gets it wrong quietly), and not by deleting the parse fallback (that
fallback exists to stop unparseable blocks nagging as permanently unread).

Co-authored-by: Simon <simon@inkie.ink>
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant

0