feat(pdf): append an incremental update

[andiwand]

🤖 Generated with Claude Code

Phase 1 of the plan in docs/design/pdf-annotation.md — the writer itself. No annotations yet: this is the machinery they will ride on. (Was stacked on #844; rebased onto main once that merged.)

What it does

IncrementalWriter pipes the source through untouched, appends the objects it collected, and closes with a cross-reference section naming only their ids plus a trailer chaining back through /Prev (7.5.6).

Nothing is re-serialized, and that is the whole point of decision 2: every read-side gap — an unmodelled key, a filter we pass through, an object stream we never recompressed — survives because it is copied, not rewritten.

• Matches the file's own xref flavor via xref_kind() from feat(pdf): expose the parse facts a writer needs #844: a classic table, or a cross-reference stream that mints an id and an entry for itself.
• Refuses a recovered file (decision 2) and an encrypted one (decision 6) — in the constructor, which is also where start_xref_position() and xref_kind() stop being optional for everything downstream.
• /ID[1] is derived from the update's own bytes, not from a clock. Writing the same update twice gives the same file, which is what lets a test pin the output at all.
• Only the update is buffered. The source is piped, so appending to a large PDF does not hold it in memory.

Verified plumbing-first

Sequenced so the append machinery could fail separately from any annotation semantics:

1. A no-op update — changes nothing, and the result still has to parse. Both xref flavors; asserts the source survives byte for byte as a prefix.
2. A /Rotate rewrite — one integer on an existing dictionary. No new object types, no appearance stream, but it exercises the risky part: overriding an object the file already defines.

Then new objects, a stream object with a computed /Length, both refusals, and an end-to-end pass over style-various-1.pdf where page 1 rotates and page 2, the existing annotations and every content stream stay intact.

Externally, on real output: qpdf --check clean, and ghostscript, CoreGraphics and our own renderer all honour the new rotation — odr's page box turns 8.5×11in into 11×8.5in.

Known gap

A page dictionary living inside an object stream is not tested. It has to be rewritten uncompressed in the new section — legal, the newer entry wins — but no fixture we have puts one there. Recorded in the doc; owed before Phase 2 ships.

Also

docs/design/pdf-annotation.md marks Phase 1 done and folds in what it settled and what it did not.

328 PDF/parser/writer tests pass; -Werror clean; clang-tidy clean on the new files.

No consumer-visible change — internal API only — so no changelog entry.