perf(cache): flat version index, pruned per tenant

[EricAndrechek]

Part of #613. Stacked on #614 (feat/cache-snapshot).

Part of #262 (fixes the two unbounded-growth paths — growth across bumps, and a departed tenant's whole index — for the local backend). The issue stays open for a residual: per-table scope cardinality is not capped, since scope is empty until #235 populates it; see the comment on #262 for the trigger. The Redis-compatible backend (#626) bounds its versions its own way: random tokens with a TTL (version_ttl).

What changes

The local version index nested each table under its tenant's version and each scope under its table's version. Nothing was ever pruned, so every InvalidateTenant left the tenant's whole old index behind, and the index kept every tenant ever served.

• Flat index (internal/cache/version_manager.go): one version per tenant, per (tenant, table) and per (tenant, table, scope). Each is keyed by name alone and bumped in place, so the index holds one entry per live tenant, table and scope however often each is bumped. The lattice is unchanged: an entry's key (QueryKey) folds the tenant's, table's and scope's versions of each dependency, and the cachetest conformance suite still passes. Key rendering goes through internal/keyenc.Join/Escape (from feat(cache): shared redis cache, snapshot keys, uncached write pipes #614) rather than fmt.Sprintf.
• A tenant's version is a process-unique generation. The first QueryKey built for a tenant hands it out. BumpTenant (behind InvalidateTenant) drops the tenant's index, and the next key gets a fresh generation that no cached entry folds. Dropping is therefore a bump, and the tenant's memory is released. A per-tenant counter that restarted at 0 would revive entries; TestVersionManager_GenerationsNeverRepeat pins this.
• A table bump drops the table's scope versions. This is safe because every key that folds a scope version also folds the table version the bump moved (TestVersionManager_BumpTableDropsScopes). So scopes are bounded by those written since the table's last whole-table write.
• Any bump against a tenant with no index is a no-op that records nothing — table, scope or tenant alike. No key folds its next generation yet, so neither the ingest worker's sharedTables fan-out nor an insert still in flight for a just-pruned tenant recreates it (TestVersionManager_BumpWithoutIndex).
• Pruning (LocalCache.Prune, wired in internal/app/wire.go:wireCache): after every settings reload, the index of each tenant no longer served (removed or rejected) is dropped. The hook sits beside Hub.Prune and the verifier pruning, and asserts as a run-time test that the wired cache actually satisfies the small pruner interface it type-asserts on a.cache — not just a hand-substituted test double — so a backend without an in-process index (Redis) simply doesn't implement it. When such a tenant comes back, its cached results are orphaned. That already happened before this PR, through the AfterAdopt InvalidateTenant of a tenant back on a pool.
• Every version is now read under one lock, so the snapshot is fully consistent.

No change to what is cached or served.

Tests

• TestVersionManager_SizeDoesNotGrowWithBumps: 10 000 rounds of table, scope and tenant bumps interleaved with key reads. The index size stays at its settled value (the perf(cache): cache version-manager map grows unbounded with tables × scopes #262 regression test).
• TestVersionManager_{GenerationsNeverRepeat,BumpTableDropsScopes,BumpWithoutIndex,Prune}, and TestLocalCache_Prune (a pruned tenant misses and a kept tenant still hits).
• TestReload_PrunesCacheIndexToServedTenants (app): a rejected tenant, then a removed one, is reported unserved to Prune, and now also asserts the wired cache is a pruner before the test substitutes its own recorder.
• Mutation-checked: a fixed generation fails 5 tests (the conformance suite included), a BumpTable that doesn't advance the version fails 4, and wiring a cache that doesn't satisfy pruner fails the new assertion. TestVersionManager_BumpWithoutIndex was also mutation-checked against a tableLocked that wrongly creates a missing tenant's index instead of returning nil.
• make ci passes locally at HEAD.

Deliberately left to later PRs

• Per-table scope cardinality (perf(cache): cache version-manager map grows unbounded with tables × scopes #262, comment has the trigger): uncapped until Clarify/implement scope (currently always empty) #235 populates scope.
• The Redis-compatible backend (feat(cache): shared cache backend on Redis, Valkey and Dragonfly #626), the config-and-wiring factory that selects it (feat(config): cache.backend=redis selects the shared cache #630; its local branch keeps the pruner hook as is), and a near-cache, are left to later PRs.

🤖 Generated with Claude Code

https://claude.ai/code/session_017aS7rLrH1RKkUMem7X4ckd

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: 3123c0e3-05c0-4c40-bd87-972a9fa1f79b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}