[DavidBellamy]

Description

Problem

Cache-aware routing treated max_cached_owners_per_prefix as a replication target. While a prefix had fewer owners than the configured value, any fleet-wide load or KV imbalance could route the next turn to an uncached worker after the cooldown. A single unrelated worker above the overload threshold could also make every prefix abandon a usable cached owner.

In the production K3 workload this caused trajectory churn: most requests with a suitable cached owner were intentionally spilled, creating repeated cold copies and heavy cache eviction instead of reusing the longest prefix.

Solution

Evaluate longest-prefix ownership before fleet-wide imbalance:

• keep routing on existing owners while at least one matching owner is below the pressure high-water mark;
• rank and filter pressure only within the matching owner set, then use atomic size-aware reserved work among suitable owners;
• create one additional owner only when every matching owner is pressured and the replication ceiling has not been reached;
• coalesce concurrent pressure spills on the existing provisional-owner cooldown;
• hold on the least-pressured owner at the ceiling or when the whole pool has no safe spill destination;
• retain size-aware P2C and owner recording for cold misses and stale or excluded owners.

Missing or stale engine telemetry fails open to known owners. Authoritative KV-event ownership is never pruned to enforce the configured ceiling.

Refs #11

Changes

• Reordered cache-aware selection so suitable longest-prefix owners precede global imbalance fallback.
• Added owner-local KV/utilization pressure selection and pressure-driven replication.
• Reinterpreted the existing owner budget as a replication ceiling instead of a target.
• Added bounded decision labels for owner holds, pressure spills, ceiling holds, and no-safe-home holds.
• Updated Rust and Python CLI help text.

Test Plan

• Exact KV-event owner remains selected when another worker is cooler and an unrelated worker exceeds the global overload threshold.
• When the only exact owner is pressured, the first request creates one provisional owner and the next request reuses it before KV events catch up.
• Sequential approximate-tree prefix extensions remain on one owner despite request-count imbalance.
• Multiple cached owners continue to use least-loaded atomic work reservations.
• The configured owner ceiling prevents pressure-driven expansion beyond the budget.
• Excluded or removed owners still fall back and age out correctly.

Validation:

• cargo +nightly fmt --all -- --check
• focused cache-aware suite: 47 passed before redundant coverage cleanup; production-path cases retained
• full SMG library suite: 1469 passed, 0 failed, 5 ignored
• cargo clippy --offline -p smg --lib --no-deps -- -D warnings -A clippy::ignored-unit-patterns
• cargo check --offline --manifest-path bindings/python/Cargo.toml
• Python ruff check and ruff format --check on touched binding files
• git diff --check

Checklist

• cargo +nightly fmt passes
• cargo clippy --all-targets --all-features -- -D warnings was not run because local OpenCV is unavailable; the production smg library target passes with warnings denied, allowing only the unrelated pre-existing current-nightly ignored-unit-patterns lint
• Documentation updated