Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

88.0 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file    world.ts
 * @brief   ECS World with C++ Registry integration
 */

import { WasmModuleAborted } from '../wasm/moduleHealth';
import { Entity, entityGeneration, entityIndex, makeEntity, INVALID_ENTITY } from '../types';
import { AnyComponentDef, ComponentDef, ComponentData, BuiltinComponentDef, isBuiltinComponent, mergeIntoDefaults, builtinComponentRegistry, extraBuiltinComponentRegistry, getUserComponents, getComponent, Disabled, Name, Parent, Children, type ParentData, type ChildrenData } from './component';
import type { CppRegistry, ESEngineModule } from '../wasm';
import { handleWasmError } from '../wasm/wasmError';
import { BuiltinBridge, builtinFromWasm, numberListFieldsOf, convertForWasm, type BridgeConnectOptions,
         type BuiltinMethods, type CompositionDelta } from './bridge/BuiltinBridge';
import { ScriptStorage } from './ScriptStorage';
import type { PoolMemory, ScriptPool } from './ScriptPool';
import { NameIndex } from './NameIndex';
import { ChangeTracker } from './ChangeTracker';
import { QueryCache, type QueryCacheStats } from './QueryCache';
import { rankByOrder, reorderMapByRank } from './entityOrder';
import { worldEngineApi } from './bridge/engineApi';
import { registerEngineStampFlush } from './engineStamps';
import { withScratch } from '../wasm/wasmScratch';
import { log } from '../util/logger';
import { hasOwn } from '../util/ownProperties';
import { getDefaultContext, type EditorBridge } from './context';

/** The slice of a core {@link World.applyEntityOrder} needs: the entry point plus
 *  the heap it marshals the entity list through (wasm memory on the web, the
 *  host's arena on a device — the writes are identical either way). */
interface EntityOrderCore {
    renderer_setEntityDrawOrder?(registry: CppRegistry, entitiesPtr: number, count: number): void;
    _malloc?(bytes: number): number;
    _free?(ptr: number): void;
    HEAPU32?: Uint32Array;
}

function editorBridge(): EditorBridge | null {
    return getDefaultContext().editorBridge;
}

function notifyBridge<K extends keyof EditorBridge>(
    method: K,
    ...args: Parameters<NonNullable<EditorBridge[K]>>
): void {
    const bridge = editorBridge();
    if (!bridge) return;
    const fn = bridge[method] as ((...a: unknown[]) => void) | undefined;
    if (typeof fn !== 'function') return;
    try {
        fn.apply(bridge, args as unknown[]);
    } catch (e) {
        log.warn('world', `EditorBridge.${String(method)} threw`, e);
    }
}

export { PTR_LAYOUTS } from '../wasm/ptrLayouts.generated';
export { BuiltinBridge } from './bridge/BuiltinBridge';
export type { BuiltinMethods } from './bridge/BuiltinBridge';

// =============================================================================
// Numeric Component IDs for Cache Keys
// =============================================================================

let nextCompNumId_ = 1;
const compNumIds_ = new WeakMap<object, number>();

function getCompNumId(comp: AnyComponentDef): number {
    let id = compNumIds_.get(comp);
    if (id === undefined) {
        id = nextCompNumId_++;
        compNumIds_.set(comp, id);
    }
    return id;
}

const _keyIds: number[] = [];

export function computeQueryCacheKey(
    components: AnyComponentDef[],
    withFilters: AnyComponentDef[] = [],
    withoutFilters: AnyComponentDef[] = [],
    filterKey?: string,
): string {
    _keyIds.length = 0;
    for (const c of components) _keyIds.push(getCompNumId(c));
    _keyIds.sort((a, b) => a - b);
    let key = _keyIds.join(',');
    if (withFilters.length > 0) {
        _keyIds.length = 0;
        for (const c of withFilters) _keyIds.push(getCompNumId(c));
        _keyIds.sort((a, b) => a - b);
        key += '|+' + _keyIds.join(',');
    }
    if (withoutFilters.length > 0) {
        _keyIds.length = 0;
        for (const c of withoutFilters) _keyIds.push(getCompNumId(c));
        _keyIds.sort((a, b) => a - b);
        key += '|-' + _keyIds.join(',');
    }
    if (filterKey) {
        key += '|F=' + filterKey;
    }
    return key;
}

/**
 * Predicate-based filter applied after the positive/negative component
 * checks. Callers (typically `QueryInstance`) compile an expression tree
 * into a `match` closure plus a list of components the tree reads so the
 * query cache can invalidate on structural changes to any of them.
 */
export interface QueryFilter {
    readonly match: (entity: Entity) => boolean;
    readonly deps: readonly AnyComponentDef[];
}

// =============================================================================
// World
// =============================================================================

/** Components whose value feeds the world-transform composition. Hierarchy is
 *  in here too: a reparent moves a subtree without touching its transforms. */
const COMPOSITION_INPUTS = new Set(['Transform', 'Parent', 'Children']);


/**
 * The cache dependencies of a query, Disabled included: switching one entity off
 * changes what EVERY query answers. Shared because QueryInstance and the AOT
 * plan precompute this set once and would each have to remember.
 */
export function queryDepIds(
    components: readonly AnyComponentDef[],
    withFilters: readonly AnyComponentDef[],
    withoutFilters: readonly AnyComponentDef[],
    filterDeps: readonly AnyComponentDef[] = [],
): symbol[] {
    const ids: symbol[] = [Disabled._id];
    for (const c of components) ids.push(c._id);
    for (const c of withFilters) ids.push(c._id);
    for (const c of withoutFilters) ids.push(c._id);
    for (const c of filterDeps) ids.push(c._id);
    return ids;
}


/** @internal Loads the asset paths an engine-backed component was handed; see World.setAssetFieldResolver. */
export type AssetFieldResolver = (entity: Entity, component: AnyComponentDef, authored: Record<string, unknown>) => void;

/**
 * The entity store, as `GetWorld()` hands it to a system — the escape hatch for
 * work the declared parameters cannot express. Prefer `Query`/`Res`/`Commands`:
 * those declare their access, so the scheduler can see it and the cache can serve
 * them. The frozen surface here is what a game does with entities; what the frame
 * runner, the query cache and the editor's projection need is `@internal`.
 *
 * @public
 */
export class World {
    private readonly builtin_ = new BuiltinBridge();
    private readonly scripts_ = new ScriptStorage();
    private readonly names_ = new NameIndex();
    /** @internal */
    readonly changes_ = new ChangeTracker();
    /** @internal */
    readonly queries_ = new QueryCache();
    /** @see inactiveEntities_ */
    private inactive_: { set: Set<Entity> } | null = null;
    private inactiveVersion_ = -1;
    private coreActivityEpoch_ = -1;
    private readonly coreDisconnect_ = new Set<() => void>();
    private entities_ = new Map<Entity, number>();
    private indexGeneration_ = new Map<number, number>();  // index -> current generation (for isStale detection)
    private iterationDepth_ = 0;
    private queryCostEnabled_ = false;
    private nextEntityIndex_ = 0;  // pure-JS fallback: monotonic index counter
    private nextGeneration_ = 0;
    private spawnCallbacks_: Array<(entity: Entity) => void> = [];
    private despawnCallbacks_: Array<(entity: Entity) => void> = [];
    private assetFieldResolver_: AssetFieldResolver | null = null;
    private despawning_: Set<Entity> | null = null;

    /** @internal */
    get builtin(): BuiltinBridge {
        return this.builtin_;
    }

    /**
     * Bind this world to an engine core. The embedding contract, not the game
     * one: a host instantiates the module and calls this, and everything below
     * reaches the same registry through {@link getCppRegistry}.
     *
     * @internal
     */
    connectCpp(
        cppRegistry: CppRegistry,
        module?: ESEngineModule,
        options?: BridgeConnectOptions,
    ): void {
        if (this.getCppRegistry()) this.notifyCoreDisconnect_();
        this.addressOf_.clear();
        this.builtin_.connect(cppRegistry, module, options);
        for (const e of this.scripts_.getStorageById(Disabled._id)?.keys() ?? []) cppRegistry.setEntityEnabled?.(e, false);
        this.coreActivityEpoch_ = cppRegistry.activityEpoch?.() ?? -1;
        this.queries_.markComponentDirty(Disabled._id);
    }

    /** @internal */
    disconnectCpp(): void {
        // What a script wrote is the engine's to know before the engine goes; and the buffer it is handed over in is its heap's.
        this.flushEngineStamps();
        this.releaseStampBuffer_();
        this.notifyCoreDisconnect_();
        this.addressOf_.clear();
        this.builtin_.disconnect();
        this.coreActivityEpoch_ = -1;
        this.queries_.markComponentDirty(Disabled._id);
    }

    /** @internal Whether an engine core is bound — false in a pure-JS world. */
    get hasCpp(): boolean {
        return this.builtin_.hasCpp;
    }

    /** @internal */
    getCppRegistry(): CppRegistry | null {
        return this.builtin_.getCppRegistry();
    }

    /** @internal Release native leases before the owning core is disconnected. */
    onCoreDisconnect(dispose: () => void): () => void {
        this.coreDisconnect_.add(dispose);
        return () => { this.coreDisconnect_.delete(dispose); };
    }

    private notifyCoreDisconnect_(): void {
        for (const dispose of [...this.coreDisconnect_]) {
            try { dispose(); } catch (error) { log.warn('world', 'Core disconnect callback error', error); }
        }
    }

    /** @internal Refresh membership mirrors after an observed native mutation. */
    refreshBuiltinMembership(entity: Entity, component: AnyComponentDef): void {
        if (!isBuiltinComponent(component) || !this.valid(entity)) return;
        const set = this.builtin_.getEntitySet(component._cppName);
        const present = this.builtin_.getBuiltinMethods(component._cppName).has(entity);
        if (set && set.has(entity) !== present) {
            if (present) set.add(entity); else set.delete(entity);
            this.queries_.markStructuralChange();
        }
        this.queries_.markComponentDirty(component._id);
    }

