Keep field-builder JSON stdout valid with modern PyMuPDF imports #95

Outcome and dependencies

Restore strict JSON output from the source-bound field-builder CLI under supported PyMuPDF 1.28.2. Prerequisite for #22; epic #12. Preserve source identity, corpus-policy checks and assessment binding.

Reproduction and confirmed cause

On unchanged delivered main 6b62693c338d222b0c415ec075a14afc543a1a53, run the existing CorpusPolicyTests.test_reconstruction_rejects_forged_eligibility_and_missing_ocr_lineage in tests/test_retrieval_corpus_policy.py using Python 3.12 / PyMuPDF 1.28.2. The field reconstruction subprocess returns output that parse_bound_json rejects at line 1, column 1.

An isolated child probe explains the failure: import fitz; print(123) writes a PyMuPDF deprecation message followed by 123 to stdout, with empty stderr. import pymupdf as fitz; print(123) writes only 123. The field builder performs two function-local legacy imports; its parent correctly expects stdout to contain exactly one JSON document.

The broad worker-repair test run exposed this existing compatibility failure: 1,362 tests, one error, six skips. The same focused field test passes with PyMuPDF 1.28.0. This is separate from #94's worker parent-process defect.

Private focused reproduction/repair receipt SHA-256: 38bb0ecf041b14084ca9ecb41c333717a77c5a0c47e18aab4fb5630c358d532f.

Proposed solution and research

Replace the two function-local imports in src/parallel_source_v4/fields.py with import pymupdf as fitz. Retain the existing API calls and strict parser. PyMuPDF's official installation documentation recommends the modern module name and lists this alias as a migration option. Verify the alias against the application's actual source-verification and reconstruction tests.

Do not strip arbitrary log lines from JSON, accept trailing content, suppress unrelated errors or relax provenance checks. Preserve the failing receipt. This changes the field-builder source identity, so generate new field/source-plan bindings before the real trial.

Acceptance

• Independently reproduce the failure on unchanged main under PyMuPDF 1.28.2 and capture child stdout/stderr.
• The field-builder subprocess returns strict JSON under 1.28.2; malformed or forged inputs remain rejected.
• All seven existing corpus-policy/OCR-lineage tests pass under 1.28.2; the focused reconstruction path also passes under established 1.28.0.
• Parser behavior, source verification, assessment identity, corpus denominator and eligibility rules remain unchanged.
• Exact diff receives independent review; supported environment and full-suite/package results are recorded with skips and limitations.
• Signed PR, exact-head CI, merge and post-merge subprocess checks complete.
• New code-identity bindings are produced before a real field rebuild; historical receipts remain unchanged.

Completion limits

Authored fixture tests establish this CLI repair. They do not establish the 10,000-paper retrieval trial, genuine OCR quality or unseen extraction qualification. Keep #22 and the epic open until their complete empirical criteria pass.

Verified completion

Delivered in PR #98, signed head 75c79f61a3a3759d4821274d47b16ad4d7e67c12, signed merge 2813c36182ff95294acee0d050f57b9f6ef0923c. All six exact-head CI checks passed. The current delivered source retains fields SHA-256 8093f8ee4e416b4184fd3d114cc5c4a76ab2596525455497fe5ad91148080b25.

Separate criterion audit SHA-256: c5a8d90a0b971b9cf513564e4d4c6951e37a4afe4a6fd96bf91f14179efb71e3. Seven corpus-policy/OCR-lineage tests passed in an independent post-merge Windows run under Python 3.12.10/PyMuPDF 1.28.2; the focused 1.28.0 comparison also passed. Full delivery validation recorded 1,362 tests, 1,356 passed, six explicit skips, zero failures/errors; package and source archive audit passed.

Fresh pre-rebuild code binding SHA-256: 0e57c7e55c737808b28a1bf516a606b35dfdf035fcf4a815c90bcd31159100d7; the lead rechecked all 87 bound method files against clean delivered main 24e1ee062103163e08d2c02669aee3bf4258fecf. Historical receipts and the old trial draft remain unchanged. This code binding is not a complete trial input/source plan and authorizes no real build.

The scoped CLI repair is complete. #22 still requires its actual corpus assessments, current input/source plan, fields/embeddings rebuild and full retrieval experiment. No full retrieval, unseen qualification or real OCR quality result is claimed here.