fix: report document load failures instead of deferring them as -1 page count

[wittjeff]

Fixes #239. Related: docling-project/docling#3031.

Problem

When qpdf cannot parse a document, pdf_decoder<DOCUMENT>::process_document_from_bytesio correctly catches the exception, logs it, and returns false — with number_of_pages still at its -1 sentinel. But every pybind loader discards that return value:

• docling_parser::load_document returns true whenever the file merely exists;
• docling_parser::load_document_from_bytesio returns true unless an exception escapes — which it never does, because the decoder catches internally;
• both docling_threaded_base loaders have the same ignored return (their try/catch is equally unreachable for this failure).

So the Python load() — which does check the loader result and would raise — never gets the signal. The failure only surfaces later and indirectly:

parser = DoclingPdfParser()
doc = parser.load(path_or_stream=BytesIO(b"%PDF-1.4\ngarbage"))  # "succeeds"
doc.is_loaded()          # True
doc.number_of_pages()    # -1

Downstream, docling propagates the -1 as Inconsistent number of pages: N!=-1 and rejects the document via is_valid() (docling#3031). In the threaded parser it is quieter still: normalise_page_numbers(key, -1, None) silently produces an empty schedule — the corrupt document "loads" and processes zero pages with no error at all, and with an explicit page list the user gets the baffling Invalid page number 1 ... with -1 pages.

#232 (page count from getAllPages()) and #240 robustify counting for documents qpdf can open; this PR closes the remaining path, where qpdf cannot open the document at all.

Fix

All four loaders now check the decoder's result; on failure they erase the just-created decoder from the registry and return false:

• a decoder that never parsed no longer stays registered (is_loaded() reporting true with number_of_pages() == -1);
• the existing Python-side raise RuntimeError("Failed to load document with key ...") now fires at load time — a loud, immediate failure exactly where the caller can act on it (e.g. docling falling back to its lenient pypdfium2 backend, as discussed in docling#3031);
• normalise_page_numbers additionally rejects a negative page count outright, so a -1 can never silently schedule an empty task list.

This is signalling-only: documents that qpdf can parse (including with warnings) load exactly as before. No groundtruth impact.

Tests

tests/test_load_failure.py: garbage bytes via BytesIO and via file path raise RuntimeError at load() for both DoclingPdfParser and DoclingThreadedPdfParser; a failed load leaves no stale key registered; minimal valid PDFs still load with the correct page count.

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

[PeterStaar-IBM]

lgtm!

[PeterStaar-IBM]

@cau-git can you have a quick look: I think it is a good solution, but need a second pair of eyes.