@ecsia/core 0.1.0

package/dist/config.js

@@ -0,0 +1,70 @@
+// WorldOptions, canonical defaults, and fail-fast resolution/validation.
+// All feature knobs are nested under their feature key ( nesting rule).
+/** Thrown synchronously at construction for any invalid configuration. */
+export class ConfigError extends Error {
+    name = 'ConfigError';
+    constructor(message) {
+        super(message);
+    }
+}
+const isPositiveInt = (n) => Number.isInteger(n) && n > 0;
+export function resolveOptions(options = {}) {
+    const generationBits = options.generationBits ?? 10;
+    if (!Number.isInteger(generationBits) || generationBits < 0 || generationBits > 31) {
+        throw new ConfigError(`generationBits must be an integer in [0, 31] (so indexBits = 32 - generationBits is valid); got ${generationBits}`);
+    }
+    const indexBits = 32 - generationBits;
+    const threaded = options.threaded ?? false;
+    // Generations are the worker stale-handle detection mechanism; 0 is unsafe under threading.
+    if (generationBits === 0 && threaded) {
+        throw new ConfigError('generationBits must be > 0 when threaded === true (worker stale-handle detection)');
+    }
+    const maxEntities = options.maxEntities ?? 1 << 20;
+    if (!isPositiveInt(maxEntities)) {
+        throw new ConfigError(`maxEntities must be a positive integer; got ${maxEntities}`);
+    }
+    const maxIndex = 2 ** indexBits;
+    if (maxEntities > maxIndex) {
+        throw new ConfigError(`maxEntities (${maxEntities}) exceeds the index space 2^${indexBits} = ${maxIndex} for generationBits=${generationBits}`);
+    }
+    const maxHotArchetypes = options.maxHotArchetypes ?? Math.max(256, maxEntities >>> 8);
+    if (!isPositiveInt(maxHotArchetypes)) {
+        throw new ConfigError(`maxHotArchetypes must be a positive integer; got ${maxHotArchetypes}`);
+    }
+    const relations = options.relations ?? [];
+    const r = options.reactivity ?? {};
+    const maxWritesPerFrame = r.maxWritesPerFrame ?? maxEntities * 4;
+    const maxShapeChangesPerFrame = r.maxShapeChangesPerFrame ?? maxEntities * 2;
+    if (!isPositiveInt(maxWritesPerFrame)) {
+        throw new ConfigError(`reactivity.maxWritesPerFrame must be a positive integer; got ${maxWritesPerFrame}`);
+    }
+    if (!isPositiveInt(maxShapeChangesPerFrame)) {
+        throw new ConfigError(`reactivity.maxShapeChangesPerFrame must be a positive integer; got ${maxShapeChangesPerFrame}`);
+    }
+    // Two-word log entries when any relation is registered ( C2).
+    const logEntryWords = r.logEntryWords ?? (relations.length > 0 ? 2 : 1);
+    const workers = options.scheduler?.workers ?? 0;
+    if (typeof workers === 'number' && (!Number.isInteger(workers) || workers < 0)) {
+        throw new ConfigError(`scheduler.workers must be a non-negative integer or 'no-sab'; got ${workers}`);
+    }
+    return {
+        components: options.components ?? [],
+        relations,
+        systems: options.systems ?? [],
+        maxEntities,
+        generationBits,
+        indexBits,
+        threaded,
+        maxHotArchetypes,
+        reactivity: {
+            maxWritesPerFrame,
+            maxShapeChangesPerFrame,
+            observerCadence: r.observerCadence ?? 'frame-end',
+            changeTrackingDefault: r.changeTrackingDefault ?? 'component',
+            logEntryWords,
+            shrinkRings: r.shrinkRings ?? false,
+        },
+        scheduler: { workers },
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/entity/codec.d.ts

@@ -0,0 +1,45 @@
+import type { EntityHandle as SchemaEntityHandle, EntityIndex as SchemaEntityIndex } from '@ecsia/schema';
+/** A packed u32: [generation: generationBits][index: indexBits], generation in the HIGH bits. */
+export type EntityHandle = SchemaEntityHandle;
+/** The low-bits index portion — the slot in the dense/sparse arrays. */
+export type EntityIndex = SchemaEntityIndex;
+/** The generation (version) counter for a slot. */
+export type EntityGeneration = number & {
+    readonly __ecsiaEntityGeneration: unique symbol;
+};
+export interface HandleLayout {
+    readonly indexBits: number;
+    readonly generationBits: number;
+    /** Low-bits mask isolating the index. */
+    readonly indexMask: number;
+    /** Unshifted generation mask (`(1 << generationBits) - 1`). */
+    readonly generationMask: number;
+    /** `=== indexBits`. */
+    readonly generationShift: number;
+    /** Largest valid index (`indexMask`). */
+    readonly maxIndex: number;
+    /** Generation value just before wrap to 0 (`generationMask`). */
+    readonly maxGeneration: number;
+    /** Number of addressable slots (`maxIndex + 1`). */
+    readonly capacity: number;
+}
+/** Sentinel for "no entity" in eid fields and APIs that may return absent. NOT a live handle. */
+export declare const NO_ENTITY: EntityHandle;
+/** Alias of {@link NO_ENTITY} for call sites that prefer the "null handle" spelling. */
+export declare const NULL_ENTITY: SchemaEntityHandle;
+/**
+ * True when `handle` is the {@link NO_ENTITY} sentinel (an absent / null handle). Use this to
+ * discriminate handles returned from APIs that may yield "no entity" without comparing against the
+ * raw `0xffffffff` literal: `if (isNoEntity(h)) { ... }`.
+ */
+export declare function isNoEntity(handle: EntityHandle): boolean;
+/**
+ * Build the immutable handle layout from a generation-bit split. `indexBits = 32 -
+ * generationBits`. `1 << 32` is 1 in JS (shift is mod-32), so the all-ones index mask is
+ * special-cased for `generationBits === 0`.
+ */
+export declare function makeHandleLayout(generationBits: number): HandleLayout;
+export declare function makeHandle(index: number, generation: number, layout: HandleLayout): EntityHandle;
+export declare function handleIndex(handle: EntityHandle, layout: HandleLayout): EntityIndex;
+export declare function handleGeneration(handle: EntityHandle, layout: HandleLayout): EntityGeneration;
+//# sourceMappingURL=codec.d.ts.map

package/dist/entity/codec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.d.ts","sourceRoot":"","sources":["../../src/entity/codec.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,IAAI,kBAAkB,EAAE,WAAW,IAAI,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAGzG,iGAAiG;AACjG,MAAM,MAAM,YAAY,GAAG,kBAAkB,CAAA;AAE7C,wEAAwE;AACxE,MAAM,MAAM,WAAW,GAAG,iBAAiB,CAAA;AAE3C,mDAAmD;AACnD,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,uBAAuB,EAAE,OAAO,MAAM,CAAA;CAAE,CAAA;AAE3F,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,+DAA+D;IAC/D,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,uBAAuB;IACvB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,yCAAyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,iEAAiE;IACjE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,iGAAiG;AACjG,eAAO,MAAM,SAAS,EAAiB,YAAY,CAAA;AAEnD,wFAAwF;AACxF,eAAO,MAAM,WAAW,oBAAY,CAAA;AAEpC;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAExD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,cAAc,EAAE,MAAM,GAAG,YAAY,CAiBrE;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,GAAG,YAAY,CAOhG;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,GAAG,WAAW,CAEnF;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,YAAY,GAAG,gBAAgB,CAE7F"}

package/dist/entity/codec.js

@@ -0,0 +1,53 @@
+// The generational handle: a packed u32 [generation: high][index: low].
+// Encode/decode are pure, branch-free bit ops; the brand is erased at runtime.
+import { IS_DEV } from '../env.js';
+/** Sentinel for "no entity" in eid fields and APIs that may return absent. NOT a live handle. */
+export const NO_ENTITY = 0xffffffff;
+/** Alias of {@link NO_ENTITY} for call sites that prefer the "null handle" spelling. */
+export const NULL_ENTITY = NO_ENTITY;
+/**
+ * True when `handle` is the {@link NO_ENTITY} sentinel (an absent / null handle). Use this to
+ * discriminate handles returned from APIs that may yield "no entity" without comparing against the
+ * raw `0xffffffff` literal: `if (isNoEntity(h)) { ... }`.
+ */
+export function isNoEntity(handle) {
+    return handle === NO_ENTITY;
+}
+/**
+ * Build the immutable handle layout from a generation-bit split. `indexBits = 32 -
+ * generationBits`. `1 << 32` is 1 in JS (shift is mod-32), so the all-ones index mask is
+ * special-cased for `generationBits === 0`.
+ */
+export function makeHandleLayout(generationBits) {
+    if (!Number.isInteger(generationBits) || generationBits < 0 || generationBits > 31) {
+        throw new RangeError(`generationBits must be an integer in [0, 31]; got ${generationBits}`);
+    }
+    const indexBits = 32 - generationBits;
+    const indexMask = generationBits === 0 ? 0xffffffff : ((1 << indexBits) - 1) >>> 0;
+    const generationMask = generationBits === 0 ? 0 : ((1 << generationBits) - 1) >>> 0;
+    return Object.freeze({
+        indexBits,
+        generationBits,
+        indexMask,
+        generationMask,
+        generationShift: indexBits,
+        maxIndex: indexMask,
+        maxGeneration: generationMask,
+        capacity: indexMask + 1,
+    });
+}
+export function makeHandle(index, generation, layout) {
+    // Dev-mode guard: a generation above maxGeneration would overflow the
+    // generation field and silently alias another slot's handle. Stripped in production builds.
+    if (IS_DEV && generation > layout.maxGeneration) {
+        throw new RangeError(`makeHandle: generation ${generation} exceeds maxGeneration ${layout.maxGeneration}`);
+    }
+    return (((generation << layout.generationShift) | index) >>> 0);
+}
+export function handleIndex(handle, layout) {
+    return ((handle & layout.indexMask) >>> 0);
+}
+export function handleGeneration(handle, layout) {
+    return ((handle >>> layout.generationShift) & layout.generationMask);
+}
+//# sourceMappingURL=codec.js.map

package/dist/entity/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/entity/codec.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,+EAA+E;AAK/E,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AA4BlC,iGAAiG;AACjG,MAAM,CAAC,MAAM,SAAS,GAAG,UAA0B,CAAA;AAEnD,wFAAwF;AACxF,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,CAAA;AAEpC;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,MAAoB;IAC7C,OAAQ,MAAiB,KAAM,SAAoB,CAAA;AACrD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,cAAsB;IACrD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,cAAc,GAAG,CAAC,IAAI,cAAc,GAAG,EAAE,EAAE,CAAC;QACnF,MAAM,IAAI,UAAU,CAAC,qDAAqD,cAAc,EAAE,CAAC,CAAA;IAC7F,CAAC;IACD,MAAM,SAAS,GAAG,EAAE,GAAG,cAAc,CAAA;IACrC,MAAM,SAAS,GAAG,cAAc,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAA;IAClF,MAAM,cAAc,GAAG,cAAc,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,cAAc,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAA;IACnF,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,SAAS;QACT,cAAc;QACd,SAAS;QACT,cAAc;QACd,eAAe,EAAE,SAAS;QAC1B,QAAQ,EAAE,SAAS;QACnB,aAAa,EAAE,cAAc;QAC7B,QAAQ,EAAE,SAAS,GAAG,CAAC;KACxB,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,KAAa,EAAE,UAAkB,EAAE,MAAoB;IAChF,sEAAsE;IACtE,4FAA4F;IAC5F,IAAI,MAAM,IAAI,UAAU,GAAG,MAAM,CAAC,aAAa,EAAE,CAAC;QAChD,MAAM,IAAI,UAAU,CAAC,0BAA0B,UAAU,0BAA0B,MAAM,CAAC,aAAa,EAAE,CAAC,CAAA;IAC5G,CAAC;IACD,OAAO,CAAC,CAAC,CAAC,UAAU,IAAI,MAAM,CAAC,eAAe,CAAC,GAAG,KAAK,CAAC,KAAK,CAAC,CAAiB,CAAA;AACjF,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,MAAoB,EAAE,MAAoB;IACpE,OAAO,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAgB,CAAA;AAC3D,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAoB,EAAE,MAAoB;IACzE,OAAO,CAAC,CAAC,MAAM,KAAK,MAAM,CAAC,eAAe,CAAC,GAAG,MAAM,CAAC,cAAc,CAAqB,CAAA;AAC1F,CAAC"}

package/dist/entity/index-allocator.d.ts

@@ -0,0 +1,46 @@
+import type { EntityHandle, HandleLayout } from './codec.js';
+export declare class CapacityExceeded extends Error {
+    readonly name = "CapacityExceeded";
+    constructor(capacity: number, aliveCount: number);
+}
+/**
+ * Asked of the store when a brand-new index would exceed the currently-addressable array
+ * length. Returns the new addressable length after growth; returns the
+ * unchanged length when growth is impossible, which makes `allocEntity` throw CapacityExceeded.
+ */
+export type GrowHook = (need: number) => number;
+export interface EntityIndexArrays {
+    /** sparse[index] = position of `index` within `dense`. */
+    readonly sparse: Uint32Array;
+    /** dense[pos] = a full EntityHandle; [0, aliveCount) alive, [aliveCount, denseLen) parked-free. */
+    readonly dense: Uint32Array;
+    /** Per-slot generation, addressed by index (only low generationBits used). */
+    readonly generation: Uint32Array;
+}
+/** Tuning for the mint-time bounds: how many indices are addressable now vs. ever allowed. */
+export interface EntityIndexBounds {
+    /** Current addressable array length (grows via the GrowHook up to `ceiling`). */
+    readonly addressable: number;
+    /**
+     * Hard mint ceiling: the largest number of distinct indices that may ever be minted. The
+     * allocator throws CapacityExceeded once denseLen reaches this with no free slot. Typically
+     * `min(maxEntities, maxIndex + 1)`, minus one when threaded to reserve `maxIndex` for the
+     * NO_ENTITY sentinel.
+     */
+    readonly ceiling: number;
+}
+export declare class EntityIndex {
+    #private;
+    constructor(layout: HandleLayout, arrays: EntityIndexArrays, bounds?: EntityIndexBounds, grow?: GrowHook);
+    /** Re-publish the backing arrays after a growth; positions/cursors are unchanged. */
+    rebind(arrays: EntityIndexArrays, addressable: number): void;
+    get aliveCount(): number;
+    get denseLen(): number;
+    get wrapped(): boolean;
+    allocEntity(): EntityHandle;
+    freeEntity(handle: EntityHandle): void;
+    /** The full (generational) handle currently occupying `index`, or NO_ENTITY-equivalent if dead. */
+    handleOfIndex(index: number): EntityHandle;
+    isAlive(handle: EntityHandle): boolean;
+}
+//# sourceMappingURL=index-allocator.d.ts.map

package/dist/entity/index-allocator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-allocator.d.ts","sourceRoot":"","sources":["../../src/entity/index-allocator.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE5D,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,SAAkB,IAAI,sBAAqB;gBAC/B,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM;CAKjD;AAED;;;;GAIG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;AAE/C,MAAM,WAAW,iBAAiB;IAChC,0DAA0D;IAC1D,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,mGAAmG;IACnG,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAA;CACjC;AAOD,8FAA8F;AAC9F,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB;AAED,qBAAa,WAAW;;gBAUV,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE,iBAAiB,EAAE,IAAI,CAAC,EAAE,QAAQ;IAaxG,qFAAqF;IACrF,MAAM,CAAC,MAAM,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IAK5D,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,WAAW,IAAI,YAAY;IAqC3B,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IAwBtC,mGAAmG;IACnG,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY;IAM1C,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO;CAOvC"}

package/dist/entity/index-allocator.js

@@ -0,0 +1,121 @@
+// The dense/sparse swap-and-move free-list: the authoritative registry of
+// which index slots are alive and at which generation. All mutation here is single-writer
+// (main-thread, serial phase). `dense` stores full handles (index ⊕ generation) so recycling
+// can reissue the bumped handle with a single read.
+import { handleIndex, makeHandle } from './codec.js';
+export class CapacityExceeded extends Error {
+    name = 'CapacityExceeded';
+    constructor(capacity, aliveCount) {
+        super(`entity index space exhausted: ${aliveCount} alive at capacity ${capacity}; raise indexBits (lower generationBits) or maxEntities`);
+    }
+}
+export class EntityIndex {
+    #layout;
+    #arrays;
+    #cursors = { aliveCount: 0, denseLen: 0 };
+    /** Set once on the first generation wrap of any slot, for the dev-mode warning. */
+    #wrapped = false;
+    #addressable;
+    #ceiling;
+    #grow;
+    constructor(layout, arrays, bounds, grow) {
+        this.#layout = layout;
+        this.#arrays = arrays;
+        const len = arrays.dense.length;
+        this.#addressable = bounds?.addressable ?? len;
+        // Without an explicit ceiling the allocator can only address what it was handed: cap mints
+        // at the array length (still never beyond the index space).
+        this.#ceiling = bounds?.ceiling ?? Math.min(len, this.#layout.maxIndex + 1);
+        // Default hook: no growth — minting past `addressable` is impossible, so it stays put and
+        // the ceiling guard throws.
+        this.#grow = grow ?? (() => this.#addressable);
+    }
+    /** Re-publish the backing arrays after a growth; positions/cursors are unchanged. */
+    rebind(arrays, addressable) {
+        this.#arrays = arrays;
+        this.#addressable = addressable;
+    }
+    get aliveCount() {
+        return this.#cursors.aliveCount;
+    }
+    get denseLen() {
+        return this.#cursors.denseLen;
+    }
+    get wrapped() {
+        return this.#wrapped;
+    }
+    allocEntity() {
+        const c = this.#cursors;
+        {
+            const { sparse, dense } = this.#arrays;
+            if (c.aliveCount < c.denseLen) {
+                const pos = c.aliveCount;
+                const handle = dense[pos];
+                const index = handleIndex(handle, this.#layout);
+                sparse[index] = pos;
+                c.aliveCount += 1;
+                return handle;
+            }
+        }
+        // Mint a brand-new index. The ceiling is the real, addressable bound (the backing-array
+        // length, capped by the index space); never mint an index we cannot store.
+        if (c.denseLen >= this.#ceiling) {
+            throw new CapacityExceeded(this.#ceiling, c.aliveCount);
+        }
+        if (c.denseLen >= this.#addressable) {
+            // Ask the store to grow the backing arrays and re-publish via rebind(); if it cannot,
+            // addressable is unchanged and we are genuinely exhausted.
+            const grown = this.#grow(c.denseLen + 1);
+            if (c.denseLen >= grown) {
+                throw new CapacityExceeded(this.#ceiling, c.aliveCount);
+            }
+        }
+        const { sparse, dense, generation } = this.#arrays;
+        const index = c.denseLen;
+        generation[index] = 0;
+        const handle = makeHandle(index, 0, this.#layout);
+        dense[index] = handle;
+        sparse[index] = index;
+        c.denseLen += 1;
+        c.aliveCount += 1;
+        return handle;
+    }
+    freeEntity(handle) {
+        const { sparse, dense, generation } = this.#arrays;
+        const c = this.#cursors;
+        const layout = this.#layout;
+        const index = handleIndex(handle, layout);
+        const pos = sparse[index];
+        const lastAlive = c.aliveCount - 1;
+        const lastHandle = dense[lastAlive];
+        const lastIndex = handleIndex(lastHandle, layout);
+        dense[pos] = lastHandle;
+        sparse[lastIndex] = pos;
+        const prevGen = generation[index];
+        const nextGen = (prevGen + 1) & layout.generationMask;
+        if (nextGen < prevGen)
+            this.#wrapped = true;
+        generation[index] = nextGen;
+        const newHandle = makeHandle(index, nextGen, layout);
+        dense[lastAlive] = newHandle;
+        sparse[index] = lastAlive;
+        c.aliveCount = lastAlive;
+    }
+    /** The full (generational) handle currently occupying `index`, or NO_ENTITY-equivalent if dead. */
+    handleOfIndex(index) {
+        if (index >= this.#cursors.denseLen)
+            return 0xffffffff;
+        const gen = this.#arrays.generation[index];
+        return makeHandle(index, gen, this.#layout);
+    }
+    isAlive(handle) {
+        const index = handleIndex(handle, this.#layout);
+        if (index >= this.#cursors.denseLen)
+            return false;
+        const pos = this.#arrays.sparse[index];
+        if (pos >= this.#cursors.aliveCount)
+            return false;
+        return this.#arrays.dense[pos] === handle;
+    }
+}
+//# sourceMappingURL=index-allocator.js.map

package/dist/entity/index-allocator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-allocator.js","sourceRoot":"","sources":["../../src/entity/index-allocator.ts"],"names":[],"mappings":"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"}

package/dist/entity/index.d.ts

@@ -0,0 +1,13 @@
+export { makeHandle, handleIndex, handleGeneration, makeHandleLayout, NO_ENTITY, NULL_ENTITY, isNoEntity } from './codec.js';
+export type { EntityHandle, EntityIndex, EntityGeneration, HandleLayout } from './codec.js';
+export { EntityIndex as EntityIndexAllocator, CapacityExceeded } from './index-allocator.js';
+export type { EntityIndexArrays } from './index-allocator.js';
+export { EntityRecord, ARCHETYPE_NONE } from './record.js';
+export type { EntityRecordArrays, EntityLocation } from './record.js';
+export { EntityRef } from './ref.js';
+export type { EntityAccessors, AccessorResolver } from './ref.js';
+export { reserveEntityBlock, returnReservedIds } from './reservation.js';
+export type { EntityReservation } from './reservation.js';
+export { EntityStore } from './store.js';
+export type { EntityStoreConfig, HandleStats } from './store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/entity/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/entity/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAC5H,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE3F,OAAO,EAAE,WAAW,IAAI,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC5F,YAAY,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAE7D,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC1D,YAAY,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAErE,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACpC,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAEjE,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACxE,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAEzD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,YAAY,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}

package/dist/entity/index.js

@@ -0,0 +1,7 @@
+export { makeHandle, handleIndex, handleGeneration, makeHandleLayout, NO_ENTITY, NULL_ENTITY, isNoEntity } from './codec.js';
+export { EntityIndex as EntityIndexAllocator, CapacityExceeded } from './index-allocator.js';
+export { EntityRecord, ARCHETYPE_NONE } from './record.js';
+export { EntityRef } from './ref.js';
+export { reserveEntityBlock, returnReservedIds } from './reservation.js';
+export { EntityStore } from './store.js';
+//# sourceMappingURL=index.js.map

package/dist/entity/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/entity/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAG5H,OAAO,EAAE,WAAW,IAAI,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAG5F,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAG1D,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAGpC,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAGxE,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}

package/dist/entity/record.d.ts

@@ -0,0 +1,28 @@
+import type { EntityHandle, HandleLayout } from './codec.js';
+/**
+ * Record sentinel for an index not yet placed into any archetype. Normatively owned by
+ * declared here as the value the record arrays carry pre-placement.
+ */
+export declare const ARCHETYPE_NONE = 4294967295;
+export interface EntityRecordArrays {
+    /** recordArchetypeId[index] = the ArchetypeId the entity currently lives in. */
+    readonly recordArchetypeId: Uint32Array;
+    /** recordArchetypeRow[index] = the row within that archetype's SoA columns. */
+    readonly recordArchetypeRow: Uint32Array;
+}
+export interface EntityLocation {
+    readonly archetypeId: number;
+    readonly row: number;
+}
+export declare class EntityRecord {
+    #private;
+    constructor(layout: HandleLayout, arrays: EntityRecordArrays);
+    rebind(arrays: EntityRecordArrays): void;
+    commitRecord(index: number, archetypeId: number, row: number): void;
+    resolveLocation(handle: EntityHandle): EntityLocation;
+    /** The archetype id of an entity by its (already-decoded) index — the storage RecordSurface. */
+    archetypeIdOf(index: number): number;
+    /** The row of an entity within its archetype by its index — the storage RecordSurface. */
+    rowOf(index: number): number;
+}
+//# sourceMappingURL=record.d.ts.map

package/dist/entity/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../src/entity/record.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE5D;;;GAGG;AACH,eAAO,MAAM,cAAc,aAAa,CAAA;AAExC,MAAM,WAAW,kBAAkB;IACjC,gFAAgF;IAChF,QAAQ,CAAC,iBAAiB,EAAE,WAAW,CAAA;IACvC,+EAA+E;IAC/E,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CAAA;CACzC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CACrB;AAED,qBAAa,YAAY;;gBAIX,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,kBAAkB;IAK5D,MAAM,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAKxC,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAKnE,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,cAAc;IAQrD,gGAAgG;IAChG,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAIpC,0FAA0F;IAC1F,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;CAG7B"}

package/dist/entity/record.js

@@ -0,0 +1,42 @@
+// The two-word entity record: two parallel flat arrays addressed by the
+// handle's index. Writing both words is the structural commit point (INVARIANT C1). The
+// commit is wrapped in `commitRecord` so a future v2 can swap the two plain stores for an
+// Atomics pair without touching callers.
+import { handleIndex } from './codec.js';
+/**
+ * Record sentinel for an index not yet placed into any archetype. Normatively owned by
+ * declared here as the value the record arrays carry pre-placement.
+ */
+export const ARCHETYPE_NONE = 0xffffffff;
+export class EntityRecord {
+    #layout;
+    #arrays;
+    constructor(layout, arrays) {
+        this.#layout = layout;
+        this.#arrays = arrays;
+    }
+    rebind(arrays) {
+        this.#arrays = arrays;
+    }
+    // Row word first, id word second; v1 stores are plain.
+    commitRecord(index, archetypeId, row) {
+        this.#arrays.recordArchetypeRow[index] = row;
+        this.#arrays.recordArchetypeId[index] = archetypeId;
+    }
+    resolveLocation(handle) {
+        const index = handleIndex(handle, this.#layout);
+        return {
+            archetypeId: this.#arrays.recordArchetypeId[index],
+            row: this.#arrays.recordArchetypeRow[index],
+        };
+    }
+    /** The archetype id of an entity by its (already-decoded) index — the storage RecordSurface. */
+    archetypeIdOf(index) {
+        return this.#arrays.recordArchetypeId[index];
+    }
+    /** The row of an entity within its archetype by its index — the storage RecordSurface. */
+    rowOf(index) {
+        return this.#arrays.recordArchetypeRow[index];
+    }
+}
+//# sourceMappingURL=record.js.map

package/dist/entity/record.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.js","sourceRoot":"","sources":["../../src/entity/record.ts"],"names":[],"mappings":"AAAA,wEAAwE;AACxE,wFAAwF;AACxF,0FAA0F;AAC1F,yCAAyC;AAEzC,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAGxC;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAA;AAcxC,MAAM,OAAO,YAAY;IACd,OAAO,CAAc;IAC9B,OAAO,CAAoB;IAE3B,YAAY,MAAoB,EAAE,MAA0B;QAC1D,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;QACrB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACvB,CAAC;IAED,MAAM,CAAC,MAA0B;QAC/B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAA;IACvB,CAAC;IAED,uDAAuD;IACvD,YAAY,CAAC,KAAa,EAAE,WAAmB,EAAE,GAAW;QAC1D,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,KAAK,CAAC,GAAG,GAAG,CAAA;QAC5C,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,KAAK,CAAC,GAAG,WAAW,CAAA;IACrD,CAAC;IAED,eAAe,CAAC,MAAoB;QAClC,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,CAAA;QAC/C,OAAO;YACL,WAAW,EAAE,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,KAAK,CAAW;YAC5D,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,KAAK,CAAW;SACtD,CAAA;IACH,CAAC;IAED,gGAAgG;IAChG,aAAa,CAAC,KAAa;QACzB,OAAO,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,KAAK,CAAW,CAAA;IACxD,CAAC;IAED,0FAA0F;IAC1F,KAAK,CAAC,KAAa;QACjB,OAAO,IAAI,CAAC,OAAO,CAAC,kBAAkB,CAAC,KAAK,CAAW,CAAA;IACzD,CAAC;CACF"}

package/dist/entity/ref.d.ts

@@ -0,0 +1,70 @@
+import type { EntityHandle } from './codec.js';
+import type { EntityRecord } from './record.js';
+import type { ComponentDef, ReadOf, Schema, WriteOf } from '@ecsia/schema';
+/**
+ * Resolves the (archetype, component) accessor singleton for an entity, pokes its row/handle, and
+ * returns it. The world installs one resolver per world; binds against a directly-allocated
+ * column set, binds against the entity's real archetype (the archetype-binding seam).
+ */
+export interface AccessorResolver {
+    resolveRead(handle: EntityHandle, archetypeId: number, row: number, def: unknown): unknown;
+    resolveWrite(handle: EntityHandle, archetypeId: number, row: number, def: unknown): unknown;
+}
+/**
+ * The accessor surface installed on `EntityRef`. The bare `entity.<comp>` getter shorthand
+ * resolves to `read()` and is Readonly; `write()` returns the mutable singleton whose
+ * setters call world.trackWrite.
+ */
+export interface EntityAccessors {
+    read(def: unknown): unknown;
+    write(def: unknown): unknown;
+}
+/**
+ * EntityRef is a POOLED SINGLETON: there is exactly ONE instance per world, and `world.entity(h)`
+ * re-points (rebinds) that one object at `h` and returns it — it does NOT allocate a fresh ref per
+ * call. The pooling contract is therefore:
+ *
+ * - The handle you bind is valid only until the NEXT `world.entity(...)` call, or until the bound
+ * entity is despawned / structurally moved. A reference captured in a local and used across
+ * either event aliases the wrong row.
+ * - Do NOT hold the ref across a `world.entity()` call. Re-resolve with `world.entity(h)` at the
+ * point of use, or extract the plain field values you need into locals first.
+ *
+ * To turn the classic silent-corruption footgun into a loud failure, the RANDOM-ACCESS read()/write()
+ * accessors verify on every call that the currently-bound handle is still alive and still occupies the
+ * location this ref cached at bind time; a stale/recycled/moved binding THROWS instead of reading or
+ * writing the wrong entity's row. (Query-iteration element accessors are a separate, hot path and are
+ * intentionally NOT guarded here.)
+ */
+export declare class EntityRef {
+    #private;
+    __handle: EntityHandle;
+    __archetypeId: number;
+    __row: number;
+    /** Set when bound via `{ lenient: true }` (e.g. an onRemove observer resolving a just-despawned entity). */
+    __lenient: boolean;
+    constructor(records: EntityRecord);
+    /** Public, frozen-surface accessor for the bound handle (the non-`__` form referenced by ). */
+    get handle(): EntityHandle;
+    /** Inject the world's accessor resolver (world wiring). */
+    __setResolver(resolver: AccessorResolver): void;
+    /** Inject the world's liveness probe so random-access read/write can fail loud on a stale binding. */
+    __setLiveness(isAlive: (handle: EntityHandle) => boolean): void;
+    /** Re-point this pooled ref at a (validated-alive) handle and resolve its location. */
+    __bind(handle: EntityHandle, lenient?: boolean): this;
+    /**
+     * Deeply-`Readonly` view of `def`'s fields for this entity.
+     * The `const C` parameter recovers the inferred `ReadOf<C>` so a random-access read is typed without
+     * caller casts; assignment through it is a TS2540 compile error. RANDOM-ACCESS path: guarded against a
+     * stale/recycled/moved pooled binding (see class jsdoc).
+     */
+    read<const C extends ComponentDef<Schema>>(def: C): ReadOf<C>;
+    /**
+     * Mutable, write-tracked `WriteView<S>` of `def`'s fields for this entity. The `const C` parameter
+     * recovers the inferred `WriteOf<C>` so a random-access write is typed without caller casts; every
+     * setter additionally drives the write log (the only tracked-mutation path). RANDOM-ACCESS path:
+     * guarded against a stale/recycled/moved pooled binding (see class jsdoc).
+     */
+    write<const C extends ComponentDef<Schema>>(def: C): WriteOf<C>;
+}
+//# sourceMappingURL=ref.d.ts.map

package/dist/entity/ref.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref.d.ts","sourceRoot":"","sources":["../../src/entity/ref.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAE1E;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAA;IAC1F,YAAY,CAAC,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAA;CAC5F;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAA;IAC3B,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAA;CAC7B;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,SAAS;;IAKpB,QAAQ,EAAE,YAAY,CAAY;IAClC,aAAa,EAAE,MAAM,CAAiB;IACtC,KAAK,SAAI;IACT,4GAA4G;IAC5G,SAAS,UAAQ;gBAEL,OAAO,EAAE,YAAY;IAIjC,+FAA+F;IAC/F,IAAI,MAAM,IAAI,YAAY,CAEzB;IAED,2DAA2D;IAC3D,aAAa,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAI/C,sGAAsG;IACtG,aAAa,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,YAAY,KAAK,OAAO,GAAG,IAAI;IAI/D,uFAAuF;IACvF,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,UAAQ,GAAG,IAAI;IAkCnD;;;;;OAKG;IACH,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,YAAY,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;IAM7D;;;;;OAKG;IACH,KAAK,CAAC,KAAK,CAAC,CAAC,SAAS,YAAY,CAAC,MAAM,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAKhE"}