@ecsia/core 0.1.0

package/dist/storage/signature.js

@@ -0,0 +1,115 @@
+// Canonical archetype signatures.
+// A Signature is the sorted, de-duplicated Uint32Array of ComponentIds defining an archetype's
+// exact component set. Sorting makes structurally-equal sets identical regardless of add order, so
+// equality is a linear word compare and the lookup map keys on an FNV-1a hash of the sorted ids.
+/** O(n) equality of two sorted signatures. */
+export function sigEquals(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i++)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+/** FNV-1a over the sorted ids → 32-bit hash for the archetype lookup map. */
+export function sigHash(a) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < a.length; i++) {
+        h ^= a[i];
+        h = Math.imul(h, 0x01000193);
+    }
+    return h >>> 0;
+}
+/** Sort + de-dup an arbitrary id multiset into the canonical form ( holds). */
+export function canonicalize(ids) {
+    const arr = Uint32Array.from(new Set(ids));
+    arr.sort();
+    return arr;
+}
+/** The neighbor signature reached by adding `c` (sorted insert). Idempotent if `c` already present. */
+export function sigWithAdded(sig, c) {
+    const v = c;
+    // Binary-search the insertion point; if found, the signature is unchanged (idempotent add).
+    let lo = 0;
+    let hi = sig.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        const cur = sig[mid];
+        if (cur === v)
+            return sig;
+        if (cur < v)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    const out = new Uint32Array(sig.length + 1);
+    out.set(sig.subarray(0, lo), 0);
+    out[lo] = v;
+    out.set(sig.subarray(lo), lo + 1);
+    return out;
+}
+/** The neighbor signature reached by removing `c`. Returns `sig` unchanged if `c` is absent. */
+export function sigWithRemoved(sig, c) {
+    const v = c;
+    let lo = 0;
+    let hi = sig.length - 1;
+    let found = -1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >>> 1;
+        const cur = sig[mid];
+        if (cur === v) {
+            found = mid;
+            break;
+        }
+        if (cur < v)
+            lo = mid + 1;
+        else
+            hi = mid - 1;
+    }
+    if (found < 0)
+        return sig;
+    const out = new Uint32Array(sig.length - 1);
+    out.set(sig.subarray(0, found), 0);
+    out.set(sig.subarray(found + 1), found);
+    return out;
+}
+/** Packed membership words for fast bitwise-AND query matching. */
+export function buildSigWords(sig, stride) {
+    const w = new Uint32Array(stride);
+    for (let i = 0; i < sig.length; i++) {
+        const c = sig[i];
+        w[c >>> 5] = (w[c >>> 5] | (1 << (c & 31))) >>> 0;
+    }
+    return w;
+}
+/** Exact membership test against the sorted signature array, O(log |sig|). */
+export function sigHas(sig, c) {
+    const v = c;
+    let lo = 0;
+    let hi = sig.length - 1;
+    while (lo <= hi) {
+        const mid = (lo + hi) >>> 1;
+        const cur = sig[mid];
+        if (cur === v)
+            return true;
+        if (cur < v)
+            lo = mid + 1;
+        else
+            hi = mid - 1;
+    }
+    return false;
+}
+/** Signature-AND helper the query module calls; exposed for testing. */
+export function signatureMatches(sigWords, withW, notW, orW) {
+    for (const t of notW)
+        if ((sigWords[t.wordIndex] & t.mask) !== 0)
+            return false;
+    for (const t of withW)
+        if ((sigWords[t.wordIndex] & t.mask) !== t.mask)
+            return false;
+    for (const c of orW)
+        if ((sigWords[c.wordIndex] & c.mask) === 0)
+            return false;
+    return true;
+}
+//# sourceMappingURL=signature.js.map

package/dist/storage/signature.js.map

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

package/dist/storage/storage.d.ts

