@adobe/ecs 0.0.0-stage → 0.2.0

package/src/implementation/world/change-blocks.test.ts

@@ -0,0 +1,264 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Entity } from "../../interface/entity/entity.js";
+import { Index } from "../../interface/indexes/index-type.js";
+import type { I32 } from "../../interface/math/i32/index.js";
+import { workers } from "../../interface/resources/workers.js";
+import { System } from "../../interface/system/system.js";
+import type { World } from "../../interface/world/world.js";
+import { createWorld, join } from "./create.js";
+import { blockShift, chunkShift } from "./kernel.js";
+import { readEach, select } from "./reads.test-helper.js";
+import type { U32 } from "../../interface/math/index.js";
+
+// Change filters skip chunks and blocks whose ticks aren't newer than their `lastRun`, so every writer of a row's tick
+// raises its chunk's and block's. Each case writes a few rows far apart in an archetype of many chunks, through one
+// writer, and every kind of reader must find exactly those rows.
+
+const value = Symbol("changeBlocksTest/value");
+const at = Symbol("changeBlocksTest/at");
+const seen = Symbol("changeBlocksTest/seen");
+const group = Symbol("changeBlocksTest/group");
+const tagged = Symbol("changeBlocksTest/tagged");
+const note = Symbol("changeBlocksTest/note");
+const parent = Symbol("changeBlocksTest/parent");
+const extra = Symbol("changeBlocksTest/extra");
+const height = Symbol("changeBlocksTest/height");
+
+declare module "@adobe/ecs" {
+    interface Threads {
+        changeBlocksTest: true;
+    }
+    interface Components {
+        [value]: { type: number };
+        [at]: { type: U32 };
+        [seen]: { type: number };
+        [group]: { type: U32 };
+        [tagged]: { type: true };
+        [note]: { type: { readonly text: string } | null; thread: "changeBlocksTest"; default: { text: "none" } };
+        [parent]: { type: Entity; reference: "owner" };
+        [extra]: { type: number };
+        [height]: { type: number };
+    }
+}
+const text = { type: "object", properties: { text: { type: "string" } } } as const;
+
+/** Rows in the archetype: five chunks, the last partial. */
+const rows = 4500;
+const plain = [value, at, seen, group] as const;
+const marked = [value, at, seen, group, tagged] as const;
+const noted = [value, at, note] as const;
+
+let entities: Entity[] = [];
+const seed = System.create({}, ({ commands }) => {
+    entities = [];
+    for (let i = 0; i < rows; i++) entities.push(commands.spawn(plain)({ [value]: 0, [at]: i, [seen]: 0, [group]: 0 }));
+    // Rows an entity tagged later moves after, so it lands far into that archetype.
+    for (let i = rows; i < 2 * rows; i++) entities.push(commands.spawn(marked)({ [value]: 0, [at]: i, [seen]: 0, [group]: 0, [tagged]: true }));
+});
+
+// Writers.
+const setValue = System.create({ target: "entity", components: { with: [value] } }, (row, _context, input: { readonly entity: Entity }) => {
+    row[value] += 1;
+});
+const replace = System.create({}, ({ commands }, input: { readonly entities: readonly Entity[] }) => {
+    for (const entity of input.entities) commands.add(entity, value, 7);
+});
+const despawn = System.create({}, ({ commands }, input: { readonly entities: readonly Entity[] }) => {
+    for (const entity of input.entities) commands.despawn(entity);
+});
+const tag = System.create({}, ({ commands }, input: { readonly entities: readonly Entity[] }) => {
+    for (const entity of input.entities) commands.add(entity, tagged);
+});
+const spawnOne = System.create({}, ({ commands }, input: { readonly at: number }) => {
+    commands.spawn(plain)({ [value]: 0, [at]: input.at, [seen]: 0, [group]: 0 });
+});
+/** Writes the rows whose `at` is in a list of up to four, which stamps row by row. */
+const writeSome = System.create({ kernel: true, components: { with: [at, value] } }, (row, _context, input: { readonly a: I32; readonly b: I32; readonly c: I32; readonly d: I32 }) => {
+    const here = row[at];
+    if (here === input.a || here === input.b || here === input.c || here === input.d) row[value] += 1;
+});
+/** Writes every row, which stamps chunks and blocks once per call. */
+const writeAll = System.create({ kernel: true, components: { with: [value] } }, row => {
+    row[value] += 1;
+});
+const setGroup = System.create({ target: "entity", components: { with: [group] } }, (row, _context, input: { readonly entity: Entity }) => {
+    row[group] = 1;
+});
+
+// Readers.
+let found: number[] = [];
+const onMain = System.create({ components: { with: [at], changed: [value] } }, row => { found.push(row[at]); });
+const observed = System.create({ observer: true, components: { with: [at], changed: [value] } }, row => { found.push(row[at]); });
+const ofTwo = System.create({ components: { with: [at], changed: [group, value] } }, row => { found.push(row[at]); });
+const inKernel = System.create({ kernel: true, components: { with: [seen], changed: [value] } }, row => { row[seen] += 1; });
+const inUp = System.create({ components: { with: [at], changed: [value] }, up: { through: parent } }, row => { found.push(row[at]); });
+const byGroup = Index.create({ key: [group] });
+let grouped: number[] = [];
+const inGroup = System.create({ lookup: { byGroup: { index: byGroup } } }, ({ lookup }) => {
+    const list = lookup.byGroup(1);
+    grouped = Array.from({ length: list.length }, (_, i) => list.at(i).entity);
+});
+
+// On a joined thread, by the object they read: a writer, and readers of its writes and of the world's thread's.
+const seedNoted = System.create({}, ({ commands }) => {
+    entities = [];
+    for (let i = 0; i < rows; i++) entities.push(commands.spawn(noted)({ [value]: 0, [at]: i }));
+});
+const noteSome = System.create({ components: { with: [at, note] } }, (row, _context, input: { readonly ats: readonly number[] }) => {
+    if (input.ats.includes(row[at])) row[note] = { text: "noted" };
+});
+const notesThere = System.create({ components: { with: [at, note], changed: [note] } }, row => { if (row[note] !== undefined) found.push(row[at]); });
+const valuesThere = System.create({ components: { with: [at, note], changed: [value] } }, row => { if (row[note] !== undefined) found.push(row[at]); });
+
+/** The `at` of the rows a main-thread reader ran, in order. */
+const ranOn = async (world: World, reader: System): Promise<number[]> => {
+    found = [];
+    await world.run(reader);
+    return [...found].sort((a, b) => a - b);
+};
+
+/** The `at` of the rows the kernel reader ran, by the `seen` it raised. */
+const ranInKernel = async (world: World): Promise<number[]> => {
+    const all = await select(world, { required: [seen] });
+    const before = await readEach(world, all, seen);
+    await world.run(inKernel);
+    const after = await readEach(world, all, seen);
+    const ats = await readEach(world, all, at);
+    return all.flatMap((_, k) => after[k] !== before[k] ? [ats[k] ?? -1] : []).sort((a, b) => a - b);
+};
+
+const readers = { onMain, observed, ofTwo, inUp } as const;
+
+/** Every reader's rows after `write`, each having run once before, so each sees only what `write` changed. */
+const seenAfter = async (world: World, write: () => Promise<unknown>): Promise<{ readonly [reader: string]: readonly number[] }> => {
+    for (const reader of Object.values(readers)) await world.run(reader);
+    await world.run(inKernel);
+    await write();
+    const result: { [reader: string]: readonly number[] } = {};
+    for (const [name, reader] of Object.entries(readers)) result[name] = await ranOn(world, reader);
+    result.inKernel = await ranInKernel(world);
+    return result;
+};
+
+const every = (expected: readonly number[]) => ({ onMain: expected, observed: expected, ofTwo: expected, inUp: expected, inKernel: expected });
+
+/** Rows far apart: in the first block, a middle block of a middle chunk, and the last chunk's last block. */
+const spread = [5, (2 << chunkShift) + (5 << blockShift) + 9, rows - 1] as const;
+
+describe("chunk and block ticks", () => {
+    for (const wasm of [false, true]) {
+        const label = wasm ? "WASM" : "JS";
+        const inline = () => createWorld({ [workers]: 0 }, { wasm });
+
+        it(`let readers find rows a main-thread system wrote (${label} kernels)`, async () => {
+            await using world = inline();
+            await world.run(seed);
+            expect(await seenAfter(world, async () => {
+                for (const row of spread) await world.run(setValue, { entity: entities[row] });
+            })).toEqual(every(spread));
+        });
+
+        it(`let readers find rows a kernel wrote, row by row and once per call (${label} kernels)`, async () => {
+            await using world = inline();
+            await world.run(seed);
+            expect(await seenAfter(world, () => world.run(writeSome, { a: spread[0], b: spread[1], c: spread[2], d: -1 }))).toEqual(every(spread));
+            const all = Array.from({ length: 2 * rows }, (_, k) => k);
+            expect(await seenAfter(world, () => world.run(writeAll))).toEqual(every(all));
+        });
+
+        it(`let readers find rows commands wrote, moved, swapped into and spawned (${label} kernels)`, async () => {
+            await using world = inline();
+            await world.run(seed);
+            expect(await seenAfter(world, () => world.run(replace, { entities: spread.map(row => entities[row]) }))).toEqual(every(spread));
+            // The last row, changed, is swapped into the first block's despawned row.
+            const last = rows - 1;
+            expect(await seenAfter(world, async () => {
+                await world.run(setValue, { entity: entities[last] });
+                await world.run(despawn, { entities: [entities[3]] });
+            })).toEqual(every([last]));
+            // A changed row moves to the end of another archetype, past its first chunks.
+            const moved = spread[1];
+            expect(await seenAfter(world, async () => {
+                await world.run(setValue, { entity: entities[moved] });
+                await world.run(tag, { entities: [entities[moved]] });
+            })).toEqual(every([moved]));
+            expect(await seenAfter(world, () => world.run(spawnOne, { at: 9999 }))).toEqual(every([9999]));
+        });
+    }
+
+    it("let a filter of two components find a row only the other component changed in", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        await world.run(seed);
+        await world.run(ofTwo);
+        await world.run(setGroup, { entity: entities[spread[1]] });
+        expect(await ranOn(world, ofTwo)).toEqual([spread[1]]);
+    });
+
+    it("let systems on a joined thread find rows written there and on the world's thread", async () => {
+        const world = createWorld({ [workers]: 0 });
+        const channel = new MessageChannel();
+        const shared = world.share(channel.port1);
+        const remote = await join(channel.port2, { threads: ["changeBlocksTest"] });
+        try {
+            await shared;
+            await world.run(seedNoted);
+            await world.run(valuesThere);
+            await world.run(notesThere);
+            for (const row of spread) await world.run(setValue, { entity: entities[row] });
+            expect(await ranOn(world, valuesThere)).toEqual(spread);
+            await world.run(noteSome, { ats: [spread[1], spread[2]] });
+            expect(await ranOn(world, notesThere)).toEqual([spread[1], spread[2]]);
+        }
+        finally {
+            await remote.dispose();
+            await world.dispose();
+        }
+    });
+
+    it("let an index refresh find a key written in a block of a chunk", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        await world.run(seed);
+        await world.run(inGroup);
+        expect(grouped).toEqual([]);
+        await world.run(setGroup, { entity: entities[spread[1]] });
+        await world.run(inGroup);
+        expect(grouped).toEqual([entities[spread[1]]]);
+    });
+
+    it("let an added filter find a component a command added, and that row once swapped into an old block", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        await world.run(seedExtra);
+        await world.run(addedExtra);
+        // Rows `rows` and `rows + 1` gain the component and land after the archetype's rows, in its last block.
+        await world.run(addExtra, { entity: entities[rows] });
+        expect(await ranOn(world, addedExtra)).toEqual([rows]);
+        // Its last row, just added, moves into the first block's despawned row.
+        await world.run(addExtra, { entity: entities[rows + 1] });
+        await world.run(despawn, { entities: [entities[3]] });
+        expect(await ranOn(world, addedExtra)).toEqual([rows + 1]);
+    });
+
+    it("let filters find what a JS kernel reading up wrote on every row", async () => {
+        await using world = createWorld({ [workers]: 0 }, { wasm: false });
+        await world.run(seedExtra);
+        await world.run(heights);
+        await world.run(raiseHeights);
+        expect((await ranOn(world, heights)).length).toBe(rows + 2);
+    });
+});
+
+// Rows that have `extra` from the start, then two that gain it; and a JS `up` kernel writing every row's height.
+const seedExtra = System.create({}, ({ commands }) => {
+    entities = [];
+    for (let i = 0; i < rows; i++) entities.push(commands.spawn([at, extra, height])({ [at]: i, [extra]: 0, [height]: 0 }));
+    for (let i = rows; i < rows + 2; i++) entities.push(commands.spawn([at, height])({ [at]: i, [height]: 0 }));
+});
+const addExtra = System.create({}, ({ commands }, input: { readonly entity: Entity }) => {
+    commands.add(input.entity, extra, 1);
+});
+const addedExtra = System.create({ components: { with: [at], added: [extra] } }, row => { found.push(row[at]); });
+const raiseHeights = System.create({ kernel: true, components: { with: [height] }, up: { through: parent } }, (row, { up }) => {
+    row[height] = up === null ? 1 : up[height] + 1;
+});
+const heights = System.create({ components: { with: [at], changed: [height] } }, row => { found.push(row[at]); });