    /** @internal */
    getWasmModule(): ESEngineModule | null {
        return this.builtin_.getWasmModule();
    }

    // =========================================================================
    // Entity Management
    // =========================================================================

    /**
     * Create an entity with no components. Throws during query iteration —
     * mutating the set a query is walking is what `Commands` exists to defer.
     */
    spawn(name?: string): Entity {
        if (this.speculation_) {
            throw new Error(
                'Cannot spawn entity inside a speculation. ' +
                'Use its Commands, which allocate no identity until the step commits.'
            );
        }
        if (this.isIterating()) {
            throw new Error(
                'Cannot spawn entity during query iteration. ' +
                'Use Commands to defer entity creation until after iteration completes.'
            );
        }
        const entity = this.allocateEntity_();
        this.commitSpawn_(entity, name);
        return entity;
    }

    /**
     * @internal An identity for a spawn {@link Commands} will apply later — what
     * `cmds.spawn(...).id()` answers while a query is running. Allowed mid-iteration
     * because it touches no component storage: a bare id is in no query. The spawn
     * itself (name, components, spawn callbacks) happens at
     * {@link commitReservedSpawn}, when the commands flush.
     */
    reserveEntity(): Entity {
        if (this.speculation_) {
            throw new Error('Cannot reserve an entity inside a speculation.');
        }
        return this.allocateEntity_();
    }

    /** @internal Finish a spawn begun by {@link reserveEntity}. */
    commitReservedSpawn(entity: Entity, name?: string): void {
        this.commitSpawn_(entity, name);
    }

    private allocateEntity_(): Entity {
        let entity: Entity;
        const cppRegistry = this.builtin_.getCppRegistry();

        if (cppRegistry) {
            try {
                entity = cppRegistry.create();
            } catch (e) {
                handleWasmError(e, 'spawn');
                throw e;
            }
        } else {
            // Pure-JS fallback: pack into the same {generation(12) | index(20)}
            // layout as C++ so Entity helpers (entityIndex/entityGeneration)
            // give consistent results whether or not WASM is connected.
            const idx = ++this.nextEntityIndex_;
            const gen = (this.indexGeneration_.get(idx) ?? 0);
            entity = makeEntity(idx, gen);
        }

        let generation = 0;
        const module = this.builtin_.getWasmModule();
        if (module && cppRegistry) {
            try {
                generation = module.registry_getGeneration(cppRegistry, entity);
            } catch { /* fallback to 0 */ }
        } else {
            generation = ++this.nextGeneration_;
        }
        this.entities_.set(entity, generation);
        this.indexGeneration_.set(entityIndex(entity), entityGeneration(entity));
        return entity;
    }

    private commitSpawn_(entity: Entity, name?: string): void {
        this.queries_.markStructuralChange();

        if (name !== undefined) {
            this.insert(entity, Name, { value: name });
        }

        for (const cb of this.spawnCallbacks_) {
            try { cb(entity); } catch (e) { log.warn('world', 'Spawn callback error', e); }
        }

        notifyBridge('onEntitySpawned', entity, name);
    }

    /**
     * Destroy `entity` and its whole subtree — children before parents, so none
     * is left orphaned and still drawing. Already-gone entities are ignored, and
     * as with {@link spawn} this throws during query iteration.
     */
    despawn(entity: Entity): void {
        if (this.speculation_) {
            throw new Error(
                'Cannot despawn entity inside a speculation. ' +
                'Use its Commands, which apply only if the step commits.'
            );
        }
        if (this.isIterating()) {
            throw new Error(
                'Cannot despawn entity during query iteration. ' +
                'Use Commands to defer entity destruction until after iteration completes.'
            );
        }
        if (!this.valid(entity) || this.despawning_?.has(entity)) return;
        const cppRegistry = this.builtin_.getCppRegistry();
        if (cppRegistry?.destructionPending?.(entity)) return;
        this.despawnSubtree_(entity, cppRegistry);
    }

    /** Depth-first teardown of `entity` and its descendants (children before parent). */
    private despawnSubtree_(entity: Entity, cppRegistry: CppRegistry | null): void {
        const reserved = this.despawning_ ??= new Set<Entity>();
        const owned: Entity[] = [], nativeOwned: Entity[] = [], postorder: Entity[] = [];
        const stack: Array<{ entity: Entity; children: Entity[] | null; next: number }> = [
            { entity, children: null, next: 0 },
        ];
        try {
            // Reserve the whole subtree before callbacks run. It cannot escape
            // through reparenting, receive new children, or be torn down twice
            // by a re-entrant callback. Snapshot each child list just once.
            while (stack.length) {
                const frame = stack[stack.length - 1];
                if (frame.children === null) {
                    if (!this.valid(frame.entity) || reserved.has(frame.entity)
                        || cppRegistry?.destructionPending?.(frame.entity)) { stack.pop(); continue; }
                    reserved.add(frame.entity); owned.push(frame.entity);
                    frame.children = this.childEntitiesOf_(frame.entity, true);
                }
                if (frame.next < frame.children.length) {
                    stack.push({ entity: frame.children[frame.next++], children: null, next: 0 });
                } else {
                    postorder.push(frame.entity); stack.pop();
                }
            }
            if (cppRegistry && cppRegistry.hasParent(entity)) {
                try { cppRegistry.setParent(entity, INVALID_ENTITY); }
                catch (e) { handleWasmError(e, `despawn(detach ${entity})`); }
            }
            // Detach before taking native ownership: setParent also rejects
            // reserved entities. The same core guard then protects raw registry
            // calls and native teardown invoked from an SDK callback.
            if (cppRegistry) {
                for (const current of owned) {
                    if (cppRegistry.reserveDestruction(current)) nativeOwned.push(current);
                }
            }
            for (const current of postorder) if (this.valid(current)) this.despawnOne_(current, cppRegistry);
        } finally {
            for (const current of nativeOwned) cppRegistry!.releaseDestruction(current);
            for (const current of owned) reserved.delete(current);
            if (reserved.size === 0) this.despawning_ = null;
        }
    }

    private abortedReported_ = false;

    private despawnOne_(entity: Entity, cppRegistry: CppRegistry | null): void {
        notifyBridge('onEntityDespawned', entity);

        for (const cb of this.despawnCallbacks_) {
            try { cb(entity); } catch (e) {
                // A module that has aborted fails every callback the same way, and one report says so for all of them.
                if (e instanceof WasmModuleAborted) { if (!this.abortedReported_) { this.abortedReported_ = true; log.warn('world', 'Despawn callbacks stopped: the engine module has aborted', e); } continue; }
                log.warn('world', 'Despawn callback error', e);
            }
        }

        this.names_.remove(entity);

        if (cppRegistry) {
            try {
                cppRegistry.destroy(entity);
            } catch (e) {
                handleWasmError(e, `despawn(entity=${entity})`);
            }
        }
        this.entities_.delete(entity);
        this.queries_.markStructuralChange();

        // Dirty exactly the component versions this entity carried so its
        // membership leaves the relevant cached queries — unrelated queries stay
        // valid (the query cache no longer honors the global structural version).
        for (const cppName of this.builtin_.deleteFromEntitySets(entity)) {
            const def = getComponent(cppName);
            if (def) {
                // Record the removal (no-op unless a Removed query tracks it) so
                // Removed(BuiltinComp) fires on despawn, not only on explicit
                // remove() — matching the script-component path below.
                this.changes_.recordRemoved(def, entity);
                this.queries_.markComponentDirty(def._id);
            }
        }
        this.queries_.markComponentDirty(Parent._id);
        this.queries_.markComponentDirty(Children._id);

        const removedIds = this.scripts_.removeEntity(entity);
        for (const id of removedIds) {
            this.changes_.recordRemovedById(id, entity);
            this.queries_.markComponentDirty(id);
        }
    }

    /**
     * Run `callback` whenever an entity is created; the returned function
     * unsubscribes. A throw is logged and swallowed, so one bad listener cannot
     * stop the others or the spawn itself.
     */
    onSpawn(callback: (entity: Entity) => void): () => void {
        this.spawnCallbacks_.push(callback);
        return () => {
            const idx = this.spawnCallbacks_.indexOf(callback);
            if (idx !== -1) this.spawnCallbacks_.splice(idx, 1);
        };
    }

    /**
     * Run `callback` whenever an entity is destroyed, once per entity in a
     * subtree teardown; the returned function unsubscribes. This is the hook a
     * per-entity side table is cleaned up from.
     */
    onDespawn(callback: (entity: Entity) => void): () => void {
        // Copy on subscription changes, so self-unsubscription during a
        // notification cannot skip the next observer. Dispatch allocates nothing.
        this.despawnCallbacks_ = [...this.despawnCallbacks_, callback];
        return () => {
            const idx = this.despawnCallbacks_.indexOf(callback);
            if (idx !== -1) this.despawnCallbacks_ = this.despawnCallbacks_.filter((_, i) => i !== idx);
        };
    }

    /** Whether `entity` currently exists. False for one never spawned and for a
     *  despawned one alike — {@link isStale} tells the two apart. */
    valid(entity: Entity): boolean {
        return this.entities_.has(entity);
    }

    /** @internal True throughout subtree teardown, including queued ancestors. */
    isDestructionPending(entity: Entity): boolean {
        return !!this.despawning_?.has(entity)
            || !!this.builtin_.getCppRegistry()?.destructionPending?.(entity);
    }

    /** Effective activity, including ancestors; unlike valid(), an inactive
     * entity remains available for inspection, cleanup and serialization. */
    isEntityActive(entity: Entity): boolean {
        return this.valid(entity) && !this.inactiveEntities_()?.has(entity);
    }

