nx_lora_pool.nx

nx_lora_pool.nx -- H9 Multi-LoRA adapter pool (bits-up). Per NISHI_ELDER_AI_OFF_DOCKER_2026_05_20.md §2.1 H9: serve hundreds of fine-tuned adapters from a single base model. Punica / S-LoRA ship this at scale -- one VRAM-resident backbone, N small LoRA-rank adapters (rank 4..64), per-request adapter selection at batch step time. V1 mechanics: a fixed pool of NxLoraAdapter records keyed by caller-supplied adapter_id. Each adapter carries opaque A/B tensor pointers (the substrate doesn't need to know the tensor shape to schedule routing; the consumer that runs the forward pass knows). A refcount tracks how many active batch slots / pending requests currently reference each adapter, so evict() can refuse while the adapter is in flight. Composition path: - register_adapter once when the adapter is loaded to disk/VRAM - acquire(id) when admit()ing a batch slot that wants the adapter - release(id) when the batch slot transitions DONE - evict(id) only when refcount drops to zero (cold-swap window) The lookup is linear over n_loaded (V1 honest scope: pool size stays small enough -- NX_LORA_POOL_MAX_ADAPTERS = 128 -- that linear scan beats a hash table on the substrate's allocation model; V2 can promote to open-addressed hash if profile demands). Pure substrate logic. No Linux features. Composes with shipped nx_batch_scheduler (each batch slot will eventually carry an adapter_id field threading through admit/step/complete). V1 honest scope: - Adapter ID is i64 caller-supplied (no auto-allocation in V1) - Allowed LoRA ranks are sealed-enum: 4, 8, 16, 32, 64 - Tensor data layout is OPAQUE to this primitive (A_data / B_data are *i64 pointers the consumer dereferences with its own shape knowledge; this matches how H1 nx_kv_arena treats per-page payload bytes) - alpha is stored as Q16 fixed-point (scale * 65536) to keep this primitive integer-only at the substrate layer