Module ns 

KV paging namespace + wire-key derivation (ATLAS_KV_PAGING, part of the tiered-cache consolidation).

The paging peer (atlas-cache-peer) keys its KV arena purely by the u64 the client sends, so the namespace folded into every key is the ONLY thing preventing (a) two MODELS and (b) two same-model CLIENTS from silently serving each other’s KV blocks. Unlike the SSM tier’s content-derived prefix_hash, a KV GroupKey.block is a CLIENT-LOCAL disk-block-pool index (HighSpeedSwap::alloc_disk_block_id), so identical keys from two same-model clients hold UNRELATED sequence data — a model-only namespace would cross-serve with certainty (every colliding block id), not 2^-64, and a restarted client would hit its own stale pre-restart blocks. The namespace therefore folds a per-client client_salt (fresh random per connect; ATLAS_KV_PAGING_SALT pins it for tests/harness). Consequence, stated honestly: the KV paging win is peer residency + NVMe depth + capacity pooling, NOT cross-client warm hits (those need content-addressed keys — a separate chunk, same seam as the SSM decode-ns residual).

The SSM ModelFingerprint VALUE alone is insufficient here by documented design: it excludes the KV dtype and every block-geometry field (fingerprint.rs “a future KV paging tier must fold its own dtype / block_size mix-in at its own call site”), and GroupLayout::group_id numbering is layout-relative (num_blocks changes with the GPU-memory budget). So the namespace re-folds the full layout identity alongside the fingerprint.

Everything here is a DURABLE on-peer contract (the peer’s swap file outlives client rebuilds): the tagged encoding is frozen behind KV_NS_VERSION, and the hash primitives are vendored byte-for-byte (FNV-1a/64 + the splitmix64 finalizer, ~25 dependency-free lines) and golden-pinned against spark-model’s copies (ns_tests.rs here, fingerprint_tests.rs there share frozen literals) so the two crates can never drift. spark-storage stays ModelConfig-free: the fingerprint arrives as a plain u64 (ModelDims::model_fp).

Constants

KV_DOMAIN

Domain separator folded into every KV namespace so a KV wire key is domain-separated from SSM keys IN THE KEY MATERIAL, not merely by the peer’s (kind, blob_bytes) registry keying (which already gives each kind its own residency map + swap file — this fold makes cross-kind aliasing unrepresentable even if that registry keying were ever collapsed). Frozen; mnemonic "KV" + "PAGE" + 1. The SSM decode tier’s analog is atlas_kernels::DECODE_DOMAIN.

KV_NS_VERSION

Bump = deliberate fleet-wide KV cache-key rotation (document it).

Functions

cascade_conflicts_with_paging

Startup guard (env-free core): the cascade T1 (ATLAS_KV_LOCAL_GB > 0) flushes evictions DOWN via per-head write_from_host, which the block-record paging backend refuses — that combination must fail fast at construction (PCND), never bail mid-decode on the first T1 eviction. Returns true iff the incompatible combination is selected.

derive_kv_ns

Derive the KV paging namespace. FROZEN tagged encoding (injective: fixed-width [tag][8-byte LE] records) — any field or order change is a deliberate fleet cache flush and must bump KV_NS_VERSION:

kv_paging_selected

ATLAS_KV_PAGING selection (env-free core): unset or 0 ⇒ the raw dumb one-sided RdmaKvBackend path (client-owned allocator; its handshake is the v2 header with blob_bytes == 0); 1 ⇒ the peer-owned paging backend. Anything else is a startup ERROR (PCND — a typo must never silently pick a path).

parse_u64_strict

Strict u64 parser for the env overrides (decimal or 0x-hex). Junk is a startup ERROR, never a silent fallthrough (PCND).

resolve_arena_bytes_from

ATLAS_KV_PAGING_ARENA_GB (REQUIRED when the flag is on — no implicit default, PCND): the peer warm-arena size in GiB (fractional accepted), floored to a multiple of block_bytes and required to hold ≥ 1 block. The raw path sized the peer to num_groups × group_stride (every group a guaranteed slot); the paging arena is a deliberately smaller warm cache over the peer’s NVMe swap, so the operator must choose it explicitly.

resolve_kv_ns_from

ATLAS_KV_PAGING_NS override (env-free core): strict parse, 0 rejected — a shared peer must always be namespaced (the ns=0 passthrough is unrepresentable, mirroring the landed SSM fix). None ⇒ the derived ns.

resolve_salt_from

ATLAS_KV_PAGING_SALT override (env-free core): strict; Ok(None) ⇒ the caller generates a fresh random per-connect salt (client isolation + self-healing restart staleness — old-salt peer entries become unreachable and LRU-age out), INFO-logging it for reproducibility.

wire_key

Wire key for one KV block: the namespace fold of the block’s BASE dense group id — group_id(GroupKey::new(layer, block, 0, K)), injective across (layer, block) within a layout (layout identity rides in the ns, so cross-layout ids cannot alias). Same splitmix fold as the SSM tier’s PagingSnapshotStore::wire — bijective per namespace, so no birthday risk over the dense group-id keyspace.