@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/world/gpu.ts

@@ -0,0 +1,393 @@
+import { labelOfItem } from '../../interface/registry/index.js';
+import { layout } from '../../interface/gpu/layout.js';
+import { recordBytes } from '../../interface/gpu/record.js';
+import type { Archetype, Storage } from './archetype.js';
+import { chunkShift } from './kernel.js';
+
+export { recordBytes };
+export const recordWords = recordBytes / 4;
+
+/** Smallest heap block, and the alignment of every block. */
+const minimumBlockBytes = 256;
+const initialHeapBytes = 1 << 20;
+
+/**
+ * The GPU copy of one storage: a block of the heap holding `capacity` rows at the storage's stride. `dirty` rows
+ * changed on the CPU since they were last uploaded, beyond those in chunks a ticked storage stamped after `uploaded`;
+ * `ahead` rows were written on the GPU since they were last read back. Each is a row range, empty when `low >= high`.
+ */
+type Resident = {
+    readonly storage: Storage;
+    readonly archetype: Archetype;
+    readonly stride: number;
+    offset: number;
+    bytes: number;
+    capacity: number;
+    dirtyLow: number;
+    dirtyHigh: number;
+    aheadLow: number;
+    aheadHigh: number;
+    /** The tick of the run that last uploaded it: CPU writes since stamp later ticks. */
+    uploaded: number;
+};
+
+/**
+ * A world's GPU state: a heap buffer holding the GPU copies of the storages GPU systems use, one buffer of 256-byte
+ * records, and the run's command encoder. Nothing here is exposed: render bodies get bind calls, not buffers, so
+ * both buffers can be replaced as they grow.
+ */
+export type GpuEngine = {
+    readonly device: GPUDevice;
+    /** Heap (read-only storage) at binding 0, a table record (uniform, dynamic offset) at binding 1. */
+    readonly renderLayout: GPUBindGroupLayout;
+    /** Heap (read-write storage) at binding 0, a parameter record (read-only storage, dynamic offset) at binding 1. */
+    readonly computeLayout: GPUBindGroupLayout;
+    readonly renderGroup: () => GPUBindGroup;
+    readonly computeGroup: () => GPUBindGroup;
+    /** The run's encoder, created on first use. */
+    readonly encoder: () => GPUCommandEncoder;
+    readonly submit: () => void;
+    /** Drops the run's encoder unsubmitted, after a body failed partway through recording. */
+    readonly discard: () => void;
+    /** The word address of a storage's GPU copy, uploading rows the CPU changed first, for a run at `tick`. */
+    readonly upload: (archetype: Archetype, storage: Storage, tick: number) => number;
+    /**
+     * The word address of a block for `key` holding the first `count` elements of `array`, written when `changed` or
+     * when the block moves, such as the row lists an `up` system's dispatches read.
+     */
+    readonly uploadIndexes: (key: string, array: Int32Array, count: number, changed: boolean) => number;
+    /** Writes a record for `key` (one per system and archetype) and returns its dynamic offset. */
+    readonly record: (key: string, words: Uint32Array) => number;
+    /** Frees the records and index blocks of keys starting with `prefix`, a system's, once nothing runs it again. */
+    readonly release: (prefix: string) => void;
+    /** For tests of what a world holds: how many records and index blocks it keeps. */
+    readonly records: () => number;
+    /** Marks every row of a storage changed on the CPU, for writes that may not stamp its chunks. */
+    readonly markCpuWrites: (archetype: Archetype, storage: Storage) => void;
+    readonly markGpuWrites: (archetype: Archetype, storage: Storage) => void;
+    /** Whether a storage has GPU writes the CPU hasn't seen. */
+    readonly isAhead: (storage: Storage) => boolean;
+    readonly anyAhead: () => boolean;
+    /** Copies GPU writes back into the CPU storages; every storage when `storages` is omitted. */
+    readonly readback: (storages?: readonly Storage[]) => Promise<void>;
+    /** Before a sync point: notes row counts, so the rows it only appends are uploaded alone. */
+    readonly beforeSync: () => void;
+    /** Once a sync point is planned: the archetypes whose existing rows it moves or writes, read back first and uploaded whole. */
+    readonly disturb: (disturbed: ReadonlySet<Archetype>) => void;
+    /** After a sync point: the archetypes it changed, whose new rows, or all rows if disturbed, are uploaded next. */
+    readonly touched: (archetypes: Iterable<Archetype>) => void;
+    /** Set once the device is lost; later runs that use the GPU reject with it, and readbacks keep the CPU's copies. */
+    readonly lost: () => string | null;
+    /** Records the first error a run's scopes report, for the next run to reject with. */
+    /** Keeps the first error of a run's GPU work, with the label of the system whose run submitted it. */
+    readonly reportErrors: (system: { readonly name: string }, validation: Promise<GPUError | null>, memory: Promise<GPUError | null>) => void;
+    /** The recorded error, cleared. */
+    readonly takeError: () => { readonly name: string; readonly message: string } | null;
+    readonly destroy: () => void;
+};
+
+const sizeClass = (bytes: number): number => Math.max(0, Math.ceil(Math.log2(Math.max(bytes, minimumBlockBytes) / minimumBlockBytes)));
+
+export const createGpu = (device: GPUDevice): GpuEngine => {
+    const renderLayout = layout(device);
+    const computeLayout = device.createBindGroupLayout({
+        entries: [
+            { binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: "storage" } },
+            { binding: 1, visibility: GPUShaderStage.COMPUTE, buffer: { type: "read-only-storage", hasDynamicOffset: true, minBindingSize: recordBytes } },
+        ],
+    });
+    const heapUsage = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST;
+    const recordUsage = GPUBufferUsage.STORAGE | GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST;
+    let heap = device.createBuffer({ size: initialHeapBytes, usage: heapUsage });
+    let top = 0;
+    const freeBlocks: number[][] = [];
+    let records = device.createBuffer({ size: 64 * recordBytes, usage: recordUsage });
+    const slots = new Map<string, number>();
+    /** Record slots released, reused before new ones. */
+    const freeSlots: number[] = [];
+    let nextSlot = 0;
+    let groups: { render: GPUBindGroup; compute: GPUBindGroup } | null = null;
+    let encoder: GPUCommandEncoder | null = null;
+    let lostReason: string | null = null;
+    let recorded: { readonly name: string; readonly message: string } | null = null;
+    const residents = new Map<Storage, Resident>();
+    const ahead = new Set<Resident>();
+    void device.lost.then(info => { lostReason = info.message === "" ? info.reason : info.message; });
+
+    const bindGroups = (): { render: GPUBindGroup; compute: GPUBindGroup } => groups ??= {
+        render: device.createBindGroup({ layout: renderLayout, entries: [{ binding: 0, resource: { buffer: heap } }, { binding: 1, resource: { buffer: records, size: recordBytes } }] }),
+        compute: device.createBindGroup({ layout: computeLayout, entries: [{ binding: 0, resource: { buffer: heap } }, { binding: 1, resource: { buffer: records, size: recordBytes } }] }),
+    };
+
+    const submit = (): void => {
+        if (encoder === null) return;
+        device.queue.submit([encoder.finish()]);
+        encoder = null;
+    };
+
+    const limit = Math.min(device.limits.maxBufferSize, device.limits.maxStorageBufferBindingSize);
+
+    /** Replaces a buffer with one of `size` bytes holding its first `used` bytes. Work recorded so far is submitted first. */
+    const replace = (old: GPUBuffer, size: number, usage: number, used: number): GPUBuffer => {
+        submit();
+        const grown = device.createBuffer({ size, usage });
+        if (used > 0) {
+            const copy = device.createCommandEncoder();
+            copy.copyBufferToBuffer(old, 0, grown, 0, used);
+            device.queue.submit([copy.finish()]);
+        }
+        old.destroy();
+        groups = null;
+        return grown;
+    };
+
+    const allocate = (bytes: number): number => {
+        const size = sizeClass(bytes);
+        const reused = freeBlocks[size]?.pop();
+        if (reused !== undefined) return reused;
+        const offset = top;
+        const end = top + minimumBlockBytes * 2 ** size;
+        if (end > heap.size) {
+            if (end > limit) throw new Error(`The GPU copy of the world needs ${end} bytes, over this device's limit of ${limit}; request a higher maxBufferSize and maxStorageBufferBindingSize.`);
+            let next = heap.size;
+            while (next < end) next *= 2;
+            heap = replace(heap, Math.min(next, limit), heapUsage, offset);
+        }
+        top = end;
+        return offset;
+    };
+
+    const residentOf = (archetype: Archetype, storage: Storage): Resident => {
+        let resident = residents.get(storage);
+        if (resident === undefined) {
+            const stride = storage.layout.kind === "linear" ? storage.layout.stride : 0;
+            resident = { storage, archetype, stride, offset: 0, bytes: 0, capacity: 0, dirtyLow: 0, dirtyHigh: 0, aheadLow: 0, aheadHigh: 0, uploaded: 0 };
+            residents.set(storage, resident);
+        }
+        if (resident.capacity < archetype.capacity) {
+            const bytes = Math.max(minimumBlockBytes, archetype.capacity * resident.stride);
+            const offset = allocate(bytes);
+            if (resident.bytes === 0) {
+                resident.dirtyLow = 0;
+                resident.dirtyHigh = archetype.count;
+            }
+            else {
+                // The old rows move on the GPU, where they may be newer than the CPU's; a buffer can't copy into itself.
+                submit();
+                const used = resident.capacity * resident.stride;
+                const scratch = device.createBuffer({ size: used, usage: GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST });
+                const copy = device.createCommandEncoder();
+                copy.copyBufferToBuffer(heap, resident.offset, scratch, 0, used);
+                copy.copyBufferToBuffer(scratch, 0, heap, offset, used);
+                device.queue.submit([copy.finish()]);
+                scratch.destroy();
+                (freeBlocks[sizeClass(resident.bytes)] ??= []).push(resident.offset);
+            }
+            resident.offset = offset;
+            resident.bytes = bytes;
+            resident.capacity = archetype.capacity;
+        }
+        return resident;
+    };
+
+    /** Writes rows `low` to `high` of a storage into its GPU copy. */
+    const write = (resident: Resident, low: number, high: number): void => {
+        // A queue write lands before work recorded but not yet submitted, which may read these rows.
+        submit();
+        const start = low * resident.stride;
+        device.queue.writeBuffer(heap, resident.offset + start, resident.storage.views.u8, start, (high - low) * resident.stride);
+    };
+
+    const upload = (archetype: Archetype, storage: Storage, tick: number): number => {
+        const resident = residentOf(archetype, storage);
+        const { count } = archetype;
+        const low = resident.dirtyLow;
+        const high = Math.min(resident.dirtyHigh, count);
+        // Rows the GPU wrote and the CPU hasn't read back are newer there, so only the dirty rows are written: CPU
+        // systems read them back before writing them, so nothing else changed.
+        if (storage.ticked && !ahead.has(resident)) {
+            // A write per run of adjacent chunks stamped since the last upload or holding dirty rows. Outside the dirty
+            // rows the CPU's rows are the GPU's, so writing whole chunks costs only bytes.
+            const { chunkChanged } = storage;
+            const { uploaded } = resident;
+            const chunks = (count + (1 << chunkShift) - 1) >> chunkShift;
+            const dirtyFirst = low < high ? low >> chunkShift : chunks;
+            const dirtyEnd = low < high ? ((high - 1) >> chunkShift) + 1 : 0;
+            let first = -1;
+            for (let chunk = 0; chunk < chunks; chunk++) {
+                if (chunkChanged[chunk] > uploaded || (chunk >= dirtyFirst && chunk < dirtyEnd)) {
+                    if (first < 0) first = chunk;
+                }
+                else if (first >= 0) {
+                    write(resident, first << chunkShift, chunk << chunkShift);
+                    first = -1;
+                }
+            }
+            if (first >= 0) write(resident, first << chunkShift, count);
+        }
+        else if (low < high) write(resident, low, high);
+        resident.dirtyLow = resident.dirtyHigh = 0;
+        resident.uploaded = tick;
+        return resident.offset / 4;
+    };
+
+    const indexBlocks = new Map<string, { offset: number; bytes: number }>();
+    const uploadIndexes = (key: string, array: Int32Array, count: number, changed: boolean): number => {
+        const bytes = Math.max(minimumBlockBytes, count * 4);
+        let block = indexBlocks.get(key);
+        let write = changed;
+        if (block === undefined || block.bytes < bytes) {
+            if (block !== undefined) (freeBlocks[sizeClass(block.bytes)] ??= []).push(block.offset);
+            block = { offset: allocate(bytes), bytes: minimumBlockBytes * 2 ** sizeClass(bytes) };
+            indexBlocks.set(key, block);
+            write = true;
+        }
+        if (write && count > 0) {
+            // A queue write lands before work recorded but not yet submitted, which may read the old lists.
+            submit();
+            device.queue.writeBuffer(heap, block.offset, array, 0, count);
+        }
+        return block.offset / 4;
+    };
+
+    const scratch = new Uint32Array(recordWords);
+    const record = (key: string, words: Uint32Array): number => {
+        let slot = slots.get(key);
+        if (slot === undefined) {
+            slot = freeSlots.pop() ?? nextSlot++;
+            // Records written earlier in this run may not be bound yet, so they move with the buffer.
+            if ((slot + 1) * recordBytes > records.size) records = replace(records, records.size * 2, recordUsage, slot * recordBytes);
+            slots.set(key, slot);
+        }
+        scratch.fill(0);
+        scratch.set(words.subarray(0, recordWords));
+        device.queue.writeBuffer(records, slot * recordBytes, scratch);
+        return slot * recordBytes;
+    };
+
+    const release = (prefix: string): void => {
+        for (const [key, slot] of slots) {
+            if (!key.startsWith(prefix)) continue;
+            slots.delete(key);
+            freeSlots.push(slot);
+        }
+        for (const [key, block] of indexBlocks) {
+            if (!key.startsWith(prefix)) continue;
+            indexBlocks.delete(key);
+            (freeBlocks[sizeClass(block.bytes)] ??= []).push(block.offset);
+        }
+    };
+
+    const markCpuWrites = (archetype: Archetype, storage: Storage): void => {
+        const resident = residents.get(storage);
+        if (resident === undefined) return;
+        resident.dirtyLow = 0;
+        resident.dirtyHigh = Math.max(resident.dirtyHigh, archetype.count);
+    };
+
+    const markGpuWrites = (archetype: Archetype, storage: Storage): void => {
+        const resident = residents.get(storage);
+        if (resident === undefined) return;
+        resident.aheadLow = 0;
+        resident.aheadHigh = Math.max(resident.aheadHigh, archetype.count);
+        ahead.add(resident);
+    };
+
+    const readback = async (storages?: readonly Storage[]): Promise<void> => {
+        // A lost device's copies are gone, so the CPU's last copies stand.
+        if (lostReason !== null) {
+            ahead.clear();
+            return;
+        }
+        const pending = storages === undefined ? [...ahead] : storages.flatMap(storage => {
+            const resident = residents.get(storage);
+            return resident !== undefined && ahead.has(resident) ? [resident] : [];
+        });
+        if (pending.length === 0) return;
+        submit();
+        const copy = device.createCommandEncoder();
+        const staged = pending.map(resident => {
+            const start = resident.aheadLow * resident.stride;
+            const bytes = (resident.aheadHigh - resident.aheadLow) * resident.stride;
+            const staging = device.createBuffer({ size: Math.max(4, bytes), usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST });
+            if (bytes > 0) copy.copyBufferToBuffer(heap, resident.offset + start, staging, 0, bytes);
+            return { resident, staging, start, bytes };
+        });
+        device.queue.submit([copy.finish()]);
+        await Promise.all(staged.map(({ staging }) => staging.mapAsync(GPUMapMode.READ)));
+        for (const { resident, staging, start, bytes } of staged) {
+            if (bytes > 0) resident.storage.views.u8.set(new Uint8Array(staging.getMappedRange(0, bytes)), start);
+            staging.destroy();
+            resident.aheadLow = resident.aheadHigh = 0;
+            ahead.delete(resident);
+        }
+    };
+
+    let disturbedNow: ReadonlySet<Archetype> = new Set();
+    /** Row counts of archetypes with GPU copies, before the sync point. */
+    const countsBefore = new Map<Archetype, number>();
+    const beforeSync = (): void => {
+        disturbedNow = new Set();
+        countsBefore.clear();
+        for (const resident of residents.values()) countsBefore.set(resident.archetype, resident.archetype.count);
+    };
+
+    const touched = (archetypes: Iterable<Archetype>): void => {
+        for (const archetype of archetypes) {
+            const from = disturbedNow.has(archetype) ? 0 : countsBefore.get(archetype) ?? 0;
+            for (const storage of archetype.storages) {
+                const resident = residents.get(storage);
+                if (resident === undefined || from >= archetype.count) continue;
+                // A disturbed archetype was read back whole, so every row is the CPU's; otherwise only the new ones are.
+                resident.dirtyLow = resident.dirtyHigh > resident.dirtyLow ? Math.min(resident.dirtyLow, from) : from;
+                resident.dirtyHigh = Math.max(resident.dirtyHigh, archetype.count);
+            }
+        }
+        disturbedNow = new Set();
+    };
+
+    return {
+        device,
+        renderLayout,
+        computeLayout,
+        renderGroup: () => bindGroups().render,
+        computeGroup: () => bindGroups().compute,
+        encoder: () => encoder ??= device.createCommandEncoder(),
+        submit,
+        discard: () => { encoder = null; },
+        upload,
+        uploadIndexes,
+        record,
+        release,
+        records: () => slots.size + indexBlocks.size,
+        markCpuWrites,
+        markGpuWrites,
+        isAhead: storage => {
+            const resident = residents.get(storage);
+            return resident !== undefined && ahead.has(resident);
+        },
+        anyAhead: () => ahead.size > 0,
+        readback,
+        beforeSync,
+        disturb: disturbed => { disturbedNow = disturbed; },
+        touched,
+        lost: () => lostReason,
+        reportErrors: (system, validation, memory) => {
+            void (async () => {
+                const [invalid, exhausted] = await Promise.all([validation, memory]);
+                if (invalid !== null) recorded ??= { name: labelOfItem(system), message: `validation: ${invalid.message}` };
+                else if (exhausted !== null) recorded ??= { name: labelOfItem(system), message: `out of memory: ${exhausted.message}` };
+            })();
+        },
+        takeError: () => {
+            const error = recorded;
+            recorded = null;
+            return error;
+        },
+        destroy: () => {
+            submit();
+            heap.destroy();
+            records.destroy();
+        },
+    };
+};

