[Flasew]

Depends on ai-dynamo/kvcr#154, which adds source-owned G2 removal for move hints, and should merge after it. Review only the three feature commits. The comparison against upstream main currently also includes the parent PR's changes.

Allow kv.fetch hints to place blocks in managed destination G2 without waiting for a framework request for those keys. An unrelated request can carry the hint. Transfers continue to use complete BlockKey values and the existing fetch/move machinery.

The feature is split into three commits:

1. Hash resolution — ea35bc4

Add the source-side resolve_hashes / hashes_resolved exchange. The source resolves each uint64 hash through KeyAdapter.decode_from_router() and returns its full key, ordered layout labels, and piece sizes. The adapter owns reverse lookup: return a full key, raise KeyError for not_found, or ValueError for ambiguous_hash. Lookup runs on progress and must not block; KVCR maintains no additional hash index.

Resolution requires a managed G2 record with layout metadata. It neither reserves source memory nor transfers data; source admission revalidates residency later. A request from the same KVCR instance fails with self_source before lookup, including through endpoint aliases. Framework-only lookup and remote G3 staging are unsupported.

Ambiguity policy belongs to the integration. The companion vLLM adapter accepts inventory updates, tracks all colliding full keys, and rejects lookup until a hash becomes unique again. This includes collisions across KV cache groups. Its map requires KV cache events to be enabled. Request-scoped transfers retain exact keys supplied by the framework.

2. Independent hints — 70c41c7

scope defaults to "request": with a request ID, the hint records advice for later framework calls. Explicit scope: "independent", or submission without a request ID, starts placement immediately. mode remains "copy" or "move", defaulting to copy.

The path is submit_hint → _IndependentHintHandler → hash resolution → destination key/layout validation → ordinary core.fetch. Resolution adds one round trip before the existing transfer protocol. _HashResolutionOp tracks this exchange locally; only the resolution request and reply are wire messages. Both owners must continue calling poll_completed().

Independent work outlives its carrier request. Private advice IDs prevent collisions with request advice; completion releases temporary claims and advice. Per-hash outcomes allow partial success and are reported internally without entering framework completion results. There is no public hint-result polling API. Move inherits the base commit’s best-effort G2 removal, existing-reader protection, and no_evict behavior; completion can precede source cleanup.

Nonfatal fetch-admission exceptions fail the affected group and discard its private advice; unexpected exceptions warn once. Fatal progress errors continue to propagate to the caller.

3. Framework fallback policy — 1cd447f

Add boolean allow_framework, defaulting to true in both scopes. If source G2 disappears after resolution, the transfer may obtain the same full key from framework memory, preserving existing behavior. false requires complete managed G2 at source admission: missing/incomplete keys fail without acquiring or reusing framework pins. The policy survives retries and deferred admission, and applies to subsequent request-scoped fetch/deliver operations too.

This provides a managed-memory-only policy without pinning during resolution. It does not make framework-only hashes resolvable.

Validation

Core unit and native KVCR tests run without vLLM or Dynamo:

• Resolution tests check adapter errors, full-key identity, malformed/wrong-endpoint/duplicate/late replies, deadlines, progress while the source owner lock is held, and self-source rejection before lookup. Independent-operation tests check carrier lifetime, mixed actions, advice isolation, layouts, cached/partial destinations, copy/move overlap, cleanup, recovery after nonfatal admission errors, and fatal progress failure during actual fetch admission. Unit tests control messages and completions to establish race ordering.
• Framework-policy tests remove or replace source G2 between resolution and admission, including capacity waits and metadata retries. They verify default/allowed fallback, denied fallback, exact-key preservation, and incomplete-source behavior. Source tests also check denial of existing-pin reuse.
• Native scenarios use two processes, real NIXL/UCX and ZMQ, and JSON hints. They verify bytes through subsequent loads, source/inventory changes, reader and no_evict protection, source/destination collisions, collision recovery, cached destinations, mixed batches, disappearance/rebinding races, and drained claims/pins/advice.

Separate integration validation uses the companion vLLM adapter and temporary Dynamo composer. vLLM units check inventory/tier/collision transitions. The two-manager runner and local Dynamo-driven extension exercise production adapter callbacks, unchanged composed envelopes, unrelated carriers, ordinary loads, partial failures, rebinding, and overlapping actions. The Dynamo-driven scenarios were rerun after review. A corrected live Qwen/A100 test submits known/unknown self-addressed copy/move actions through LLMEngine.add_request: all fail with self_source before lookup or transfer, preserving cached bytes and carrier output.

Native/component transfers use CPU buffers. The live test covers rejection on one engine, superseding the earlier self-copy success claim. Full frontend HTTP/discovery transport, two complete serving workers, GPU-to-GPU transfer, and throughput are outside this validation. Unit/native checks cover the reviewed code; the independent-hint commit was also rechecked without the later framework-policy commit.