feat(pdf): expose the parse facts a writer needs

[andiwand]

🤖 Generated with Claude Code

Rebased onto main now that #842 and #843 have landed. Two commits.

1. The parse facts a writer needs

Appending an incremental update means knowing four things about the file you are appending to. DocumentParser computed all four and kept one:

Fact	Needed for	Before
xref(), trailer()	/Size, /Root, /ID, ids in use	already exposed
newest section's offset	the new trailer's /Prev	a local in read_trailer_chain, dropped on return
classic table vs xref stream	which flavor to append	a branch in read_xref_section whose answer was discarded
came from recovery	the refusal gate	m_recovered, private, no accessor

read_xref_section returns a named XrefSection { xref, trailer, kind } instead of a std::pair, so the kind it already determines survives the return. The chain walk records the newest section's position and kind as it goes — the newest being the one an appended section chains onto.

Four accessors: start_xref_position(), xref_kind(), is_recovered(), highest_object_id().

The first two are std::optional and recovery clears them. That is the point rather than a detail: a rebuilt table has no section of the file's own to point /Prev at, which is precisely what makes such a file unappendable (design decision 2). The refusal gate and the missing value are the same fact.

Three test cases, all on fixtures that already existed — classic table, xref stream, recovered. The position assertion reads the offset back out of the built PDF rather than hardcoding it.

2. What the spike proved

Before writing any of this in C++, a throwaway script wrote a /Highlight and an /Ink onto odr-public/pdf/style-various-1.pdf as one incremental update. qpdf --check passes and four independent engines paint both annotations with the page text showing through the highlight: ghostscript, PDFium (Chrome), CoreGraphics (Preview), and our own renderer — which emits <path fill="rgb(255,230,51)" style="mix-blend-mode:multiply"> plus a round-capped stroke.

Now facts rather than assumptions: the transparency group composites against the page and not a black backdrop; appending to a page's existing /Annots works and the newer page object wins; a classic section listing only changed ids is accepted everywhere; to_box places the result correctly.

Three things it could not reach, now called out as such in the doc:

• /QuadPoints ordering. With an /AP present, the appearance is what every one of those engines painted — the quad points were never read. Added as an open question, because it needs a different kind of oracle rather than more of the same.
• A page dictionary inside an object stream (the fixture's was plain).
• Appending to a file whose newest section is an xref stream (the fixture's was a classic table).

The last two are exactly what xref_kind() exists for, and both are owed tests in Phase 1.

The doc also marks Phases 0 and 0.5 done and splits Phase 1 so a no-op update and a /Rotate write fail separately from the annotation semantics.

327 PDF/parser/transform tests pass; -Werror clean. clang-tidy is clean on the file bar one pre-existing performance-move-const-arg at line 1724 (commit 1761fe22, untouched here).

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