package/src/implementation/world/holders.ts

@@ -0,0 +1,68 @@
+import { indexOf } from './entities.js';
+
+/**
+ * The holders of each target for one reference component, as linked lists by entity index: holder index `h` is in
+ * the list of `indexOf(targets[h])`, after `next[h] - 1` and before `previous[h] - 1` (0 for none), and holds
+ * `targets[h]`, generation included, so a list never mixes a target's generations.
+ */
+export type Holders = { first: Int32Array; next: Int32Array; previous: Int32Array; targets: Float64Array; holders: Float64Array };
+
+export const createHolders = (): Holders => ({ first: new Int32Array(0), next: new Int32Array(0), previous: new Int32Array(0), targets: new Float64Array(0), holders: new Float64Array(0) });
+
+const grownInt = (array: Int32Array, length: number): Int32Array => {
+    if (array.length >= length) return array;
+    const grown = new Int32Array(Math.max(length, 2 * array.length));
+    grown.set(array);
+    return grown;
+};
+
+const grownFloat = (array: Float64Array, length: number): Float64Array => {
+    if (array.length >= length) return array;
+    const grown = new Float64Array(Math.max(length, 2 * array.length));
+    grown.set(array);
+    return grown;
+};
+
+/** Grows the lists to cover entity indexes below `length`. */
+export const fitHolders = (lists: Holders, length: number): void => {
+    if (lists.first.length >= length) return;
+    lists.first = grownInt(lists.first, length);
+    lists.next = grownInt(lists.next, length);
+    lists.previous = grownInt(lists.previous, length);
+    lists.targets = grownFloat(lists.targets, length);
+    lists.holders = grownFloat(lists.holders, length);
+};
+
+/** Adds `holder` to the list of `target`. Each holder is in at most one list, so it must be unlinked first. */
+export const linkHolder = (lists: Holders, target: number, holder: number): void => {
+    const at = indexOf(holder);
+    const into = indexOf(target);
+    const first = lists.first[into];
+    lists.next[at] = first;
+    lists.previous[at] = 0;
+    if (first !== 0) lists.previous[first - 1] = at + 1;
+    lists.first[into] = at + 1;
+    lists.targets[at] = target;
+    lists.holders[at] = holder;
+};
+
+/** Removes `holder` from the list of `target`, if it's there. */
+export const unlinkHolder = (lists: Holders, target: number, holder: number): void => {
+    const at = indexOf(holder);
+    if (at >= lists.first.length || lists.targets[at] !== target || lists.holders[at] !== holder) return;
+    const previous = lists.previous[at];
+    const next = lists.next[at];
+    if (previous !== 0) lists.next[previous - 1] = next;
+    else lists.first[indexOf(target)] = next;
+    if (next !== 0) lists.previous[next - 1] = previous;
+    lists.targets[at] = 0;
+};
+
+/** Calls `each` with every holder of `target`. */
+export const forEachHolder = (lists: Holders, target: number, each: (holder: number) => void): void => {
+    const into = indexOf(target);
+    if (into >= lists.first.length) return;
+    for (let at = lists.first[into]; at !== 0; at = lists.next[at - 1]) {
+        if (lists.targets[at - 1] === target) each(lists.holders[at - 1]);
+    }
+};

