@ecsia/core 0.1.0

package/dist/world.js

@@ -0,0 +1,831 @@
+// The World keystone: option resolution, the phase/tick contracts, and the module-wiring seam.
+// The seven owning modules attach in the fixed order
+// registry → buffers → storage → reactivity → queries → scheduler → serialization.
+import { resolveOptions } from './config.js';
+import { EntityStore, handleIndex, makeHandleLayout, reserveEntityBlock, returnReservedIds, } from './entity/index.js';
+import { Buffers, probeCapabilities } from './memory/index.js';
+import { ComponentRegistry } from './registry.js';
+import { SidecarStore, sidecarKey } from './component/index.js';
+import { Bitmask } from './bitmask/index.js';
+import { Storage } from './storage/index.js';
+import { QueryEngine } from './query/index.js';
+import { ShapeKind } from './reactivity/index.js';
+import { Reactivity, ObserverCommandBuffer, onAdd, onRemove, onChange } from './reactivity/index.js';
+import { IS_DEV } from './env.js';
+import { isSharedBacking } from './memory/buffers.js';
+/**
+ * The only world constructor. Resolves and validates options fail-fast, then
+ * (at later milestones) probes capabilities, allocates bounded buffers, and wires the owning
+ * modules. Returns a frozen World facade.
+ */
+export function createWorld(options = {}) {
+    const resolved = resolveOptions(options);
+    // --- Module wiring seam ---
+    // registry → buffers → storage → reactivity → queries → scheduler → serialization.
+    // The entity layer lands first; later layers fill in around it.
+    const state = { phase: 'serial', tick: 0 };
+    const handleLayout = makeHandleLayout(resolved.generationBits);
+    const entities = new EntityStore({
+        layout: handleLayout,
+        maxEntities: resolved.maxEntities,
+        shared: resolved.threaded,
+    });
+    // --- buffers: one capability probe, one SAB-vs-AB decision ---
+    const workerMode = resolved.threaded
+        ? resolved.scheduler.workers === 'no-sab'
+            ? 'no-sab'
+            : 'auto'
+        : 'single';
+    const capabilities = probeCapabilities(workerMode, (message) => {
+        if (typeof console !== 'undefined')
+            console.warn(`[ecsia] ${message}`);
+    });
+    const buffers = new Buffers({ capabilities, maxEntities: resolved.maxEntities });
+    // The accessor seam: a setter calls world.trackWrite. handleIndex strips the generation so the LOW
+    // handle bits index the write log. Routes to the reactivity module once built
+    // (late-bound so the acyclic construction order registry → buffers → storage → reactivity holds).
+    let reactivity = null;
+    const trackWrite = (index, componentId, fieldIndex) => {
+        reactivity?.trackWrite(index, componentId, fieldIndex);
+    };
+    // The shared "any write consumer exists" cell the accessor setters read to fast-out the trackWrite
+    // chain. Reactivity owns recomputing `.active` on every flavor/observer/changeVersion
+    // (de)registration; until reactivity is wired it stays false (no consumers can exist yet).
+    const tracking = { active: false };
+    // The rich-field sidecar. Created BEFORE accessorWorld so the accessor's rich
+    // getters/setters can delegate through the seam. Main-thread-only; never shared with workers.
+    const sidecar = new SidecarStore();
+    // During an observer drain the rich getter must read the DYING entity's value (RF-REMOVE-READ); the
+    // sidecar disambiguates via its pending-clear table, so route reads through readForObserver while a
+    // pending window is open and through the generation-guarded read otherwise.
+    const accessorWorld = {
+        trackWrite,
+        tracking,
+        handleIndex: (handle) => handleIndex(handle, handleLayout),
+        sidecarRead: (key, index, gen) => sidecar.hasPending() ? sidecar.readForObserver(key, index, gen) : sidecar.read(key, index, gen),
+        sidecarWrite: (key, index, gen, value) => sidecar.write(key, index, gen, value),
+        generationOf: (index) => entities.decodeHandle(entities.handleOfIndex(index)).generation,
+    };
+    // --- registry: mint dense user ids, wire accessor factories ---
+    const registry = new ComponentRegistry();
+    registry.register(resolved.components);
+    // Declare a sidecar column per rich field of every registered component. This
+    // is the single place the sidecar learns about a rich column; ensureColumn is idempotent.
+    for (const def of resolved.components) {
+        const id = registry.idOf(def);
+        if (id === undefined)
+            continue;
+        let fieldIndex = 0;
+        for (const f of def.fields) {
+            if (f.rich !== undefined)
+                sidecar.ensureColumn(sidecarKey(id, fieldIndex), f.rich, f.default);
+            fieldIndex += 1;
+        }
+    }
+    // --- bitmask + storage: the per-entity membership index and the
+    // archetype tables. The bitmask stride = ceil(nextComponentId/32); both derive from the SAME
+    // registered-component count so sigWords and bitmask layouts align. Structural mutation is
+    // serial; the bitmask asserts world.phase === 'serial'.
+    const bitmask = new Bitmask(buffers, registry.nextComponentId, resolved.maxEntities, () => state.phase);
+    const stride = bitmask.stride;
+    const records = entities.records;
+    const handleIndexOf = (handle) => handleIndex(handle, handleLayout);
+    // Relations attach late: the pair-resolver feeds the query compiler, the preDespawn hook runs
+    // before storage tears the row down, and the apply-pair fns back __apply for the scheduler. All are
+    // mutable so the relations runtime injects them post-construction without a core→relations import.
+    let pairResolver = null;
+    let preDespawnHook = null;
+    let applyAddPair = null;
+    let applyRemovePair = null;
+    let serializationProvider = null;
+    // The query engine is created AFTER storage (it subscribes to storage.onArchetypeCreated), but
+    // storage's single-entity maintenance hooks must call into the engine. Late-bind through a mutable
+    // reference so the wiring stays acyclic (storage → engine, set once below).
+    let engine = null;
+    const storage = new Storage({
+        buffers,
+        accessorWorld,
+        bitmask,
+        record: records,
+        registry,
+        maxHotArchetypes: resolved.maxHotArchetypes,
+        stride,
+        maxEntities: resolved.maxEntities,
+        enqueueRemoveLog: (index, c) => reactivity?.enqueueRemoveLog(index, c),
+        hasRemoveObserver: (c) => reactivity?.hasRemoveObserver(c) ?? false,
+        trackShape: (index, c, kind) => reactivity?.trackShape(index, c, kind),
+        maintainEntity: (index, c) => engine?.maintainEntity(index, c),
+        onEntitySpawned: (index) => engine?.onEntitySpawned(index, storage.archetypes.emptyArchetype),
+        dropEntity: (index) => engine?.dropEntity(index),
+        tick: () => state.tick,
+        handleIndex: handleIndexOf,
+    });
+    // --- queries: the canonical-hash dedup cache + per-archetype matching, kept
+    // current by the archetypeCreated hook. fixedBitCount = stride*32 (ids below it pack into the
+    // signature words; larger pair ids are residual — ).
+    engine = new QueryEngine({
+        buffers,
+        bitmask,
+        maxEntities: resolved.maxEntities,
+        byId: storage.archetypes.byId,
+        onArchetypeCreated: (fn) => storage.onArchetypeCreated(fn),
+        compileContext: {
+            idOf: (def) => {
+                const id = 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;
+            },
+            fixedBitCount: stride * 32,
+            resolvePair: (relationId, target) => {
+                if (pairResolver === null)
+                    return { componentId: 0, unsatisfiable: true };
+                return pairResolver(relationId, target);
+            },
+        },
+        resolveLocation: (index) => entities.locationOfIndex(index),
+        handleOf: (index) => entities.handleOfIndex(index),
+        indexOfHandle: handleIndexOf,
+        coldResidentsOf: (archetypeId) => storage.coldResidentsOf(archetypeId),
+        coldColumnSet: (componentId) => storage.coldColumnSet(componentId),
+        coldRowOf: (index, componentId) => storage.coldRowOf(index, componentId),
+        signatureOf: (index) => {
+            const archId = records.archetypeIdOf(index);
+            return storage.archetypes.byId[archId].signature;
+        },
+    });
+    // Rich-field despawn clear. Walk the dying entity's signature for rich
+    // fields and decide whether to DEFER the clear: when any held component has a remove-observer, the
+    // deferred row reclaim keeps numeric values readable in onRemove, so the sidecar must stash the
+    // dying rich values for the same observer window (RF-REMOVE-READ). The decision mirrors storage's
+    // `defer` gate exactly so rich and numeric parity holds.
+    const sidecarOnDespawn = (handle) => {
+        const index = handleIndexOf(handle);
+        const archId = records.archetypeIdOf(index);
+        const arch = storage.archetypes.byId[archId];
+        if (arch === undefined)
+            return;
+        const richKeys = [];
+        let defer = false;
+        for (let i = 0; i < arch.signature.length; i++) {
+            const c = arch.signature[i];
+            const def = registry.defOf(c);
+            if (def !== undefined && def.hasRichFields) {
+                let fieldIndex = 0;
+                for (const f of def.fields) {
+                    if (f.rich !== undefined)
+                        richKeys.push(sidecarKey(c, fieldIndex));
+                    fieldIndex += 1;
+                }
+            }
+            if (reactivity?.hasRemoveObserver(c) === true)
+                defer = true;
+        }
+        if (richKeys.length > 0)
+            sidecar.onDespawn(index, richKeys, defer);
+    };
+    entities.setAccessorResolver(storage);
+    entities.setLifecycle({
+        onSpawn: (handle) => storage.onSpawn(handle),
+        onDespawn: (handle) => {
+            // PreDespawn (cascade + pair teardown) runs WHILE `dying` is still
+            // alive/resolvable, BEFORE storage.onDespawn shuffle-pops the row and the entity layer frees it.
+            preDespawnHook?.(handle);
+            // The rich clear runs BEFORE storage.onDespawn so the dying entity's signature is still resolvable
+            // (storage.onDespawn shuffle-pops the row; the entity index record is unchanged either way).
+            sidecarOnDespawn(handle);
+            storage.onDespawn(handle);
+        },
+    });
+    // --- reactivity: the write/shape rings, changeVersion stamps, deferred
+    // observers, and the query-flavor hooks. Wired AFTER storage + queries so trackWrite/trackShape and
+    // observer dispatch can resolve locations and re-test entities.
+    reactivity = new Reactivity({
+        buffers,
+        maxEntities: resolved.maxEntities,
+        indexBits: handleLayout.indexBits,
+        logEntryWords: resolved.reactivity.logEntryWords,
+        maxWritesPerFrame: resolved.reactivity.maxWritesPerFrame,
+        maxShapeChangesPerFrame: resolved.reactivity.maxShapeChangesPerFrame,
+        shrinkRings: resolved.reactivity.shrinkRings,
+        dev: IS_DEV,
+        resolveLocation: (index) => entities.locationOfIndex(index),
+        tick: () => state.tick,
+        advanceTick: () => {
+            state.tick = (state.tick + 1) >>> 0;
+        },
+        idOf: (def) => {
+            const id = 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;
+        },
+        holdsAll: (index, componentIds) => {
+            for (const c of componentIds)
+                if (!bitmask.bitmaskHas(index, c))
+                    return false;
+            return true;
+        },
+        refOf: (index) => entities.entity(entities.handleOfIndex(index), { lenient: true }),
+        resolveHandle: (index) => entities.handleOfIndex(index),
+        tracking,
+    });
+    // The shape-log drain re-runs the same idempotent single-entity maintenance the synchronous
+    // hook performs; the conservative overflow path needs a "current matches" source for change
+    // observers.
+    reactivity.setMaintainHook((index, c) => engine?.maintainEntity(index, c));
+    reactivity.setCurrentMembersSource(() => collectCurrentMembers(engine));
+    engine.setReactivity({
+        attachChangedFlavor: (q, ids) => reactivity.attachChangedFlavor(q, ids),
+        drainChanged: (q) => reactivity.drainChanged(q),
+    });
+    // --- deferred-observer command buffer ---
+    // While observerDrain runs, the world's structural verbs (spawn/spawnWith/add/remove/despawn and
+    // the relations apply-pair seam) STAGE here instead of direct-applying, so an observer handler that
+    // mutates structure cannot corrupt the wave the drain is replaying. The staged ops apply at
+    // the start of the NEXT drain — i.e. the next serial flush. applyAddPair/applyRemovePair are the
+    // SAME relation seams the scheduler's command-apply path drives (filled by __installRelations).
+    const observerCommands = new ObserverCommandBuffer();
+    const observerApply = {
+        placeReserved(handle, defs) {
+            // The handle was reserved-alive when the observer called spawn; place it into the EMPTY archetype
+            // (emitting Create), then migrate it to the requested signature in one move (spawnWith semantics).
+            storage.onSpawn(handle);
+            if (defs.length > 0)
+                storage.addMany(handle, defs);
+        },
+        add: (handle, def) => storage.add(handle, def),
+        remove: (handle, def) => storage.remove(handle, def),
+        despawn: (handle) => entities.despawn(handle),
+        isAlive: (handle) => entities.isAlive(handle),
+        writePayload: (handle, def, values) => {
+            const view = entities.entity(handle).write(def);
+            for (const k of Object.keys(values))
+                view[k] = values[k];
+        },
+        addPair: (subject, relationId, target, payload) => applyAddPair?.(subject, relationId, target, payload),
+        removePair: (subject, relationId, target) => applyRemovePair?.(subject, relationId, target),
+    };
+    // --- serialization surface -------------------------
+    // Reads archetype columns/signatures + the registry + the relation provider; drives deserialize-side
+    // spawn/migrate. The user-component metadata is the registered defs in dense-id order. Synthetic ids
+    // (pair/presence/overflow) are intentionally excluded from `components()` — they are reconstructed by
+    // re-minting on the receiver, never shipped as schema.
+    const userComponents = resolved.components;
+    const componentIdByName = new Map();
+    for (const def of userComponents) {
+        const id = registry.idOf(def);
+        if (id !== undefined)
+            componentIdByName.set(def.name, id);
+    }
+    // Rich-field enumeration for the serialization sidecar section. Built once
+    // from the registered defs in (componentId, fieldIndex) order; the snapshot/delta writers join this
+    // with each entity's signature — they MUST NOT read `archetypeView().components`, which strips rich
+    // fields (and drops rich-only components entirely).
+    const richFieldList = [];
+    for (const def of userComponents) {
+        const id = registry.idOf(def);
+        if (id === undefined)
+            continue;
+        let fieldIndex = 0;
+        for (const f of def.fields) {
+            if (f.rich !== undefined)
+                richFieldList.push({ componentId: id, fieldIndex, name: f.name, kind: f.rich });
+            fieldIndex += 1;
+        }
+    }
+    const computeSchemaHash = () => {
+        // FNV-1a over the canonical (componentName, fieldName, token)* + relation names. The receiver
+        // recomputes it from ITS defineComponent set and must match — a fail-fast guard against stale code.
+        let h = 0x811c9dc5;
+        const fnv = (s) => {
+            for (let i = 0; i < s.length; i++) {
+                h ^= s.charCodeAt(i);
+                h = Math.imul(h, 0x01000193);
+            }
+        };
+        for (const def of userComponents) {
+            fnv(def.name);
+            for (const f of def.fields) {
+                fnv(f.name);
+                fnv(typeof f.token === 'string' ? f.token : JSON.stringify(f.token));
+            }
+        }
+        const prov = serializationProvider;
+        if (prov !== null)
+            for (const r of prov.relations())
+                fnv(r.name);
+        return h >>> 0;
+    };
+    const archetypeView = (arch) => {
+        const components = [];
+        // Iterate the signature in canonical (sorted) order so column order is deterministic.
+        for (let i = 0; i < arch.signature.length; i++) {
+            const c = arch.signature[i];
+            const set = arch.columnSets.get(c);
+            if (set === undefined)
+                continue; // tag / pair / no column
+            const def = registry.defOf(c);
+            if (def === undefined)
+                continue;
+            const fields = [];
+            for (const f of def.fields)
+                if (f.ctor !== null)
+                    fields.push(f);
+            components.push({ componentId: c, columns: set.columns, fields });
+        }
+        return {
+            id: arch.id,
+            signature: arch.signature,
+            count: arch.count,
+            rows: arch.rows,
+            components,
+        };
+    };
+    const serialize = {
+        schemaHash: computeSchemaHash,
+        components() {
+            const out = [];
+            for (const def of userComponents) {
+                const id = registry.idOf(def);
+                if (id === undefined)
+                    continue;
+                const rt = def;
+                out.push({ name: def.name, id, fieldCount: def.fields.length, storage: rt.options.storage });
+            }
+            return out;
+        },
+        fieldsOf(id) {
+            return registry.defOf(id)?.fields;
+        },
+        componentIdByName(name) {
+            return componentIdByName.get(name);
+        },
+        numComponentTypes() {
+            return registry.nextComponentId;
+        },
+        archetypes() {
+            const out = [];
+            for (const arch of storage.archetypes.byId) {
+                if (arch.cold || arch.count === 0)
+                    continue;
+                out.push(archetypeView(arch));
+            }
+            // id-ascending (byId is already in id order, but tag/cold gaps are filtered above).
+            out.sort((a, b) => a.id - b.id);
+            return out;
+        },
+        relations() {
+            return serializationProvider ?? undefined;
+        },
+        richFields() {
+            return richFieldList;
+        },
+        richValueOf(handle, componentId, fieldIndex) {
+            if (!entities.isAlive(handle))
+                return undefined;
+            const index = handleIndexOf(handle);
+            const key = sidecarKey(componentId, fieldIndex);
+            if (!sidecar.hasColumn(key))
+                return undefined;
+            const gen = entities.decodeHandle(entities.handleOfIndex(index)).generation;
+            return sidecar.read(key, index, gen);
+        },
+        richIsPresent(handle, componentId, fieldIndex) {
+            if (!entities.isAlive(handle))
+                return false;
+            const index = handleIndexOf(handle);
+            const key = sidecarKey(componentId, fieldIndex);
+            if (!sidecar.hasColumn(key))
+                return false;
+            const gen = entities.decodeHandle(entities.handleOfIndex(index)).generation;
+            return sidecar.isPresent(key, index, gen);
+        },
+        setRichValue(handle, componentId, fieldIndex, value) {
+            if (!entities.isAlive(handle))
+                return;
+            const index = handleIndexOf(handle);
+            const key = sidecarKey(componentId, fieldIndex);
+            if (!sidecar.hasColumn(key))
+                return;
+            const gen = entities.decodeHandle(entities.handleOfIndex(index)).generation;
+            sidecar.write(key, index, gen, value);
+            // Mark the loaded value changed identically to a live write so a delta from THIS receiver re-emits
+            // it (parity with the column path, which writes through tracked accessor setters). Whole-entity
+            // changeVersion stamp; fieldIndex forwarded but discarded downstream as for numeric fields.
+            trackWrite(index, componentId, fieldIndex);
+        },
+        enableStructuralJournal() {
+            ;
+            reactivity.enableStructuralJournal();
+        },
+        drainStructuralSince(since) {
+            return reactivity.drainStructuralSince(since);
+        },
+        relationIdOfPair(pairId) {
+            return serializationProvider?.relationIdOfPair(pairId);
+        },
+        spawn() {
+            return entities.spawn();
+        },
+        spawnInto(handle, componentIds) {
+            if (componentIds.length === 0)
+                return;
+            const defs = [];
+            for (const c of componentIds) {
+                const def = registry.defOf(c);
+                if (def !== undefined)
+                    defs.push(def);
+            }
+            storage.addMany(handle, defs);
+        },
+        removeComponents(handle, componentIds) {
+            if (componentIds.length === 0 || !entities.isAlive(handle))
+                return;
+            const defs = [];
+            for (const c of componentIds) {
+                const def = registry.defOf(c);
+                if (def !== undefined)
+                    defs.push(def);
+            }
+            if (defs.length > 0)
+                storage.removeMany(handle, defs);
+        },
+        despawn(handle) {
+            if (entities.isAlive(handle))
+                entities.despawn(handle);
+        },
+        columnsOf(handle, componentId) {
+            if (!entities.isAlive(handle))
+                return null;
+            const index = handleIndexOf(handle);
+            const archId = records.archetypeIdOf(index);
+            const arch = storage.archetypes.byId[archId];
+            if (arch === undefined || arch.cold)
+                return null;
+            const set = arch.columnSets.get(componentId);
+            if (set === undefined)
+                return null;
+            const def = registry.defOf(componentId);
+            if (def === undefined)
+                return null;
+            const fields = [];
+            for (const f of def.fields)
+                if (f.ctor !== null)
+                    fields.push(f);
+            return { columns: set.columns, fields, row: records.rowOf(index) };
+        },
+        clearAll() {
+            // Collect alive handles from every hot archetype first (despawn shuffle-pops rows mid-iteration).
+            const handles = [];
+            for (const arch of storage.archetypes.byId) {
+                if (arch.cold)
+                    continue;
+                for (let r = 0; r < arch.count; r++)
+                    handles.push(arch.rows[r]);
+            }
+            for (const h of handles)
+                if (entities.isAlive(h))
+                    entities.despawn(h);
+        },
+        aliveCount() {
+            return entities.handleStats().aliveCount;
+        },
+        indexBits: handleLayout.indexBits,
+        handleIndex: (handle) => handleIndexOf(handle),
+        capabilities: () => capabilities,
+    };
+    // --- introspection surface (@ecsia/devtools) -------------------------
+    // The FULL archetype census (cold + empty, which __serialize.archetypes() filters out) and the live
+    // query enumeration (the QueryEngine's `liveQueries` getter is core-private). Pure reads.
+    const inspect = {
+        archetypes() {
+            const out = [];
+            for (const arch of storage.archetypes.byId) {
+                out.push({
+                    // Copy: arch.signature is the LIVE typed-array backing the archetype; the seam is read-only
+                    // and must never hand out a buffer a consumer could mutate to corrupt storage.
+                    id: arch.id,
+                    signature: Array.from(arch.signature),
+                    count: arch.count,
+                    cold: arch.cold,
+                });
+            }
+            out.sort((a, b) => a.id - b.id);
+            return out;
+        },
+        queries() {
+            const out = [];
+            for (const lq of engine.liveQueries) {
+                out.push({ terms: lq.terms, matchedArchetypes: lq.matchingArchetypes.length, size: lq.count });
+            }
+            return out;
+        },
+    };
+    const world = {
+        get options() {
+            return resolved;
+        },
+        get phase() {
+            return state.phase;
+        },
+        __setPhase(phase) {
+            state.phase = phase;
+        },
+        __spawnReserved(handle) {
+            storage.onSpawn(handle);
+        },
+        __apply: {
+            defOf(id) {
+                return registry.defOf(id);
+            },
+            addMany(handle, defs) {
+                storage.addMany(handle, defs);
+            },
+            removeMany(handle, defs) {
+                storage.removeMany(handle, defs);
+            },
+            writePayload(handle, def, values) {
+                const view = entities.entity(handle).write(def);
+                for (const k of Object.keys(values))
+                    view[k] = values[k];
+            },
+            addPair(subject, relationId, target, payload) {
+                applyAddPair?.(subject, relationId, target, payload);
+            },
+            removePair(subject, relationId, target) {
+                applyRemovePair?.(subject, relationId, target);
+            },
+        },
+        __installRelations() {
+            return {
+                allocSyntheticId: () => registry.allocSyntheticId(),
+                registerSynthetic: (def, id) => registry.registerSynthetic(def, id),
+                defOf: (id) => registry.defOf(id),
+                migrateAddingMany: (handle, defs) => storage.addMany(handle, defs),
+                migrateRemovingMany: (handle, defs) => storage.removeMany(handle, defs),
+                bitmaskHas: (index, id) => bitmask.bitmaskHas(index, id),
+                columnSetFor: (handle, def) => {
+                    if (!entities.isAlive(handle))
+                        return null;
+                    const index = handleIndexOf(handle);
+                    const archId = records.archetypeIdOf(index);
+                    const arch = storage.archetypes.byId[archId];
+                    if (arch === undefined || arch.cold)
+                        return null;
+                    const set = arch.columnSets.get(registry.idOf(def));
+                    if (set === undefined)
+                        return null;
+                    return { set, row: records.rowOf(index) };
+                },
+                isAlive: (handle) => entities.isAlive(handle),
+                handleIndex: (handle) => handleIndexOf(handle),
+                handleOfIndex: (index) => entities.handleOfIndex(index),
+                despawn: (handle) => entities.despawn(handle),
+                deferRelationOp: (op, subject, relation, target, payload) => {
+                    if (!observerCommands.deferring)
+                        return false;
+                    const relationId = relation.id;
+                    if (op === 'add')
+                        observerCommands.stageAddPair(subject, relation, relationId, target, payload);
+                    else
+                        observerCommands.stageRemovePair(subject, relation, relationId, target);
+                    return true;
+                },
+                trackWrite: (index, componentId) => trackWrite(index, componentId),
+                trackShapePair: (index, pairId, targetIndex, add) => {
+                    ;
+                    reactivity.trackShapePair(index, pairId, targetIndex, add ? ShapeKind.AddPair : ShapeKind.RemovePair);
+                },
+                trackShapeSetPayload: (index, pairId, targetIndex) => {
+                    ;
+                    reactivity.trackShapeSetPayload(index, pairId, targetIndex);
+                },
+                buffers,
+                accessorWorld,
+                setPreDespawn: (hook) => {
+                    preDespawnHook = hook;
+                },
+                setPairResolver: (resolve) => {
+                    pairResolver = resolve;
+                },
+                setApplyPair: (addPair, removePair) => {
+                    applyAddPair = addPair;
+                    applyRemovePair = removePair;
+                },
+                setSerializationProvider: (provider) => {
+                    serializationProvider = provider;
+                },
+                maxEntities: resolved.maxEntities,
+                indexBits: handleLayout.indexBits,
+            };
+        },
+        __exportShared() {
+            const base = buffers.exportSharedHandles();
+            // The entity-record regions are owned by EntityStore (allocU32), not the Buffers registry, so
+            // merge them into the manifest here — a worker needs them to resolve (archetypeId, row).
+            const rec = entities.sharedRecordRegions();
+            const extra = [];
+            if (isSharedBacking(rec.archetypeId)) {
+                extra.push({ key: 'entity.archetypeId', backing: rec.archetypeId, element: 'u32' });
+            }
+            if (isSharedBacking(rec.archetypeRow)) {
+                extra.push({ key: 'entity.archetypeRow', backing: rec.archetypeRow, element: 'u32' });
+            }
+            return { columns: base.columns, regions: [...base.regions, ...extra] };
+        },
+        __columnGrowth() {
+            return buffers.columnGrowth();
+        },
+        __serialize: serialize,
+        __inspect: inspect,
+        __mergeWorkerWrites(pairs, count) {
+            ;
+            reactivity.mergeWorkerWrites(pairs, count);
+        },
+        get tick() {
+            return state.tick;
+        },
+        currentTick() {
+            return state.tick;
+        },
+        spawn() {
+            if (observerCommands.deferring) {
+                // A spawn inside an observer reserves a live handle NOW (so the handler can configure it)
+                // but defers archetype placement to the next flush — the command-buffer reserved-spawn model.
+                const handle = reserveEntityBlock(entities.index, -1, 1).handles[0];
+                observerCommands.stageSpawnWith(handle, []);
+                return handle;
+            }
+            return entities.spawn();
+        },
+        spawnWith(...specs) {
+            // Split each arg into its def (for the single EMPTY→target migration) and any `[def, values]`
+            // initializer (Item 8). Values are written AFTER placement through the tracked accessor path so
+            // onChange/write-log fire exactly as a post-spawn write would.
+            const defs = [];
+            const values = [];
+            for (const spec of specs) {
+                if (Array.isArray(spec)) {
+                    const [def, vals] = spec;
+                    defs.push(def);
+                    values.push([def, vals]);
+                }
+                else {
+                    defs.push(spec);
+                }
+            }
+            if (observerCommands.deferring) {
+                const handle = reserveEntityBlock(entities.index, -1, 1).handles[0];
+                observerCommands.stageSpawnWith(handle, defs, values);
+                return handle;
+            }
+            const handle = entities.spawn();
+            storage.spawnWith(handle, defs);
+            for (const [def, vals] of values) {
+                const view = entities.entity(handle).write(def);
+                for (const k of Object.keys(vals))
+                    view[k] = vals[k];
+            }
+            return handle;
+        },
+        add(handle, def) {
+            if (observerCommands.deferring) {
+                observerCommands.stageAdd(handle, def);
+                return;
+            }
+            storage.add(handle, def);
+        },
+        remove(handle, def) {
+            if (observerCommands.deferring) {
+                observerCommands.stageRemove(handle, def);
+                return;
+            }
+            storage.remove(handle, def);
+        },
+        warm(...defs) {
+            storage.warm(defs);
+        },
+        despawn(handle) {
+            if (observerCommands.deferring) {
+                observerCommands.stageDespawn(handle);
+                return;
+            }
+            entities.despawn(handle);
+        },
+        isAlive(handle) {
+            return entities.isAlive(handle);
+        },
+        has(handle, def) {
+            // Liveness first, WITHOUT the bitmask; a dead handle is never a member.
+            if (!entities.isAlive(handle))
+                return false;
+            return storage.has(handle, def);
+        },
+        entity(handle, opts) {
+            return entities.entity(handle, opts);
+        },
+        reserveEntityBlock(workerIndex, count) {
+            return reserveEntityBlock(entities.index, workerIndex, count);
+        },
+        returnReservedIds(reservation, consumedCount) {
+            returnReservedIds(entities.index, reservation, consumedCount);
+        },
+        handleLayout,
+        encodeHandle(index, generation) {
+            return entities.encodeHandle(index, generation);
+        },
+        decodeHandle(handle) {
+            return entities.decodeHandle(handle);
+        },
+        handleStats() {
+            return entities.handleStats();
+        },
+        trackWrite(index, componentId, fieldIndex) {
+            trackWrite(index, componentId, fieldIndex);
+        },
+        observe(term, handler) {
+            return reactivity.observe(term, handler);
+        },
+        changedSince(handle, since) {
+            ;
+            reactivity.enableChangeVersion();
+            return reactivity.changedSince(handle, since);
+        },
+        changedRows(archetypeId, since) {
+            const arch = storage.archetypes.byId[archetypeId];
+            const count = arch === undefined ? 0 : arch.count;
+            const rows = arch?.rows;
+            return reactivity.changedRows(archetypeId, since, count, (row) => rows === undefined ? 0 : handleIndexOf(rows[row]));
+        },
+        advanceTick() {
+            state.tick = (state.tick + 1) >>> 0;
+        },
+        mergeCorrals() {
+            ;
+            reactivity.mergeCorrals();
+        },
+        maintainStructural() {
+            ;
+            reactivity.maintainStructural();
+        },
+        observerDrain() {
+            // re-entrancy guard: a drain must never re-enter itself (the flush below can trigger query
+            // maintenance / structural ops that must not recursively re-drain). If already draining, return.
+            if (!observerCommands.enterDrain())
+                return;
+            try {
+                // "applied at the NEXT serial flush": apply the ops staged by the PREVIOUS drain's
+                // observers before reading this drain's frozen log snapshot. For 'frame-end' cadence this is the
+                // next frame; for 'per-system' it is the next wave's slot. Applying here (not synchronously
+                // mid-handler) is what makes a spawned entity observable by onAdd NEXT drain, deterministically.
+                observerCommands.flush(observerApply);
+                // Structural ops the handlers issue during THIS drain stage to the buffer instead of mutating
+                // the world mid-drain (so no observer ever sees a partially-applied wave).
+                observerCommands.beginDeferring();
+                try {
+                    ;
+                    reactivity.observerDrain();
+                }
+                finally {
+                    observerCommands.endDeferring();
+                }
+            }
+            finally {
+                observerCommands.exitDrain();
+                // Flush the deferred rich-field clears now that onRemove handlers have run
+                // — the same post-observer point storage's deferred row reclaim ceases to be readable. After this
+                // the dying entity's rich values are gone (RF-REMOVE-READ window closes); a recycled index reads
+                // the default via the generation guard regardless.
+                sidecar.flushPending();
+            }
+        },
+        flushLogs() {
+            ;
+            reactivity.flushLogs();
+        },
+        query: ((...terms) => {
+            // The LiveQuery structurally satisfies Query<T> (terms, each, [Symbol.iterator], flavors,
+            // count); the WorldQuery overload family supplies the element typing per the actual terms.
+            return engine.query(terms);
+        }),
+        frameReset() {
+            // Reactivity.frameReset advances the world tick + recycles the rings; then the query
+            // engine clears its per-frame added/removed delta lists.
+            ;
+            reactivity.frameReset();
+            engine.frameReset();
+        },
+    };
+    return Object.freeze(world);
+}
+/** Collect the union of every live query's current matching indices. */
+function collectCurrentMembers(engine) {
+    const seen = new Set();
+    for (const lq of engine.liveQueries) {
+        for (const index of lq.current)
+            seen.add(index);
+    }
+    return seen;
+}
+//# sourceMappingURL=world.js.map