@ecsia/core 0.1.0

package/dist/entity/ref.js

@@ -0,0 +1,104 @@
+// The pooled EntityRef identity carrier: ONE object per world, NOT per
+// entity, NOT a Proxy. This module owns its identity fields and location resolution; the
+// read/write accessor split is installed on the prototype here but its body
+// delegates to a pluggable AccessorResolver the world injects, so this module stays free of any
+// dependency on the component/storage layers.
+import { NO_ENTITY } from './codec.js';
+import { ARCHETYPE_NONE } from './record.js';
+/**
+ * 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 class EntityRef {
+    #records;
+    #resolver = null;
+    #isAlive = null;
+    __handle = NO_ENTITY;
+    __archetypeId = ARCHETYPE_NONE;
+    __row = 0;
+    /** Set when bound via `{ lenient: true }` (e.g. an onRemove observer resolving a just-despawned entity). */
+    __lenient = false;
+    constructor(records) {
+        this.#records = records;
+    }
+    /** Public, frozen-surface accessor for the bound handle (the non-`__` form referenced by ). */
+    get handle() {
+        return this.__handle;
+    }
+    /** Inject the world's accessor resolver (world wiring). */
+    __setResolver(resolver) {
+        this.#resolver = resolver;
+    }
+    /** Inject the world's liveness probe so random-access read/write can fail loud on a stale binding. */
+    __setLiveness(isAlive) {
+        this.#isAlive = isAlive;
+    }
+    /** Re-point this pooled ref at a (validated-alive) handle and resolve its location. */
+    __bind(handle, lenient = false) {
+        this.__handle = handle;
+        this.__lenient = lenient;
+        const loc = this.#records.resolveLocation(handle);
+        this.__archetypeId = loc.archetypeId;
+        this.__row = loc.row;
+        return this;
+    }
+    /**
+     * Assert the ref's cached binding still names the SAME live entity at the SAME location. Throws an
+     * actionable error if the bound entity was despawned/recycled (liveness) or structurally moved since
+     * bind (location drift) — both of which mean a held ref would otherwise read/write the wrong row.
+     */
+    #assertFresh(verb) {
+        // A lenient binding deliberately resolves a possibly-dead/shuffled slot (e.g. an onRemove observer
+        // reading the just-despawned entity's last values); the caller has opted out of the guard.
+        if (this.__lenient)
+            return;
+        const isAlive = this.#isAlive;
+        if (isAlive !== null && !isAlive(this.__handle)) {
+            throw new Error(`EntityRef.${verb}(): entity ${this.__handle} is no longer alive. The pooled EntityRef is rebound by ` +
+                `world.entity(...) and invalidated on despawn — do not hold it across calls; re-resolve via world.entity(h).`);
+        }
+        const loc = this.#records.resolveLocation(this.__handle);
+        if (loc.archetypeId !== this.__archetypeId || loc.row !== this.__row) {
+            throw new Error(`EntityRef.${verb}(): stale binding for entity ${this.__handle} — it moved since this ref was resolved ` +
+                `(another world.entity(...) call or a structural change rebound the pooled ref). Re-resolve via world.entity(h).`);
+        }
+    }
+    /**
+     * 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(def) {
+        if (this.#resolver === null)
+            throw new Error('EntityRef.read: no accessor resolver installed');
+        this.#assertFresh('read');
+        return this.#resolver.resolveRead(this.__handle, this.__archetypeId, this.__row, def);
+    }
+    /**
+     * 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(def) {
+        if (this.#resolver === null)
+            throw new Error('EntityRef.write: no accessor resolver installed');
+        this.#assertFresh('write');
+        return this.#resolver.resolveWrite(this.__handle, this.__archetypeId, this.__row, def);
+    }
+}
+//# sourceMappingURL=ref.js.map

package/dist/entity/ref.js.map

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

package/dist/entity/reservation.d.ts

@@ -0,0 +1,12 @@
+import type { EntityHandle } from './codec.js';
+import type { EntityIndex } from './index-allocator.js';
+export interface EntityReservation {
+    /** Pre-fully-formed handles, ready to use. */
+    readonly handles: readonly EntityHandle[];
+    readonly workerIndex: number;
+}
+/** Reserve `count` entity handles for `workerIndex` to consume mid-wave. Serial-phase only. */
+export declare function reserveEntityBlock(index: EntityIndex, workerIndex: number, count: number): EntityReservation;
+/** After the wave, reclaim any handles the worker did not consume (returns them to the pool). */
+export declare function returnReservedIds(index: EntityIndex, reservation: EntityReservation, consumedCount: number): void;
+//# sourceMappingURL=reservation.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reservation.d.ts","sourceRoot":"","sources":["../../src/entity/reservation.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAEvD,MAAM,WAAW,iBAAiB;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAA;IACzC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AAED,+FAA+F;AAC/F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,iBAAiB,CAS5G;AAED,iGAAiG;AACjG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAWjH"}

