nx_entity_store.nx

nx_entity_store.nx -- the SOVEREIGN ENTITY STORE. nx_gamebench gap-queue rank 1 after save/load and rpg-stats landed: entity-component-sim was PARTIAL and blocks 7 of 12 benchmarked titles (Doom actors, OpenXcom units, Diablo monsters, Cataclysm, Veloren, Freeciv, NetHack). THE HAZARD THIS PART EXISTS TO KILL -- the stale handle. Every naive entity store hands out a raw slot index. An entity dies, its slot is recycled for a new entity, and any handle still held by old code now silently addresses a DIFFERENT entity: a homing missile retargets onto a random unit, a dead unit's buff lands on its replacement. It is one of the nastiest bug classes in game code because it is invisible until it is a bug report. Here every handle carries a GENERATION stamped into it, bumped on destroy, so a stale handle is DETECTABLY invalid -- rejection is by construction, not by discipline. Other certified properties (each a gate tooth): - O(1) spawn and destroy (free-list + swap-remove), no scanning - DENSE iteration: visiting the alive set never walks holes - REPLAY-DETERMINISTIC: the same operation sequence yields the same handles and the same iteration order, so recorded input replays identically (the determinism exceed carried into simulation) - CAPACITY-BOUNDED: spawning past capacity returns the null handle, never corrupts the arena - Component values are plain i64 so entity state drops straight into gs_save/gs_load (nx_gamesave). Arena layout follows the nx_swgpu base+offset idiom: one mmap block, all offsets derived from cap/ncomp. LIB ONLY -- no main() by ecosystem convention. license_tier: ORIGINAL expect_exit: 0