@ecsia/core 0.1.0

package/dist/query/engine.js

@@ -0,0 +1,230 @@
+// The query engine: the canonical-hash dedup cache (Map<hash, LiveQuery>),
+// the per-archetype matching (signatureMatches over matchingArchetypes — O(A), NOT per-entity), the
+// archetypeCreated incremental upkeep, the reverse queriesReferencing index, and the single-entity
+// incremental matcher (matchEntity over entityShapeWords) used ONLY to re-test one migrated entity.
+//
+// Wired by the world: it subscribes to storage.onArchetypeCreated and supplies storage's
+// maintainEntity / dropEntity hooks. All matching/maintenance is serial / main-thread.
+import { sigHas, signatureMatches } from '../storage/index.js';
+import { compileQuery } from './compile.js';
+import { LiveQuery } from './live-query.js';
+import { SparseSetU32 } from './sparse-set.js';
+export class QueryEngine {
+    #deps;
+    #byHash = new Map();
+    /** componentId → the live queries that reference it (reverse maintenance index). */
+    #referencing = new Map();
+    #reactivity = null;
+    #seq = 0;
+    constructor(deps) {
+        this.#deps = deps;
+        deps.onArchetypeCreated((arch) => this.#onArchetypeCreated(arch));
+    }
+    /** Late-bind the reactivity write-log hooks so the Changed flavor works (world wiring). */
+    setReactivity(hooks) {
+        this.#reactivity = hooks;
+        for (const lq of this.#byHash.values())
+            lq.__setReactivity(hooks);
+    }
+    /**: compile, dedup by canonical hash, seed on a miss. */
+    query(terms) {
+        const compiled = compileQuery(terms, this.#deps.compileContext);
+        const existing = this.#byHash.get(compiled.hash);
+        if (existing !== undefined) {
+            existing.ensureValueSignature(compiled);
+            return existing;
+        }
+        const lq = this.#createLiveQuery(compiled, terms);
+        this.#byHash.set(compiled.hash, lq);
+        return lq;
+    }
+    /** Exposed for the world facade / tests: iterate every live query (e.g. for frameReset). */
+    get liveQueries() {
+        return this.#byHash.values();
+    }
+    // ---: allocate the result container, seed all existing archetypes ----------
+    #createLiveQuery(compiled, terms) {
+        const id = this.#seq++;
+        const denseKey = `query.${id}.dense`;
+        const sparseKey = `query.${id}.sparse`;
+        const current = new SparseSetU32(this.#deps.buffers, denseKey, sparseKey, 64, this.#deps.maxEntities);
+        const lq = new LiveQuery(compiled, terms, current, this.#deps.byId, this.#deps);
+        lq.ensureValueSignature(compiled);
+        if (this.#reactivity !== null)
+            lq.__setReactivity(this.#reactivity);
+        if (!compiled.unsatisfiable) {
+            for (const arch of this.#deps.byId) {
+                if (this.#archetypeMatches(arch, compiled)) {
+                    lq.addMatchingArchetype(arch);
+                    this.#seedCurrentFromArchetype(lq, arch);
+                }
+            }
+        }
+        // Register in the reverse maintenance index for incremental upkeep.
+        for (const cid of compiled.referencedIds) {
+            let set = this.#referencing.get(cid);
+            if (set === undefined) {
+                set = new Set();
+                this.#referencing.set(cid, set);
+            }
+            set.add(lq);
+        }
+        lq.lastMatchTick = 0;
+        return lq;
+    }
+    // --- (one AND per signature word) ------------------------------
+    #archetypeMatches(arch, q) {
+        if (q.unsatisfiable)
+            return false;
+        if (!signatureMatches(arch.sigWords, q.withWords, q.notWords, []))
+            return false;
+        for (const r of q.residualWith) {
+            const present = sigHas(arch.signature, r.componentId);
+            if (r.negate ? present : !present)
+                return false;
+        }
+        return true;
+    }
+    /**
+     * (a) row filter for the single-entity matcher: an exclusive specific-target pair
+     * matches the archetype by presence, then this checks the entity's own eid target column value so
+     * `current` stays precise (count/has agree with the iteration filter in LiveQuery).
+     */
+    #passesRowFilters(index, q) {
+        if (q.rowFilters.length === 0)
+            return true;
+        const loc = this.#deps.resolveLocation(index);
+        const arch = this.#deps.byId[loc.archetypeId];
+        if (arch === undefined || arch.cold)
+            return q.rowFilters.length === 0;
+        for (const rf of q.rowFilters) {
+            const cs = arch.columnSets.get(rf.presenceId);
+            if (cs === undefined)
+                return false;
+            const col = cs.columns[rf.targetFieldIndex];
+            if (col === undefined)
+                return false;
+            const stored = col.view[loc.row * col.layout.stride];
+            if (stored === -1 || (stored >>> 0) !== (rf.targetEid >>> 0))
+                return false;
+        }
+        return true;
+    }
+    /**: add every live row's entity index to `current`. New archetypes start empty. */
+    #seedCurrentFromArchetype(lq, arch) {
+        if (arch.cold) {
+            // Cold rows are index-keyed in the overflow store; seed from the cold archetype's residents so
+            // a query created AFTER cold entities exist sees them ( cold transparency), matching the
+            // per-entity maintenance path that adds residents as they migrate in.
+            for (const index of this.#deps.coldResidentsOf(arch.id))
+                lq.addEntity(index);
+            return;
+        }
+        const count = arch.count;
+        const filters = lq.compiled.rowFilters;
+        for (let row = 0; row < count; row++) {
+            const handle = arch.rows[row];
+            const index = this.#handleIndex(handle);
+            if (filters.length > 0 && !this.#rowPasses(arch, row, lq.compiled))
+                continue;
+            lq.addEntity(index);
+        }
+    }
+    /** Row-filter test against a known (archetype, row) for seeding ((a)). */
+    #rowPasses(arch, row, q) {
+        for (const rf of q.rowFilters) {
+            const cs = arch.columnSets.get(rf.presenceId);
+            if (cs === undefined)
+                return false;
+            const col = cs.columns[rf.targetFieldIndex];
+            if (col === undefined)
+                return false;
+            const stored = col.view[row * col.layout.stride];
+            if (stored === -1 || (stored >>> 0) !== (rf.targetEid >>> 0))
+                return false;
+        }
+        return true;
+    }
+    #handleIndex(handle) {
+        // The dense rows store full handles; the entity index is the low handle bits. The engine resolves
+        // it via the same bitmask stride the rest of the world uses — but here we only need the index, and
+        // the record's resolveLocation already addresses by index, so derive it from the handle directly.
+        return this.#deps.indexOfHandle(handle);
+    }
+    // ---
+    #onArchetypeCreated(arch) {
+        for (const lq of this.#byHash.values()) {
+            if (this.#archetypeMatches(arch, lq.compiled)) {
+                lq.addMatchingArchetype(arch);
+                // A brand-new archetype starts with count 0 (entities migrate in afterward), so nothing to
+                // seed here; the per-entity migration path populates `current` as entities enter. A
+                // non-empty new archetype only arises via warm promotion, which re-seeds separately.
+                this.#seedCurrentFromArchetype(lq, arch);
+            }
+        }
+    }
+    // --- (the ONLY per-entity AND) -------------------------
+    /**: re-test ONE migrated entity against only the queries referencing the changed component. */
+    maintainEntity(index, componentId) {
+        const set = this.#referencing.get(componentId);
+        if (set === undefined)
+            return;
+        for (const lq of set) {
+            const wasMatch = lq.current.has(index);
+            const isMatch = this.#matchesEntityNow(lq, index);
+            if (isMatch && !wasMatch)
+                lq.addEntity(index);
+            else if (!isMatch && wasMatch)
+                lq.removeEntity(index);
+        }
+    }
+    /**
+     *: a freshly spawned entity lands in the EMPTY archetype. It carries no component, so
+     * the per-component `maintainEntity` path never fires for it — yet a constraint-less query (empty
+     * withWords/notWords/residualWith) DOES match the empty signature and the seed already
+     * includes such entities. To keep the incremental path symmetric with the seed (so a query created
+     * BEFORE a plain spawn agrees with one created after), re-test the new index against every query
+     * that matches the empty archetype and add it.
+     */
+    onEntitySpawned(index, emptyArchetype) {
+        for (const lq of this.#byHash.values()) {
+            if (this.#archetypeMatches(emptyArchetype, lq.compiled))
+                lq.addEntity(index);
+        }
+    }
+    /**: evict a despawned entity from EVERY live query (constraint-less queries included). */
+    dropEntity(index) {
+        for (const lq of this.#byHash.values())
+            lq.removeEntity(index);
+    }
+    /**: AND the entity's shape words against the query masks. */
+    #matchesEntityNow(lq, index) {
+        const q = lq.compiled;
+        if (q.unsatisfiable)
+            return false;
+        const shape = this.#deps.bitmask.entityShapeWords(index);
+        for (const t of q.notWords)
+            if ((shape[t.wordIndex] & t.mask) !== 0)
+                return false;
+        for (const t of q.withWords)
+            if ((shape[t.wordIndex] & t.mask) !== t.mask)
+                return false;
+        if (q.residualWith.length > 0) {
+            const sig = this.#deps.signatureOf(index);
+            for (const r of q.residualWith) {
+                const present = sigHas(sig, r.componentId);
+                if (r.negate ? present : !present)
+                    return false;
+            }
+        }
+        if (!this.#passesRowFilters(index, q))
+            return false;
+        return true;
+    }
+    /** Reset every live query's per-frame transient flavor lists (FRAME_RESET). */
+    frameReset() {
+        for (const lq of this.#byHash.values())
+            lq.frameReset();
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/query/engine.js.map

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

package/dist/query/index.d.ts

@@ -0,0 +1,8 @@
+export { QueryEngine } from './engine.js';
+export type { QueryEngineDeps } from './engine.js';
+export { LiveQuery } from './live-query.js';
+export type { LiveQueryDeps, PooledElement, ReactivityQueryHooks } from './live-query.js';
+export { SparseSetU32 } from './sparse-set.js';
+export { compileQuery } from './compile.js';
+export type { CompiledQuery, CompiledValueTerm, CompileContext, ResidualTerm, ResolvedPair, RowFilterTerm, ValueRole, Word, } from './compile.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAElD,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAC3C,YAAY,EAAE,aAAa,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAEzF,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE9C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC3C,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,aAAa,EACb,SAAS,EACT,IAAI,GACL,MAAM,cAAc,CAAA"}

package/dist/query/index.js

@@ -0,0 +1,10 @@
+// @ecsia/core query subsystem. The query DSL runtime: compilation + canonical-hash
+// dedup cache (compile.ts), the SAB-capable sparse-set result container (sparse-set.ts), the
+// LiveQuery with the matchingArchetypes pointer cache and the .each iteration (live-query.ts), and
+// the QueryEngine that owns matching, the archetypeCreated hook, and single-entity maintenance
+// (engine.ts). world.query(...) delegates here; the query DSL TYPES live in @ecsia/schema.
+export { QueryEngine } from './engine.js';
+export { LiveQuery } from './live-query.js';
+export { SparseSetU32 } from './sparse-set.js';
+export { compileQuery } from './compile.js';
+//# sourceMappingURL=index.js.map

package/dist/query/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,6FAA6F;AAC7F,mGAAmG;AACnG,+FAA+F;AAC/F,2FAA2F;AAE3F,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAGzC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAG3C,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAE9C,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA"}

package/dist/query/live-query.d.ts

@@ -0,0 +1,122 @@
+import type { ArchetypeId, ComponentDef, ComponentId, EntityHandle, Schema } from '@ecsia/schema';
+import type { ColumnSet } from '../component/index.js';
+import type { Archetype } from '../storage/index.js';
+import type { TypedArray } from '../memory/index.js';
+import type { CompiledQuery } from './compile.js';
+import type { SparseSetU32 } from './sparse-set.js';
+declare const NO_HANDLE: EntityHandle;
+/** The pooled element handed to each callback: value props (per value term) + the entity handle. */
+type PooledElement = Record<string, unknown> & {
+    handle: EntityHandle;
+};
+/** The reactivity write-log hooks the Changed flavor drives. */
+export interface ReactivityQueryHooks {
+    /**: allocate this query's changed-flavor LogPointer + dedup bitset (idempotent). */
+    attachChangedFlavor(q: LiveQuery, componentIds: Iterable<number>): void;
+    /**: drain this frame's changed entity indices (deduped, intersected with `current`). */
+    drainChanged(q: LiveQuery): Uint32Array;
+}
+export interface LiveQueryDeps {
+    /** index → its (archetypeId, row) — the entity record. */
+    resolveLocation(index: number): {
+        archetypeId: number;
+        row: number;
+    };
+    /** index → its full EntityHandle (generation from the entity layer). */
+    handleOf(index: number): EntityHandle;
+    /**
+     * The entity indices currently resident in cold archetype `archetypeId`. Backed by the
+     * ColdStore's per-archetype membership so cold iteration is O(rows in that archetype), NOT
+     * O(|current|) per cold archetype.
+     */
+    coldResidentsOf(archetypeId: number): Iterable<number>;
+    /** The cold per-TYPE 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;
+}
+export declare class LiveQuery {
+    #private;
+    readonly compiled: CompiledQuery;
+    readonly terms: readonly unknown[];
+    readonly matchingArchetypes: Archetype[];
+    readonly current: SparseSetU32;
+    lastMatchTick: number;
+    constructor(compiled: CompiledQuery, terms: readonly unknown[], current: SparseSetU32, byId: Archetype[], deps: LiveQueryDeps);
+    get count(): number;
+    /** Chainable flavor declarations. Allocate nothing for undeclared flavors. */
+    added(): this;
+    removed(): this;
+    /** Install the reactivity write-log hooks (world wiring); enables the Changed flavor. */
+    __setReactivity(hooks: ReactivityQueryHooks): void;
+    changed(...components: ReadonlyArray<unknown>): this;
+    /** Reset per-frame transient flavor lists (FRAME_RESET). */
+    frameReset(): void;
+    /** The value-role signature: the P/W-tagged value subset, read-vs-write distinguished. */
+    static valueSignature(compiled: CompiledQuery): string;
+    ensureValueSignature(compiled: CompiledQuery): void;
+    /** Append a newly-created (or seeded) archetype to the pointer cache. */
+    addMatchingArchetype(arch: Archetype): void;
+    /**: add an entity index to `current`, recording a NET `added` delta where declared. */
+    addEntity(index: number): void;
+    /**: remove an entity index from `current`, recording a NET `removed` delta where declared. */
+    removeEntity(index: number): void;
+    /** The hot loop: walk matchingArchetypes contiguous rows, poke the accessor singletons, call fn. */
+    each(fn: (e: PooledElement) => void): void;
+    /**
+     * Opt-in column-cursor iteration (the SoA fast path). Instead of the per-row pooled element +
+     * accessor getters/setters, `eachChunk` hands the callback ONE reused {@link QueryChunk} per matched
+     * (non-cold) archetype, exposing the raw typed column views + a contiguous row span. The caller indexes
+     * `view[row]` directly (stride-1 scalars) — bypassing the accessor decode/encode AND the per-write
+     * change-tracking push, so it lands close to a raw SoA loop. Cold archetypes (no contiguous columns)
+     * are NOT visited by `eachChunk`; mix `each`/`eachCold` if a query can fragment. Writes through the
+     * cursor are NOT recorded in the reactivity write log: a `.changed`/observer consumer will not see them
+     * — use `each` when reactivity must observe the write.
+     *
+     * The chunk and its column lookups are reused across calls/archetypes — do NOT store the chunk or a
+     * returned view across iterations.
+     */
+    eachChunk(fn: (chunk: QueryChunk) => void): void;
+    [Symbol.iterator](): Iterator<PooledElement>;
+    eachAdded(fn: (e: PooledElement) => void): void;
+    eachRemoved(fn: (index: number, handle: EntityHandle) => void): void;
+    /**
+     *: the Changed filter reads the reactivity WRITE LOG, not changeVersion. The write log lands
+     * at; until then there are no recorded writes, so the changed set is empty. The matching surface
+     * (binding the cursor per changed index) is in place for to fill the index source.
+     */
+    eachChanged(fn: (e: PooledElement) => void): void;
+}
+/**
+ * The reused per-archetype cursor handed to {@link LiveQuery.eachChunk}. Exposes one matched archetype's
+ * raw SoA columns + its contiguous row span. Resolve each column ONCE before the inner row loop:
+ *
+ * ```ts
+ * q.eachChunk((c) => {
+ * const px = c.column(Position, 'x'), py = c.column(Position, 'y')
+ * const dx = c.column(Velocity, 'dx'), dy = c.column(Velocity, 'dy')
+ * for (let i = 0; i < c.count; i) { px[i] += dx[i] * dt; py[i] += dy[i] * dt }
+ * })
+ * ```
+ *
+ * `column` returns the live typed view; `stride` is the slots-per-row (>1 for vec fields, where row `r`
+ * starts at `r * stride`). The cursor (and every returned view) is reused across archetypes/calls — do NOT
+ * store either across iterations. Writes here bypass the reactivity write log (see `eachChunk`).
+ */
+export declare class QueryChunk {
+    #private;
+    /** @internal — point the chunk at one matched archetype (the cursor loop owns this). */
+    __bind(arch: Archetype): void;
+    /** Rows in this chunk (the archetype's dense row count). Iterate `0..count`. */
+    get count(): number;
+    /** The dense row→EntityHandle list for this chunk (row `r`'s entity is `entities[r]`). */
+    get entities(): Uint32Array;
+    /** The live typed column view for `def.field` in this chunk. Stride-1 scalars index by row directly. */
+    column<S extends Schema>(def: ComponentDef<S>, field: string): TypedArray;
+    /** Slots per row for `def.field` (1 scalar, N vec): row `r` starts at `r * stride`. */
+    stride<S extends Schema>(def: ComponentDef<S>, field: string): number;
+}
+export type { PooledElement };
+export { NO_HANDLE };
+export type { ArchetypeId, ComponentId, Schema };
+//# sourceMappingURL=live-query.d.ts.map

package/dist/query/live-query.d.ts.map

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