package/src/implementation/world/changes-finalizers.test.ts

@@ -0,0 +1,38 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { expect, it } from "vitest";
+import { Finalizer, System, World } from "../../index.js";
+import { Observe } from "../../observe/index.js";
+import { createWorld } from "../index.js";
+
+const name = Symbol("changesFinalizers/name");
+const score = Symbol("changesFinalizers/score");
+const journal = Symbol("changesFinalizers/journal");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [name]: { type: string };
+        [score]: { type: number };
+    }
+    interface Resources {
+        [journal]: { type: readonly string[]; default: [] };
+    }
+}
+
+
+// A changes finalizer sees each sync point's structural changes to the components it watches, grouped by how
+// they changed, with values before and after: for persistence, replication and undo.
+Finalizer.changes({ watch: [name, score] }, (changes, { resources }) => {
+    const lines = changes.groups.flatMap(group => group.entities.map(entity =>
+        `${changes.previous(entity, name) ?? changes.next(entity, name)}: +${group.added.length} -${group.removed.length} score ${changes.previous(entity, score)} → ${changes.next(entity, score)}`));
+    resources[journal] = [...resources[journal], ...lines];
+});
+
+const spawn = System.create({}, ({ commands }) => { commands.spawn([name, score])({ [name]: "ada", [score]: 3 }); });
+const retire = System.create({ components: { with: [score] } }, (row, { commands }) => { commands.remove(row.entity, score); });
+
+it("records each sync point's structural changes", async () => {
+    await using world = createWorld();
+    await world.run(spawn);
+    await world.run(retire);
+    expect(await Observe.toPromise(Observe.resource(world, journal))).toEqual(["ada: +2 -0 score null → 3", "ada: +0 -1 score 3 → null"]);
+});

