Optional source locator on document observations (page → context, resolvable against the extraction page map)

[phernandez]

Follow-up from #1178 (raised by @calebjpicker) and related to #135.

DocumentAgentObservationV1 (in the document ingestion contracts, #1178) is intentionally minimal: category, content, tags, context — no locator. So an extracted quote is traceable to a document and to an exact stored version of it, but not to a place inside it. For legal/academic work that's the difference between a source and a cite ("Exhibit 12" vs "Exhibit 12 at 4:17–22"). The extractor already knows pages (source.page_count, extraction.pages_needing_ocr), and that information is dropped before it reaches an observation.

Shape (deferred from #1178 deliberately, additive to v1)

• An optional structured locator on the agent observation model — at least a page number, optionally line/offset — that renders deterministically into the existing context parenthetical so the line still round-trips through the real Markdown parser and satisfies require_exact_parser_semantics. (Option 2 from the feat(core): add portable document ingestion contracts #1178 discussion.)
• A page map on the document/run provenance side (offset→page ranges captured once at extraction) so any later feature can resolve a span to a page without re-parsing the PDF.
• Optionally carry the source checksum alongside the locator so a citation is verifiable (confirm the quote still matches the extracted bytes; detect drift on re-extraction) — cheap here because the ingestion contract already checksums heavily.

Because DocumentAgentObservationV1 is versioned and extra-forbidden, adding an optional field later is additive, not a breaking migration — which is why #1178 does not need to block on this.

Relationship to #135

#135 asks for section/observation anchor wikilinks at the note level generally. This issue is the document-ingestion instance of it: a PDF page anchor is one concrete kind of observation locator. Whatever addressing scheme #135 settles on, the document locator should use it rather than inventing a parallel one.

[claude]

Claude finished @phernandez's task in 37s —— View job

---

Triage

Type: Enhancement — proposes an optional, additive field on DocumentAgentObservationV1 plus a page map, not a defect.

Component: Document ingestion contracts (cloud pipeline introduced in #1178); labeled cloud accordingly. Touches the extraction/provenance side (source.page_count, extraction.pages_needing_ocr) and the observation context rendering path.

Priority: Low/Medium — no user-facing breakage; this is precision/traceability for legal/academic citation use cases. Not blocking #1178, which is explicitly designed to accept this additively later.

Complexity: Medium — the core idea (deterministic locator → context parenthetical, round-tripping through the real Markdown parser per require_exact_parser_semantics) is well-scoped, but the design has real dependencies:

• Should stay blocked on feat(core): add portable document ingestion contracts #1178 landing (it's still labeled On Hold), since the locator hangs off DocumentAgentObservationV1.
• Explicitly deferred on Section and Observation Anchor Wikilinks Support #135: the addressing scheme for observation/section anchors should be decided there first so this doesn't invent a parallel scheme for the document case.
• The optional checksum-verification piece is a further nice-to-have, not core to the ask.

No duplicate issues found. Given the two upstream dependencies (#1178, #135), this reads as well-scoped future work rather than something to start now — worth confirming with @phernandez whether this should stay open as a tracked follow-up or be folded into #135's design discussion once that scheme is settled.