package/dist/entity/reservation.js

@@ -0,0 +1,28 @@
+// The worker-ID reservation handshake. v1 ships the LAYOUT plus the
+// single-thread path: the main thread reserves a block by calling the ordinary serial
+// `allocEntity`, so the entities are fully alive the instant they are reserved. The
+// Atomics.sub-on-reservedHead worker take is the v2 path exercised at.
+/** Reserve `count` entity handles for `workerIndex` to consume mid-wave. Serial-phase only. */
+export function reserveEntityBlock(index, workerIndex, count) {
+    if (!Number.isInteger(count) || count < 0) {
+        throw new RangeError(`reserveEntityBlock count must be a non-negative integer; got ${count}`);
+    }
+    const handles = [];
+    for (let i = 0; i < count; i++) {
+        handles.push(index.allocEntity());
+    }
+    return { handles, workerIndex };
+}
+/** After the wave, reclaim any handles the worker did not consume (returns them to the pool). */
+export function returnReservedIds(index, reservation, consumedCount) {
+    if (!Number.isInteger(consumedCount) || consumedCount < 0 || consumedCount > reservation.handles.length) {
+        throw new RangeError(`returnReservedIds consumedCount must be an integer in [0, ${reservation.handles.length}]; got ${consumedCount}`);
+    }
+    // Free the unconsumed tail in reverse so the free-list reissues them LIFO.
+    for (let i = reservation.handles.length - 1; i >= consumedCount; i--) {
+        const h = reservation.handles[i];
+        if (h !== undefined && index.isAlive(h))
+            index.freeEntity(h);
+    }
+}
+//# sourceMappingURL=reservation.js.map

package/dist/entity/reservation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reservation.js","sourceRoot":"","sources":["../../src/entity/reservation.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,sFAAsF;AACtF,oFAAoF;AACpF,uEAAuE;AAWvE,+FAA+F;AAC/F,MAAM,UAAU,kBAAkB,CAAC,KAAkB,EAAE,WAAmB,EAAE,KAAa;IACvF,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;QAC1C,MAAM,IAAI,UAAU,CAAC,gEAAgE,KAAK,EAAE,CAAC,CAAA;IAC/F,CAAC;IACD,MAAM,OAAO,GAAmB,EAAE,CAAA;IAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC;QAC/B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAA;IACnC,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,CAAA;AACjC,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,iBAAiB,CAAC,KAAkB,EAAE,WAA8B,EAAE,aAAqB;IACzG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,aAAa,CAAC,IAAI,aAAa,GAAG,CAAC,IAAI,aAAa,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QACxG,MAAM,IAAI,UAAU,CAClB,6DAA6D,WAAW,CAAC,OAAO,CAAC,MAAM,UAAU,aAAa,EAAE,CACjH,CAAA;IACH,CAAC;IACD,2EAA2E;IAC3E,KAAK,IAAI,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,aAAa,EAAE,CAAC,EAAE,EAAE,CAAC;QACrE,MAAM,CAAC,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,CAAA;QAChC,IAAI,CAAC,KAAK,SAAS,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;YAAE,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAA;IAC9D,CAAC;AACH,CAAC"}

package/dist/entity/store.d.ts