package/src/implementation/world/ids.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from "vitest";
+import { Component } from "../../interface/component/component.js";
+import type { Entity } from "../../interface/entity/entity.js";
+import { Finalizer } from "../../interface/finalizer/finalizer.js";
+import { identify } from "../../interface/registry/ids.test-helper.js";
+import { workers } from "../../interface/resources/workers.js";
+import { Rule } from "../../interface/rule/rule.js";
+import { System } from "../../interface/system/system.js";
+import { createWorld } from "./create.js";
+import { read } from "./reads.test-helper.js";
+
+// Each pair is one module's key and the key that module makes when evaluated again: one id, two symbols.
+const score = Symbol("score");
+const scoreAgain = Symbol("score");
+const shown = Symbol("shown");
+const shownAgain = Symbol("shown");
+
+identify(score, "worldIdsTest/keys.ts#score");
+identify(scoreAgain, "worldIdsTest/keys.ts#score");
+identify(shown, "worldIdsTest/keys.ts#shown");
+identify(shownAgain, "worldIdsTest/keys.ts#shown");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [score]: { type: number };
+        [scoreAgain]: { type: number };
+        [shown]: { type: true; derived: true };
+        [shownAgain]: { type: true; derived: true };
+    }
+}
+
+Component.register(score, { type: { type: "number" } });
+Component.register(shown, { type: { const: true }, derived: true });
+Rule.create(identify({ name: "worldIdsTest/shown", components: { has: [score] }, derive: [shown] }, "worldIdsTest/systems.ts#shown"));
+const changes: (readonly symbol[])[] = [];
+Finalizer.changes(identify({ name: "worldIdsTest/changes", watch: [score] }, "worldIdsTest/systems.ts#changes"), ({ groups }) => {
+    for (const group of groups) changes.push(group.added);
+});
+
+// The module evaluated again, after the world met its first keys.
+const evaluateAgain = (): void => {
+    Component.register(scoreAgain, { type: { type: "number" } });
+    Component.register(shownAgain, { type: { const: true }, derived: true });
+    Rule.create(identify({ name: "worldIdsTest/shown", components: { has: [scoreAgain] }, derive: [shownAgain] }, "worldIdsTest/systems.ts#shown"));
+    Finalizer.changes(identify({ name: "worldIdsTest/changes", watch: [scoreAgain] }, "worldIdsTest/systems.ts#changes"), ({ groups }) => {
+        for (const group of groups) changes.push(group.added);
+    });
+};
+
+const spawn = System.create({ name: "worldIdsTest/spawn" }, ({ commands }) => { spawned.push(commands.spawn([score])({ [score]: 1 })); });
+const spawned: Entity[] = [];
+
+describe("a world given keys with ids", () => {
+    it("stores the symbols of one id as one component, giving values by the newest", async () => {
+        const world = createWorld({ [workers]: 0 });
+        await world.run(spawn);
+        evaluateAgain();
+        const spawnAgain = System.create({ name: "worldIdsTest/spawnAgain" }, ({ commands }) => { spawned.push(commands.spawn([scoreAgain])({ [scoreAgain]: 2 })); });
+        const add = System.create({ name: "worldIdsTest/add", components: { write: [scoreAgain] } }, row => { row[scoreAgain] += 10; });
+        await world.run(spawnAgain);
+        await world.run(add);
+        const [first, second] = spawned;
+        expect([await read(world, first, score), await read(world, first, scoreAgain), await read(world, second, score)]).toEqual([11, 11, 12]);
+        expect([await read(world, first, shownAgain), await read(world, second, shown)]).toEqual([true, true]);
+        expect(changes).toEqual([[score], [scoreAgain]]);
+        await world.dispose();
+    });
+});

