perf(mcp): 2.2× codedb_context — line-offset-cache windows for top sites

[justrach]

What

codedb_context is the heaviest gated bench case (3.6× the next tool) and the flagship first-touch call — and its "Top sites (±2 lines)" phase was 63% of the wall time: for every hit in every top file it walked the whole file byte-by-byte from offset 0 to locate the [line-2 .. line+2] window.

This PR resolves both window edges through the existing #611 LineOffsetCache in O(log n) instead, borrowing the canonical cached bytes (stable pointer — the cache keys on it; also kills the per-file arena copy) under the shared lock the phase already holds. Uncached files (released contents / CODEDB_LOW_MEMORY) keep the old scanning path as a fallback, so behavior is unchanged everywhere the fast path can't prove itself.

Two small Explorer accessors (cachedContentLocked, lineSpansFor) expose the existing private machinery; no new data structures.

Also ships CODEDB_CONTEXT_PROFILE=1 — per-phase ns breakdown of the composer on stderr (same pattern as CODEDB_LOAD_PROFILE). It's what located this hotspot, and it maps the next ones: the per-keyword search loop (48% of what remains) and the callers/callees render (32%).

Numbers (CI-identical recipe: run-bench-json.py + compare-bench.py, same machine)

	base	head	delta
codedb_context avg	224.8µs	102.6µs	−54.4%
phase: sites	122.9µs	0.9µs	−99.3%
phase profile total	195.1µs	70.9µs	−63.7%

Every other gated tool: OK (no regressions; most improved slightly from run noise).

Quality

• Slice math is edge-for-edge identical to the scanning loop (EOF-truncated windows, missing trailing newline, hit lines past EOF, empty files — all verified against lineSpans's split semantics).
• The 1-byte response_bytes delta in the bench is the response's own embedded elapsed-time string (mcpFormatDuration at mcp.zig runToolCall/handleCall) rendering fewer digits because the call got faster — confirmed by A/B'ing the binaries: the only differing bytes are the duration digits.
• zig build test: 23/23 steps, 865/865. e2e_mcp_test.py: 20/20.

🤖 Generated with Claude Code

[github-actions]

Benchmark Regression Report

Thresholds: 10.00% and 50,000 ns absolute delta

NOISE means the percentage threshold was exceeded, but the absolute delta was too small to fail CI.

Tool	Base (ns)	Head (ns)	Delta	Abs Delta (ns)	Status
codedb_bundle	71876	79398	+10.47%	+7522	NOISE
codedb_changes	10572	14097	+33.34%	+3525	NOISE
codedb_context	728663	285471	-60.82%	-443192	OK
codedb_deps	397	334	-15.87%	-63	OK
codedb_edit	41994	44141	+5.11%	+2147	OK
codedb_find	2634	2612	-0.84%	-22	OK
codedb_hot	25206	25222	+0.06%	+16	OK
codedb_outline	15882	16543	+4.16%	+661	OK
codedb_read	12647	12636	-0.09%	-11	OK
codedb_search	64389	65948	+2.42%	+1559	OK
codedb_snapshot	81754	67567	-17.35%	-14187	OK
codedb_status	9734	9139	-6.11%	-595	OK
codedb_symbol	62733	58416	-6.88%	-4317	OK
codedb_tree	33675	37387	+11.02%	+3712	NOISE
codedb_word	12768	11984	-6.14%	-784	OK

[justrach]

Post-merge addendum for the record — closing the last theoretical gap in the byte-parity claim:

The fast path borrows content via Explorer.cachedContentLocked → contents.get(path). The old path went through readContentForSearch, whose first branch is the very same contents.get(path) (explore.zig:2490) — the two paths read from one source whenever the cache holds the file. In the only case they'd diverge (cache miss → old path reads disk), the fast path is not taken at all: the original scanning code runs unchanged as the fallback. So identical bytes are structural, not coincidental — on top of the edge-for-edge window-math verification (EOF-truncated windows, no-trailing-newline files, hit lines past EOF, empty files) and the empirical A/B, where the only differing response bytes were the embedded mcpFormatDuration digits shrinking because the call got faster.