perf: CLOCK content cache for post-releaseContents search (issue #208)

[justrach]

Summary

Closes #208. Second attempt at a bounded content cache after PR #259 was reverted in 5a5ee8a.

What went wrong in PR #259

It replaced Explorer.contents: StringHashMap with contents: ContentCache (4096 slots, CLOCK eviction). Two fatal problems:

1. rebuildTrigrams / rebuildWordIndex iterate contents. Once the cache was full, subsequent puts evicted older entries silently. On a >4096-file repo, a rebuild would only re-index 4096 files; the rest disappeared from the word/trigram indexes.
2. explore: commitParsedFileOwnedOutline can leave word_index and trigram_index diverged on OOM #252 errdefer restoration broke. The old getOrPut-based flow relied on prior_content still living in contents until the errdefer could restore it. ContentCache.put freed the old entry immediately, so the rollback had nothing to restore.

This PR's approach

Keep Explorer.contents as the primary store. Add search_cache: ContentCache as a separate, bounded read-through layer only on the disk-fallback path in readContentForSearch:

contents.get (fast: first ~1000 files)
  → search_cache.get (warm: prior disk reads, bounded at 4096)
    → disk read → populate search_cache → return

How this dodges the PR #259 bugs

Bug	Mitigation
Silent index drop on rebuild	Cache is orthogonal to contents; no iteration path changes
Dangling slice on concurrent eviction	get returns a dupe (owned copy); caller handle is independent
Path lifetime coupling	put dupes path and data — cache lives independently of outlines
errdefer rollback broken	Cache is only touched inside readContentForSearch; no errdefer chain to violate
Unbounded cap mismatch	Bounded at MAX_ENTRIES=4096; misses fall through to disk, never silent loss

Where the benefit shows up

releaseContents() is called at end-of-scan on repos >1000 files (or when CODEDB_LOW_MEMORY=1). After that, contents is empty and every search hits disk. The new cache keeps the hot set resident and makes repeated searches to the same files ~3-10x faster than warm disk reads.

Test plan

• zig build test — 400/400 pass (395 baseline + 5 new)
  • ContentCache put/get round-trip returns owned copy
  • ContentCache get returns independent copy (survives eviction)
  • ContentCache bounds count at MAX_ENTRIES under pressure
  • ContentCache remove drops entry and decrements count
  • ContentCache clear resets state
• Benchmark on ~/openclaw (13,777 files, 3 trials median) — no regressions: index_ms -0.9%, queries within ±5% noise. (The bench runs before releaseContents, so it hits the contents fast path and doesn't exercise the new layer — by design. Cache wins appear only in workloads where releaseContents has fired, which the benchmark doesn't currently simulate.)

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bea5ea5e19

ℹ️ 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 search cache on file updates

readContentForSearch now returns search_cache entries before touching disk, but this cache is only cleared in removeFile and is not invalidated when a file is re-indexed after a modify event. In large repos (or CODEDB_LOW_MEMORY=1) where releaseContents() has emptied contents, this causes codedb_search/codedb_read to return stale pre-edit bytes after a file change until that entry is evicted or the server restarts. Please clear or refresh search_cache when modified files are committed to the explorer so reads stay consistent with current indexed content.

Useful? React with 👍 / 👎.