package/src/implementation/world/check-kernel.ts

@@ -0,0 +1,100 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { declarationOf, labelOf } from '../../interface/registry/index.js';
+import { layoutOf, samePath, type Layout, type Path } from '../../interface/registry/layout.js';
+import type { Leaf } from '../../interface/system/leaf.js';
+import type { KernelDescription } from './kernel.js';
+import type { Key } from './state.js';
+
+/**
+ * A key's layout, or null for one this copy of the package didn't register, as a library bundling its own copy
+ * registers its keys: a world binding the kernel checks those.
+ */
+const layoutOfKey = (key: Key): Layout | null => {
+    const declaration = declarationOf(key);
+    return declaration === undefined ? null : layoutOf(declaration.type);
+};
+
+/** Whether `path` names a scalar leaf of `layout`; true for an unknown layout. */
+const hasLeaf = (layout: Layout | null, path: Path): boolean => layout === null || (layout.kind === "linear" && layout.leaves.some(leaf => samePath(leaf.path, path)));
+
+/** Whether `leaves` are every scalar leaf of `layout`, each once; true for an unknown layout. */
+const exactly = (layout: Layout | null, leaves: readonly Path[]): boolean => {
+    if (layout === null) return true;
+    const own = layout.kind === "linear" ? layout.leaves : [];
+    return own.length === leaves.length && own.every(leaf => leaves.some(path => samePath(path, leaf.path)));
+};
+
+/**
+ * How a compiled kernel doesn't match its declaration and the registered schemas, or null when it does. They don't
+ * depend on a world, so registering the kernel rejects it where it's declared: every column, whole-value write, lookup,
+ * `up` read and reduction it uses is declared, and names scalar leaves of its component's schema, each spawn site names
+ * each of its components once, from its keys, and a tuple or struct a command or spawn gives goes to a component
+ * stored in linear memory. The first mismatch.
+ */
+export const kernelMismatch = (leaf: Leaf, description: KernelDescription): string | null => {
+    const { lookup, components: query, resources, up } = leaf.declaration;
+    const reduces = new Set<Key>(resources?.reduce);
+    const queried = new Set<Key>([...query?.read ?? [], ...query?.write ?? []]);
+    const written = new Set<Key>(query?.write);
+    // A condition in `is` is readable too, and the compiler lists it with the reads.
+    const readable = new Set<Key>([...resources?.read ?? [], ...resources?.is ?? []]);
+    for (const key of description.resources) if (!readable.has(key)) return `reads resource "${labelOf(key)}", which isn't in resources.read.`;
+    for (const key of description.shared ?? []) {
+        if (!queried.has(key)) return `reads "${labelOf(key)}", which isn't in its components' read.`;
+        if (declarationOf(key) !== undefined && declarationOf(key)?.shared !== true) return `reads "${labelOf(key)}" as shared, which it isn't; rebuild.`;
+    }
+    for (const column of description.columns) {
+        if (column.kind === "entity") continue;
+        if (!queried.has(column.component)) return `"${labelOf(column.component)}" isn't in its components' read or write.`;
+        if (column.kind === "changed" || column.kind === "chunks" || column.kind === "blocks") {
+            if (!written.has(column.component)) return `writes "${labelOf(column.component)}", which isn't in its components' write.`;
+            continue;
+        }
+        if (column.kind === "present") continue;
+        const layout = layoutOfKey(column.component);
+        if (layout !== null && layout.kind !== "linear") return `"${labelOf(column.component)}" isn't stored in linear memory.`;
+        if (!hasLeaf(layout, column.path)) return `"${labelOf(column.component)}" has no scalar at [${column.path.join(", ")}]; destructure tuples and structs or index their fields.`;
+    }
+    for (const shape of description.shapes) {
+        if (!written.has(shape.component)) return `writes "${labelOf(shape.component)}", which isn't in its components' write.`;
+        if (!exactly(layoutOfKey(shape.component), shape.leaves)) return `a whole-value write of "${labelOf(shape.component)}" doesn't match its schema.`;
+    }
+    for (const lookupName of description.lookups) if (lookup?.[lookupName] === undefined) return `unknown lookup "${lookupName}".`;
+    if ((description.up === true) !== (up !== undefined)) return description.up === true ? "reads up, which its declaration doesn't declare." : "its declaration declares up, which it doesn't read.";
+    const upReadable = new Set<Key>(up?.read);
+    for (const column of description.upColumns ?? []) {
+        if (column.kind !== "field" || !upReadable.has(column.component)) return `reads "${labelOf(column.kind === "field" ? column.component : column.kind)}" through up, which isn't in up.read.`;
+        const layout = layoutOfKey(column.component);
+        if (layout !== null && layout.kind !== "linear") return `up reads "${labelOf(column.component)}", which isn't stored in linear memory.`;
+        if (!hasLeaf(layout, column.path)) return `"${labelOf(column.component)}" has no scalar at [${column.path.join(", ")}]; destructure tuples and structs or index their fields.`;
+    }
+    for (const reduced of description.reductions) {
+        if (!reduces.has(reduced.resource)) return `reduces "${labelOf(reduced.resource)}", which isn't in its resources' reduce.`;
+        if (declarationOf(reduced.resource)?.reduce !== reduced.operator) return `reduces "${labelOf(reduced.resource)}" with "${reduced.operator}", but it's declared reduce: "${labelOf(declarationOf(reduced.resource)?.reduce)}"; rebuild.`;
+        if (!hasLeaf(layoutOfKey(reduced.resource), reduced.path)) return `contributes to "${labelOf(reduced.resource)}" at [${reduced.path.join(", ")}], which isn't a scalar of its value; destructure tuples and structs or build them.`;
+    }
+    for (const list of description.spawns) {
+        for (let position = 0; position < list.length; position++) {
+            const k = list[position] ?? -1;
+            if (!Number.isInteger(k) || k < 0 || k >= description.keys.length) return `spawns a list naming component ${k} of its ${description.keys.length} keys.`;
+            if (list.findIndex(other => description.keys[other] === description.keys[k]) < position) return `spawns a list naming "${labelOf(description.keys[k])}" twice.`;
+        }
+    }
+    for (const k of description.structuredValues) {
+        const key = description.keys[k];
+        const layout = key === undefined ? null : layoutOfKey(key);
+        if (layout !== null && layout.kind !== "linear") return `gives "${labelOf(key)}" a tuple or struct, which only a component stored in linear memory takes.`;
+    }
+    for (const shape of description.reducedShapes) {
+        if (!reduces.has(shape.component) || !exactly(layoutOfKey(shape.component), shape.leaves)) {
+            return `contributes a value to "${labelOf(shape.component)}" that doesn't match its schema.`;
+        }
+    }
+    return null;
+};
+
+/** Throws with the first way a compiled kernel doesn't match its declaration and the registered schemas (`kernelMismatch`). */
+export const checkKernel = (leaf: Leaf, description: KernelDescription): void => {
+    const mismatch = kernelMismatch(leaf, description);
+    if (mismatch !== null) throw new Error(`Kernel "${leaf.name}": ${mismatch}`);
+};

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

@@ -0,0 +1,42 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { claimPiece, startRanges } from "./claims.js";
+import { lineWords } from "./protocol.js";
+
+const drain = (words: Int32Array, self: number, participants: number): number[] => {
+    const claimed: number[] = [];
+    for (let piece = claimPiece(words, self, participants); piece >= 0; piece = claimPiece(words, self, participants)) claimed.push(piece);
+    return claimed;
+};
+
+describe("claims", () => {
+    it("take the home range in order, then steal from the back of the fullest", () => {
+        const words = new Int32Array(new SharedArrayBuffer(3 * lineWords * 4));
+        startRanges(words, 3, 10);
+        // Ranges: 0..3, 3..6, 6..10.
+        expect(claimPiece(words, 1, 3)).toBe(3);
+        expect(claimPiece(words, 1, 3)).toBe(4);
+        expect(claimPiece(words, 1, 3)).toBe(5);
+        // Participant 2 has 4 left, more than participant 0's 3.
+        expect(claimPiece(words, 1, 3)).toBe(9);
+        expect(claimPiece(words, 1, 3)).toBe(2);
+        expect(drain(words, 0, 3)).toEqual([0, 1, 8, 7, 6]);
+        expect(claimPiece(words, 2, 3)).toBe(-1);
+    });
+
+    it("claim every piece exactly once however participants interleave", () => {
+        for (const [participants, pieces] of [[1, 1], [4, 3], [9, 72], [7, 100]]) {
+            const words = new Int32Array(new SharedArrayBuffer(participants * lineWords * 4));
+            startRanges(words, participants, pieces);
+            const claimed: number[] = [];
+            let active = participants;
+            for (let turn = 0; active > 0; turn = (turn * 5 + 3) % participants) {
+                const piece = claimPiece(words, turn, participants);
+                if (piece < 0) active--;
+                else claimed.push(piece);
+                if (claimed.length > pieces) break;
+            }
+            expect(claimed.sort((a, b) => a - b)).toEqual(Array.from({ length: pieces }, (_, i) => i));
+        }
+    });
+});

package/src/implementation/world/claims.ts

@@ -0,0 +1,51 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { lineWords } from './protocol.js';
+
+/**
+ * Pieces of a claimed split, as a home range per participant: one Int32 per participant, each on its own cache line,
+ * holding its next piece (`front`, low 16 bits) and the end of its range (`back`, high 16 bits). An owner takes pieces
+ * from its front, in order, so it streams forward through rows it ran last tier; a participant whose range is empty
+ * steals from the back of the fullest other range, so owner and thief meet only at the end. Every change is one
+ * compare-and-swap of the whole word, so a piece is claimed exactly once.
+ */
+
+/** Split pieces into at most 32767, so a range's bounds fit its word. */
+export const maximumPieces = 0x7fff;
+
+const rangeWord = (front: number, back: number): number => (back << 16) | front;
+
+/** Gives each of `participants` an equal home range of `pieces`, in order. */
+export const startRanges = (words: Int32Array, participants: number, pieces: number): void => {
+    for (let i = 0; i < participants; i++) {
+        Atomics.store(words, i * lineWords, rangeWord(Math.floor(i * pieces / participants), Math.floor((i + 1) * pieces / participants)));
+    }
+};
+
+/** Claims the next piece for participant `self`: its own front, else the back of the fullest other range; -1 once none are left. */
+export const claimPiece = (words: Int32Array, self: number, participants: number): number => {
+    for (;;) {
+        const own = Atomics.load(words, self * lineWords);
+        const front = own & 0xffff;
+        const back = own >>> 16;
+        if (front < back) {
+            if (Atomics.compareExchange(words, self * lineWords, own, rangeWord(front + 1, back)) === own) return front;
+            continue;
+        }
+        let victim = -1;
+        let most = 0;
+        let word = 0;
+        for (let i = 0; i < participants; i++) {
+            if (i === self) continue;
+            const other = Atomics.load(words, i * lineWords);
+            const left = (other >>> 16) - (other & 0xffff);
+            if (left > most) {
+                most = left;
+                victim = i;
+                word = other;
+            }
+        }
+        if (victim < 0) return -1;
+        const last = (word >>> 16) - 1;
+        if (Atomics.compareExchange(words, victim * lineWords, word, rangeWord(word & 0xffff, last)) === word) return last;
+    }
+};

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

@@ -0,0 +1,40 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { strataOf, type RuleFacts } from "../../interface/registry/strata.js";
+import { closedComponents } from "./closure.js";
+
+// Components 0 to 9: 0 mesh, 1 transform, 2 hidden, 3 slot (derived), 4 ready (within slot), 5 visible (derived), 6 resident (derived), 7 sprite.
+const derived = [false, false, false, true, false, true, true, false];
+const hosts = [-1, -1, -1, -1, 3, -1, -1, -1];
+const name = (id: number): string => `c${id}`;
+const rule = (has: number[], not: number[], derives: number[]): RuleFacts => ({ has, not, derives });
+const closure = (rules: readonly RuleFacts[], components: number[]): number[] => closedComponents(components, derived, hosts, strataOf(rules, hosts, name));
+
+describe("closure", () => {
+    const slots = rule([0, 1], [2], [3]);
+    it("derives where a rule matches, and drops what no rule derives", () => {
+        expect(closure([slots], [0, 1])).toEqual([0, 1, 3]);
+        expect(closure([slots], [0, 1, 2, 3])).toEqual([0, 1, 2]);
+        expect(closure([slots], [0, 3])).toEqual([0]);
+    });
+    it("keeps a component within its host only while the host is present", () => {
+        expect(closure([slots], [0, 1, 3, 4])).toEqual([0, 1, 3, 4]);
+        expect(closure([slots], [0, 1, 2, 3, 4])).toEqual([0, 1, 2]);
+    });
+    it("chains rules and unions owners, after the strata their negations read", () => {
+        const visible = rule([3], [], [5]);
+        const fromSprite = rule([7], [], [5]);
+        const resident = rule([5], [4], [6]);
+        expect(closure([slots, visible, fromSprite, resident], [0, 1])).toEqual([0, 1, 3, 5, 6]);
+        expect(closure([slots, visible, fromSprite, resident], [0, 1, 4])).toEqual([0, 1, 3, 4, 5]);
+        expect(closure([slots, visible, fromSprite, resident], [7])).toEqual([5, 6, 7]);
+    });
+    it("is a least fixed point: positive cycles derive nothing on their own", () => {
+        expect(closure([rule([5], [], [6]), rule([6], [], [5])], [0])).toEqual([0]);
+        expect(closure([rule([5], [], [6]), rule([6], [], [5]), rule([0], [], [5])], [0])).toEqual([0, 5, 6]);
+    });
+    it("rejects cycles through a negation or within", () => {
+        expect(() => strataOf([rule([], [6], [5]), rule([5], [], [6])], hosts, name)).toThrow("cycle through a negation, which could oscillate: c5, c6");
+        expect(() => strataOf([rule([4], [], [3])], hosts, name)).toThrow("within each other in a cycle: c3, c4");
+    });
+});

