release: 0.2.5830 performance groundwork

[justrach]

Release 0.2.5830 — performance and parity guardrails

This PR targets release/0.2.5829 and prepares the complete 0.2.5830 release. The executable benchmark candidate is bc72bfca4f4dcb9316f2f00f0ca78ab18c4e3c74; PR head 7837a33 is its documentation-only evidence successor.

Follow-up to #673.

Performance work

• rolling raw/normalized trigram construction
• O(1) exact-name symbol-index lookup
• bounded generation-validated caches for tree, outline, exact-word, and fuzzy-file results
• cached content hashes keyed by non-reused content-entry generations
• cached newline offsets and offset-based deep/context reads
• compact MCP JSON-RPC payload fast path with CR/LF sanitization retained
• render-cache synchronization with watcher mutations

No ranking formula, result cap, parser behavior, path-security policy, telemetry behavior, or MCP response schema changes.

Final paired release gate

Twenty clean, counterbalanced AB/BA pairs compared production baseline dd36e94 through pinned harness-only baseline 24e89c7 against candidate bc72bfc, using the same fixed 21-file corpus and Zig 0.17.0-dev.813+2153f8143.

• corpus fingerprint: PASS in all pairs
• commit/tree/compiler/corpus/pair/order/sequence provenance: PASS
• duration-normalized full JSON-RPC response parity across every measured iteration: PASS for every parity-enabled tool
• paired regression gate (>10% and >50us): PASS
• largest paired-median gains: symbol 81.72%, tree 67.60%, outline 59.79%, word 37.16%, bundle 27.73%, hot 17.81%, context 11.89%

Persisted report: docs/bench-0.2.5830-paired-report.md

Full methodology and transport measurements: docs/performance-0.2.5830.md

Verification

• zig build test
• zig build -Doptimize=ReleaseFast
• Windows x86_64 ReleaseFast cross-build
• zig build wasm
• MCP E2E: 20/20 passed
• paired comparator tests: 12/12 passed
• final local paired release gate: 20/20 pairs passed
• GitHub paired benchmark workflow on executable candidate passed
• git diff --check

Release preparation

• version synchronized to 0.2.5830 in Zig, release info, and npm metadata
• changelog and release notes finalized
• release workflow builds macOS arm64/x86_64, Linux arm64/x86_64, and Windows x86_64
• raw 20-pair samples are archived for attachment to the GitHub Release

[github-actions]

👋 Thanks for the contribution! Quick heads-up: this repo lands changes on the current release/* branch, not main.

Please retarget this PR via Edit → base branch to the active release branch (currently release/0.2.5825).

(Automated hint — reply here if you need a hand.)

[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	93580	61719	-34.05%	-31861	OK
codedb_changes	11068	11588	+4.70%	+520	OK
codedb_context	294694	271226	-7.96%	-23468	OK
codedb_deps	324	269	-16.98%	-55	OK
codedb_edit	61191	39582	-35.31%	-21609	OK
codedb_find	2744	3721	+35.60%	+977	NOISE
codedb_hot	24730	10744	-56.55%	-13986	OK
codedb_outline	17229	11202	-34.98%	-6027	OK
codedb_read	12971	12883	-0.68%	-88	OK
codedb_search	89920	47584	-47.08%	-42336	OK
codedb_snapshot	76563	68922	-9.98%	-7641	OK
codedb_status	10007	9998	-0.09%	-9	OK
codedb_symbol	58649	26625	-54.60%	-32024	OK
codedb_tree	14039	7920	-43.59%	-6119	OK
codedb_word	11304	10153	-10.18%	-1151	OK

[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	96322	51891	-46.13%	-44431	OK
codedb_changes	13633	10998	-19.33%	-2635	OK
codedb_context	293828	267127	-9.09%	-26701	OK
codedb_deps	366	322	-12.02%	-44	OK
codedb_edit	41204	38236	-7.20%	-2968	OK
codedb_find	2628	2782	+5.86%	+154	OK
codedb_hot	25498	10654	-58.22%	-14844	OK
codedb_outline	16408	12193	-25.69%	-4215	OK
codedb_read	13164	12387	-5.90%	-777	OK
codedb_search	90353	56572	-37.39%	-33781	OK
codedb_snapshot	70012	69300	-1.02%	-712	OK
codedb_status	9406	9440	+0.36%	+34	OK
codedb_symbol	57552	26483	-53.98%	-31069	OK
codedb_tree	13710	9002	-34.34%	-4708	OK
codedb_word	12163	10082	-17.11%	-2081	OK

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7837a331b2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Invalidate word cache when swapping indexes

If a codedb_word result is cached before replaceWordIndex() swaps in a different persisted word index, this cache is still keyed only by search_gen. replaceWordIndex() updates self.word_index/word_index_generation without changing search_gen, so a later lookup for the same word can return the pre-replacement postings from word_render_cache; include the word-index generation in the cache key or bump search_gen on every word-index replacement/invalidation.

Useful? React with 👍 / 👎.