    /**
     * True if `entity` refers to a slot that has been recycled — its index is
     * currently live, but held by a *different* generation. Useful for
     * diagnostic logs: `valid()` alone can't distinguish "never existed" from
     * "was despawned and its slot reassigned" since both return false.
     */
    isStale(entity: Entity): boolean {
        if (this.entities_.has(entity)) return false;
        const idx = entityIndex(entity);
        const currentGen = this.indexGeneration_.get(idx);
        return currentGen !== undefined && currentGen !== entityGeneration(entity);
    }

    /** How many entities exist. */
    entityCount(): number {
        return this.entities_.size;
    }

    /**
     * @internal Live sizes of every map the world keeps, for the resource census.
     *
     * `indexSlots` never shrinks by design — it is keyed by entity INDEX, which
     * the registry recycles, so it settles at the session's peak. One that keeps
     * climbing means indices are not being reused, which entityCount() cannot show.
     */
    getStorageSizes(): {
        entities: number;
        indexSlots: number;
        spawnCallbacks: number;
        despawnCallbacks: number;
        coreDisconnectCallbacks: number;
        names: ReturnType<NameIndex['sizes']>;
        scripts: ReturnType<ScriptStorage['sizes']>;
        changes: ReturnType<ChangeTracker['sizes']>;
        queryCacheEntries: number;
    } {
        return {
            entities: this.entities_.size,
            indexSlots: this.indexGeneration_.size,
            spawnCallbacks: this.spawnCallbacks_.length,
            despawnCallbacks: this.despawnCallbacks_.length,
            coreDisconnectCallbacks: this.coreDisconnect_.size,
            names: this.names_.sizes(),
            scripts: this.scripts_.sizes(),
            changes: this.changes_.sizes(),
            queryCacheEntries: this.queries_.getStats().size,
        };
    }

    /** @internal Structural version the query cache invalidates against. */
    getWorldVersion(): number {
        this.syncActivityEpoch_();
        return this.queries_.structuralVersion;
    }

    /** @internal Cumulative query-cache counters (hits, misses, invalidation causes). */
    getQueryCacheStats(): QueryCacheStats {
        return this.queries_.getStats();
    }

    /** @internal Reset the query-cache counters. Entries themselves are kept. */
    resetQueryCacheStats(): void {
        this.queries_.resetStats();
    }

    /**
     * @internal Whether queries count what they scan. Per-World rather than a
     * module flag: the editor realm and the play realm are separate Apps in one
     * process, and a shared switch would have each turn the other's accounting on.
     */
    setQueryCostEnabled(enabled: boolean): void {
        this.queryCostEnabled_ = enabled;
    }

    /** @internal */
    get queryCostEnabled(): boolean {
        return this.queryCostEnabled_;
    }

    /** @internal Iteration depth is what makes spawn/despawn refuse mid-query. */
    beginIteration(): void {
        this.iterationDepth_++;
    }

    /** @internal */
    endIteration(): void {
        this.iterationDepth_--;
        if (this.iterationDepth_ < 0) {
            log.warn('world', 'World.endIteration: mismatched begin/end calls');
            this.iterationDepth_ = 0;
        }
    }

    /** @internal Depth is reset rather than unwound when a frame aborts. */
    resetIterationDepth(): void {
        this.iterationDepth_ = 0;
    }

    /**
     * @internal Set the guard aside for a system suspended at an `await`, and
     * give it back when that system resumes.
     *
     * The depth is the WORLD's, and a system parked mid-query would otherwise
     * lend its iteration to whoever runs next: their spawn is refused for an
     * iteration that is not theirs, and their reset frees a query still walking.
     */
    suspendIteration(): number {
        const depth = this.iterationDepth_;
        this.iterationDepth_ = 0;
        return depth;
    }

    /** @internal Pairs with {@link suspendIteration}. */
    resumeIteration(depth: number): void {
        this.iterationDepth_ = depth;
    }

    /** @internal */
    isIterating(): boolean {
        return this.iterationDepth_ > 0;
    }

    /** Every entity, in storage order — which is the order queries walk and,
     *  within a sorting layer, the order the renderer draws. A fresh array. */
    getAllEntities(): Entity[] {
        return Array.from(this.entities_.keys());
    }

    /**
     * Reorder the world's storage so every iteration follows `entities`.
     *
     * Within a sorting layer the renderer draws in the order it walks the ECS —
     * so an entity that iterates later lands on top. That order is storage order,
     * which a scene gets for free by spawning in its authored order and which this
     * re-establishes on a world that is already populated: the picture a reload
     * would give, without respawning anything (entity ids, component values and
     * every subsystem keyed on them survive untouched).
     *
     * Entities left out of `entities` keep their relative order after the listed
     * ones. Both halves of the world move together — the engine's component pools
     * and the JS-side storages the SDK's own queries walk — so an editor's outliner
     * drag and a game's "bring this card to the front" mean one thing.
     *
     * @param entities the desired iteration order (first iterates first, draws first)
     */
    /** @internal */
    applyEntityOrder(entities: readonly Entity[]): void {
        if (entities.length === 0) return;
        if (this.isIterating()) {
            log.warn('world', 'applyEntityOrder ignored during query iteration');
            return;
        }
        const rankOf = rankByOrder(entities);

        // The engine's pools first: it owns the draw path, and its call is the one
        // that can fail (no core, or a core built before this entry point existed).
        this.pushEntityOrderToCore_(entities);

        reorderMapByRank(this.entities_, rankOf);
        this.builtin_.reorderEntitySets(rankOf);
        this.scripts_.reorderStorages(rankOf);
        // Cached query results are entity ARRAYS — their order is now wrong, and no
        // component version moved, so drop them wholesale.
        this.queries_.invalidateAll();
    }

    /** Marshal the order to whichever core is connected (see applyEntityOrder). */
    private pushEntityOrderToCore_(entities: readonly Entity[]): void {
        const cppRegistry = this.builtin_.getCppRegistry();
        if (!cppRegistry) return;
        const core = worldEngineApi(this) as EntityOrderCore | null;
        const push = core?.renderer_setEntityDrawOrder;
        if (!core || !push || !core._malloc || !core._free || !core.HEAPU32) return;
        try {
            withScratch({ _malloc: core._malloc, _free: core._free }, (alloc) => {
                const ptr = alloc(entities.length * 4);
                // HEAPU32 is re-read here (not captured above): emscripten swaps the
                // views out when the heap grows, and _malloc can grow it.
                core.HEAPU32!.set(entities as ArrayLike<number>, ptr >> 2);
                push.call(core, cppRegistry, ptr, entities.length);
            });
        } catch (e) {
            handleWasmError(e, `applyEntityOrder(count=${entities.length})`);
        }
    }

    /** Keep {@link Parent} and {@link Children} consistent when reparenting. */
    setParent(child: Entity, parent: Entity): void {
        this.trySetParent(child, parent);
    }

    /** Reject invalid relationships without changing hierarchy or notifications. */
    trySetParent(child: Entity, parent: Entity): boolean {
        if (parent === (0xFFFFFFFF as Entity)) parent = INVALID_ENTITY;
        if (this.despawning_?.has(child) || this.despawning_?.has(parent)) return false;
        if (!this.valid(child) || (parent !== INVALID_ENTITY && !this.valid(parent))) return false;
        const cppRegistry = this.builtin_.getCppRegistry();
        if (cppRegistry) {
            try {
                const previous = cppRegistry.hasParent(child) ? cppRegistry.getParent(child).entity : INVALID_ENTITY;
                if (previous === parent) {
                    return !cppRegistry.destructionPending?.(child) && !cppRegistry.destructionPending?.(parent);
                }
                // New cores return acceptance. A legacy void host remains
                // compatible; only an explicit rejection prevents bookkeeping.
                if (cppRegistry.setParent(child, parent) === false) return false;
            } catch (e) {
                handleWasmError(e, `setParent(child=${child}, parent=${parent})`);
                return false;
            }
        }
        const linkedParent = parent === INVALID_ENTITY ? null : parent;
        this.trackHierarchyWrite_(child, linkedParent);
        notifyBridge('onParentChanged', child, linkedParent);
        return true;
    }

    /** Detach `entity` from its parent, leaving its own children attached to it. */
    removeParent(entity: Entity): void {
        if (this.despawning_?.has(entity)) return;
        if (!this.valid(entity)) return;
        const cppRegistry = this.builtin_.getCppRegistry();
        if (cppRegistry?.destructionPending?.(entity)) return;
        if (cppRegistry) {
            try {
                cppRegistry.removeParent(entity);
            } catch (e) {
                handleWasmError(e, `removeParent(entity=${entity})`);
            }
        }
        this.trackHierarchyWrite_(entity, null);
        notifyBridge('onParentChanged', entity, null);
    }

    /** `entity`'s children, snapshotted out of the wasm vector that holds them. */
    private childEntitiesOf_(entity: Entity, strict = false): Entity[] {
        const cppRegistry = this.builtin_.getCppRegistry();
        if (!cppRegistry || !cppRegistry.hasChildren(entity)) return [];
        const children: Entity[] = [];
        try {
            // Snapshot then free the wasm VectorEntity (it leaks if left alive).
            const vec = cppRegistry.getChildren(entity).entities;
            try {
                const count = vec.size();
                for (let i = 0; i < count; i++) children.push(vec.get(i) as Entity);
            } finally { vec.delete(); }
        } catch (e) {
            handleWasmError(e, `getChildren(entity=${entity})`);
            // A partial snapshot is unsafe for deletion: it would remove the
            // parent while leaving unread children alive with dangling links.
            if (strict) throw e;
        }
        return children;
    }

    // Parent/Children are one relationship with two halves, and setParent is the
    // only writer that keeps both. Writing either as a component lands here.
    private insertHierarchy_(entity: Entity, component: AnyComponentDef, data?: unknown): unknown {
        if (component._id === Parent._id) {
            const parent = (data as Partial<ParentData> | undefined)?.entity;
            if (parent === undefined || parent === INVALID_ENTITY) {
                this.removeParent(entity);
                return { entity: INVALID_ENTITY };
            }
            this.setParent(entity, parent);
            return this.has(entity, Parent) ? this.get(entity, Parent) : { entity: INVALID_ENTITY };
        }
        const listed = (data as Partial<ChildrenData> | undefined)?.entities ?? [];
        for (const child of listed) this.setParent(child as Entity, entity);
        return { entities: this.builtin_.hasCpp ? this.childEntitiesOf_(entity) : [...listed] };
    }