@@ -0,0 +1,60 @@
+import type { EntityGeneration, EntityHandle, EntityIndex as EntityIndexBrand, HandleLayout } from './codec.js';
+import { EntityIndex } from './index-allocator.js';
+import { ARCHETYPE_NONE, EntityRecord } from './record.js';
+import { EntityRef } from './ref.js';
+import type { AccessorResolver } from './ref.js';
+export interface EntityStoreConfig {
+    readonly layout: HandleLayout;
+    readonly maxEntities: number;
+    readonly shared: boolean;
+}
+export interface HandleStats {
+    readonly aliveCount: number;
+    readonly minted: number;
+    readonly capacity: number;
+    readonly wrapTimeFormula: string;
+}
+export declare class EntityStore {
+    #private;
+    readonly layout: HandleLayout;
+    constructor(config: EntityStoreConfig);
+    setLifecycle(hooks: {
+        onSpawn(handle: EntityHandle): void;
+        onDespawn(handle: EntityHandle): void;
+    }): void;
+    spawn(): EntityHandle;
+    despawn(handle: EntityHandle): void;
+    isAlive(handle: EntityHandle): boolean;
+    entity(handle: EntityHandle, opts?: {
+        lenient?: boolean;
+    }): EntityRef;
+    encodeHandle(index: number, generation: number): EntityHandle;
+    decodeHandle(handle: EntityHandle): {
+        index: EntityIndexBrand;
+        generation: EntityGeneration;
+    };
+    /** Install the read/write accessor resolver onto the pooled ref (world wiring). */
+    setAccessorResolver(resolver: AccessorResolver): void;
+    get index(): EntityIndex;
+    get records(): EntityRecord;
+    /**
+     * The two entity-record region backings (archetypeId, archetypeRow), for the worker bootstrap
+     * manifest. A worker resolves an entity's (archetypeId, row) from these shared
+     * regions — reading ARCHETYPE TABLES ONLY, never the bitmask. Backings are SAB when
+     * threaded + isolation present; otherwise plain AB (the worker path then has nothing to share).
+     */
+    sharedRecordRegions(): {
+        archetypeId: ArrayBufferLike;
+        archetypeRow: ArrayBufferLike;
+    };
+    /** The full (generational) handle occupying `index` — the query engine's index→handle resolver. */
+    handleOfIndex(index: number): EntityHandle;
+    /** index → its (archetypeId, row) location — the query engine's resolveLocation seam. */
+    locationOfIndex(index: number): {
+        archetypeId: number;
+        row: number;
+    };
+    handleStats(): HandleStats;
+}
+export { ARCHETYPE_NONE };
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/entity/store.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,WAAW,IAAI,gBAAgB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC/G,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAElD,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAE1D,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA;AAOhD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;CACjC;AAED,qBAAa,WAAW;;IACtB,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAA;gBAoBjB,MAAM,EAAE,iBAAiB;IAqErC,YAAY,CAAC,KAAK,EAAE;QAAE,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAC;QAAC,SAAS,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAAA;KAAE,GAAG,IAAI;IAIzG,KAAK,IAAI,YAAY;IAYrB,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI;IASnC,OAAO,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO;IAItC,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS;IASrE,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,YAAY;IAU7D,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG;QAAE,KAAK,EAAE,gBAAgB,CAAC;QAAC,UAAU,EAAE,gBAAgB,CAAA;KAAE;IAO7F,mFAAmF;IACnF,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI;IAIrD,IAAI,KAAK,IAAI,WAAW,CAEvB;IAED,IAAI,OAAO,IAAI,YAAY,CAE1B;IAED;;;;;OAKG;IACH,mBAAmB,IAAI;QAAE,WAAW,EAAE,eAAe,CAAC;QAAC,YAAY,EAAE,eAAe,CAAA;KAAE;IAOtF,mGAAmG;IACnG,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY;IAI1C,yFAAyF;IACzF,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;IAIpE,WAAW,IAAI,WAAW;CAmB3B;AAED,OAAO,EAAE,cAAc,EAAE,CAAA"}

package/dist/entity/store.js

