fix(cache): exact-match index replaces the global similarity walk

[TAIPANBOX]

What

SemanticCache::get/put (crates/core/src/cache.rs) are rewritten
around a per-partition exact-match index instead of one global Mutex
plus a linear walk:

1. Exact-match fast path. A cheap 64-bit hash of the normalized core
   text maps to the (small) set of candidate entries; each is verified
   against a SHA-256 digest of its own normalized core text before ever
   being served, so a 64-bit bucket collision can never serve the wrong
   response. An identical core is found in O(1) average with no embedding
   call and no similarity walk at all.
2. put replaces, not appends. A core already present in its
   partition is refreshed in place (new response, cost, created_millis,
   same id) instead of growing the partition with a duplicate.
3. Embeddings stored L2-normalized, query normalized once per lookup;
   similarity is a plain dot product. A zero vector normalizes to itself
   and dots to 0.0 against anything, never NaN.
4. No retain() inside get. Expired entries are skipped while
   walking, not swept; the sweep is partition-local and runs inside put.
5. RwLock instead of Mutex, so concurrent get callers are never
   serialized against each other. put takes the write lock.
6. O(1) eviction via a VecDeque of insertion order, with the
   exact-match index kept consistent on both eviction and replacement.

This is T3 (a wrong hit silently serves another request's response in
On mode); correctness is prioritized over speed throughout.

Why

Issue #319, same root cause as PR #326: SemanticCache::get ran under
one global lock with a full linear walk on every eligible call.

Tests

14 new, all in core::cache::tests, plus every pre-existing test (the
original 7) unchanged and green:

• identical_core_twice_replaces_not_appends
• an_exact_hit_never_walks_similarity
• a_miss_still_falls_through_to_the_similarity_walk
• hash_collision_never_serves_the_wrong_response (a test-only hook
  forces two different cores into one bucket, since a real 64-bit SipHash
  collision cannot be hand-crafted, then queries through the same
  find_exact the real get calls)
• an_expired_exact_entry_is_not_served
• expired_entries_disappear_after_a_put
• zero_vector_embedding_never_matches
• eviction_keeps_the_exact_index_in_step
• entity_and_length_guards_still_apply_on_the_similarity_path
• threshold_boundary_is_inclusive_on_the_similarity_path
• a_similarity_just_under_the_threshold_never_hits
• the_query_is_normalized_before_the_similarity_walk
• concurrent_get_and_put_never_deadlock_or_cross_wires (8 threads x 200
  put/get pairs; asserts every response served is the one its own thread
  just wrote)
• shadow_mode_still_records_and_reports_would_hits (replaces
  shadow_mode_still_never_serves: my first version of that test
  encoded a wrong assumption about get's mode contract — Shadow
  still finds and reports a hit, only Off skips lookup entirely, and
  the caller in proxy.rs is what decides not to serve it. Caught by
  running it, not by review.)

347 tests in tokenfuse-core, 1500 across the workspace, all green
(cargo test --all).

Mutation table (7 mutants, hand-planted and reverted)

#	Mutant	Caught by
m1	find_exact's digest check skipped (any candidate in the bucket accepted)	hash_collision_never_serves_the_wrong_response
m2	Exact path's TTL check dropped	an_expired_exact_entry_is_not_served, ttl_expires_entries
m3	put always appends, never checks for an existing entry	identical_core_twice_replaces_not_appends
m4a	Threshold >= -> >	threshold_boundary_is_inclusive_on_the_similarity_path
m4b	Threshold >= -> <=	a_similarity_just_under_the_threshold_never_hits
m5	Entity guard removed	eviction_keeps_the_exact_index_in_step (NOT entity_guard_blocks_number_mismatch as I expected — that pair's HashEmbedder similarity happens to stay under its own 0.9 threshold even with the guard gone, so it's a weaker witness than it looks. Recorded rather than quietly relabelled.)
m6	Partition::remove drops the exact-index cleanup on eviction	eviction_keeps_the_exact_index_in_step
m7	Query's l2_normalize call removed from get	the_query_is_normalized_before_the_similarity_walk

Every mutant was applied, the cache test suite run to confirm red, then
reverted and re-confirmed green.

Benchmark

Ignored, timing-only test (get_cost_at_10k_entries, run with --ignored --nocapture), 10,000 entries/partition (the default cap), release build:

	before (old code)	after (this PR)
exact-repeat lookup	79.751us	717ns (~111x faster)
genuine miss (similarity walk)	83.864us	207.854us (~2.5x slower)

The miss-path regression is real and reported rather than hidden: the
walk now iterates a HashMap<u64, Entry> instead of a contiguous
Vec<Entry>, which costs more per entry than it saves. Recorded as
CLAUDE.md invariant 64's own "not closed" note — a slab/Vec-backed
partition indexed by id would recover it, not done here. The hot path
this PR exists for is repeated/near-repeated traffic (most calls become
exact repeats once a cache has run for a while), and even at 207.854us
the miss path is three orders of magnitude below a live provider call.

Gates

cargo fmt --all -- --check, cargo clippy --all-targets and
cargo clippy --all-targets --all-features -- -D warnings, cargo test --all, cargo test -p tokenfuse-gateway --features cluster --test cluster_backend, every scripts/*.sh in CLAUDE.md's gate list
(core-deps.sh confirms no new dependency: sha2 is already on
tokenfuse-core's allowed list, invariant 1), and gates-have-teeth.sh
after committing: 65 cases, all as expected.

Also added: features/the-cache-stops-walking-everything.feature (8
scenarios, each bound) and CLAUDE.md invariant 64.

NOT proven

The miss-path regression (see benchmark above) is not closed, only
measured and recorded. This PR does not touch TOKENFUSE_CACHE's
default (that's PR #326) or anything about Shadow/On mode's
behavior beyond the lookup mechanics. cosine (the old, general-purpose
similarity primitive) is kept public but is no longer called from inside
this file; nothing outside it calls it either, at least as far as this
repository's own source goes.

Refs #319

🤖 Generated with Claude Code