Module ns 

2026-09-25: KV paging namespace and wire-key derivation, and the strict parsers for the METRALE_KV_PAGING* variables.

Owner: storage, KV paging tier. Invariants:

• Every namespace returned is non-zero: derive_kv_ns falls back to FNV_OFFSET and an override of 0 is an error.
• The namespace is a pure function of its six arguments, encoded as the tagged records listed on derive_kv_ns.
• The parsers never default: junk input is an error.

The paging peer keys its residency by the u64 the client sends (snapshot_swap::run_paging_loop_shared), so the namespace folded into that key is what separates two models, and two clients of one model, on one peer. A KV GroupKey.block is a client-local disk-block index (HighSpeedSwap::alloc_disk_block_id), so two clients of one model use the same block ids for unrelated data. The namespace therefore folds a per-client salt, random per connect unless METRALE_KV_PAGING_SALT pins it: clients share peer capacity, not cached blocks.

The model fingerprint does not encode the KV cache dtype or block layout, and GroupLayout::group_id depends on num_blocks, so the namespace folds the full layout next to the fingerprint. The fingerprint arrives as a plain u64 (ModelDims::model_fp); this crate does not depend on the model config.

Constants

KV_DOMAIN

2026-09-25: Domain separator hashed into every KV namespace as the tag-0x02 record, so KV keys differ from SSM keys in the key material as well as by the peer’s per-(kind, blob_bytes) arena. ASCII "KV" + "PAGE" + 1.

KV_NS_VERSION

2026-09-25: Encoding version, hashed as the tag-0x00 record. Changing it changes every KV namespace.

Functions

cascade_conflicts_with_paging

2026-09-25: true when kv_peer_set and flag_raw selects the paging backend; an invalid flag_raw is an error. CascadeBackend evicts through per-head write_from_host, which KvPagingBackend refuses.

derive_kv_ns

2026-09-25: Derive the KV paging namespace: FNV-1a/64 over fixed-width [tag][8-byte LE] records. A change to the fields or their order must bump KV_NS_VERSION:

kv_paging_selected

2026-09-25: Resolve the METRALE_KV_PAGING value after trimming: unset or 0 is false (the raw one-sided RdmaKvBackend), 1 is true (the paging backend), anything else is an error.

parse_u64_strict

2026-09-25: Parse a u64 in decimal or 0x/0X hex, after trimming; anything else is an error naming var.

resolve_arena_bytes_from

2026-09-25: Resolve METRALE_KV_PAGING_ARENA_GB, the peer arena size in GiB (fractional accepted), floored to a multiple of block_bytes. Unset, non-finite, not above 0, or smaller than one block is an error. The raw backend sizes its arena to hold every group (RdmaKvBackend::connect); the paging arena has no such size to derive, so it must be given.

resolve_kv_ns_from

2026-09-25: Resolve the METRALE_KV_PAGING_NS value: None returns derived; a value is parsed strictly and 0 is an error.

resolve_salt_from

2026-09-25: Resolve the METRALE_KV_PAGING_SALT value: None returns Ok(None), and the caller draws a random salt; a value is parsed strictly.

wire_key

2026-09-25: Wire key for one KV block: mix64(base_group_id, ns), the fold the SSM tier’s PagingSnapshotStore::wire also uses. For a fixed namespace it is a bijection, so distinct group ids never share a key. The caller passes the id of the block’s first group, group_id(GroupKey::new(layer, block, 0, K)).