nx_kvcache.nx

nx_kvcache.nx -- sovereign PAGED KV-CACHE (census OPPORTUNITY axis "KV-cache / paged attention", momentum 3; vLLM-class, Kwon 2023). The contiguous NxF32KVCache allocates max_seq_len rows per sequence up front: fragmentation, no sharing, one sequence per buffer. Paging fixes all three: the cache is a POOL of fixed-size BLOCKS (BS tokens); a sequence is a PAGE TABLE of block ids; blocks allocate on demand and refcount for sharing. KEY STRUCTURAL FACT exploited here: decode is APPEND-ONLY -- past rows are never mutated -- so full blocks are IMMUTABLE and can be shared forever; only the PARTIAL TAIL block ever needs copy-on-append. fork() is therefore O(page-table) + refcounts: prefill a prompt ONCE, fork N sequences that share the prompt blocks (the self-consistency / best-of-N serving pattern), each fork copies at most ONE partial block on its first append. Pool layout (f32 bits in i64 slots, engine convention): K_pool/V_pool: [n_blocks][n_layers][BS][kv_dim] row t of seq -> block pt[t / BS], offset t % BS. Fail-fast: pool exhaustion returns an error id (-1) -- NO silent fallback to contiguous. genealogy_id: kwon_2023_pagedattention lineage_id: substrate_paged_kv_v1