patch: revise a document as a diff, not as a re-upload (#59)

[alcor]

Closes #59.

Revising a draft meant one replace spanning the whole document. That overwrites any edit a person made in the middle since the read, gives every block a new id so anchored comments lose their text, shows up in history as one opaque rewrite, and is charged for the whole document rather than for the change. With RATE_LIMIT_CHARS_PER_HOUR at 20,000, the 9.5k-character rewrite in Nicholas's comment on the issue spent half an hour's budget restating text that had not moved.

patch(doc_id, markdown, anchors?) takes the document as it should read and applies the smallest set of block operations that gets there.

patch(doc_id, markdown, anchors?) -> { ok, replaced, inserted, deleted, charged }

How it keeps ids

app/shared/block-patch.ts is an LCS over block texts. Each run of differences between two surviving blocks is paired position by position, so a three-block run rewritten in place is three replaces that each keep their block's id, not three deletes and three inserts that do not. Leftovers become inserts or deletes.

Every index is against the document as read, so agentPatch applies back to front. A test fixes that contract.

The measured result: after patching one paragraph of a three-block document, the two untouched blocks have byte-identical anchors, and the rewritten block has the same id with a new hash.

The window it does not close, and the one it does

Running the diff inside the Durable Object closes the gap between the read and the write. It does not close the more damaging one: the agent's markdown carries its own idea of every block, so a paragraph a person rewrote since the read gets put back without anyone noticing. That is the same lost work the issue is about, arriving by a different door.

So anchors is checked — but only for the blocks the patch would actually touch. An edit in a block the patch leaves alone is none of its business and does not block it. Both cases have a test.

anchors is optional, as it is on replace. The tool description says plainly what happens without it.

empty_patch

markdown is the whole document, so an empty or truncated argument deletes it. A patch that would empty a non-empty document is refused with a new empty_patch code pointing the caller at replace. This came out of writing the test: I expected an empty string to fail parsing, and instead watched it wipe the fixture.

Charging

patchCharge counts the text the patch adds. A 3,000-character paragraph left alone while a neighbour is reworded costs the length of the reworded block, which the integration test asserts exactly.

Tests

15 unit tests on the pure diff, 8 DocumentAgent integration tests on the tool. 953 tests run, 937 pass; the 16 failures are the three localStorage suites on Node 25, which fail identically on main. Lint and typecheck clean.

Not verified: no agent has driven this over a live MCP connection, and the mode: "suggest" variant floated in the issue is not built.

🤖 Generated with Claude Code