@@ -0,0 +1,72 @@
+import type { ComponentDef, ComponentId, EntityHandle, Schema } from '@ecsia/schema';
+import type { AccessorWorld, ColumnSet } from '../component/index.js';
+import type { Bitmask } from '../bitmask/index.js';
+import { ArchetypeStore } from './store.js';
+import type { RecordSurface, StorageDeps } from './store.js';
+import type { Archetype } from './archetype.js';
+export interface DefRegistry {
+    idOf(def: ComponentDef<Schema>): ComponentId | undefined;
+    defOf(id: ComponentId): ComponentDef<Schema> | undefined;
+}
+export interface StorageConfig {
+    readonly buffers: StorageDeps['buffers'];
+    readonly accessorWorld: AccessorWorld;
+    readonly bitmask: Bitmask;
+    readonly record: RecordSurface;
+    readonly registry: DefRegistry;
+    readonly maxHotArchetypes: number;
+    readonly stride: number;
+    readonly maxEntities: number;
+    enqueueRemoveLog(index: number, c: ComponentId): void;
+    /**
+     *: does any observer subscribe to `c`'s removal? When true for any held component, despawn
+     * defers the dying row's column reclaim (swap-pop) so an onRemove handler can read the last value.
+     * Optional so a query-less harness can construct storage without reactivity.
+     */
+    hasRemoveObserver?(c: ComponentId): boolean;
+    /** Shape-log hook: structural entry at the commit point. Wired by the world to reactivity. */
+    trackShape?(index: number, c: ComponentId, kind: number): void;
+    /** Single-entity incremental query maintenance; wired by the world to the engine. */
+    maintainEntity(index: number, c: ComponentId): void;
+    /**
+     * Spawn-time maintenance: a component-less entity lands in EMPTY and never drives
+     * `maintainEntity`, so constraint-less queries are told about it here (keeps the incremental path
+     * symmetric with the despawn path). No-op for component-constrained queries.
+     */
+    onEntitySpawned(index: number): void;
+    /** Despawn eviction: remove the index from EVERY live query unconditionally. */
+    dropEntity(index: number): void;
+    tick(): number;
+    handleIndex(handle: EntityHandle): number;
+}
+export declare class Storage {
+    #private;
+    readonly archetypes: ArchetypeStore;
+    constructor(cfg: StorageConfig);
+    /** Subscribe to archetypeCreated; forwarded from the ArchetypeStore. */
+    onArchetypeCreated(fn: (arch: Archetype) => void): void;
+    /** Entity indices currently resident in cold archetype `archetypeId` (O(rows in that archetype)). */
+    coldResidentsOf(archetypeId: number): Iterable<number>;
+    /** The per-TYPE cold ColumnSet for `componentId` (cold blocks are keyed by component, not archetype). */
+    coldColumnSet(componentId: ComponentId): ColumnSet | undefined;
+    /** The cold-block row holding `componentId`'s fields for entity `index`, or -1 if absent. */
+    coldRowOf(index: number, componentId: ComponentId): number;
+    onSpawn(handle: EntityHandle): void;
+    onDespawn(handle: EntityHandle): void;
+    add(handle: EntityHandle, def: ComponentDef<Schema>): void;
+    remove(handle: EntityHandle, def: ComponentDef<Schema>): void;
+    spawnWith(handle: EntityHandle, defs: readonly ComponentDef<Schema>[]): void;
+    /** Atomic multi-id add — ONE migration to a single target signature (relations path). */
+    addMany(handle: EntityHandle, defs: readonly ComponentDef<Schema>[]): void;
+    /** Atomic multi-id remove — symmetric to addMany. */
+    removeMany(handle: EntityHandle, defs: readonly ComponentDef<Schema>[]): void;
+    warm(defs: readonly ComponentDef<Schema>[]): void;
+    /**
+     * (has() never reads the
+     * bitmask for a dead handle); this asserts world.phase === 'serial' inside bitmaskHas.
+     */
+    has(handle: EntityHandle, def: ComponentDef<Schema>): boolean;
+    resolveRead(handle: EntityHandle, archetypeId: number, row: number, def: unknown): unknown;
+    resolveWrite(handle: EntityHandle, archetypeId: number, row: number, def: unknown): unknown;
+}
+//# sourceMappingURL=storage.d.ts.map

package/dist/storage/storage.d.ts.map

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

package/dist/storage/storage.js