package/src/implementation/world/imported-lists.test-helper.ts

@@ -0,0 +1,22 @@
+import { Archetype } from '../../interface/archetype/archetype.js';
+import { Component } from '../../interface/component/component.js';
+
+/** Keys and lists another module's kernels import, in `imported-lists.test.ts`. */
+
+export const ember = Symbol("importedListsTest/ember");
+/** A key only this module's lists name to the kernels. */
+const glow = Symbol("importedListsTest/glow");
+export const marked = Symbol("importedListsTest/marked");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [ember]: { type: number };
+        [glow]: { type: true };
+        [marked]: { type: true };
+    }
+}
+Component.register(ember, { type: { type: "number" } });
+Component.register(glow, { type: { const: true } });
+Component.register(marked, { type: { const: true } });
+
+export const Spark = Archetype.create([ember, glow]);
+export const Marks = [ember, marked] as const;

package/src/implementation/world/imported-lists.test.ts

@@ -0,0 +1,45 @@
+import { expect, it } from "vitest";
+import { Component } from "../../interface/component/component.js";
+import { System } from "../../interface/system/system.js";
+import { count, read, select } from "./reads.test-helper.js";
+import { createWorld } from "./create.js";
+import { ember, marked, Spark } from "./imported-lists.test-helper.js";
+import * as Lists from "./imported-lists.test-helper.js";
+import { workers } from "../../interface/resources/workers.js";
+
+const heat = Symbol("importedListsTest/heat");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [heat]: { type: number };
+    }
+}
+Component.register(heat, { type: { type: "number" } });
+
+const seed = System.create({ name: "importedListsTest/seed" }, ({ commands }) => {
+    commands.spawn([heat])({ [heat]: 2 });
+    commands.spawn([heat])({ [heat]: 5 });
+});
+
+/** Spawns and adds through lists another module declares, naming one of their keys only through the list. */
+const ignite = System.create({ name: "importedListsTest/ignite", kernel: "cpu", components: { read: [heat] } }, (row, { commands }) => {
+    commands.spawn(Spark)({ [ember]: row[heat] * 2 });
+    commands.add(row.entity, Lists.Marks, { [ember]: row[heat] });
+});
+
+/** Declares an imported list, and removes through one. */
+const cool = System.create({ name: "importedListsTest/cool", kernel: "cpu", components: { read: [ember], has: Lists.Spark } }, (row, { commands }) => {
+    if (row[ember] > 4) commands.remove(row.entity, Spark);
+});
+
+it("kernels spawn, add, remove and declare through lists imported from another module", async () => {
+    // Kernels run here: under Vitest's module runner, node workers can't load the sources.
+    await using world = createWorld({ [workers]: 0 });
+    await world.run(seed);
+    await world.run(ignite);
+    const sparks = await select(world, { required: Spark });
+    expect((await Promise.all(sparks.map(entity => read(world, entity, ember)))).sort((a, b) => (a ?? 0) - (b ?? 0))).toEqual([4, 10]);
+    expect(await count(world, { required: [heat, ...Lists.Marks] })).toBe(2);
+    await world.run(cool);
+    expect(await count(world, { required: Spark })).toBe(1);
+    expect(await count(world, { required: [marked] })).toBe(2);
+});