@@ -0,0 +1,193 @@
+// Construction wiring for the entity layer: allocate the five
+// identity/record flat arrays through memory.allocU32, sized by maxEntities, and assemble the
+// EntityIndex + EntityRecord + pooled EntityRef. Lives between the world facade and the
+// per-module primitives so world.ts stays a thin delegator.
+import { allocU32 } from '../memory/index.js';
+import { handleIndex, makeHandle } from './codec.js';
+import { EntityIndex } from './index-allocator.js';
+import { ARCHETYPE_NONE, EntityRecord } from './record.js';
+import { EntityRef } from './ref.js';
+// EMPTY_ARCHETYPE_ID is normatively; the empty-signature archetype is
+// dense id 0 (a real archetype, distinct from the ARCHETYPE_NONE sentinel). Storage lands at;
+// until then a freshly spawned entity records archetype 0 at row 0.
+const EMPTY_ARCHETYPE_ID = 0;
+export class EntityStore {
+    layout;
+    #index;
+    #records;
+    #ref;
+    #maxEntities;
+    /** Hard mint ceiling: the index space, minus the reserved NO_ENTITY slot when threaded. */
+    #ceiling;
+    /** Current addressable length; doubles on growth up to `#ceiling`. */
+    #addressable;
+    #wrapWarned = false;
+    // Held only so growth re-reads/re-publishes the layout structs from the same regions.
+    #regions;
+    constructor(config) {
+        this.layout = config.layout;
+        this.#maxEntities = config.maxEntities;
+        this.#addressable = config.maxEntities;
+        // The index space is [0, maxIndex]; when threaded, maxIndex is reserved for the NO_ENTITY
+        // sentinel so a minted+wrapped handle can never alias 0xffffffff.
+        this.#ceiling = config.shared ? config.layout.maxIndex : config.layout.maxIndex + 1;
+        const opts = { shared: config.shared, maxLength: config.layout.capacity };
+        this.#regions = {
+            sparse: allocU32(config.maxEntities, opts),
+            dense: allocU32(config.maxEntities, opts),
+            generation: allocU32(config.maxEntities, opts),
+            recordArchetypeId: allocU32(config.maxEntities, opts),
+            recordArchetypeRow: allocU32(config.maxEntities, opts),
+        };
+        const bounds = { addressable: this.#addressable, ceiling: this.#ceiling };
+        this.#index = new EntityIndex(config.layout, this.#indexArrays(), bounds, (need) => this.#grow(need));
+        this.#records = new EntityRecord(config.layout, this.#recordArrays());
+        this.#ref = new EntityRef(this.#records);
+        this.#ref.__setLiveness((handle) => this.#index.isAlive(handle));
+    }
+    /**
+     * Grow every identity/record region to at least `need` elements (doubling), then
+     * re-publish the widened views to the index/record/ref structs and return the new addressable
+     * length. Returns the unchanged length when growth is impossible (capped at `#ceiling`), which
+     * makes the allocator throw CapacityExceeded. Serial-phase only.
+     */
+    #grow(need) {
+        if (need <= this.#addressable)
+            return this.#addressable;
+        const cap = Math.min(this.#ceiling, this.layout.capacity);
+        if (this.#addressable >= cap)
+            return this.#addressable;
+        let next = this.#addressable;
+        while (next < need)
+            next = Math.min(cap, next * 2);
+        if (next <= this.#addressable)
+            return this.#addressable;
+        for (const region of Object.values(this.#regions))
+            region.grow(next);
+        this.#addressable = next;
+        // Length-tracking views over resizable buffers widen in place, but re-publishing keeps the
+        // non-resizable fallback path correct too.
+        this.#index.rebind(this.#indexArrays(), next);
+        this.#records.rebind(this.#recordArrays());
+        return next;
+    }
+    #indexArrays() {
+        return {
+            sparse: this.#regions.sparse.view,
+            dense: this.#regions.dense.view,
+            generation: this.#regions.generation.view,
+        };
+    }
+    #recordArrays() {
+        return {
+            recordArchetypeId: this.#regions.recordArchetypeId.view,
+            recordArchetypeRow: this.#regions.recordArchetypeRow.view,
+        };
+    }
+    /**
+     * Storage hook installed at: places a freshly-minted handle into its initial archetype (via
+     * allocRow) and commits the record; on despawn it performs the + bitmask clear
+     * BEFORE identity invalidation. Until installed, spawn falls back to the empty-archetype row 0.
+     */
+    #lifecycle = null;
+    setLifecycle(hooks) {
+        this.#lifecycle = hooks;
+    }
+    spawn() {
+        const handle = this.#index.allocEntity();
+        if (this.#lifecycle !== null) {
+            this.#lifecycle.onSpawn(handle);
+        }
+        else {
+            const index = handleIndex(handle, this.layout);
+            this.#records.commitRecord(index, EMPTY_ARCHETYPE_ID, 0);
+        }
+        this.#warnOnWrap();
+        return handle;
+    }
+    despawn(handle) {
+        if (!this.#index.isAlive(handle))
+            return;
+        // Storage runs removeRow + bitmask clear here; identity invalidation (freeEntity) runs
+        // LAST so the above could still resolve the dying entity's location.
+        this.#lifecycle?.onDespawn(handle);
+        this.#index.freeEntity(handle);
+        this.#warnOnWrap();
+    }
+    isAlive(handle) {
+        return this.#index.isAlive(handle);
+    }
+    entity(handle, opts) {
+        if (!this.#index.isAlive(handle)) {
+            // Dead handles throw unless the caller opts into lenient resolution (it then binds
+            // the stale handle anyway; the location words are whatever the slot last held).
+            if (opts?.lenient !== true)
+                throw new Error(`entity(${handle}): handle is not alive`);
+        }
+        return this.#ref.__bind(handle, opts?.lenient === true);
+    }
+    encodeHandle(index, generation) {
+        if (index < 0 || index > this.layout.maxIndex) {
+            throw new RangeError(`index out of range [0, ${this.layout.maxIndex}]; got ${index}`);
+        }
+        if (generation < 0 || generation > this.layout.maxGeneration) {
+            throw new RangeError(`generation out of range [0, ${this.layout.maxGeneration}]; got ${generation}`);
+        }
+        return makeHandle(index, generation, this.layout);
+    }
+    decodeHandle(handle) {
+        return {
+            index: ((handle & this.layout.indexMask) >>> 0),
+            generation: ((handle >>> this.layout.generationShift) & this.layout.generationMask),
+        };
+    }
+    /** Install the read/write accessor resolver onto the pooled ref (world wiring). */
+    setAccessorResolver(resolver) {
+        this.#ref.__setResolver(resolver);
+    }
+    get index() {
+        return this.#index;
+    }
+    get records() {
+        return this.#records;
+    }
+    /**
+     * The two entity-record region backings (archetypeId, archetypeRow), for the worker bootstrap
+     * manifest. A worker resolves an entity's (archetypeId, row) from these shared
+     * regions — reading ARCHETYPE TABLES ONLY, never the bitmask. Backings are SAB when
+     * threaded + isolation present; otherwise plain AB (the worker path then has nothing to share).
+     */
+    sharedRecordRegions() {
+        return {
+            archetypeId: this.#regions.recordArchetypeId.backing,
+            archetypeRow: this.#regions.recordArchetypeRow.backing,
+        };
+    }
+    /** The full (generational) handle occupying `index` — the query engine's index→handle resolver. */
+    handleOfIndex(index) {
+        return this.#index.handleOfIndex(index);
+    }
+    /** index → its (archetypeId, row) location — the query engine's resolveLocation seam. */
+    locationOfIndex(index) {
+        return { archetypeId: this.#records.archetypeIdOf(index), row: this.#records.rowOf(index) };
+    }
+    handleStats() {
+        return {
+            aliveCount: this.#index.aliveCount,
+            minted: this.#index.denseLen,
+            capacity: this.#maxEntities,
+            wrapTimeFormula: `2^${this.layout.generationBits} / recycleRate`,
+        };
+    }
+    #warnOnWrap() {
+        if (this.#wrapWarned || !this.#index.wrapped)
+            return;
+        this.#wrapWarned = true;
+        // Dev-mode-only signal so users can raise generationBits; never a production throw.
+        if (typeof console !== 'undefined') {
+            console.warn(`[ecsia] entity generation wrapped (generationBits=${this.layout.generationBits}); stale-handle aliasing window reached — consider raising generationBits`);
+        }
+    }
+}
+export { ARCHETYPE_NONE };
+//# sourceMappingURL=store.js.map

package/dist/entity/store.js.map

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

package/dist/env.d.ts

@@ -0,0 +1,2 @@
+export declare const IS_DEV: boolean;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,MAAM,EAAE,OAMjB,CAAA"}

package/dist/env.js

@@ -0,0 +1,12 @@
+// Portable dev-mode detection. Evaluated ONCE: browsers have no `process` (typeof guard),
+// permission-less Deno THROWS on env access (try/catch), Node reads NODE_ENV. Defaults to
+// dev=true where unknowable — extra guards beat silent production behavior in a sandbox.
+export const IS_DEV = (() => {
+    try {
+        return typeof process === 'undefined' || process.env?.['NODE_ENV'] !== 'production';
+    }
+    catch {
+        return true;
+    }
+})();
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,0FAA0F;AAC1F,yFAAyF;AACzF,MAAM,CAAC,MAAM,MAAM,GAAY,CAAC,GAAG,EAAE;IACnC,IAAI,CAAC;QACH,OAAO,OAAO,OAAO,KAAK,WAAW,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,YAAY,CAAA;IACrF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC,CAAC,EAAE,CAAA"}

package/dist/ids.d.ts

@@ -0,0 +1,9 @@
+/** A dense component type id. Branded so raw numbers can't be passed where a ComponentId is required. */
+export type ComponentId = number & {
+    readonly __ecsiaComponentId: unique symbol;
+};
+/** The reserved "no component" sentinel. Also the shape-log CREATE/DESTROY marker. */
+export declare const NO_COMPONENT: ComponentId;
+/** First id handed out to user components; everything below is reserved. */
+export declare const FIRST_USER_COMPONENT_ID: ComponentId;
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAIA,yGAAyG;AACzG,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,kBAAkB,EAAE,OAAO,MAAM,CAAA;CAAE,CAAA;AAEjF,sFAAsF;AACtF,eAAO,MAAM,YAAY,EAAQ,WAAW,CAAA;AAE5C,4EAA4E;AAC5E,eAAO,MAAM,uBAAuB,EAAQ,WAAW,CAAA"}

package/dist/ids.js

@@ -0,0 +1,8 @@
+// Reserved ComponentId space (C3).
+// ComponentId 0 is NEVER a user component: it is the NO_COMPONENT sentinel, doubling as the
+// CREATE/DESTROY shape-log "no component" marker and the changeVersion sentinel.
+/** The reserved "no component" sentinel. Also the shape-log CREATE/DESTROY marker. */
+export const NO_COMPONENT = 0;
+/** First id handed out to user components; everything below is reserved. */
+export const FIRST_USER_COMPONENT_ID = 1;
+//# sourceMappingURL=ids.js.map

package/dist/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../src/ids.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,4FAA4F;AAC5F,iFAAiF;AAKjF,sFAAsF;AACtF,MAAM,CAAC,MAAM,YAAY,GAAG,CAAgB,CAAA;AAE5C,4EAA4E;AAC5E,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAgB,CAAA"}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+export type { ComponentId } from './ids.js';
+export { ConfigError, resolveOptions } from './config.js';
+export type { WorldOptions, ResolvedWorldOptions, ResolvedReactivityOptions, ReactivityOptions, SchedulerOptions, ObserverCadence, ChangeTracking, WorkerOption, } from './config.js';
+export { createWorld } from './world.js';
+export type { World, WorldPhase } from './world.js';
+export { NO_ENTITY, NULL_ENTITY, isNoEntity, EntityRef, handleIndex } from './entity/index.js';
+export type { EntityHandle, EntityIndex, HandleLayout } from './entity/index.js';
+export { defineComponent, defineTag, } from './component/index.js';
+export { createStableIndex } from './util/stable-index.js';
+export type { StableIndex } from './util/stable-index.js';
+export { ShapeKind, onAdd, onRemove, onChange, } from './reactivity/index.js';
+export type { ObserverHandle, ObserverTerm, ObserverContext, } from './reactivity/index.js';
+export type { SharedHandleManifest, ColumnGrowthNotice, ColumnGrowthLog } from './memory/index.js';
+export { vec, vec2, vec3, vec4, staticString, object, field, MAX_QUERY_ARITY, read, write, has, without, optional, } from '@ecsia/schema';
+export type { ScalarToken, VecToken, StaticStringToken, ObjectToken, RichToken, FieldToken, FieldSpec, FieldValue, Schema, ComponentDef, ComponentOptions, ReadView, WriteView, ReadOf, WriteOf, SchemaOf, QueryTerm, QueryElement, Query, QueryChunk, LooseQuery, Has, HasWrite, RelationDef, RelationOptions, PairDef, WildcardToken, Tick, } from '@ecsia/schema';
+export { NO_COMPONENT, FIRST_USER_COMPONENT_ID } from './ids.js';
+export type { WorldApplySurface, RelationsHost } from './world.js';
+export type { SerializationSurface, SerializeArchetype, SerializeComponentColumns, SerializeComponentMeta, SerializeRichField, SerializePair, SerializeRelationProvider, SerializeStructuralRecord, } from './serialize-surface.js';
+export type { InspectSurface, InspectArchetype, InspectQuery } from './inspect-surface.js';
+export { makeHandleLayout, ARCHETYPE_NONE, reserveEntityBlock, returnReservedIds } from './entity/index.js';
+export type { EntityReservation } from './entity/index.js';
+export { encodeEid, decodeEid, elementCtor, elementBytes, makeColumnLayout, } from './memory/index.js';
+export type { ColumnKey, RegionKey, RuntimeCapabilities, Column, ElementKind, TypedArray, ColumnLayout, } from './memory/index.js';
+export { buildColumnSet, bindAccessorRow } from './component/index.js';
+export type { ColumnSet } from './component/index.js';
+export type { StorageStrategy } from '@ecsia/schema';
+export type { ResolvedPair } from './query/index.js';
+export { IS_DEV } from './env.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,33 @@
+// @ecsia/core — the single-threaded kernel. PUBLIC surface.
+//
+// This barrel is split into two sections:
+// • PUBLIC — the documented user/umbrella surface: createWorld + config, component/tag definition,
+// entity sentinels, reactivity observer builders, and the schema token/inference re-exports the
+// umbrella (ecsia) curates.
+// • INTERNAL (cross-package) — kernel seams that sibling packages (@ecsia/{relations,serialization})
+// import via '@ecsia/core'. They are NOT user API, but removing them would break those siblings,
+// so they stay exported here under a clearly-marked banner rather than on a hidden subpath
+// (package.json#exports maps only `.`).
+//
+// The rest of the kernel (store/bitmask/registry/query-engine/memory-backing classes + low-level
+// schema helpers) is implementation detail and lives in ./internal.ts — NOT re-exported here. This
+// package's own tests reach those through a relative `../src/internal.js` import.
+export { ConfigError, resolveOptions } from './config.js';
+export { createWorld } from './world.js';
+export { NO_ENTITY, NULL_ENTITY, isNoEntity, EntityRef, handleIndex } from './entity/index.js';
+export { defineComponent, defineTag, } from './component/index.js';
+export { createStableIndex } from './util/stable-index.js';
+export { ShapeKind, onAdd, onRemove, onChange, } from './reactivity/index.js';
+// Schema surface re-exported so users import tokens/inference from @ecsia/core (the umbrella).
+export { vec, vec2, vec3, vec4, staticString, object, field, MAX_QUERY_ARITY, read, write, has, without, optional, } from '@ecsia/schema';
+// ===========================================================================
+// INTERNAL (cross-package) — imported by @ecsia/{relations,serialization} via '@ecsia/core'.
+// NOT user API; kept here only because those siblings need them and exports map only `.`.
+// ===========================================================================
+export { NO_COMPONENT, FIRST_USER_COMPONENT_ID } from './ids.js';
+export { makeHandleLayout, ARCHETYPE_NONE, reserveEntityBlock, returnReservedIds } from './entity/index.js';
+export { encodeEid, decodeEid, elementCtor, elementBytes, makeColumnLayout, } from './memory/index.js';
+export { buildColumnSet, bindAccessorRow } from './component/index.js';
+// INTERNAL (cross-package): portable dev-mode flag
+export { IS_DEV } from './env.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,EAAE;AACF,0CAA0C;AAC1C,mGAAmG;AACnG,gGAAgG;AAChG,4BAA4B;AAC5B,qGAAqG;AACrG,iGAAiG;AACjG,2FAA2F;AAC3F,wCAAwC;AACxC,EAAE;AACF,iGAAiG;AACjG,mGAAmG;AACnG,kFAAkF;AAOlF,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAWzD,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAGxC,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAG9F,OAAO,EACL,eAAe,EACf,SAAS,GACV,MAAM,sBAAsB,CAAA;AAE7B,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAG1D,OAAO,EACL,SAAS,EACT,KAAK,EACL,QAAQ,EACR,QAAQ,GACT,MAAM,uBAAuB,CAAA;AAS9B,+FAA+F;AAC/F,OAAO,EACL,GAAG,EACH,IAAI,EACJ,IAAI,EACJ,IAAI,EACJ,YAAY,EACZ,MAAM,EACN,KAAK,EACL,eAAe,EACf,IAAI,EACJ,KAAK,EACL,GAAG,EACH,OAAO,EACP,QAAQ,GACT,MAAM,eAAe,CAAA;AAiCtB,8EAA8E;AAC9E,6FAA6F;AAC7F,0FAA0F;AAC1F,8EAA8E;AAE9E,OAAO,EAAE,YAAY,EAAE,uBAAuB,EAAE,MAAM,UAAU,CAAA;AAgBhE,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AAG3G,OAAO,EACL,SAAS,EACT,SAAS,EACT,WAAW,EACX,YAAY,EACZ,gBAAgB,GACjB,MAAM,mBAAmB,CAAA;AAW1B,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAMtE,mDAAmD;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA"}

package/dist/inspect-surface.d.ts

@@ -0,0 +1,27 @@
+import type { ComponentId } from '@ecsia/schema';
+/** One archetype's identity census — INCLUDING cold + empty archetypes (the `__serialize` gap). */
+export interface InspectArchetype {
+    readonly id: number;
+    /** The sorted canonical signature (ComponentIds, including tag/pair/presence ids). */
+    readonly signature: readonly ComponentId[];
+    readonly count: number;
+    /** false = hot (column-backed tables); true = cold (lazily-materialized, archetype-storage ). */
+    readonly cold: boolean;
+}
+/** One live (compiled, cached) query's introspectable shape — the QueryEngine enumeration gap. */
+export interface InspectQuery {
+    /** The raw QueryTerm[] the query was compiled from (read/write/has/without/optional terms). */
+    readonly terms: readonly unknown[];
+    /** Number of archetypes the query currently matches. */
+    readonly matchedArchetypes: number;
+    /** Current live match count (entities satisfying the query). */
+    readonly size: number;
+}
+/** The read-only datum surface @ecsia/devtools drives. All members are serial / main-thread, pure reads. */
+export interface InspectSurface {
+    /** Every archetype (hot AND cold, including empty), in id-ascending order. */
+    archetypes(): readonly InspectArchetype[];
+    /** Every live (cached) query, in creation order. Empty before the first `world.query(...)`. */
+    queries(): readonly InspectQuery[];
+}
+//# sourceMappingURL=inspect-surface.d.ts.map

package/dist/inspect-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect-surface.d.ts","sourceRoot":"","sources":["../src/inspect-surface.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEhD,mGAAmG;AACnG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,sFAAsF;IACtF,QAAQ,CAAC,SAAS,EAAE,SAAS,WAAW,EAAE,CAAA;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,iGAAiG;IACjG,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CACvB;AAED,kGAAkG;AAClG,MAAM,WAAW,YAAY;IAC3B,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,EAAE,SAAS,OAAO,EAAE,CAAA;IAClC,wDAAwD;IACxD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,4GAA4G;AAC5G,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,UAAU,IAAI,SAAS,gBAAgB,EAAE,CAAA;IACzC,+FAA+F;IAC/F,OAAO,IAAI,SAAS,YAAY,EAAE,CAAA;CACnC"}

package/dist/inspect-surface.js

@@ -0,0 +1,14 @@
+// The read-only introspection seam @ecsia/devtools reads through, exposed on World as `__inspect`.
+// Keeps the dependency direction acyclic: devtools imports @ecsia/core for this surface; core NEVER
+// imports devtools. Everything here is serial / main-thread, read-only, and side-effect-free — a pure
+// view over already-live state.
+//
+// WHY a NEW seam (not `__serialize`): the existing SerializationSurface deliberately exposes ONLY the
+// data a snapshot needs — its `archetypes()` skips COLD and EMPTY archetypes (world.ts ), and there
+// is no live-query enumeration anywhere on the public/`__` surface (the QueryEngine's `liveQueries`
+// getter is class-private to core). Those two data are genuinely unreachable for an inspector that wants
+// the FULL archetype census (with the hot/cold flag) and the active query set. Everything else the
+// inspector reports (component metadata, rich fields, relations, alive/capacity counts) is already
+// reachable via `__serialize` + `world.options`, so this seam stays minimal: just the two gaps.
+export {};
+//# sourceMappingURL=inspect-surface.js.map

package/dist/inspect-surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspect-surface.js","sourceRoot":"","sources":["../src/inspect-surface.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,oGAAoG;AACpG,sGAAsG;AACtG,gCAAgC;AAChC,EAAE;AACF,sGAAsG;AACtG,oGAAoG;AACpG,oGAAoG;AACpG,yGAAyG;AACzG,mGAAmG;AACnG,mGAAmG;AACnG,gGAAgG"}