    private isHierarchyComponent_(component: AnyComponentDef): boolean {
        return component._id === Parent._id || component._id === Children._id;
    }

    // The C++ side owns both halves of the link; these are the JS mirrors that
    // has() and the query cache read, so they move with it or the two disagree.
    private trackHierarchyWrite_(child: Entity, parent: Entity | null): void {
        const parents = this.builtin_.getOrCreateEntitySet(Parent._cppName);
        const children = this.builtin_.getOrCreateEntitySet(Children._cppName);
        // Re-parenting moves the switched-off closure, so every query's answer can
        // change — but ONLY in a world that has something switched off. Charged
        // against the tag rather than the hierarchy, which moves on every despawn.
        if (this.scripts_.getStorageById(Disabled._id)?.size) {
            this.queries_.markComponentDirty(Disabled._id);
        }

        if (parent === null) {
            if (parents.delete(child)) this.changes_.recordRemoved(Parent, child);
        } else {
            if (!parents.has(child)) {
                parents.add(child);
                this.changes_.recordAdded(Parent, child);
            }
            this.recordComponentWrite_(child, Parent);

            if (!children.has(parent)) {
                children.add(parent);
                this.changes_.recordAdded(Children, parent);
            }
            this.recordComponentWrite_(parent, Children);
        }

        this.queries_.markStructuralChange();
        this.queries_.markComponentDirty(Parent._id);
        this.queries_.markComponentDirty(Children._id);
    }

    // =========================================================================
    // Component Management
    // =========================================================================

    /**
     * Add `component` to `entity`, with `data` merged over the component's
     * defaults, and answer the stored value. Adding one that is already there
     * replaces it.
     */
    insert<C extends AnyComponentDef>(entity: Entity, component: C, data?: Partial<ComponentData<C>>): ComponentData<C> {
        this.speculation_?.record(this, entity, component);
        if (this.isHierarchyComponent_(component)) {
            return this.insertHierarchy_(entity, component, data) as ComponentData<C>;
        }
        if (isBuiltinComponent(component)) {
            const refs = this.takeAssetRefs_(component, data as Record<string, unknown> | undefined);
            const merged = this.insertBuiltin_(entity, component, (refs?.clean ?? data) as Partial<ComponentData<C>>) as ComponentData<C>;
            if (refs?.authored) this.resolveAssetRefs_(entity, component, refs.authored);
            return merged;
        }
        return this.insertScript_(entity, component as ComponentDef<any>, data) as ComponentData<C>;
    }

    /**
     * Store a whole component value and stamp the change tick a `Changed` filter
     * reads. Insert-or-replace: an entity that lacks the component gets it.
     */
    set<C extends AnyComponentDef>(entity: Entity, component: C, data: ComponentData<C>): void {
        this.speculation_?.record(this, entity, component);
        if (this.isHierarchyComponent_(component)) {
            this.insertHierarchy_(entity, component, data);
            return;
        }
        if (isBuiltinComponent(component)) {
            const refs = this.takeAssetRefs_(component, data as Record<string, unknown>);
            if (refs) {
                this.set(entity, component, refs.clean as ComponentData<C>);
                if (refs.authored) this.resolveAssetRefs_(entity, component, refs.authored);
                return;
            }
            // `set` is insert-or-replace: adding a builtin the entity LACKS must run
            // the full structural bookkeeping (entity set + query dirty + recordAdded),
            // or the C++ side holds it while queries / has() (entity-set fast path)
            // never see it. Route the new case through insert.
            if (this.builtin_.hasCpp && !this.has(entity, component)) {
                this.insert(entity, component, data as Partial<ComponentData<C>>);
                return;
            }
            if (this.builtin_.hasCpp) {
                try {
                    const defaults = component._default as Record<string, unknown>;
                    const raw = data as Record<string, unknown>;
                    let wasmData = raw;
                    for (const k of Object.keys(raw)) {
                        if (!hasOwn(defaults, k)) {
                            if (wasmData === raw) wasmData = { ...raw };
                            delete wasmData[k];
                        }
                    }
                    // Merged into the defaults one level in, as an add is: a field
                    // that grew an axis (ParticleEmitter.gravity went vec2 -> vec3)
                    // still reads the {x, y} a document wrote before it did, where
                    // embind refused the whole value for its missing `z`.
                    wasmData = mergeIntoDefaults(defaults, wasmData);
                    // Through the bridge's own write, so a replace marshals the
                    // way an add does: a list field crosses as the vector embind
                    // registered, never as the JS array a document holds.
                    this.builtin_.replace(entity, component._cppName,
                                          convertForWasm(wasmData, component.colorKeys),
                                          component.entityFields ?? []);
                } catch (e) {
                    handleWasmError(e, `set(${component._name}, entity=${entity})`);
                }
            }
            this.recordComponentWrite_(entity, component);
            notifyBridge('onComponentChanged', entity, component._name);
            return;
        }
        // Insert-or-replace means the ADD case owes the same bookkeeping insert
        // does, or a warmed query never learns the entity matched. The builtin
        // branch above says so; this one did not.
        const { isNew } = this.scripts_.set(entity, component as ComponentDef<any>, data);
        if (isNew) {
            this.queries_.markComponentDirty(component._id);
            this.queries_.markStructuralChange();
            this.changes_.recordAdded(component, entity);
            notifyBridge('onComponentAdded', entity, component._name);
        }
        this.recordComponentWrite_(entity, component);
        if ((component as ComponentDef<any>)._id === Name._id) {
            this.names_.update(entity, (data as { value: string }).value);
        }
        notifyBridge('onComponentChanged', entity, component._name);
    }

    /**
     * @internal What turns an asset path written into an engine-backed
     * component's handle field (`Sprite.texture = 'assets/hero.png'`,
     * `MeshRenderer.mesh = 'builtin:cube'`) into the handle. Installed by the
     * asset layer on every core; see bindAssetReferenceTracking.
     */
    setAssetFieldResolver(resolver: AssetFieldResolver | null): void {
        this.assetFieldResolver_ = resolver;
    }

    /**
     * An engine-backed component's asset fields hold handles, and the engine
     * cannot store a string there: written straight through, `texture` read
     * back as the path while the engine held 0, and nothing drew. A string in
     * one is a path to load — the same ref a scene file carries — so it leaves
     * the data here (the field takes its default until the load lands) and goes
     * to the resolver. An empty string is no path: it names nothing, so it is the
     * default and nobody is asked to load it (`authored` is null when that is all
     * there was). Sent to the resolver it came back unresolved, was written again
     * as a string, and asked for itself for good.
     */
    private takeAssetRefs_(
        component: AnyComponentDef, data: Record<string, unknown> | undefined,
    ): { clean: Record<string, unknown>; authored: Record<string, unknown> | null } | null {
        const fields = (component as { assetFields?: readonly { field: string }[] }).assetFields;
        if (!data || !fields || fields.length === 0) return null;
        let clean: Record<string, unknown> | null = null;
        let paths = false;
        for (const { field } of fields) {
            const value = data[field];
            if (typeof value !== 'string') continue;
            clean ??= { ...data };
            clean[field] = (component._default as Record<string, unknown>)[field] ?? 0;
            if (value !== '') paths = true;
        }
        if (!clean) return null;
        if (!paths) return { clean, authored: null };
        // The resolver is handed the paths only: an empty one beside a real one is already the default above.
        const authored: Record<string, unknown> = { ...data };
        for (const { field } of fields) if (authored[field] === '') authored[field] = clean[field];
        return { clean, authored };
    }

    private resolveAssetRefs_(entity: Entity, component: AnyComponentDef, authored: Record<string, unknown>): void {
        if (this.assetFieldResolver_) {
            this.assetFieldResolver_(entity, component, authored);
            return;
        }
        log.warn('world', `${component._name} on entity ${entity} was given an asset path, but this world has no asset layer `
            + 'to load it: the field holds no handle. Load it first (await assets.loadTexture(path)) and write the handle.');
    }

    /**
     * Edit a component in place and report the change — the write path for
     * "read it, adjust a field, keep the rest". The draft is BORROWED for the
     * call, and for a script component it IS the stored object, so nothing may
     * keep it. Reporting is unconditional; a false positive costs one look.
     *
     * @throws if `entity` does not carry `component`.
     */
    update<C extends AnyComponentDef>(
        entity: Entity,
        component: C,
        edit: (draft: ComponentData<C>) => void,
    ): void {
        if (!this.has(entity, component)) {
            throw new Error(
                `update(${component._name}, entity=${entity}): the entity does not carry it. `
                + 'Use insert() or set() to add a component.'
            );
        }
        if (isBuiltinComponent(component)) {
            // A projection, so the write-back is what stores it; `set` owns that
            // for every builtin shape, hierarchy included, and records the change.
            const draft = this.builtin_.get(entity, component) as ComponentData<C>;
            try {
                edit(draft);
            } finally {
                this.set(entity, component, draft);
            }
            return;
        }
        const draft = this.scripts_.get(entity, component as ComponentDef<any>) as ComponentData<C>;
        try {
            edit(draft);
        } finally {
            // A throwing `edit` has already written to the live object, so the
            // change is reported before the error escapes.
            this.recordComponentWrite_(entity, component);
            if ((component as ComponentDef<any>)._id === Name._id) {
                this.names_.update(entity, (draft as { value: string }).value);
            }
            notifyBridge('onComponentChanged', entity, component._name);
        }
    }

