Pymarc-compatible current_exception and current_chunk accessors on MARCReader

[dchud]

Closes #156

Summary

After each MARCReader.__next__ step, two pymarc-compatible accessors carry diagnostic information about what was just read:

• current_chunk — bytes of the record just read from the source (declared length per the leader). Set on every successful chunk read, regardless of whether the parse step then succeeded or failed.
• current_exception — typed MrrcException swallowed by permissive=True, or None on a clean read.

This is the bead's recommended Option A: enrich permissive=True rather than add a new pymarc_compat mode. Existing pymarc-shape error-diagnosis code (if reader.current_exception: ...) works against mrrc unchanged.

Implementation

• Rust binding (src-python/src/readers.rs): PyMARCReader carries last_chunk: Option<Vec<u8>>, populated in both read_record() and __next__() after the chunk is read, before the parse step. Exposed via #[getter] fn last_chunk.
• Python wrapper (mrrc/__init__.py): MARCReader.__init__ initializes the two attributes to None; __next__ reads _inner.last_chunk and stashes both. Clean-read path resets current_exception so callers don't see stale state.
• Type stub (mrrc/_mrrc.pyi): documented _MARCReader.last_chunk property.

Tests

tests/python/test_pymarc_compat_accessors.py covers:

• Default state (both None before any iteration).
• Clean read: current_chunk matches leader-declared length, current_exception stays None.
• Clean iteration clears stale current_exception after a prior failure.
• Permissive swallow: both accessors populated, full chunk bytes preserved.
• Strict mode raises (the accessors aren't the intended catch surface).
• Cross-library iteration-shape parity vs pymarc — guarded by pytest.importorskip("pymarc") so we don't gain a hard dep.

Documented divergences

Updated docs/guides/migration-from-pymarc.md:

• Encoding strictness: mrrc raises EncodingError (swallowed via current_exception under permissive=True) on invalid UTF-8 in subfield values where pymarc applies lossy substitution silently. Iteration shape unchanged.
• current_chunk on byte-read errors: When the underlying read of the next record's bytes fails before parsing begins (truncated stream, I/O error), current_chunk may be None even though current_exception is set. For parse failures of fully-read chunks (the common case), current_chunk carries the full record bytes as pymarc does.

Verification

• cargo test --test fuzz_regressions + full Python suite — 538 Rust + 700+ Python tests pass
• tests/python/test_pymarc_compat_accessors.py — 5 pass, 1 skip (pymarc parity, since pymarc isn't a project dep)
• .cargo/check.sh --quick and full — all green
• PR CI green on all platforms

Bead: bd-0x73.7

🤖 Generated with Claude Code

[codspeed-hq]

Merging this PR will degrade performance by 18.51%

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚡ 7 improved benchmarks
❌ 1 regressed benchmark
✅ 52 untouched benchmarks
⏩ 16 skipped benchmarks¹

⚠️ Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Mode	Benchmark	BASE	HEAD	Efficiency
⚡	WallTime	test_pipeline_parallel_4x_10k_threaded	118.2 ms	102.1 ms	+15.81%
⚡	WallTime	test_pipeline_sequential_extraction_4x_10k	118.5 ms	104.1 ms	+13.86%
⚡	WallTime	test_process_4_files_sequential	99.8 ms	84.5 ms	+18.13%
⚡	WallTime	test_process_4_files_parallel_4_threads	118.3 ms	97 ms	+21.96%
❌	WallTime	test_threaded_reading_2x_10k	285.3 ms	350.1 ms	-18.51%
⚡	WallTime	test_pipeline_sequential_1x_10k	22.4 ms	20.3 ms	+10.21%
⚡	WallTime	test_pipeline_sequential_4x_10k	99.6 ms	85.5 ms	+16.55%
⚡	WallTime	test_pipeline_parallel_2x_10k_threaded	54.5 ms	47.5 ms	+14.71%

---

_{Comparing feat/permissive-pymarc-compat (b1e0f2e) with main (297626a)}

Footnotes

1. 16 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