feat: honour a reading order supplied by an upstream stage

[wittjeff]

Implements the mechanism proposed in #3958: let a stage upstream of reading order supply the order of a page, instead of the reading-order stage recomputing it.

What

• Cluster.reading_order: int | None = None. Any stage that knows the order of a page sets it: a layout model that predicts reading order (PP-DocLayoutV3, [Feature] Support defining reading order from the layout stage #3958, Add support for PP-DocLayout-V3 layout detection and polygon bounding boxes. #3224), the structure tree of a tagged PDF (Proposal: tagged-PDF structure ingestion for PDF/UA-2 beyond forms (companion to #4143) #4146, feat(pdf): derive layout, heading levels and alt text from the tagged-PDF structure tree #4148), native form widgets inside a field region (feat: integrate native AcroForm widgets as typed fields #4140).
• ReadingOrderModel._order_siblings: within each sibling group (top level or the children of a container), a page whose every element carries an index is sorted by it; every other page goes through the predictor together, as before. Pages are concatenated in page order, which is also how the predictor lays out its result.
• Caption, footnote and merge mapping run on the combined result unchanged, so a supplied order does not skip them (the concern raised on feat: add do_reading_order option to PdfPipelineOptions #3233).

Rules

• A page is all-or-nothing. One element without an index on a page disqualifies the page and the indices that are present are ignored, rather than interleaving two orderings. A finer merge can come later if a real case needs it.
• No index anywhere means no behaviour change: the predictor is called exactly as before with the same input.
• Ties between equal indices break on assembled order.

Relation to #3233

reorder_elements=False there is the degenerate case where postprocessor order is the supplied order for every page. This PR does not add that flag; it can be layered on top, or #3233 rebased onto this.

Tests

tests/test_readingorder_supplied_order.py:

• a fully indexed page follows the supplied order even when it contradicts geometry, and the same fixture without indices follows the predictor;
• a page with one unindexed element is predicted whole;
• a supplied page and a predicted page keep page order;
• children of a container are ordered among themselves by their indices, independently of the page's top-level elements.

No in-tree producer sets the index yet; the tagged-structure stage in #4148 is the first consumer and will be rebased onto this once the field name and the per-page rule are agreed.

Checklist:

• Documentation has been updated, if necessary.
• Examples have been added, if necessary.
• Tests have been added, if necessary.

🤖 Generated with Claude Code

[github-actions]

✅ DCO Check Passed

Thanks @wittjeff, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

🟢 Merge protection satisfied — ready to merge.

Show 1 satisfied protection

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?: