@adobe/ecs 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,86 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Rule } from "../../interface/rule/rule.js";
+import { System } from "../../interface/system/system.js";
+import { createWorld } from "../index.js";
+import { readResource } from "./reads.test-helper.js";
+import { Entity, F32, I32, Mat4x4, Quat, U32, Vec2, Vec3, Vec4 } from "../../index.js";
+
+const pool = Symbol();
+const names = Symbol();
+const count = Symbol();
+const tagged = Symbol();
+const index = Symbol();
+const turn = Symbol();
+const least = Symbol();
+const all = Symbol();
+
+/** A pool declared through an alias of ReadonlyMap. */
+type Pool = ReadonlyMap<string, number>;
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [tagged]: { type: true };
+        [index]: { type: ReadonlyMap<string, number>; derived: true };
+    }
+    export interface Resources {
+        [pool]: { type: Pool };
+        [names]: { type: ReadonlyMap<string, number> };
+        [count]: { type: number };
+        [turn]: { type: Quat };
+        [least]: { type: F32; reduce: "min" };
+        [all]: { type: boolean; reduce: "&" };
+    }
+}
+
+Rule.create({ components: { with: [tagged] }, derive: [index] });
+
+describe("a resource declared without a default", () => {
+    it("starts at its type's zero value, and a ReadonlyMap or ReadonlySet at an empty one of its world's own", async () => {
+        await using first = createWorld();
+        await using second = createWorld();
+        const [firstPool, secondPool] = [await readResource(first, pool), await readResource(second, pool)];
+        expect(firstPool).toEqual(new Map());
+        expect(secondPool).toEqual(new Map());
+        expect(firstPool).not.toBe(secondPool);
+        expect(await readResource(first, pool)).toBe(firstPool);
+        expect(await readResource(first, names)).toEqual(new Map());
+        expect(await readResource(first, count)).toBe(0);
+    });
+});
+
+describe("a derived component declared without a default", () => {
+    it("starts every row of a world at one empty Map of its own, since values are replaced whole", async () => {
+        const spawn = System.create(({ commands }) => {
+            commands.spawn([tagged])({});
+            commands.spawn([tagged])({});
+        });
+        const seen: unknown[] = [];
+        const read = System.create({ observer: true, components: { with: [index] } }, row => { seen.push(row[index]); });
+        await using first = createWorld();
+        await using second = createWorld();
+        for (const world of [first, second]) {
+            await world.run(spawn);
+            await world.run(read);
+        }
+        expect(seen).toHaveLength(4);
+        expect(seen[0]).toEqual(new Map());
+        expect(seen[1]).toBe(seen[0]);
+        expect(seen[3]).toBe(seen[2]);
+        expect(seen[2]).not.toBe(seen[0]);
+    });
+});
+
+describe("the package's types' defaults", () => {
+    it("are zeros, identities, and none for an entity", () => {
+        expect([F32.default, I32.default, U32.default, Vec2.default, Vec3.default, Vec4.default, Vec3.I32.default, Vec4.U32.default, Entity.default])
+            .toEqual([0, 0, 0, [0, 0], [0, 0, 0], [0, 0, 0, 0], [0, 0, 0], [0, 0, 0, 0], Entity.none]);
+        expect([Quat.default, Mat4x4.default]).toEqual([Quat.identity, Mat4x4.identity]);
+    });
+    it("start a world's resources, and a reduction its operator's identity", async () => {
+        await using world = createWorld();
+        expect(await readResource(world, turn)).toEqual([0, 0, 0, 1]);
+        expect(await readResource(world, least)).toBe(Infinity);
+        expect(await readResource(world, all)).toBe(true);
+    });
+});

package/src/implementation/world/directories.ts

@@ -0,0 +1,87 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { allocateArray, freeArray } from './arrays.js';
+import type { State } from './state.js';
+
+/**
+ * A lookup's directory for WASM kernels: per archetype id, a match flag, then for a lookup through an index the address
+ * of the archetype's entities, then the column address of each component the lookup reads, then the `changed` tick
+ * column address of each it watches, 0 for one keeping no ticks. It lives in shared memory, so workers read the same
+ * one. Rebuilt at sync points when archetypes are created or grow, or start ticks, since all change those addresses.
+ */
+export type Directory = {
+    readonly entities: boolean;
+    readonly read: readonly number[];
+    readonly watched: readonly number[];
+    readonly has: readonly number[];
+    readonly not: readonly number[];
+    records: Int32Array;
+    /** Archetypes described. */
+    count: number;
+    /** The layout it was built for: archetype count plus every archetype's version. */
+    built: number;
+};
+
+const words = (directory: Directory): number => 1 + (directory.entities ? 1 : 0) + directory.read.length + directory.watched.length;
+
+const layoutOf = (state: State): number => {
+    let layout = state.archetypes.length;
+    for (const archetype of state.archetypes) layout += archetype.version;
+    return layout;
+};
+
+/** Rebuilds a directory if archetypes changed since it was built. Allocates, so it runs only at sync points or registration. */
+export const refreshDirectory = (state: State, directory: Directory, layout = layoutOf(state)): void => {
+    if (directory.built === layout) return;
+    const length = state.archetypes.length * words(directory);
+    if (directory.records.length < length) {
+        freeArray(state.memory, directory.records);
+        directory.records = allocateArray(state.memory, Int32Array, Math.max(length, directory.records.length * 2));
+    }
+    const { records, read, has, not, watched } = directory;
+    state.archetypes.forEach((archetype, id) => {
+        const base = id * words(directory);
+        const { storageById } = archetype;
+        const matches = !archetype.resource && [...read, ...has].every(component => storageById[component] !== undefined) && not.every(component => storageById[component] === undefined);
+        records[base] = matches ? 1 : 0;
+        const first = directory.entities ? 2 : 1;
+        if (directory.entities) records[base + 1] = matches ? archetype.entities.byteOffset : 0;
+        read.forEach((component, i) => {
+            const storage = storageById[component];
+            records[base + first + i] = matches && storage !== undefined ? storage.views.u8.byteOffset : 0;
+        });
+        watched.forEach((component, i) => {
+            const storage = storageById[component];
+            records[base + first + read.length + i] = matches && storage !== undefined && storage.ticked ? storage.changed.byteOffset : 0;
+        });
+    });
+    directory.count = state.archetypes.length;
+    directory.built = layout;
+};
+
+export const createDirectory = (state: State, read: readonly number[], has: readonly number[], not: readonly number[], entities = false, watched: readonly number[] = []): Directory => {
+    const directory: Directory = { entities, read, watched, has, not, records: allocateArray(state.memory, Int32Array, 16), count: 0, built: -1 };
+    state.directories.add(directory);
+    refreshDirectory(state, directory);
+    return directory;
+};
+
+/** Stops keeping a directory, freeing its records, once no kernel looks up through it again. */
+export const releaseDirectory = (state: State, directory: Directory): void => {
+    if (!state.directories.delete(directory)) return;
+    freeArray(state.memory, directory.records);
+};
+
+/** At a sync point: brings every directory up to date with the archetypes. */
+export const refreshDirectories = (state: State): void => {
+    if (state.directories.size === 0) return;
+    const layout = layoutOf(state);
+    for (const directory of state.directories) refreshDirectory(state, directory, layout);
+};
+
+/** What a WASM kernel with lookups takes, in its lookup parameters: the entity table, then each directory. */
+export const lookupParameters = (state: State, directories: readonly Directory[]): number[] => {
+    const { entities } = state;
+    const parameters = [entities.archetype.byteOffset, entities.row.byteOffset, entities.generation.byteOffset, entities.length];
+    for (const directory of directories) parameters.push(directory.records.byteOffset, directory.count);
+    return parameters;
+};

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

@@ -0,0 +1,53 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { indexOf, reserve } from "./entities.js";
+import { recordFlags, recordStorages, recordWords, resourceEntityWord, resourceFlag, storageColumn, storageComponent, storageWords, structureWord, tableOffsetWord } from "./layout-directory.js";
+import { ensureResources } from "./resources.js";
+import { createState, idOf } from "./state.js";
+import { applySync, prepareSync } from "./synchronize.js";
+
+const gravity = Symbol("directoryTest/gravity");
+declare module "@adobe/ecs" {
+    export interface Resources {
+        [gravity]: { type: number; default: -9.8 };
+    }
+}
+
+describe("the layout directory", () => {
+    it("keeps the structure epoch odd from a sync point's start until its directory writes, and even otherwise, once a thread may read it", () => {
+        const state = createState(true);
+        const words = new Int32Array(state.memory.memory.buffer, 0, 16);
+        expect(words[structureWord]).toBe(0);
+        // No joined thread reads it, so a sync point leaves it.
+        reserve(state.entities);
+        expect(prepareSync(state)).toBe(true);
+        expect(words[structureWord]).toBe(0);
+        applySync(state);
+        expect(words[structureWord]).toBe(0);
+        if (state.directory !== null) state.directory.guarded = true;
+        // Nothing to apply leaves it.
+        expect(prepareSync(state)).toBe(false);
+        expect(words[structureWord]).toBe(0);
+        reserve(state.entities);
+        expect(prepareSync(state)).toBe(true);
+        expect(words[structureWord]).toBe(1);
+        applySync(state);
+        expect(words[structureWord]).toBe(2);
+    });
+    it("records the resource archetype, flagged, and the resource entity, so other threads find resources' cells", () => {
+        const state = createState(true);
+        const words = new Uint32Array(state.memory.memory.buffer);
+        expect(words[resourceEntityWord]).toBe(0);
+        ensureResources(state, [gravity]);
+        const index = words[resourceEntityWord] - 1;
+        expect(index).toBe(indexOf(state.resourceEntity));
+        const archetype = state.entities.archetype[index];
+        const record = words[words[tableOffsetWord] / 4 + archetype] / 4;
+        expect(words[record + recordFlags]).toBe(resourceFlag);
+        const storages = Array.from({ length: words[record + recordStorages] }, (_, s) => record + recordWords + s * storageWords);
+        const storage = storages.find(base => words[base + storageComponent] === idOf(state, gravity));
+        if (storage === undefined) throw new Error("No storage for gravity.");
+        const row = state.entities.row[index];
+        expect(new Float64Array(state.memory.memory.buffer, words[storage + storageColumn], row + 1)[row]).toBe(-9.8);
+    });
+});

package/src/implementation/world/dispatch.cases.ts

@@ -0,0 +1,33 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import type * as Fixture from "./dispatch.fixture.js";
+
+/** Tasks reach workers in order, through rings and messages: the cases, over the fixture built for node or from source. */
+export const dispatchCases = (load: () => Promise<typeof Fixture>) => describe("worker dispatch", () => {
+    it("reloads kernels on workers when an observer registers", async () => {
+        const fixture = await load();
+        expect(await fixture.reloadedOnObserver()).toBe(4096);
+    }, 200000);
+    for (const failing of [1, 2]) it(`keeps worker kernels in step after a failed registration (compile ${failing})`, async () => {
+        const fixture = await load();
+        const { rejected, rows } = await fixture.afterFailedRegistration(failing);
+        expect(rejected).toContain("injected");
+        expect(rows).toBe(4096);
+    }, 200000);
+    it("delivers layouts between back-to-back runs", async () => {
+        const fixture = await load();
+        expect(await fixture.backToBack()).toEqual([0, 0, 0, 0, 0, 0]);
+    }, 200000);
+    for (const name of ["fastA,slowB", "fastA,fastC", "slowB,fastC"] as const) it(`runs tiers of ${name}`, async () => {
+        const fixture = await load();
+        expect(await fixture.tier(name)).toBe("ok");
+    }, 200000);
+    it("fast, message, fast kernels in one tier don't hang", async () => {
+        const fixture = await load();
+        expect(await fixture.tier("fastA,slowB,fastC")).toBe("ok");
+    }, 200000);
+    it("ring overflow followed by a message task in the same tier doesn't hang", async () => {
+        const fixture = await load();
+        expect(await fixture.overflowThenMessage()).toBe("ok");
+    }, 200000);
+});

package/src/implementation/world/dispatch.fixture.ts