package/src/implementation/world/index-build-csp.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { Component } from "../../interface/component/component.js";
+import { Index } from "../../interface/indexes/index-type.js";
+import { workers } from "../../interface/resources/workers.js";
+import { System } from "../../interface/system/system.js";
+import { createWorld } from "./create.js";
+
+const spot = Symbol("indexBuildCspTest/spot");
+const size = Symbol("indexBuildCspTest/size");
+const bulk = Symbol("indexBuildCspTest/bulk");
+declare module "@adobe/ecs" {
+    interface Components {
+        [spot]: { type: readonly [number, number] };
+        [size]: { type: number };
+        [bulk]: { type: number };
+    }
+}
+Component.register(spot, { type: { type: "array", items: { type: "integer", minimum: -1000, maximum: 1000 }, minItems: 2, maxItems: 2 } });
+Component.register(size, { type: { type: "number" } });
+Component.register(bulk, { type: { type: "number", precision: 2 } });
+
+/** A key of a pair of i32s and an f64, so the steps encode three kinds of leaf. */
+const bySpot = Index.create({ key: [spot, bulk], components: { has: [size] } });
+const count = 70_000;
+
+describe("index builds in phases where code can't be generated", () => {
+    it("list keys in a loop over their leaves, building the same index", async () => {
+        const generate = globalThis.Function;
+        // A content security policy without 'unsafe-eval' makes `new Function` throw.
+        globalThis.Function = new Proxy(generate, { construct: () => { throw new EvalError("blocked"); } });
+        try {
+            await using world = createWorld({ [workers]: 0 });
+            await world.run(System.create(({ commands }) => {
+                for (let k = 0; k < count; k++) commands.spawn([spot, size, bulk])({ [spot]: [k % 37 - 18, k % 11], [size]: k, [bulk]: (k % 3) / 4 });
+            }));
+            const expected = new Map<string, number[]>();
+            await world.run(System.create({ components: { read: [spot, size, bulk] } }, row => {
+                const text = `${row[spot][0]},${row[spot][1]},${row[bulk]}`;
+                const held = expected.get(text) ?? [];
+                held.push(row[size]);
+                expected.set(text, held);
+            }));
+            const found = new Map<string, number[]>();
+            await world.run(System.create({ lookup: { at: { index: bySpot, read: [size] } } }, ({ lookup }) => {
+                for (const text of expected.keys()) {
+                    const [x, y, b] = text.split(",").map(Number);
+                    const list = lookup.at([x, y], b);
+                    found.set(text, Array.from({ length: list.length }, (_, i) => list.at(i)[size]));
+                }
+            }));
+            // Rows were spawned in entity order, so each bucket's sizes ascend.
+            expect(found).toEqual(new Map([...expected].map(([text, sizes]) => [text, [...sizes].sort((a, b) => a - b)])));
+            expect((await world.tables()).phasedBuilds).toBe(1);
+        }
+        finally {
+            globalThis.Function = generate;
+        }
+    });
+});