# Notes incremental read failure

## Dev Notes — 2026-09-28

Installed CLI 0.33.0 against production reproduced `400 bad_reference` for both
a retained SHA-256 reference and a relative timestamp. Inspecting the HTTP error
body revealed `Character alignment trace limit exceeded`. Reference resolution
was valid; the broad route catch mislabeled patch generation failures. The CLI
currently displays the flat error code without its explanatory message.

The saved source pair was 2,475 and 4,747 UTF-16 units. The old generator fails
on that pair; direct line alignment produces an exact round trip. Private source
text is excluded from this repository. Synthetic fixtures cover the same failure.

Read-only unified diffs use bounded line alignment, three context lines, exact
newline preservation and existing source/output limits. Character alignment and
native-identity write compilation retain their safety limits. No merge/exact
policy changes are introduced. Invalid references are 400, missing baselines
404, generation errors 422, and service failures 503 with server-side logging.

Validation covers large rewrites, distant localized hunks, Unicode, CRLF, missing
final newline, empty/no-op sources, hash and time route reads, and error classes.
Production disposable-note checks verified task presence, a browser-originated
RTC edit read through the CLI, and a merge-mode inline comment with live readback.
These checks do not establish deployment of this fix.

The separate successful-but-missing eight-comment incident is now reproduced:
installed native CLI 0.33.0 sends an empty `payload.patch` for
`--file - < patch.dff`, visible in `--dry-run --json`. A pipe or explicit file
path preserves the bytes. Both retained receipt journals contain only additional
browser operations and no corresponding native comment message. The server
acknowledged a no-op, rather than discarding a submitted merge. A companion CLI
fix uses Bun's native stdin stream and rejects empty patches before sending.
Its native packaging gate checks regular-file redirection, pipes, explicit file
paths, and empty/UTF-8/size rejection. A newly compiled fixed CLI submitted eight
comments via redirected stdin to a disposable note; all eight appeared exactly
once in the acknowledged snapshot, preserving previous comments and a peer edit.

The preserved unified patch independently hits the character-alignment trace
budget in the write parser. The CLI now retains that explanatory error instead
of asserting a baseline mismatch. Existing write limits remain intentional.
A live stale-baseline MERGE test inserted eight comments and preserved a peer's
intervening RTC insertion. A browser-originated edit was independently verified
through incremental reads; a second browser concurrency run was interrupted by
browser-control unavailability. No pitch-note writes were performed.

Legacy `insert --if-match` uses a quoted ETag, not an RTC token. The companion
CLI rejects that mismatch before network activity and updates generated help.
A guarded legacy insertion example was executed on a disposable note and read
back through the modern interface. Exact mode remains opt-in; a 412 during
concurrent editing is not independently evidence of a defect.

Affected skill: `dreamlake-notes`, generated from the Notes reference. Synchronize
its public companion from this committed source. Release requires review, merge,
API/docs deployment, skill publication and fresh installed readback. None is
implied by local validation or PR creation.