@@ -0,0 +1,163 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Schema } from "../../interface/schema/schema.js";
+import { System } from "../../interface/system/system.js";
+import { readEach, select } from "./reads.test-helper.js";
+import { createWorld } from "./create.js";
+import { workers } from "../../interface/resources/workers.js";
+import type { World } from "../../interface/world/world.js";
+import type { F32 } from "../../interface/math/index.js";
+
+/** Scenarios of dispatching tasks to workers, run built in node and from source in chromium. */
+
+type Vec2 = readonly [number, number];
+const vec2 = { type: "array", items: { type: "number", precision: 1 }, minItems: 2, maxItems: 2 } as const satisfies Schema;
+const position = Symbol("dispatchTest/position");
+const velocity = Symbol("dispatchTest/velocity");
+const offset = Symbol("dispatchTest/offset");
+const tagA = Symbol("dispatchTest/a");
+const tagB = Symbol("dispatchTest/b");
+const tagC = Symbol("dispatchTest/c");
+const tagD = Symbol("dispatchTest/d");
+const tagE = Symbol("dispatchTest/e");
+const tagF = Symbol("dispatchTest/f");
+const tagG = Symbol("dispatchTest/g");
+const tags = [tagA, tagB, tagC, tagD, tagE, tagF, tagG] as const;
+declare module "@adobe/ecs" {
+    export interface Components {
+        [position]: { type: Schema.Type<{ type: "array"; items: { type: "number"; precision: 1 }; minItems: 2; maxItems: 2 }> };
+        [velocity]: { type: Schema.Type<{ type: "array"; items: { type: "number"; precision: 1 }; minItems: 2; maxItems: 2 }> };
+        [offset]: { type: F32 };
+        [tagA]: { type: true }; [tagB]: { type: true }; [tagC]: { type: true }; [tagD]: { type: true };
+        [tagE]: { type: true }; [tagF]: { type: true }; [tagG]: { type: true };
+    }
+}
+
+const scatter = System.create({}, ({ commands }) => {
+    for (let i = 0; i < 128 * 64; i++) {
+        const components: (typeof position | typeof velocity | typeof offset | (typeof tags)[number])[] = [position, velocity, offset];
+        tags.forEach((tag, bit) => { if (((i >> 6) & (1 << bit)) !== 0) components.push(tag); });
+        commands.spawn(components)({ [position]: [i, 0], [velocity]: [1, i % 5], [offset]: 0 });
+    }
+});
+const seed = System.create({}, ({ commands }) => {
+    for (let i = 0; i < 4096; i++) commands.spawn([position, velocity, offset])({ [position]: [i, 0], [velocity]: [1, i % 5], [offset]: 0 });
+});
+const fastA = System.create({ kernel: true, components: { with: [velocity, position] } }, row => {
+    const [x, y] = row[position];
+    const [vx, vy] = row[velocity];
+    row[position] = [x + vx, y + vy];
+});
+// Commands make it a JS kernel, dispatched by message.
+const slowB = System.create({ kernel: true, components: { with: [velocity] } }, (row, { commands }) => {
+    const [vx] = row[velocity];
+    if (vx > 100) commands.despawn(row.entity);
+});
+const fastC = System.create({ kernel: true, components: { with: [velocity, offset] } }, row => {
+    const [vx, vy] = row[velocity];
+    row[offset] = vx + vy;
+});
+
+const withTimeout = <T>(promise: Promise<T>, ms: number): Promise<T | "timeout"> =>
+    Promise.race([promise, new Promise<"timeout">(resolve => setTimeout(() => resolve("timeout"), ms))]);
+
+const grow = System.create({}, ({ commands }) => {
+    for (let i = 0; i < 3000; i++) commands.spawn([position, velocity, offset])({ [position]: [i, 1], [velocity]: [2, i % 3], [offset]: 0 });
+});
+let observedRows = 0;
+const bump = System.create({ kernel: true, components: { with: [offset] } }, row => {
+    row[offset] = row[offset] + 1;
+});
+const watch = System.create({ components: { changed: [offset] } }, () => { observedRows++; });
+const later = System.create({ kernel: true, components: { with: [velocity, offset] }, after: [watch] }, row => {
+    const [vx, vy] = row[velocity];
+    row[offset] = vx + vy;
+});
+/** Runs `use` with a world, then disposes it. */
+const using = async <T>(world: World, use: (world: World) => Promise<T>): Promise<T> => {
+    try {
+        return await use(world);
+    }
+    finally {
+        await world.dispose();
+    }
+};
+
+/** Rows an observer registered after a kernel saw change once that kernel ran again. */
+export const reloadedOnObserver = (): Promise<number> => using(createWorld({ [workers]: 2 }, { minimumChunk: 64 }), async world => {
+    await world.run(seed);
+    await world.run(bump);
+    await world.run(watch);
+    observedRows = 0;
+    await world.run(bump);
+    await world.run(watch);
+    return observedRows;
+});
+
+/** After a registration whose WASM failed to compile: what it rejected with, and the rows the observer then saw change. */
+export const afterFailedRegistration = (failing = 2): Promise<{ readonly rejected: string; readonly rows: number }> => using(createWorld({ [workers]: 2 }, { minimumChunk: 64 }), async world => {
+    await world.run(seed);
+    await world.run(bump);
+    const original = WebAssembly.compile;
+    let calls = 0;
+    WebAssembly.compile = (bytes: BufferSource) => (++calls === failing ? Promise.reject(new Error("injected")) : original(bytes));
+    let rejected = "resolved";
+    try {
+        await world.run(System.create({ systems: [watch, later] }));
+    }
+    catch (error) {
+        rejected = String(error);
+    }
+    finally {
+        WebAssembly.compile = original;
+    }
+    await world.run(watch);
+    observedRows = 0;
+    await world.run(bump);
+    await world.run(watch);
+    return { rejected, rows: observedRows };
+});
+
+/** Positions after 12 frames of growth then a kernel, back to back, or "timeout". */
+const backToBackRun = (count: number, wasm = true, delay = false): Promise<readonly string[] | "timeout"> => using(createWorld({ [workers]: count }, { minimumChunk: 64, wasm }), async world => {
+    for (let frame = 0; frame < 12; frame++) {
+        const r = await withTimeout((async () => { await world.run(grow); if (delay) await new Promise(r => setTimeout(r, 30)); await world.run(fastA); })(), 20000);
+        if (r === "timeout") return "timeout";
+    }
+    return (await readEach(world, await select(world, { required: [position] }), position)).map(each => JSON.stringify(each)).sort();
+});
+
+/** Positions that differ from the main thread alone's, or "timeout", for workers with JS and WASM kernels, with and without a delay. */
+export const backToBack = async (): Promise<readonly (number | "timeout")[]> => {
+    const alone = await backToBackRun(0);
+    const diff = (a: readonly string[] | "timeout", b: readonly string[] | "timeout"): number | "timeout" =>
+        a === "timeout" || b === "timeout" ? "timeout" : a.filter((v, i) => v !== b[i]).length;
+    const results = [diff(await backToBackRun(3, false), alone), diff(await backToBackRun(0, true), alone)];
+    for (let i = 0; i < 2; i++) results.push(diff(await backToBackRun(3), alone));
+    for (let i = 0; i < 2; i++) results.push(diff(await backToBackRun(3, true, true), alone));
+    return results;
+};
+
+/** Tiers dispatched together: fast tasks through rings and message tasks, by the names of their systems. */
+export const tierSystems = {
+    "fastA,slowB": [fastA, slowB],
+    "fastA,fastC": [fastA, fastC],
+    "slowB,fastC": [slowB, fastC],
+    "fastA,slowB,fastC": [fastA, slowB, fastC],
+} as const;
+
+let tiers = 0;
+
+/** A tier of `systems` run `frames` times on `count` workers after `prepare`: "ok", or "timeout" if a run hung. */
+const runTier = (systems: readonly System[], count: number, frames: number, prepare: System): Promise<"ok" | "timeout"> => using(createWorld({ [workers]: count }, { minimumChunk: 64 }), async world => {
+    const tier = System.create({ systems: [...systems] });
+    await world.run(prepare);
+    let result: unknown = "ok";
+    for (let frame = 0; frame < frames && result !== "timeout"; frame++) result = await withTimeout(world.run(tier), 3000);
+    return result === "timeout" ? "timeout" : "ok";
+});
+
+/** 50 frames of a tier on two workers. */
+export const tier = (name: keyof typeof tierSystems): Promise<"ok" | "timeout"> => runTier(tierSystems[name], 2, 50, seed);
+
+/** Five frames of a fast task and a message task in one tier, after one worker's ring overflowed. */
+export const overflowThenMessage = (): Promise<"ok" | "timeout"> => runTier([fastA, slowB], 1, 5, scatter);

