feat: optionally preserve page numbers when concatenating

[ZhiyaoWen999]

Summary

• add an opt-in preserve_page_numbers argument to DoclingDocument.concatenate()
• preserve page keys, PageItem.page_no, item provenance, and key-value/form graph-cell provenance when enabled
• reject overlapping input page numbers instead of silently replacing pages
• keep the existing continuous renumbering behavior as the default

Motivation

_DocIndex.index() always calculates a page offset that shifts every input document into a continuous sequence. This also shifts the first chunk when its original page range does not start at page 1, so callers processing PDF page ranges in parallel lose the source page numbers after concatenation.

The new opt-in mode uses a zero page offset after checking that the input ranges do not overlap. Existing callers are unaffected.

Closes docling-project/docling#3890.

Validation

• targeted concatenate and filter tests: 6 passed
• Ruff lint and format checks
• MyPy on the changed implementation and tests
• issue fixtures: pages 5–10 and page 11 concatenate to pages 5–11; the 3,723-item result passes JSON serialization and model validation

[github-actions]

✅ DCO Check Passed

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

[mergify]

Merge Protections

🔴 1 of 2 protections blocking · waiting on 👀 reviews

	Protection	Waiting on
🔴	Require two reviewer for test updates	👀 reviews
🟢	Enforce conventional commit	—

🔴 Require two reviewer for test updates

Waiting for

• #approved-reviews-by >= 2

This rule is failing.

When test data is updated, we require two reviewers

• #approved-reviews-by >= 2

---

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)(?:\(.+\))?(!)?:

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[ceberam]

LGTM

[dolfim-ibm]

the PR looks good, but we want to hold until we do a full integration testing on the Docling CLI behavior and the Docling Serve API

the expected behavior is indeed, for example, that setting page_range=(10,20) will produce an output starting at page 10.