    /**
     * The component's value, to READ. Writing to the result is deprecated: it
     * stores nothing for an engine-backed component and changes a script one
     * with nothing observing it — use {@link update}, {@link set} or `Mut()`.
     * Asking for a component the entity lacks throws; {@link tryGet} allows it.
     */
    get<C extends AnyComponentDef>(entity: Entity, component: C): ComponentData<C> {
        this.speculation_?.record(this, entity, component);
        if (isBuiltinComponent(component)) {
            return this.builtin_.get(entity, component) as ComponentData<C>;
        }
        return this.scripts_.get(entity, component as ComponentDef<any>) as ComponentData<C>;
    }

    /** Whether `entity` carries `component`. */
    has(entity: Entity, component: AnyComponentDef): boolean {
        if (component._builtin) {
            if (!this.builtin_.hasCpp) return false;
            const cppName = (component as BuiltinComponentDef<any>)._cppName;
            const bset = this.builtin_.getEntitySet(cppName);
            if (bset) return bset.has(entity);
            return this.builtin_.getBuiltinMethods(cppName).has(entity);
        }
        return this.scripts_.has(entity, component as ComponentDef<any>);
    }

    /** {@link get}, answering null instead of throwing when the component is
     *  absent. Reading only, on the same terms — writing to the result is
     *  deprecated; {@link update} is the edit. */
    tryGet<C extends AnyComponentDef>(entity: Entity, component: C): ComponentData<C> | null {
        this.speculation_?.record(this, entity, component);
        if (isBuiltinComponent(component)) {
            if (!this.builtin_.hasCpp) return null;
            const bset = this.builtin_.getEntitySet(component._cppName);
            if (bset && !bset.has(entity)) return null;
            try {
                const methods = this.builtin_.getBuiltinMethods(component._cppName);
                if (!bset && !methods.has(entity)) return null;
                return builtinFromWasm(methods.get(entity), component) as ComponentData<C>;
            } catch (e) {
                handleWasmError(e, `tryGet(${component._name}, entity=${entity})`);
                return null;
            }
        }
        const storage = this.scripts_.getStorageById(component._id as symbol);
        if (!storage) return null;
        const val = storage.get(entity);
        return val !== undefined ? val as ComponentData<C> : null;
    }

    /** Take `component` off `entity`. Throws during query iteration, as
     *  {@link spawn} does. */
    remove(entity: Entity, component: AnyComponentDef): void {
        this.speculation_?.record(this, entity, component);
        if (this.isIterating()) {
            throw new Error(
                'Cannot remove component during query iteration. ' +
                'Use Commands to defer component removal until after iteration completes.'
            );
        }

        if (component._id === Parent._id) {
            this.removeParent(entity);
            return;
        }
        if (component._id === Children._id) {
            for (const child of this.childEntitiesOf_(entity)) this.removeParent(child);
            return;
        }

        if (isBuiltinComponent(component)) {
            this.builtin_.remove(entity, component);
            this.changes_.recordRemoved(component, entity);
            this.queries_.markComponentDirty(component._id);
            this.queries_.markStructuralChange();
            notifyBridge('onComponentRemoved', entity, component._name);
        } else {
            this.removeScript_(entity, component as ComponentDef<any>);
        }
    }

    // =========================================================================
    // Builtin Component Insert (delegates to BuiltinBridge)
    // =========================================================================

    private insertBuiltin_<T>(entity: Entity, component: BuiltinComponentDef<T>, data?: Partial<T>): T {
        const { merged, isNew } = this.builtin_.insert(entity, component, data);
        if (isNew) {
            this.queries_.markComponentDirty(component._id);
            this.queries_.markStructuralChange();
            this.changes_.recordAdded(component, entity);
            notifyBridge('onComponentAdded', entity, component._name);
        }
        this.recordComponentWrite_(entity, component);
        notifyBridge('onComponentChanged', entity, component._name);
        return merged;
    }

    // =========================================================================
    // Script Component Operations (delegates to ScriptStorage)
    // =========================================================================

    private insertScript_<T>(entity: Entity, component: ComponentDef<T>, data?: unknown): T {
        const { value, isNew } = this.scripts_.insert(entity, component, data);
        if (isNew) {
            this.queries_.markComponentDirty(component._id);
            this.queries_.markStructuralChange();
            this.changes_.recordAdded(component, entity);
            notifyBridge('onComponentAdded', entity, component._name);
        }
        this.recordComponentWrite_(entity, component);
        if (component._id === Name._id) {
            this.names_.update(entity, (value as { value: string }).value);
        }
        notifyBridge('onComponentChanged', entity, component._name);
        return value;
    }

    private removeScript_<T>(entity: Entity, component: ComponentDef<T>): void {
        if (component._id === Name._id) {
            this.names_.remove(entity);
        }
        this.scripts_.remove(entity, component);
        if (component._id === Disabled._id) this.builtin_.getCppRegistry()?.setEntityEnabled?.(entity, true);
        this.changes_.recordRemoved(component, entity);
        this.queries_.markComponentDirty(component._id);
        this.queries_.markStructuralChange();
        notifyBridge('onComponentRemoved', entity, component._name);
    }

    // =========================================================================
    // Name Index
    // =========================================================================

    /** The entity with this {@link Name}, or null. Names are not identities —
     *  with two matches, which one comes back is not defined. */
    findEntityByName(name: string): Entity | null {
        return this.names_.findByName(name);
    }

    /** @internal Pre-resolve a component to its direct storage/getter for fast iteration. */
    resolveGetter(component: AnyComponentDef, mode: 'borrowed' | 'retained' = 'borrowed'):
    ((entity: Entity) => unknown) | null {
        if (isBuiltinComponent(component)) {
            if (!this.builtin_.hasCpp) return null;

            if (this.builtin_.getWasmModule()) {
                const ptrGetter = this.builtin_.resolvePtrGetter(component._cppName, mode);
                if (ptrGetter) return ptrGetter;
            }

            const methods = this.builtin_.getBuiltinMethods(component._cppName);
            const plain = component.colorKeys.length === 0 && component.entityFields.length === 0
                && numberListFieldsOf(component._cppName).length === 0;
            if (plain) return (e) => methods.get(e);
            return (e) => builtinFromWasm(methods.get(e), component);
        }
        const storage = this.scripts_.getStorageById(component._id);
        if (!storage) return null;
        return (e) => storage.get(e);
    }

    /** @internal Pre-resolve a component to a direct has-check for fast query matching. */
    resolveHas(component: AnyComponentDef): ((entity: Entity) => boolean) | null {
        if (isBuiltinComponent(component)) {
            if (!this.builtin_.hasCpp) return null;
            const methods = this.builtin_.getBuiltinMethods(component._cppName);
            return (e) => methods.has(e);
        }
        const storage = this.scripts_.getStorageById(component._id);
        if (!storage) return null;
        return (e) => storage.has(e);
    }

    /** @internal Pre-resolve a component to a direct setter for fast Mut write-back. */
    resolveSetter(component: AnyComponentDef): ((entity: Entity, data: unknown) => void) | null {
        if (isBuiltinComponent(component)) {
            if (!this.builtin_.hasCpp) return null;

            if (this.builtin_.getWasmModule()) {
                const ptrSetter = this.builtin_.resolvePtrSetter(component._cppName);
                if (ptrSetter) return ptrSetter;
            }

            const name = component._cppName;
            const { colorKeys, entityFields } = component;
            if (colorKeys.length === 0 && entityFields.length === 0 && numberListFieldsOf(name).length === 0) {
                const methods = this.builtin_.getBuiltinMethods(name);
                return (e, d) => methods.add(e, d);
            }
            // The one marshalled write, as world.set and insert take it: a list field crosses as the vector embind
            // registered, never as the JS array a row holds.
            return (e, d) => this.builtin_.replace(e, name, convertForWasm(d as Record<string, unknown>, colorKeys), entityFields);
        }
        // Through ScriptStorage, not into the map: a pooled component's stored
        // value is a live view onto its row, and replacing it with a plain
        // object would leave the row behind.
        const storage = this.scripts_.getStorageById(component._id);
        if (!storage) return null;
        return (e, d) => { this.scripts_.set(e, component as ComponentDef<any>, d); };
    }

    // =========================================================================
    // Query Support
    // =========================================================================

    /** @internal Per-frame reuse of the query instance pool. */
    resetQueryPool(): void {
        // No-op: query pool removed, results stored directly in cache
    }

    /** The names of every component on `entity` — for inspectors and diagnostics;
     *  a system asks {@link has} about the definitions it knows. */
    getComponentTypes(entity: Entity): string[] {
        return this.componentTypes_(entity);
    }

    /** @internal Inspect a group with one script catalogue index, preserving input order. */
    getComponentTypesBatch(entities: readonly Entity[]): string[][] {
        if (entities.length === 0) return [];
        const scriptNames = new Map<symbol, string>();
        for (const [name, def] of getUserComponents()) {
            // Match the scalar lookup's first registered name for an id.
            if (!scriptNames.has(def._id)) scriptNames.set(def._id, name);
        }
        return entities.map(entity => this.componentTypes_(entity, scriptNames));
    }

    private componentTypes_(entity: Entity, scriptNames?: ReadonlyMap<symbol, string>): string[] {
        const names = this.builtin_.componentNames(entity);
        const types = new Set<string>(names ?? []);
        const methods = this.builtin_.getMethodCache();
        for (const [name, binding] of names === null ? methods : this.builtin_.getExtraMethodCache()) {
            try { if (binding.has(entity)) types.add(name); } catch (e) { log.warn('world', `Component check failed for ${name}`, e); }
        }
        if (this.builtin_.hasCpp) {
            for (const [name, comp] of names === null ? builtinComponentRegistry() : extraBuiltinComponentRegistry()) {
                if (isBuiltinComponent(comp) && !methods.has(name)) {
                    try {
                        const m = this.builtin_.getBuiltinMethods(comp._cppName);
                        if (m.has(entity)) types.add(name);
                    } catch (e) { log.warn('world', `Builtin check failed for ${name}`, e); }
                }
            }
        }
        const ids = this.scripts_.getEntityComponentIds(entity);
        if (ids) {
            const registry = scriptNames ? null : getUserComponents();
            for (const id of ids) {
                if (scriptNames) {
                    const name = scriptNames.get(id);
                    if (name !== undefined) types.add(name);
                    continue;
                }
                for (const [name, def] of registry!) {
                    if (def._id === id) {
                        types.add(name);
                        break;
                    }
                }
            }
        }
        return Array.from(types);
    }


