chunker: range-tighten clip + opt-in row-group splitter (no recall move; correctness only)

[arnav2]

Summary

Two chunker-side changes. Neither moves retrieval recall on the full 912 SpreadsheetBench v0.1 with either BGE-small or text-embedding-3-large. I'm proposing this for correctness / citation-grade output, not for the bench number. Be honest about that going in.

Stacked on #10 (recall-90 harness PR) since the bench instrumentation it adds is what I used to measure the (lack of) impact below.

What changed

A · Range-tightening clip in _block_to_chunk

_tight_content_bbox(block, sheet) walks the cells inside block.cell_range and returns the bbox of cells whose raw_value is non-None or display_value is non-empty whitespace. The chunk's claimed (top_left_cell, bottom_right_cell) is then clipped to that bbox before emission. The renderer continues iterating the original block.cell_range, so the narrowed claim is always a superset of cells that contributed to render_text — invariant preserved.

Concrete pathology this fixes: on the SpreadsheetBench corpus, several sheets carry styled-empty cells stretching across the full XFD width (16,384 columns). The segmenter sees them, the chunker dutifully emits a chunk claiming A1:XFD4 despite zero actual data outside the upper-left corner. Without the clip, citation UIs would highlight the entire sheet width as the "source" of any retrieved chunk.

B · _split_block_by_rows + KS_CHUNK_BUDGET_CHARS env var

Row-group splitter for oversize blocks. Each child has a tight, non-overlapping A1 range over its data rows; siblings sum to the parent's row coverage exactly. Default KS_CHUNK_BUDGET_CHARS=100000 — effectively OFF for any reasonable workbook. Available behind the env var for downstream consumers with strict per-chunk token economy.

Empirical numbers (full 912 / text-embedding-3-large)

Metric	Before this PR	After this PR	Δ
recall_text@5	0.750	0.750	—
recall_text@5_in_scope	0.838	0.838	—
recall_geometric@5	0.482	0.482	—
recall_geometric@5_in_scope	0.538	0.538	—
mean_parse_ms	156	174	+18 ms
net instance flips	—	—	0 miss→hit, 0 hit→miss

Why no retrieval delta despite a real bug fix

The over-claims happen on sheets where the GT cells live in other blocks. So the over-claim was already a false negative for geom scoring, not a false positive that needed correction — the metric just didn't see the lie. Citation UIs that highlight the chunk's claimed range are the actual beneficiaries. Without a citation-accuracy metric we can't surface that gain numerically; that metric is follow-up work (see #issue-when-i-file-it).

Type of change

• 🐞 Bug fix (chunk over-claims A1:XFD4-style ranges)
• ✨ New feature (opt-in row-group splitter behind env var, default off)
• 🧪 Parser edge case / new regression test (8 new test cases)

Test plan

• make test passes — 1071 → 1079 tests
• Full 912 SpreadsheetBench v0.1 with text-embedding-3-large: 0 instance flips, recall unchanged
• tests/test_chunker_range_tighten.py — 3 cases including a corpus-fixture invariant
• tests/test_chunker_size_cap.py — 5 cases including the env-var-driven split + default-no-split

Notes for reviewers

• Honest framing on the value: this PR is a correctness fix. If your review heuristic is "does it move the bench number," it doesn't. If it's "is the chunk's claimed range honest about what cells it covers," yes.
• B is plumbing, not active code. The default keeps tables whole. Lower the budget at your own risk, validate against your own corpus.
• Stacks on bench(harness): make malformed GT specs scorable + add in-scope recall filter #10 — review bench(harness): make malformed GT specs scorable + add in-scope recall filter #10 first.

🤖 Generated with Claude Code