package/src/implementation/world/closure.ts

@@ -0,0 +1,41 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * Structural derivation: which components an archetype's entities have once rules and `within` are applied.
+ * Datalog with stratified negation over the components each entity has. A rule adds the components it derives where
+ * its query matches; a component declared within a host stays only while the host is present. Each stratum is a least
+ * fixed point, evaluated after every stratum it depends on, so the result is a pure function of the archetype.
+ */
+
+import type { Strata } from '../../interface/registry/strata.js';
+
+/**
+ * The sorted components an entity with `components` has once derived: derived components only where a rule derives
+ * them, and components within a host only where the host is.
+ */
+export const closedComponents = (components: readonly number[], derived: readonly boolean[], hosts: readonly number[], strata: Strata): number[] => {
+    const present = new Set<number>();
+    const given = new Set<number>();
+    for (const id of components) {
+        if ((hosts[id] ?? -1) >= 0) given.add(id);
+        else if (derived[id] !== true) present.add(id);
+    }
+    for (const { rules, within } of strata) {
+        for (let changed = true; changed;) {
+            changed = false;
+            for (const rule of rules) {
+                if (!rule.has.every(id => present.has(id)) || rule.not.some(id => present.has(id))) continue;
+                for (const id of rule.derives) {
+                    if (present.has(id)) continue;
+                    present.add(id);
+                    changed = true;
+                }
+            }
+            for (const { dependent, host } of within) {
+                if (present.has(dependent) || !given.has(dependent) || !present.has(host)) continue;
+                present.add(dependent);
+                changed = true;
+            }
+        }
+    }
+    return [...present].sort((a, b) => a - b);
+};