@@ -0,0 +1,192 @@
+// The storage facade: ties the entity record + the per-entity bitmask + the
+// ArchetypeStore into the world's structural-verb surface and the accessor-resolution path. It is
+// the AccessorResolver the pooled EntityRef calls (resolveRead/resolveWrite) — resolving the
+// (archetype, component) ColumnSet from the entity's REAL archetype now, replacing the seam that
+// keyed column sets purely by (archetypeId, componentId) on the registry.
+//
+// All structural verbs run serial / main-thread. In the single-thread executor
+// world.phase stays 'serial' permanently, so every op takes the synchronous direct-apply path
+import { bindAccessorRow } from '../component/index.js';
+import { ArchetypeStore, EMPTY_ARCHETYPE_ID } from './store.js';
+import { coldRowOf } from './cold-store.js';
+import { canonicalize } from './signature.js';
+// ShapeKind ordinals for the lifecycle commit points.
+const SHAPE_CREATE = 0;
+const SHAPE_DESTROY = 1;
+const NO_COMPONENT_SHAPE = 0;
+export class Storage {
+    archetypes;
+    #cfg;
+    constructor(cfg) {
+        this.#cfg = cfg;
+        this.archetypes = new ArchetypeStore({
+            buffers: cfg.buffers,
+            accessorWorld: cfg.accessorWorld,
+            bitmask: cfg.bitmask,
+            record: cfg.record,
+            maxHotArchetypes: cfg.maxHotArchetypes,
+            stride: cfg.stride,
+            maxEntities: cfg.maxEntities,
+            enqueueRemoveLog: cfg.enqueueRemoveLog,
+            ...(cfg.trackShape !== undefined ? { trackShape: cfg.trackShape } : {}),
+            maintainEntity: cfg.maintainEntity,
+            tick: cfg.tick,
+            defOf: (c) => cfg.registry.defOf(c),
+            handleIndex: (h) => cfg.handleIndex(h),
+        });
+    }
+    /** Subscribe to archetypeCreated; forwarded from the ArchetypeStore. */
+    onArchetypeCreated(fn) {
+        this.archetypes.onArchetypeCreated(fn);
+    }
+    // --- cold-query support: per-archetype residents + per-type cold value access ---
+    /** Entity indices currently resident in cold archetype `archetypeId` (O(rows in that archetype)). */
+    *coldResidentsOf(archetypeId) {
+        for (const [index, archId] of this.archetypes.cold.archOf) {
+            if (archId === archetypeId)
+                yield index;
+        }
+    }
+    /** The per-TYPE cold ColumnSet for `componentId` (cold blocks are keyed by component, not archetype). */
+    coldColumnSet(componentId) {
+        return this.archetypes.cold.blocks.get(componentId);
+    }
+    /** The cold-block row holding `componentId`'s fields for entity `index`, or -1 if absent. */
+    coldRowOf(index, componentId) {
+        return coldRowOf(this.archetypes.cold, index, componentId);
+    }
+    // --- entity lifecycle hooks (driven by EntityStore.spawn/despawn) ----------
+    onSpawn(handle) {
+        const index = this.#cfg.handleIndex(handle);
+        const empty = this.archetypes.emptyArchetype;
+        const row = this.archetypes.allocRow(empty, handle);
+        this.#cfg.record.commitRecord(index, EMPTY_ARCHETYPE_ID, row);
+        // Empty signature → no bits set; bitmaskApplyDelta from empty to empty is a no-op but keeps the
+        // coherence discipline explicit.
+        this.#cfg.bitmask.bitmaskApplyDelta(index, empty.signature, empty.signature);
+        // Emit the Create shape entry once the entity is committed to the empty
+        // archetype (componentId = NO_COMPONENT; the kind disambiguates).
+        this.#cfg.trackShape?.(index, NO_COMPONENT_SHAPE, SHAPE_CREATE);
+        // The component-less entity matches no component-constrained query, but a constraint-less
+        // query DOES match the empty signature. Tell those queries now (the seed already includes such
+        // entities, so this keeps the before-/after-spawn incremental paths symmetric).
+        this.#cfg.onEntitySpawned(index);
+    }
+    onDespawn(handle) {
+        const index = this.#cfg.handleIndex(handle);
+        const archId = this.#cfg.record.archetypeIdOf(index);
+        const arch = this.archetypes.byId[archId];
+        // /: emit Destroy BEFORE removeRow AND before identity invalidation
+        // (freeEntity runs after onDespawn in EntityStore), so a remove/destroy observer can still
+        // resolve the dying entity's last location. The full fixed sequence is: Destroy + remove-logs,
+        // then removeRow, then bitmask clear, then freeEntity.
+        this.#cfg.trackShape?.(index, NO_COMPONENT_SHAPE, SHAPE_DESTROY);
+        // Removal reactivity for every held component, BEFORE the row is reclaimed.
+        // If ANY held component has a remove-observer, defer the row reclaim so its values survive
+        // the drain. The gate keeps the no-observer path free of the swap window cost.
+        let defer = false;
+        const hasRemoveObserver = this.#cfg.hasRemoveObserver;
+        for (let i = 0; i < arch.signature.length; i++) {
+            const c = arch.signature[i];
+            this.#cfg.enqueueRemoveLog(index, c);
+            if (hasRemoveObserver !== undefined && hasRemoveObserver(c))
+                defer = true;
+        }
+        const row = this.#cfg.record.rowOf(index);
+        const fixSibling = (movedIndex, newRow) => {
+            this.#cfg.record.commitRecord(movedIndex, archId, newRow);
+        };
+        if (defer) {
+            this.archetypes.removeRow(arch, row, fixSibling, (newRow) => {
+                this.#cfg.record.commitRecord(index, archId, newRow);
+            });
+        }
+        else {
+            this.archetypes.removeRow(arch, row, fixSibling);
+        }
+        this.#cfg.bitmask.bitmaskClear(index);
+        // The despawned entity leaves every query that held it, INCLUDING a constraint-less query
+        // (which a now-empty shape would otherwise still appear to match). dropEntity unconditionally
+        // evicts the index from every live query's `current` (recording a `removed` delta where declared).
+        this.#cfg.dropEntity(index);
+    }
+    // --- structural verbs ------------------------------------------------------
+    add(handle, def) {
+        const id = this.#requireId(def);
+        this.archetypes.migrateAdding(handle, id);
+    }
+    remove(handle, def) {
+        const id = this.#requireId(def);
+        this.archetypes.migrateRemoving(handle, id);
+    }
+    spawnWith(handle, defs) {
+        for (const d of defs)
+            this.#requireId(d);
+        this.archetypes.spawnWith(handle, defs);
+    }
+    /** Atomic multi-id add — ONE migration to a single target signature (relations path). */
+    addMany(handle, defs) {
+        const ids = [];
+        for (const d of defs)
+            ids.push(this.#requireId(d));
+        this.archetypes.migrateAddingMany(handle, ids);
+    }
+    /** Atomic multi-id remove — symmetric to addMany. */
+    removeMany(handle, defs) {
+        const ids = [];
+        for (const d of defs)
+            ids.push(this.#requireId(d));
+        this.archetypes.migrateRemovingMany(handle, ids);
+    }
+    warm(defs) {
+        const ids = [];
+        for (const d of defs)
+            ids.push(this.#requireId(d));
+        this.archetypes.warm(canonicalize(ids));
+    }
+    /**
+     * (has() never reads the
+     * bitmask for a dead handle); this asserts world.phase === 'serial' inside bitmaskHas.
+     */
+    has(handle, def) {
+        const id = this.#requireId(def);
+        return this.#cfg.bitmask.bitmaskHas(this.#cfg.handleIndex(handle), id);
+    }
+    // --- AccessorResolver -------------------------------
+    resolveRead(handle, archetypeId, row, def) {
+        return this.#resolve(handle, archetypeId, row, def);
+    }
+    resolveWrite(handle, archetypeId, row, def) {
+        return this.#resolve(handle, archetypeId, row, def);
+    }
+    #resolve(handle, archetypeId, row, def) {
+        const id = this.#requireId(def);
+        const arch = this.archetypes.byId[archetypeId];
+        if (arch === undefined)
+            throw new Error(`storage.resolve: unknown archetype ${archetypeId}`);
+        let set;
+        let boundRow = row;
+        if (arch.cold) {
+            set = this.archetypes.cold.blocks.get(id);
+            boundRow = coldRowOf(this.archetypes.cold, this.#cfg.handleIndex(handle), id);
+        }
+        else {
+            set = arch.columnSets.get(id);
+        }
+        if (set === undefined) {
+            const rt = def;
+            if (rt.columnLayouts.length === 0 && !rt.hasRichFields) {
+                throw new Error(`storage.resolve: component '${def.name}' is a tag (no fields to read/write)`);
+            }
+            throw new Error(`storage.resolve: entity does not hold component '${def.name}'`);
+        }
+        return bindAccessorRow(set, boundRow, handle);
+    }
+    #requireId(def) {
+        const id = this.#cfg.registry.idOf(def);
+        if (id === undefined)
+            throw new Error(`component '${def.name}' is not registered with this world — register it in createWorld({ components: [...] })`);
+        return id;
+    }
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage/storage.js.map

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

package/dist/storage/store.d.ts

@@ -0,0 +1,88 @@
+import type { ComponentId, ComponentDef, Schema } from '@ecsia/schema';
+import type { ArchetypeId } from '@ecsia/schema';
+import type { Buffers } from '../memory/index.js';
+import type { AccessorWorld } from '../component/index.js';
+import type { Bitmask } from '../bitmask/index.js';
+import type { Signature } from './signature.js';
+import type { Archetype } from './archetype.js';
+import type { ColdStore } from './cold-store.js';
+export declare const EMPTY_ARCHETYPE_ID: ArchetypeId;
+export declare const ARCHETYPE_NONE: ArchetypeId;
+/** The two-word record surface the store commits through. */
+export interface RecordSurface {
+    commitRecord(index: number, archetypeId: number, row: number): void;
+    archetypeIdOf(index: number): number;
+    rowOf(index: number): number;
+}
+export interface StorageDeps {
+    readonly buffers: Buffers;
+    readonly accessorWorld: AccessorWorld;
+    readonly bitmask: Bitmask;
+    readonly record: RecordSurface;
+    readonly maxHotArchetypes: number;
+    /** Bitmask/sigWords stride = ceil(N/32) ( C4). */
+    readonly stride: number;
+    /** Mint ceiling; clamps a new column's initial reservation so it never exceeds the world cap. */
+    readonly maxEntities: number;
+    /** Removal-reactivity hook for components in fromArch \ toArch ( fills the body). */
+    enqueueRemoveLog(index: number, c: ComponentId): void;
+    /**
+     * Shape-log hook: emit a structural entry at the commit point. Optional so a
+     * query-less harness (unit tests) constructs the store directly; the world wires it to reactivity.
+     */
+    trackShape?(index: number, c: ComponentId, kind: number): void;
+    /**
+     * Single-entity incremental query maintenance: called once per component in the
+     * symmetric difference of a migration AFTER the bitmask delta is applied, so matchesEntityNow reads
+     * a coherent shape. Optional so a query-less harness ( unit tests) constructs the store directly.
+     * re-routes this through reactivity's MAINTAIN_STRUCTURAL shape-log drain.
+     */
+    maintainEntity?(index: number, c: ComponentId): void;
+    tick(): number;
+    defOf(c: ComponentId): ComponentDef<Schema> | undefined;
+    handleIndex(handle: number): number;
+}
+export declare class ArchetypeStore {
+    #private;
+    readonly byId: Archetype[];
+    readonly cold: ColdStore;
+    constructor(deps: StorageDeps);
+    get hotCount(): number;
+    get emptyArchetype(): Archetype;
+    getOrCreateArchetype(sig: Signature): Archetype;
+    /** Subscribe to archetypeCreated. Serial-phase only. */
+    onArchetypeCreated(fn: (arch: Archetype) => void): void;
+    edgeAdd(arch: Archetype, c: ComponentId): Archetype;
+    edgeRemove(arch: Archetype, c: ComponentId): Archetype;
+    /** Reserve a row in `arch` for `handle`; records the occupant. Caller writes column values. */
+    allocRow(arch: Archetype, handle: number): number;
+    /**
+     * Swap-pop removal: move the last live row into `row`, then fix the moved sibling's record via
+     * the callback. `fixSibling` fires exactly once iff row !== count-1 (I6). Serial only.
+     *
+     *: when `relocateDying` is supplied (a remove-observer subscribes to a
+     * held component), the dying entity's column data must survive intact until after observerDrain so
+     * an onRemove handler can read its last value. Instead of a one-way overwrite of the dying row, we
+     * SWAP it with the last live row: the sibling's data lands in `row` (record fixed), and the dying
+     * entity's data lands at the now-excluded `last` slot (record relocated via `relocateDying`). The
+     * dying row is naturally reclaimed — it sits at/above `count`, outside every `[0,count)` iteration,
+     * and is overwritten by the next allocRow (which only happens next frame, since observer mutations
+     * stage to command buffers). For hot rows this needs no per-frame stale-row list.
+     */
+    removeRow(arch: Archetype, row: number, fixSibling: (movedIndex: number, newRow: number) => void, relocateDying?: (newRow: number) => void): void;
+    /** Move one entity from fromArch to toArch: K-shared copy + init-added + shuffle-pop + commit. */
+    migrate(handle: number, fromArch: Archetype, toArch: Archetype): number;
+    /** entity.add(C): single-id add via the cached edge. */
+    migrateAdding(handle: number, c: ComponentId): number;
+    /** entity.remove(C): single-id remove via the cached edge. */
+    migrateRemoving(handle: number, c: ComponentId): number;
+    /** Multi-id atomic add — ONE target signature, one migration (relations atomicity). */
+    migrateAddingMany(handle: number, addIds: readonly ComponentId[]): number;
+    /** Multi-id atomic remove — symmetric to migrateAddingMany. */
+    migrateRemovingMany(handle: number, removeIds: readonly ComponentId[]): number;
+    /** spawnWith fast path: compute the target signature up front and migrate ONCE. */
+    spawnWith(handle: number, defs: readonly ComponentDef<Schema>[]): number;
+    /** Promote a cold archetype (by signature) to hot: allocate columns, migrate its rows out. */
+    warm(sig: Signature): void;
+}
+//# sourceMappingURL=store.d.ts.map

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

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