    /**
     * Every entity switched off, ITSELF or by an ancestor.
     *
     * Derived, not tagged down the tree: a scene that wrote the tag on each
     * descendant would lose which of them the author switched off. Recomputed
     * when the tag or the hierarchy moves; free when nothing is switched off.
     */
    private inactiveEntities_(): { has(entity: Entity): boolean } | null {
        const core = this.builtin_.getCppRegistry();
        if (core?.isEntityActive && core.hasInactiveEntities) {
            return core.hasInactiveEntities() ? { has: e => !core.isEntityActive!(e) } : null;
        }
        const storage = this.scripts_.getStorageById(Disabled._id);
        if (!storage || storage.size === 0) return null;
        // One version covers both halves: a re-parent in a world that has anything
        // switched off bumps the tag's version too (see trackHierarchyWrite_).
        const version = this.queries_.componentVersion(Disabled._id);
        if (this.inactive_ && this.inactiveVersion_ === version) return this.inactive_.set;

        const set = new Set<Entity>();
        const walk = (entity: Entity): void => {
            if (set.has(entity)) return;
            set.add(entity);
            if (!this.has(entity, Children)) return;
            for (const child of (this.get(entity, Children) as ChildrenData).entities) {
                walk(child as Entity);
            }
        };
        for (const entity of storage.keys()) walk(entity as Entity);
        this.inactive_ = { set };
        this.inactiveVersion_ = version;
        return set;
    }

    private resolveStorages_(
        comps: AnyComponentDef[],
        scriptOut: Map<Entity, unknown>[],
        builtinOut: BuiltinMethods[],
    ): boolean {
        for (const comp of comps) {
            if (isBuiltinComponent(comp)) {
                if (!this.builtin_.hasCpp) return false;
                builtinOut.push(this.builtin_.getBuiltinMethods(comp._cppName));
            } else {
                const storage = this.scripts_.getStorageById(comp._id);
                if (!storage) return false;
                scriptOut.push(storage);
            }
        }
        return true;
    }

    private collectComponentIds_(
        components: AnyComponentDef[],
        withFilters: AnyComponentDef[],
        withoutFilters: AnyComponentDef[],
    ): symbol[] {
        return queryDepIds(components, withFilters, withoutFilters);
    }

    /**
     * Entities carrying every component in `components`, narrowed by `with` and
     * `without`. Answered from the query cache, so calling it every frame is the
     * intended use; the array is the cache's own and must not be mutated.
     *
     * @public
     */
    getEntitiesWithComponents(
        components: AnyComponentDef[],
        withFilters: AnyComponentDef[] = [],
        withoutFilters: AnyComponentDef[] = [],
    ): readonly Entity[] {
        return this.queryEntities(components, withFilters, withoutFilters);
    }

    /**
     * @internal The same walk, with the cache key, dependency ids and predicate
     * filter supplied by the caller. `QueryInstance` computes those once per
     * query so a cache hit allocates nothing — which is why they are not
     * parameters of the frozen door above: they are the cache's shape, and
     * freezing them would freeze it.
     */
    queryEntities(
        components: AnyComponentDef[],
        withFilters: AnyComponentDef[] = [],
        withoutFilters: AnyComponentDef[] = [],
        precomputedKey?: string,
        filter?: QueryFilter,
        precomputedDepIds?: symbol[],
    ): readonly Entity[] {
        this.syncActivityEpoch_();
        const cacheKey = precomputedKey ?? computeQueryCacheKey(components, withFilters, withoutFilters);
        // The dep-id set is static per query; QueryInstance precomputes it (incl.
        // filter deps) so cache-hit iteration allocates nothing here.
        let depIds: symbol[];
        if (precomputedDepIds) {
            depIds = precomputedDepIds;
        } else {
            depIds = this.collectComponentIds_(components, withFilters, withoutFilters);
            if (filter) {
                for (const c of filter.deps) depIds.push(c._id);
            }
        }

        // `Disabled`'s whole contract is that the systems skip it, answered once
        // here rather than remembered at 78 call sites. A query that NAMES the
        // tag is the exception: managing the switch means seeing it.
        const namesDisabled = components.includes(Disabled)
            || withFilters.includes(Disabled) || withoutFilters.includes(Disabled);

        return this.queries_.getOrCompute(cacheKey, depIds, () => {
            const entities: Entity[] = [];
            const off = namesDisabled ? null : this.inactiveEntities_();

            const reqScript: Map<Entity, unknown>[] = [];
            const reqBuiltin: BuiltinMethods[] = [];
            if (!this.resolveStorages_(components, reqScript, reqBuiltin)) {
                return [];
            }

            let withScript: Map<Entity, unknown>[] | null = null;
            let withBuiltin: BuiltinMethods[] | null = null;
            if (withFilters.length > 0) {
                withScript = [];
                withBuiltin = [];
                if (!this.resolveStorages_(withFilters, withScript, withBuiltin)) {
                    return [];
                }
            }

            let woScript: Map<Entity, unknown>[] | null = null;
            let woBuiltin: BuiltinMethods[] | null = null;
            if (withoutFilters.length > 0) {
                woScript = [];
                woBuiltin = [];
                this.resolveStorages_(withoutFilters, woScript, woBuiltin);
            }

            let smallestSet: { keys(): IterableIterator<Entity>; size: number } | null = null;
            let smallestSize = Infinity;
            for (let i = 0; i < reqScript.length; i++) {
                const size = reqScript[i].size;
                if (size < smallestSize) {
                    smallestSize = size;
                    smallestSet = reqScript[i];
                }
            }
            for (const comp of components) {
                if (isBuiltinComponent(comp)) {
                    const bset = this.builtin_.getEntitySet(comp._cppName);
                    if (bset && bset.size < smallestSize) {
                        smallestSize = bset.size;
                        smallestSet = bset;
                    }
                }
            }

            const candidates = smallestSet ? smallestSet.keys() : this.entities_.keys();
            const rsLen = reqScript.length;
            const rbLen = reqBuiltin.length;

            for (const entity of candidates) {
                if (off?.has(entity)) continue;
                let match = true;
                for (let i = 0; i < rsLen; i++) {
                    if (!reqScript[i].has(entity)) { match = false; break; }
                }
                if (match) {
                    for (let i = 0; i < rbLen; i++) {
                        if (!reqBuiltin[i].has(entity)) { match = false; break; }
                    }
                }
                if (match && withScript) {
                    for (let i = 0; i < withScript.length; i++) {
                        if (!withScript[i].has(entity)) { match = false; break; }
                    }
                    if (match) {
                        for (let i = 0; i < withBuiltin!.length; i++) {
                            if (!withBuiltin![i].has(entity)) { match = false; break; }
                        }
                    }
                }
                if (match && woScript) {
                    for (let i = 0; i < woScript.length; i++) {
                        if (woScript[i].has(entity)) { match = false; break; }
                    }
                    if (match) {
                        for (let i = 0; i < woBuiltin!.length; i++) {
                            if (woBuiltin![i].has(entity)) { match = false; break; }
                        }
                    }
                }
                if (match && filter && !filter.match(entity)) {
                    match = false;
                }
                if (match) {
                    entities.push(entity);
                }
            }

            return entities;
        });
    }

    // =========================================================================
    // Change Detection (delegates to ChangeTracker)
    // =========================================================================

    /** @internal The frame runner's clock for change detection. */
    advanceTick(): void {
        this.changes_.advanceTick();
        this.flushEngineStamps();
        // Once a frame, while the audit is on: the engine compares its components with the copy it kept and counts each one
        // whose bytes changed without a change stamp (Registry::auditChanges).
        if (this.changeAudit_) this.builtin_.getCppRegistry()?.auditChanges?.();
    }

    private changeAudit_ = false;
    /** Engine type id by component, -1 where the engine has none; dropped when the engine's registry is replaced. */
    private readonly engineTypeIds_ = new Map<AnyComponentDef, number>();
    private engineTypeIdsFor_: unknown = null;

    /** The engine-heap block stamps are handed over in, its room in pairs, and whose heap it is in. */
    private stampBuffer_ = 0;
    private stampBufferPairs_ = 0;
    private stampBufferApi_: ReturnType<typeof worldEngineApi> = null;

    private releaseStampBuffer_(): void {
        if (this.stampBuffer_ !== 0) this.stampBufferApi_?._free?.(this.stampBuffer_);
        this.stampBuffer_ = 0;
        this.stampBufferPairs_ = 0;
        this.stampBufferApi_ = null;
    }

    /** (engine type id, entity) pairs waiting to be stamped in the engine; see flushEngineStamps. */
    private stampPairs_ = new Uint32Array(2 * 256);
    private stampCount_ = 0;
    private static readonly STAMP_BATCH = 8192;

    /**
     * @internal Stamps an engine component as written, in the engine, without telling this world's Changed() queries: what a
     * write path deliberately outside them (physics moving bodies) still owes the engine's own readers of changes. Every write
     * through set/insert/update/markChanged comes here too. Batched, and handed over by flushEngineStamps.
     */
    stampEngineWrite(entity: Entity, component: AnyComponentDef): void {
        if (!isBuiltinComponent(component)) return;
        const registry = this.builtin_.getCppRegistry();
        if (!registry?.componentTypeId) return;
        if (this.engineTypeIdsFor_ !== registry) {
            this.flushEngineStamps();
            this.engineTypeIds_.clear();
            this.engineTypeIdsFor_ = registry;
            registerEngineStampFlush(registry, () => this.flushEngineStamps());
        }
        let id = this.engineTypeIds_.get(component);
        if (id === undefined) {
            id = registry.componentTypeId(component._cppName);
            this.engineTypeIds_.set(component, id);
        }
        if (id < 0) return;
        if (this.stampCount_ * 2 >= this.stampPairs_.length) {
            const grown = new Uint32Array(this.stampPairs_.length * 2);
            grown.set(this.stampPairs_);
            this.stampPairs_ = grown;
        }
        this.stampPairs_[this.stampCount_ * 2] = id;
        this.stampPairs_[this.stampCount_ * 2 + 1] = entity as number;
        if (++this.stampCount_ >= World.STAMP_BATCH) this.flushEngineStamps();
    }