package/src/implementation/world/entities.ts

@@ -0,0 +1,190 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Entity } from '../../interface/entity/entity.js';
+import { allocateArray, growArray } from './arrays.js';
+import type { Memory } from './memory.js';
+
+/** An entity is `index + generation * 2^32`, so a stale reference to a reused index is detected. */
+const generationScale = 0x100000000;
+/** Generations wrap at 2^21 so entities stay safe integers. */
+const generationMask = 0x1FFFFF;
+
+export const indexOf = (entity: number): number => entity >>> 0;
+export const generationOf = (entity: number): number => Math.floor(entity / generationScale);
+
+/**
+ * The entity an id names. Ids passed here come only from the entity table, entity columns and command buffers,
+ * which hold nothing but entities.
+ */
+export const asEntity = (id: number): Entity => id as Entity;
+
+/** `cursor` slots. */
+const taken = 0;
+const freeCount = 1;
+export const tableLength = 2;
+
+/** What spawning needs, on the main thread or a worker. All of it lives in shared memory. */
+export type Reservations = {
+    /** `[reservations since the last sync point, free count, table length]`. */
+    readonly cursor: Int32Array;
+    readonly free: Int32Array;
+    readonly generation: Uint32Array;
+};
+
+/**
+ * Where each entity index lives. `archetype` is -1 for an index that isn't alive.
+ * Spawning reserves through one atomic cursor: first indexes freed before the last sync point, from the end of `free`,
+ * then new indexes past `length`.
+ */
+export type Entities = Reservations & {
+    archetype: Int32Array;
+    row: Uint32Array;
+    generation: Uint32Array;
+    free: Int32Array;
+    length: number;
+    /** Indexes freed during the current sync point, reusable after it. */
+    readonly released: number[];
+    /** Incremented whenever `free`, `archetype`, `row` or `generation` is replaced, for the layout directory. */
+    version: number;
+};
+
+const initialCapacity = 64;
+
+/** Index 0 is never alive and never freed, so `Entity.none` and zeroed entity values name no entity. */
+export const createEntities = (memory: Memory): Entities => {
+    const cursor = allocateArray(memory, Int32Array, 4).fill(0);
+    cursor[tableLength] = 1;
+    const archetype = allocateArray(memory, Int32Array, initialCapacity);
+    archetype[0] = -1;
+    return {
+        cursor,
+        free: allocateArray(memory, Int32Array, initialCapacity),
+        archetype,
+        row: allocateArray(memory, Uint32Array, initialCapacity),
+        generation: allocateArray(memory, Uint32Array, initialCapacity).fill(0),
+        length: 1,
+        released: [],
+        version: 0,
+    };
+};
+
+/** Reserves an entity. Safe to call from any thread between sync points. */
+export const reserve = ({ cursor, free, generation }: Reservations): Entity => entityAt(cursor, free, generation, Atomics.add(cursor, taken, 1));
+
+/**
+ * Reservations a thread takes in blocks of positions, so threads spawning together don't contend for the cursor.
+ * Positions a block leaves unused are reserved entities that never spawn, which the sync point releases.
+ */
+export type Block = { readonly table: Reservations; next: number; end: number; size: number };
+
+const firstBlock = 8;
+const largestBlock = 4096;
+
+export const createBlock = (table: Reservations): Block => ({ table, next: 0, end: 0, size: firstBlock });
+
+/** Reserves an entity from the block, taking a block twice the last one's size, up to a limit, once it's used up. */
+export const reserveFrom = (block: Block): Entity => {
+    if (block.next === block.end) {
+        block.next = Atomics.add(block.table.cursor, taken, block.size);
+        block.end = block.next + block.size;
+        block.size = Math.min(block.size * 2, largestBlock);
+    }
+    const { cursor, free, generation } = block.table;
+    return entityAt(cursor, free, generation, block.next++);
+};
+
+/**
+ * Ends the block once its thread's task is done, appending the positions it left unused to `unused`, as start and end
+ * pairs, for the sync point to `unreserve`; the next block starts at the first size.
+ */
+export const endBlock = (block: Block, unused: number[]): void => {
+    if (block.next < block.end) unused.push(block.next, block.end);
+    block.next = block.end = 0;
+    block.size = firstBlock;
+};
+
+/**
+ * Returns positions `start` to `end` of the reservations a sync point materialized, which no spawn used, to the free
+ * list at its end. Their entities were never handed out, so their generations stay. Returns how many it returned.
+ */
+export const unreserve = (entities: Entities, { reused, firstNew }: Reserved, start: number, end: number): number => {
+    const { length } = reused;
+    for (let position = start; position < end; position++) entities.released.push(position < length ? reused[length - 1 - position] : firstNew + position - length);
+    return end - start;
+};
+
+/** The entity a reservation position names: first indexes freed before the last sync point, then new ones. */
+const entityAt = (cursor: Int32Array, free: Int32Array, generation: Uint32Array, position: number): Entity => {
+    const available = cursor[freeCount];
+    if (position < available) {
+        const index = free[available - 1 - position];
+        return asEntity(index + generation[index] * generationScale);
+    }
+    return asEntity(cursor[tableLength] + position - available);
+};
+
+/** Whether any entity was reserved since the last sync point. */
+export const reserved = (entities: Entities): boolean => Atomics.load(entities.cursor, taken) > 0;
+
+/** The index of a live entity, or -1. */
+export const locate = (entities: Pick<Entities, "archetype" | "generation" | "length">, entity: number): number => {
+    const index = indexOf(entity);
+    return index < entities.length && entities.archetype[index] >= 0 && entities.generation[index] === generationOf(entity) ? index : -1;
+};
+
+const capacityFor = (current: number, needed: number): number => {
+    let capacity = current;
+    while (capacity < needed) capacity *= 2;
+    return capacity;
+};
+
+/** Indexes reserved since the last sync point: the reused ones, and new ones from `firstNew` up to the table's length. */
+export type Reserved = { readonly reused: Int32Array; readonly firstNew: number };
+
+/** At the start of a sync point: makes reserved indexes addressable, not yet alive. */
+export const materialize = (memory: Memory, entities: Entities): Reserved => {
+    const { cursor } = entities;
+    const count = Atomics.exchange(cursor, taken, 0);
+    const reusedCount = Math.min(count, cursor[freeCount]);
+    // A typed copy, since the sync point recycles freed indexes over these.
+    const reused = entities.free.slice(cursor[freeCount] - reusedCount, cursor[freeCount]);
+    cursor[freeCount] -= reusedCount;
+    const firstNew = entities.length;
+    const length = entities.length + count - reusedCount;
+    if (length > entities.archetype.length) {
+        const capacity = capacityFor(entities.archetype.length, length);
+        entities.archetype = growArray(memory, entities.archetype, Int32Array, capacity, entities.length);
+        entities.row = growArray(memory, entities.row, Uint32Array, capacity, entities.length);
+        entities.generation = growArray(memory, entities.generation, Uint32Array, capacity, entities.length);
+        entities.version++;
+    }
+    entities.archetype.fill(-1, entities.length, length);
+    entities.generation.fill(0, entities.length, length);
+    entities.length = length;
+    cursor[tableLength] = length;
+    return { reused, firstNew };
+};
+
+/** Kills an index, which isn't reusable until it's released: a joined thread's finalizers hold it. */
+export const kill = (entities: Entities, index: number): void => {
+    entities.archetype[index] = -1;
+    entities.generation[index] = (entities.generation[index] + 1) & generationMask;
+};
+
+/** Kills an index; it becomes reusable after the current sync point. */
+export const release = (entities: Entities, index: number): void => {
+    kill(entities, index);
+    entities.released.push(index);
+};
+
+/** At the end of a sync point: freed indexes become reservable. */
+export const recycle = (memory: Memory, entities: Entities): void => {
+    const { cursor, released } = entities;
+    const count = cursor[freeCount] + released.length;
+    if (count > entities.free.length) {
+        entities.free = growArray(memory, entities.free, Int32Array, capacityFor(entities.free.length, count), cursor[freeCount]);
+        entities.version++;
+    }
+    entities.free.set(released, cursor[freeCount]);
+    cursor[freeCount] = count;
+    released.length = 0;
+};

package/src/implementation/world/entity-lookup-workers.cases.ts

@@ -0,0 +1,19 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import type * as Fixture from "./entity-lookup-workers.fixture.js";
+
+/** Kernels' lookups by entity with `changed` across workers: the cases, over the fixture built for node or from source. */
+export const entityLookupWorkersCases = (load: () => Promise<typeof Fixture>) => describe("kernels' lookups by entity with changed on workers", () => {
+    it.each([[true], [false]])("give what a main-thread system gives, WASM %s", async wasm => {
+        const fixture = await load();
+        const alone = await fixture.simulate(0, wasm);
+        const one = await fixture.simulate(1, wasm);
+        const three = await fixture.simulate(3, wasm);
+        expect(alone.agree).toBe(true);
+        expect(one.agree).toBe(true);
+        expect(three.agree).toBe(true);
+        expect(one.rows).toEqual(alone.rows);
+        expect(three.rows).toEqual(alone.rows);
+        expect(three.tasks).toBeGreaterThan(0);
+    });
+});