Keep figures in the chunk they came from

[Paul Lizer (paullizer)]

Refs #1277

Problem

Images extracted from Word and PowerPoint were appended as extra chunks at the end of the document, with page numbers continuing past the real content. A figure on page 5 of a 15-page document became chunk 16.

That breaks retrieval in two ways: a search hit on the figure loses the text it belongs to, and a citation points at a page that does not exist.

The constraint that shaped the fix

chunk_id = f"{document_id}_{page_number}".

Two chunks sharing a page number therefore overwrite each other in the search index. Emitting a second chunk tagged "page 5" would have silently destroyed the original. Image content is instead folded into the existing chunk's content — which is both the desired behavior and the only safe one.

How placement is resolved

Source	Resolution
PDF via Content Understanding	Already correct. Figures are attributed to their page by span. Unchanged, now regression-tested.
PDF via Document Intelligence Layout	Already correct. Tables and figures are inlined into the page markdown by the service.
Equations	Already correct. Returned inline in the page markdown by both engines, so they inherit the right page.
PPTX	The slide that references the image, mapped onto the chunk covering that slide so grouped slides work.
DOCX	Position in reading order from word/document.xml, mapped proportionally onto the word-count chunks.
Legacy .doc / .ppt	No recoverable position, so the image anchors to the final chunk rather than inventing a page beyond the document.

Why proportional and not absolute for DOCX: Word has no fixed pages until rendered, and the extractor's word count does not match the raw document body exactly — it adds markdown structure and may include headers, footers, and table formatting. An absolute word offset would drift systematically and cluster every image toward the front. Relative position is self-correcting.

Merged chunks are held under a size budget derived from the chunk size cap; anything that does not fit spills to a trailing chunk rather than producing an oversized chunk.

A bug caught by verifying first

The DOCX offset groundwork was written before this PR and was unverified. Running it against a real document immediately exposed a defect: relationship targets are written as media/image1.emf in Word but ../media/image1.png in PowerPoint, and the shared path logic produced word/media/media/image1.emf for the Word form — so nothing matched. PowerPoint worked only because its ../ prefix happened to satisfy the same logic. Both now resolve through one target normalizer that requires a media parent segment, which also rejects unrelated targets such as hyperlinks.

Investigating also confirmed a surprise worth recording: in the sample document the four diagrams genuinely are at the very top (paragraphs 0–2, before the "Introduction" heading), stored as inline w:object OLE shapes with no absolute positioning. An offset of 0 was correct, not a bug.

Verification

Placement measured against a synthetic DOCX with images planted at known positions:

total body words: 1200          document produces 3 chunks
image1  offset=120  (10%) -> chunk 1
image2  offset=600  (50%) -> chunk 2
image3  offset=1080 (90%) -> chunk 3
OLD behavior would have produced chunks 4, 5, 6

New test file with 9 tests covering position detection, DOCX placement, PPTX slide mapping including the grouped case, the positionless fallback, the size budget spill, page-number uniqueness, and that Content Understanding still keeps figures on their origin page. All previously passing suites still pass.

Reviewer notes

• DOCX placement is approximate by design. Word has no pages until rendered, so this maps onto word-count chunks; it will be close, not paragraph-exact. Stated plainly in the feature doc rather than implying precision we do not have.
• Existing documents are unaffected until reprocessed. Anything already ingested keeps its trailing figure chunks until Change Extraction or a re-upload. Called out in the release notes.
• No Cosmos or search index migration; only chunk content and page assignment change.

Version bumped to 0.250.228.