    /**
     * @internal Hands the batched stamps to the engine: one call where it takes a list (registry_markComponentsChanged), one each
     * where it does not. The render pipeline calls it before the frame's transforms are composed, and the frame's tick before the
     * audit; anything else in the engine that reads changes has to come after one of the two.
     */
    flushEngineStamps(): void {
        const count = this.stampCount_;
        if (count === 0) return;
        this.stampCount_ = 0;
        const registry = this.builtin_.getCppRegistry();
        if (!registry || registry !== this.engineTypeIdsFor_) return;
        const api = worldEngineApi(this);
        if (api?.registry_markComponentsChanged && api._malloc && api._free && api.HEAPU32) {
            // One block in the engine's heap, kept and grown: a hand-over a frame allocates nothing.
            if (this.stampBuffer_ === 0 || this.stampBufferPairs_ < count || this.stampBufferApi_ !== api) {
                this.releaseStampBuffer_();
                this.stampBufferPairs_ = Math.max(count, 1024);
                this.stampBuffer_ = api._malloc(this.stampBufferPairs_ * 8);
                this.stampBufferApi_ = api;
            }
            if (this.stampBuffer_ !== 0) {
                // The view is asked for after the allocation: a heap that grew detached the one from before.
                api.HEAPU32.set(this.stampPairs_.subarray(0, count * 2), this.stampBuffer_ >>> 2);
                api.registry_markComponentsChanged(registry, this.stampBuffer_, count);
                return;
            }
        }
        if (!registry.markComponentChanged) return;
        for (let i = 0; i < count; i++) registry.markComponentChanged(this.stampPairs_[i * 2]!, this.stampPairs_[i * 2 + 1]!);
    }

    /**
     * @internal Turns on the engine's change audit, for tests and gates: every frame from here on, a component written without
     * a change stamp is counted, and its type named in the log the first time. It copies every component once a frame.
     */
    setChangeAudit(enabled: boolean): void {
        const registry = this.builtin_.getCppRegistry();
        registry?.setChangeAudit?.(enabled);
        this.changeAudit_ = enabled && typeof registry?.auditChanges === 'function';
    }

    /** @internal Component writes the audit has found without a change stamp since it was turned on. */
    changeAuditTotal(): number {
        return this.builtin_.getCppRegistry()?.changeAuditTotal?.() ?? 0;
    }

    /** @internal */
    getWorldTick(): number {
        return this.changes_.getWorldTick();
    }

    /** @internal Opted into by a query that declares an Added/Changed filter;
     *  tracking every component would cost every write. */
    enableChangeTracking(component: AnyComponentDef): void {
        this.changes_.enableChangeTracking(component);
    }

    /** @internal Opt a system query into precise change boundaries, separately from tick sampling. */
    enableChangeSequenceTracking(component: AnyComponentDef, added: boolean): void {
        this.changes_.enableChangeSequenceTracking(component, added);
    }

    /** @internal Latest opted-in component mutation sequence. */
    getChangeSequence(): number { return this.changes_.getChangeSequence(); }

    /** @internal Bind a live sequence index once for a system query's entity loop. */
    resolveChangeSequenceMatcher(component: AnyComponentDef, added: boolean): (entity: Entity, after: number) => boolean {
        return this.changes_.resolveChangeSequenceMatcher(component, added);
    }

    /** @internal Live additions after a completed system boundary. */
    isAddedAfterSequence(entity: Entity, component: AnyComponentDef, after: number): boolean {
        return this.changes_.isAddedAfterSequence(entity, component, after);
    }

    /** @internal Live changes after a completed system boundary. */
    isChangedAfterSequence(entity: Entity, component: AnyComponentDef, after: number): boolean {
        return this.changes_.isChangedAfterSequence(entity, component, after);
    }

    /** @internal O(1) empty-window checks before enumerating system query candidates. */
    anyAddedAfterSequence(component: AnyComponentDef, after: number): boolean {
        return this.changes_.anyAddedAfterSequence(component, after);
    }

    /** @internal O(1) empty-window checks before enumerating system query candidates. */
    anyChangedAfterSequence(component: AnyComponentDef, after: number): boolean {
        return this.changes_.anyChangedAfterSequence(component, after);
    }

    /** @internal Opt in to live component identities, independent of frame ticks. */
    enableIncarnationTracking(component: AnyComponentDef): void {
        this.changes_.enableIncarnationTracking(component);
    }

    /** @internal Changes on remove/reinsert, including multiple edits in one tick.
     * Components present before tracking was enabled share the initial identity 0. */
    getComponentIncarnation(entity: Entity, component: AnyComponentDef): number {
        return this.changes_.getComponentIncarnation(entity, component);
    }

    /** @internal What `Added`/`Changed` filters are implemented in terms of. */
    isAddedSince(entity: Entity, component: AnyComponentDef, sinceTick: number): boolean {
        return this.changes_.isAddedSince(entity, component, sinceTick);
    }

    /** @internal */
    isChangedSince(entity: Entity, component: AnyComponentDef, sinceTick: number): boolean {
        return this.changes_.isChangedSince(entity, component, sinceTick);
    }

    /** @internal True if ANY entity changed `component` after `sinceTick` (O(1) gate). */
    anyChangedSince(component: AnyComponentDef, sinceTick: number): boolean {
        return this.changes_.anyChangedSince(component, sinceTick);
    }

    /** @internal What a `Removed` query reads. */
    getRemovedEntitiesSince(component: AnyComponentDef, sinceTick: number): Entity[] {
        return this.changes_.getRemovedEntitiesSince(component, sinceTick);
    }

    /** @internal A tick-based removal lease for samples after the current tick. */
    registerRemovedReader(component: AnyComponentDef): number {
        return this.changes_.registerRemovedReader(component);
    }

    /** @internal A removal lease starting at the current event sequence. */
    registerRemovedCursorReader(component: AnyComponentDef): number {
        return this.changes_.registerRemovedCursorReader(component);
    }

    /** @internal Latest removal sequence, independent of frame ticks. */
    getRemovalSequence(): number { return this.changes_.getRemovalSequence(); }

    /** @internal Unacknowledged removals belonging to this cursor reader. */
    getRemovedEntitiesForReader(component: AnyComponentDef, readerId: number): Entity[] {
        return this.changes_.getRemovedEntitiesForReader(component, readerId);
    }

    /** @internal Release only events this run observed, preserving later removals. */
    advanceRemovedCursorReader(component: AnyComponentDef, readerId: number, through: number): void {
        this.changes_.advanceRemovedCursorReader(component, readerId, through);
    }

    /** @internal A claim from an explicit tick, for a reader that reads with an
     *  overlap rather than "since I last ran". */
    registerRemovedReaderFrom(component: AnyComponentDef, retainFromTick: number): number {
        return this.changes_.registerRemovedReaderFrom(component, retainFromTick);
    }

    /** @internal That reader is done with everything up to `lastRunTick`. */
    advanceRemovedReader(component: AnyComponentDef, readerId: number, lastRunTick: number): void {
        this.changes_.advanceRemovedReader(component, readerId, lastRunTick);
    }

    /** @internal The reader is gone; its share of the watermark goes with it. */
    disposeRemovedReader(component: AnyComponentDef, readerId: number): void {
        this.changes_.disposeRemovedReader(component, readerId);
    }

    /** @internal How many readers hold `component`'s removal history. */
    removedReaderCount(component: AnyComponentDef): number {
        return this.changes_.removedReaderCount(component);
    }

    /** @internal A claim on `component`'s MEMBERSHIP journal — who gained or
     *  lost it — independent of ordinary change tracking. */
    registerTopologyReaderFrom(component: AnyComponentDef, retainFromTick: number): number {
        return this.changes_.registerTopologyReaderFrom(component, retainFromTick);
    }

    /** @internal A mutation cursor distinguishes writes within one world tick. */
    registerMutationCursor(component: AnyComponentDef, kind: 'write' | 'topology'): number {
        return this.changes_.registerMutationCursor(component, kind);
    }

    /** @internal Current boundary to acknowledge after a successful read. */
    mutationSequence(kind: 'write' | 'topology'): number { return this.changes_.mutationSequence(kind); }

    /** @internal Component stamps survive released mutation-history readers. */
    mutationRevision(component: AnyComponentDef, kind: 'write' | 'topology'): number {
        return this.changes_.mutationRevision(component, kind);
    }

    /** @internal Unacknowledged component mutations for this reader. */
    mutationsForCursor(component: AnyComponentDef, kind: 'write' | 'topology', reader: number): Entity[] {
        return this.changes_.mutationsForCursor(component, kind, reader);
    }

    /** @internal Preserve mutations that arrived after the read's boundary. */
    advanceMutationCursor(component: AnyComponentDef, kind: 'write' | 'topology', reader: number, through: number): void {
        this.changes_.advanceMutationCursor(component, kind, reader, through);
    }

    /** @internal Release this reader's history claim. */
    disposeMutationCursor(component: AnyComponentDef, kind: 'write' | 'topology', reader: number): void {
        this.changes_.disposeMutationCursor(component, kind, reader);
    }

    /** @internal Entities worth re-reading because their membership moved. */
    getTopologyChangedEntitiesSince(component: AnyComponentDef, sinceTick: number): Entity[] {
        return this.changes_.getTopologyChangedEntitiesSince(component, sinceTick);
    }

    /** @internal That reader is done with everything up to `lastRunTick`. */
    advanceTopologyReader(component: AnyComponentDef, readerId: number, lastRunTick: number): void {
        this.changes_.advanceTopologyReader(component, readerId, lastRunTick);
    }

    /** @internal The reader is gone; its share of the watermark goes with it. */
    disposeTopologyReader(component: AnyComponentDef, readerId: number): void {
        this.changes_.disposeTopologyReader(component, readerId);
    }

    /** @internal How many readers hold `component`'s membership journal. */
    topologyReaderCount(component: AnyComponentDef): number {
        return this.changes_.topologyReaderCount(component);
    }

    /** @internal A claim on `component`'s WRITE journal — which entities had it
     *  written, enumerable sparsely, unlike the per-entity changed map. */
    registerWriteReaderFrom(component: AnyComponentDef, retainFromTick: number): number {
        return this.changes_.registerWriteReaderFrom(component, retainFromTick);
    }

    /** @internal Entities whose `component` was written after `sinceTick`. */
    getWrittenEntitiesSince(component: AnyComponentDef, sinceTick: number): Entity[] {
        return this.changes_.getWrittenEntitiesSince(component, sinceTick);
    }

    /** @internal An O(1) upper bound on what `getWrittenEntitiesSince` returns,
     *  for a caller choosing between reading the journal and a scan. */
    bufferedWriteRows(component: AnyComponentDef): number {
        return this.changes_.bufferedWriteRows(component);
    }

    /** @internal That reader is done with everything up to `lastRunTick`. */
    advanceWriteReader(component: AnyComponentDef, readerId: number, lastRunTick: number): void {
        this.changes_.advanceWriteReader(component, readerId, lastRunTick);
    }

    /** @internal The reader is gone; its share of the watermark goes with it. */
    disposeWriteReader(component: AnyComponentDef, readerId: number): void {
        this.changes_.disposeWriteReader(component, readerId);
    }

    /** @internal How many readers hold `component`'s write journal. */
    writeReaderCount(component: AnyComponentDef): number {
        return this.changes_.writeReaderCount(component);
    }

    /**
     * @internal One place for "this component was written".
     *
     * The composition epoch hangs off the LOGICAL mutation contract, not off the
     * storage path: `set`, `insert`, `update` and a `Mut` write-back all arrive
     * here whether or not the fast pointer setter moved the bytes.
     */
    private recordComponentWrite_(entity: Entity, component: AnyComponentDef): void {
        if (component._id === Disabled._id) this.builtin_.getCppRegistry()?.setEntityEnabled?.(entity, false);
        // An engine component's write is stamped where the engine keeps it, beside the component: the engine's own readers
        // (the renderer) ask there what changed, whoever wrote it.
        if (isBuiltinComponent(component)) this.stampEngineWrite(entity, component);
        if (COMPOSITION_INPUTS.has(component._name)) {
            this.builtin_.invalidateTransformComposition();
        }
        this.changes_.recordChanged(component, entity);
    }

    private syncActivityEpoch_(): void {
        const epoch = this.builtin_.getCppRegistry()?.activityEpoch?.();
        if (epoch === undefined || epoch === this.coreActivityEpoch_) return;
        if (this.coreActivityEpoch_ === -1) { this.coreActivityEpoch_ = epoch; return; }
        this.coreActivityEpoch_ = epoch;
        this.queries_.markComponentDirty(Disabled._id);
        this.queries_.markStructuralChange();
    }

    /** @internal Say composed world transforms are stale, for a producer that
     *  wrote the bytes without going through the mutation seam. */
    invalidateTransformComposition(): void {
        this.builtin_.invalidateTransformComposition();
    }

    /** @internal Compose world transforms if a producer invalidated them. */
    ensureTransformsComposed(): void {
        this.builtin_.ensureTransformsComposed();
    }

    /** @internal What the composition staleness counter reads. */
    transformEpoch(): number {
        return this.builtin_.transformEpoch();
    }

    /** @internal Ask composition to record which entities' output changed.
     *  Answers whether this core can report it at all. */
    setTransformChangeTracking(on: boolean): boolean {
        return this.builtin_.setTransformChangeTracking(on);
    }

    /** @internal What every composition since the last acknowledgement changed;
     *  null from a core that cannot say. The ids view engine memory, so a
     *  consumer reads, applies and acknowledges within one turn. */
    compositionChanges(): CompositionDelta | null {
        return this.builtin_.compositionChanges();
    }

    /** @internal Acknowledge that set: it starts again. */
    takeCompositionChanges(): void {
        this.builtin_.takeCompositionChanges();
    }

    /** @internal Mark component as changed without writing data (for in-place Mut query) */
    markChanged(entity: Entity, component: AnyComponentDef): void {
        this.recordComponentWrite_(entity, component);
    }

    /**
     * @internal The open speculation's undo log, or null.
     *
     * The pre-image is taken where the HANDLE leaves, not where the write
     * arrives: script storage hands out the stored object itself, so by `set`
     * the old value is gone (docs/MUTATION_CONTRACT.md). Hence `get`/`tryGet`
     * ask here too, and only a component's first touch is kept.
     */
    private speculation_: { record(world: World, entity: Entity, component: AnyComponentDef): void } | null = null;

    /** @internal */
    openSpeculation(log: { record(world: World, entity: Entity, component: AnyComponentDef): void }): void {
        if (this.speculation_) throw new Error('A speculation is already open on this World — nesting is not supported.');
        this.speculation_ = log;
    }

    /** @internal */
    closeSpeculation(): void {
        this.speculation_ = null;
    }

    /** @internal Whether a step that can be taken back is running. */
    get speculating(): boolean {
        return this.speculation_ !== null;
    }

    /** @internal Whether any query is asking about `component`'s changes. */
    isChangeTracked(component: AnyComponentDef): boolean {
        return this.changes_.isTracked(component);
    }

    /**
     * @internal Where script-component rows are allocated from. A wasm runtime
     * installs linear memory here BEFORE any component is added, because
     * compiled code cannot reach a JS-heap array.
     */
    useScriptPoolMemory(memory: PoolMemory, validateOnly = false): void {
        this.scripts_.usePoolMemory(memory, validateOnly);
    }

    /**
     * @internal `component`'s bytes for `entity`, in the memory compiled code
     * reads: an engine component through the bridge, a script one through its
     * pool. Undefined where there are no flat bytes. The resolver is cached per
     * component — finding it walks a generated table, and this is asked once per
     * entity per frame.
     */
    addressOfComponent(component: AnyComponentDef, entity: Entity): number | undefined {
        return this.addressResolver(component)(entity);
    }

    /**
     * @internal One number for "could any component have moved since you last
     * asked": the engine's pools (`Registry::layoutEpoch`) plus this SDK's own (a
     * claimed, released or grown script row). Null where the engine cannot be
     * asked, which means re-resolve. It says nothing about which entities MATCH;
     * that is the query cache's answer, and a caller needing both asks both.
     */
    layoutEpoch(): number | null {
        const engine = this.builtin_.layoutEpoch();
        if (engine === null && this.builtin_.hasCpp) return null;
        return (engine ?? 0) + this.scripts_.layoutEpoch;
    }

    /**
     * @internal The script pools' half of {@link layoutEpoch}, on its own.
     *
     * A host that reads the engine's half itself needs only this one, and must
     * have it: a row added to or deleted from a script pool moves nothing the
     * registry's version numbers can see.
     */
    scriptLayoutEpoch(): number {
        return this.scripts_.layoutEpoch;
    }

    /**
     * @internal Where a SCRIPT component's whole column is, for a host that
     * walks it in its own address space. Undefined for an engine component,
     * whose column belongs to the registry and is reached by its own door.
     */
    scriptSpanOf(component: AnyComponentDef): {
        rows: number; stride: number; sparse: number; sparseCount: number;
        owners: number; ownerCount: number;
    } | undefined {
        if (isBuiltinComponent(component)) return undefined;
        return this.scripts_.poolFor(component._id as symbol)?.span();
    }

    /** @internal Whether script rows still carry a portable asset reference. */
    hasPortableScriptAssetRefs(component: AnyComponentDef): boolean {
        return this.scripts_.hasPortableAssetRefs(component._id as symbol);
    }

    /** @internal Release script memory after its application stops using it. */
    releaseScriptPools(): void {
        this.addressOf_.clear();
        this.scripts_.releasePools();
    }

    /**
     * @internal The same answer as a function, for a caller with a whole column
     * to walk: the lookup above is per entity, and a loop that pays it per row is
     * paying to be told the same thing every time.
     */
    addressResolver(component: AnyComponentDef): (entity: Entity) => number | undefined {
        let at = this.addressOf_.get(component._id as symbol);
        if (at === undefined) {
            at = isBuiltinComponent(component)
                ? (this.builtin_.resolveComponentAddress(component._cppName) ?? NO_ADDRESS)
                : scriptAddress(this.scripts_, component._id as symbol);
            this.addressOf_.set(component._id as symbol, at);
        }
        return at;
    }

    /** Cleared with the bridge, because a reconnect may serve other memory. */
    private readonly addressOf_ = new Map<symbol, (entity: Entity) => number | undefined>();
}

/** A component whose backend serves no flat memory: never has an address. */
const NO_ADDRESS = (): undefined => undefined;

/**
 * A script component's address, with the pool looked up once rather than per
 * entity. Sound because a pool is never dropped once made, and because the pool
 * re-views itself after a growth — the block moving is its business, not this
 * closure's.
 */
function scriptAddress(scripts: ScriptStorage, id: symbol): (entity: Entity) => number | undefined {
    let pool: ScriptPool | undefined;
    return (entity: Entity) => {
        if (pool?.disposed) pool = undefined;
        pool ??= scripts.poolFor(id);
        return pool?.address(entity);
    };
}