@adobe/ecs 0.0.0-stage → 0.2.0

package/src/implementation/world/command-rings.fixture.ts

@@ -0,0 +1,180 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Entity } from "../../interface/entity/entity.js";
+import type { Schema } from "../../interface/schema/schema.js";
+import { System } from "../../interface/system/system.js";
+import type { World } from "../../interface/world/world.js";
+import { workers } from "../../interface/resources/workers.js";
+import { createWorld } from "./create.js";
+import { countingWorkers } from "./platforms.test-helper.js";
+import { read, readEach, select } from "./reads.test-helper.js";
+import { runOutcome } from "./outcomes.test-helper.js";
+import type { U32, Vec4 } from "../../interface/math/index.js";
+
+/** Scenarios of workers' command rings against the main thread alone, run built in node and from source in chromium. */
+
+const vec4 = { type: "array", items: { type: "number", precision: 1 }, minItems: 4, maxItems: 4 } as const satisfies Schema;
+
+const index = Symbol("commandRingsTest/index");
+const weight = Symbol("commandRingsTest/weight");
+const extent = Symbol("commandRingsTest/extent");
+const made = Symbol("commandRingsTest/made");
+const doomed = Symbol("commandRingsTest/doomed");
+const target = Symbol("commandRingsTest/target");
+const name = Symbol("commandRingsTest/name");
+const maybe = Symbol("commandRingsTest/maybe");
+const tally = Symbol("commandRingsTest/tally");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [index]: { type: U32 };
+        [weight]: { type: number };
+        [extent]: { type: Vec4 };
+        [made]: { type: U32 };
+        [doomed]: { type: true };
+        [target]: { type: Entity };
+        [name]: { type: string | null; default: "unnamed" };
+        [maybe]: { type: string | null };
+        [tally]: { type: number | null };
+    }
+}
+
+/** Objects: a nullable string starting at "unnamed", a nullable string, and a nullable number. */
+
+const seed = System.create({}, ({ commands }, input: { readonly count: number }) => {
+    for (let i = 0; i < input.count; i++) commands.spawn([index])({ [index]: i });
+});
+
+/**
+ * About 120 bytes of ring per row: two adds to the row, the later winning, a list add of a vec4, a spawn, and a despawn
+ * of every seventh spawn's row, so a run of a few thousand rows overflows a worker's ring.
+ */
+const burst = System.create({
+    kernel: true,
+    components: { with: [index] },
+}, (row, { commands }, input: { readonly shift: number }) => {
+    const i = row[index];
+    commands.add(row.entity, weight, -1);
+    commands.add(row.entity, weight, i + input.shift);
+    commands.add(row.entity, [extent, doomed], { [extent]: [i, i + 1, i + 2, input.shift] });
+    const spawned = commands.spawn([made])({ [made]: i });
+    if (i % 7 === 0) commands.despawn(spawned);
+});
+
+/** Every row's values and spawns, in a canonical order, since entity ids depend on reservation interleaving. */
+const burstState = async (world: World): Promise<readonly string[]> => {
+    const rows = await Promise.all((await select(world, { required: [index] })).map(entity => Promise.all([
+        read(world, entity, index), read(world, entity, weight), read(world, entity, extent), read(world, entity, doomed),
+    ])));
+    const spawned = await readEach(world, await select(world, { required: [made] }), made);
+    return [...rows.map(row => JSON.stringify(row)).sort(), JSON.stringify(spawned.sort((a, b) => Number(a) - Number(b)))];
+};
+
+/** Using `world`, then disposing it. */
+const using = async <T>(world: World, use: (world: World) => Promise<T>): Promise<T> => {
+    try {
+        return await use(world);
+    }
+    finally {
+        await world.dispose();
+    }
+};
+
+/**
+ * `burst` over 8,000 rows twice, and the completions that spilled after each: the first run's rings overflow, and the
+ * sync point grows them to what the run needed, so the second spills nothing more.
+ */
+export const overflow = (count: number): Promise<{ readonly rows: readonly string[]; readonly first: number; readonly second: number }> => {
+    const counting = countingWorkers();
+    return using(createWorld({ [workers]: count }, { minimumChunk: 64, pool: counting.platform }), async world => {
+        await world.run(seed, { count: 8_000 });
+        await world.run(burst, { shift: 1 });
+        const first = counting.spilled();
+        await world.run(burst, { shift: 2 });
+        return { rows: await burstState(world), first, second: counting.spilled() };
+    });
+};
+
+/** Rows targeting a live entity, but for the last, whose target never lived. */
+const targets = System.create({}, ({ commands }, input: { readonly count: number }) => {
+    const first = commands.spawn([index])({ [index]: 0 });
+    for (let i = 1; i < input.count; i++) commands.spawn([index, target])({ [index]: i, [target]: i === input.count - 1 ? Entity.none : first });
+});
+
+/** A spawn and an add for each row, then a read through its target, which throws at the last row, whose target is none. */
+const failing = System.create({
+    kernel: true,
+    components: { with: [index, target] },
+    lookup: { targets: { with: [index] } },
+}, (row, { lookup, commands }) => {
+    commands.spawn([made])({ [made]: row[index] });
+    commands.add(row.entity, weight, row[index]);
+    const other = lookup.targets(row[target]);
+    // @ts-expect-error the last row's target is none, so reading through it throws, as a kernel failing partway does
+    commands.add(row.entity, extent, [other[index], 0, 0, 0]);
+});
+
+type Failed = { readonly failures: readonly string[]; readonly rejected: string; readonly weights: readonly unknown[]; readonly extents: readonly string[]; readonly spawned: readonly unknown[] };
+
+/**
+ * The run's failures and what it rejected with, then every row's weight and extent, and the spawns, after `failing`
+ * throws at its last row.
+ */
+export const failed = (count: number): Promise<Failed> => using(createWorld({ [workers]: count }, { minimumChunk: 64 }), async world => {
+    await world.run(targets, { count: 1_000 });
+    const { outcome: report, error } = await runOutcome(world, failing);
+    const rows = await select(world, { required: [index] });
+    const spawned = await readEach(world, await select(world, { required: [made] }), made);
+    return {
+        failures: report.failures.map(failure => failure.name),
+        rejected: error instanceof Error ? error.message : String(error),
+        weights: (await readEach(world, rows, weight)).sort((a, b) => Number(a) - Number(b)),
+        extents: (await readEach(world, rows, extent)).map(value => JSON.stringify(value)).sort(),
+        spawned: spawned.sort((a, b) => Number(a) - Number(b)),
+    };
+});
+
+/** A spawn for every 64th row: each chunk uses one position of its block of eight and returns the rest. */
+const sparse = System.create({
+    kernel: true,
+    components: { with: [index], not: [made] },
+}, (row, { commands }) => {
+    if (row[index] % 64 === 0) commands.spawn([made])({ [made]: row[index] });
+});
+
+const many = System.create({}, ({ commands }) => {
+    for (let i = 0; i < 5_000; i++) commands.spawn([made])({ [made]: 1_000_000 + i });
+});
+
+/**
+ * Sparse spawns from workers over five runs, then 5,000 from the main thread, which reuse the positions blocks returned:
+ * how many entities have `made`, and how many of them are distinct. A position returned twice would be reserved twice.
+ */
+export const returned = (count: number): Promise<{ readonly spawned: number; readonly distinct: number }> => using(createWorld({ [workers]: count }, { minimumChunk: 64 }), async world => {
+    await world.run(seed, { count: 4_096 });
+    for (let run = 0; run < 5; run++) await world.run(sparse);
+    await world.run(many);
+    const entities = await select(world, { required: [made] });
+    return { spawned: entities.length, distinct: new Set(entities).size };
+});
+
+/** Object components from a kernel: left out, null, and a number, by add and by spawn. */
+const objects = System.create({
+    kernel: true,
+    components: { with: [index] },
+}, (row, { commands }) => {
+    const i = row[index];
+    commands.add(row.entity, [name, maybe, tally], { [maybe]: null, [tally]: i });
+    commands.spawn([made, name, maybe, tally])({ [made]: i, [tally]: null });
+});
+
+/** Each row's object components, then each spawn's, in index order. */
+export const objectValues = (count: number): Promise<readonly unknown[]> => using(createWorld({ [workers]: count }, { minimumChunk: 64 }), async world => {
+    await world.run(seed, { count: 1_000 });
+    await world.run(objects);
+    const rows = await select(world, { required: [index], order: { [index]: true } });
+    const spawned = await select(world, { required: [made], order: { [made]: true } });
+    return [
+        await readEach(world, rows, name), await readEach(world, rows, maybe), await readEach(world, rows, tally),
+        await readEach(world, spawned, name), await readEach(world, spawned, maybe), await readEach(world, spawned, tally),
+    ];
+});

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

@@ -0,0 +1,385 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import type { Essential } from "../../interface/component/value.js";
+import { Entity } from "../../interface/entity/entity.js";
+import { Rule } from "../../interface/rule/rule.js";
+import type { Schema } from "../../interface/schema/schema.js";
+import type { Commands } from "../../interface/system/commands.js";
+import { System } from "../../interface/system/system.js";
+import type { World } from "../../interface/world/world.js";
+import { workers } from "../../interface/resources/workers.js";
+import { Observe } from "../../observe/index.js";
+import { count, read, readEntity, select } from "./reads.test-helper.js";
+import { createWorld } from "./create.js";
+import { runReported } from "./outcomes.test-helper.js";
+import { recordDeclaration } from "../../interface/registry/ids.test-helper.js";
+import type { F32 } from "../../interface/math/index.js";
+
+type Vec3 = readonly [number, number, number];
+const vec3 = { type: "array", items: { type: "number", precision: 1 }, minItems: 3, maxItems: 3 } as const satisfies Schema;
+const position = Symbol("commandsTest/position");
+const score = Symbol("commandsTest/score");
+const health = Symbol("commandsTest/health");
+const label = Symbol("commandsTest/label");
+const tag = Symbol("commandsTest/tag");
+const other = Symbol("commandsTest/other");
+const slot = Symbol("commandsTest/slot");
+// Never declared, so never registered.
+const unregistered = Symbol("commandsTest/unregistered");
+const level = Symbol("commandsTest/level");
+const bit0 = Symbol("commandsTest/bit0");
+const bit1 = Symbol("commandsTest/bit1");
+const bit2 = Symbol("commandsTest/bit2");
+const bit3 = Symbol("commandsTest/bit3");
+const bits = [bit0, bit1, bit2, bit3] as const;
+declare module "@adobe/ecs" {
+    export interface Components {
+        [position]: { type: Schema.Type<{ type: "array"; items: { type: "number"; precision: 1 }; minItems: 3; maxItems: 3 }> };
+        [score]: { type: F32 };
+        [health]: { type: number };
+        [label]: { type: string | null };
+        [tag]: { type: true };
+        [other]: { type: true };
+        [slot]: { type: number; derived: true };
+        [bit0]: { type: true };
+        [bit1]: { type: true };
+        [bit2]: { type: true };
+        [bit3]: { type: true };
+    }
+    export interface Resources {
+        [level]: { type: number };
+    }
+}
+Rule.create({ components: { with: [other, score] }, derive: [slot] });
+
+const unit = [position, score, tag] as const;
+const made = [score, tag] as const;
+const marks = [other, label] as const;
+
+/** Every component of these tests an entity has, or `null` if it is dead. */
+const components = (world: World, entity: Entity) =>
+    Observe.toPromise(Observe.entity(world, entity, { optional: [position, score, health, label, tag, other, slot, bit0, bit1, bit2, bit3] }));
+
+/** Spawns and adds with literal values, which the plugin passes positionally, from one site over several lists. */
+const literals: Entity[] = [];
+const spawnLiterals = System.create({}, ({ commands }) => {
+    for (let i = 0; i < 6; i++) literals.push(commands.spawn(i % 3 === 0 ? defaulted : i % 3 === 1 ? made : [score, label])({ [score]: i }));
+});
+const addLiterals = System.create({ components: { with: [score], not: [health] } }, (row, { commands }) => {
+    commands.add(row.entity, [health, label], { [label]: "x", [health]: 5 });
+});
+
+const spawnFrom = System.create({ kernel: true, components: { with: [score], not: [tag, other] } }, (row, { commands }) => {
+    commands.spawn(made)({ [score]: row[score] + 10 });
+});
+const mark = System.create({ kernel: true, components: { with: [tag], not: [other] } }, (row, { commands }) => {
+    commands.add(row.entity, marks, {});
+});
+const unmark = System.create({ kernel: true, components: { with: [other] } }, (row, { commands }) => {
+    commands.remove(row.entity, marks);
+});
+const defaulted = [score, label, tag] as const;
+
+/** A world, and a function running `body` once in a system with the world's commands, rejecting with what it threw. */
+const withCommands = () => {
+    const world = createWorld({ [workers]: 0 });
+    let body: (commands: Commands) => void = () => {};
+    const issue = System.create({}, ({ commands }) => body(commands));
+    const run = async (next: (commands: Commands) => void): Promise<void> => {
+        body = next;
+        const [failure] = (await runReported(world, issue)).failures;
+        if (failure !== undefined) throw new Error(failure.message);
+    };
+    return { world, run };
+};
+
+describe("spawn", () => {
+    it("spawns exactly the components listed, through lists declared as const, made at runtime and inline", async () => {
+        const { world, run } = withCommands();
+        const plain: readonly Essential[] = [score, tag];
+        const spawned: Entity[] = [];
+        await run(commands => {
+            spawned.push(commands.spawn(unit)({ [position]: [1, 2, 3], [score]: 4 }));
+            spawned.push(commands.spawn(plain)({ [score]: 5 }));
+            spawned.push(commands.spawn([position, score])({ [position]: [6, 6, 6], [score]: 6 }));
+        });
+        expect(await components(world, spawned[0])).toEqual({ [position]: [1, 2, 3], [score]: 4, [tag]: true });
+        expect(await components(world, spawned[1])).toEqual({ [score]: 5, [tag]: true });
+        expect(await components(world, spawned[2])).toEqual({ [position]: [6, 6, 6], [score]: 6 });
+        await world.dispose();
+    });
+    it("spawns a list made at runtime as it is at each spawn, though it changed since the last", async () => {
+        const { world, run } = withCommands();
+        const changing: Essential[] = [score];
+        const spawned: Entity[] = [];
+        await run(commands => { spawned.push(commands.spawn(changing)({ [score]: 1 })); });
+        changing.push(tag);
+        await run(commands => { spawned.push(commands.spawn(changing)({ [score]: 2 })); });
+        expect(await components(world, spawned[0])).toEqual({ [score]: 1 });
+        expect(await components(world, spawned[1])).toEqual({ [score]: 2, [tag]: true });
+        await world.dispose();
+    });
+    it("gives lists made at runtime on every call one index per set of components, however many are made", async () => {
+        const { world, run } = withCommands();
+        const count = (): number => {
+            const value: unknown = Reflect.get(globalThis, Symbol.for("@adobe/ecs/archetypes@1"));
+            return typeof value === "number" ? value : 0;
+        };
+        // Fifteen subsets of four bits, more than are kept as recent, each list made afresh at every spawn.
+        const spawnAll = (commands: Commands): void => {
+            for (let subset = 1; subset < 16; subset++) commands.spawn(bits.filter((_, bit) => (subset & (1 << bit)) !== 0))({});
+        };
+        await run(spawnAll);
+        const before = count();
+        for (let round = 0; round < 20; round++) await run(spawnAll);
+        expect(count() - before).toBe(0);
+        await world.dispose();
+    });
+    it("fails only the systems using a key whose declaration failed, each time, never another key's", async () => {
+        const { world, run } = withCommands();
+        await run(() => {});
+        // As a module imported after the world exists records it.
+        const broken = Symbol("commandsTest/broken");
+        recordDeclaration(broken, "component", { type: { type: "number" }, reduce: "+" });
+        await run(commands => { commands.spawn([bit0])({}); });
+        for (let round = 0; round < 2; round++) {
+            // Undeclared to the types, so spawned as an untyped caller would.
+            await expect(run(commands => { Reflect.apply(Reflect.apply(commands.spawn, commands, [[broken]]), undefined, [{}]); })).rejects.toThrow("only a resource is reduced");
+        }
+        await world.dispose();
+    });
+    it("spawns a list made at runtime in each world that uses it", async () => {
+        const first = withCommands();
+        const second = withCommands();
+        const shared: readonly Essential[] = [score, tag];
+        const spawned: Entity[] = [];
+        for (let round = 0; round < 2; round++) {
+            await first.run(commands => { spawned.push(commands.spawn(shared)({ [score]: 1 })); });
+            await second.run(commands => { spawned.push(commands.spawn(shared)({ [score]: 2 })); });
+        }
+        expect(await components(first.world, spawned[2])).toEqual({ [score]: 1, [tag]: true });
+        expect(await components(second.world, spawned[3])).toEqual({ [score]: 2, [tag]: true });
+        await first.world.dispose();
+        await second.world.dispose();
+    });
+    it("starts a tag or a component whose type allows null, left out or given undefined, at true or null, never leaving it out", async () => {
+        const { world, run } = withCommands();
+        const spawned: Entity[] = [];
+        await run(commands => {
+            spawned.push(commands.spawn(defaulted)({ [score]: 1 }));
+            spawned.push(commands.spawn(defaulted)({ [score]: 2, [label]: undefined, [tag]: undefined }));
+            spawned.push(commands.spawn(defaulted)({ [score]: 3, [label]: "a", [tag]: true }));
+        });
+        expect(await Promise.all(spawned.map(entity => components(world, entity)))).toEqual([
+            { [score]: 1, [label]: null, [tag]: true },
+            { [score]: 2, [label]: null, [tag]: true },
+            { [score]: 3, [label]: "a", [tag]: true },
+        ]);
+        await world.dispose();
+    });
+    it("reads only the listed components' values", async () => {
+        const { world, run } = withCommands();
+        let spawned = Entity.none;
+        await run(commands => {
+            spawned = Reflect.apply(commands.spawn([score]), undefined, [{ [score]: 1, [position]: [1, 1, 1], [tag]: true, "commandsTest/score": 2 }]);
+        });
+        expect(await components(world, spawned)).toEqual({ [score]: 1 });
+        await world.dispose();
+    });
+    it("gives the same spawner for a world and set of components, from any system, for a new list or another order", async () => {
+        const { world, run } = withCommands();
+        const spawners: unknown[] = [];
+        await run(commands => {
+            spawners.push(commands.spawn(unit), commands.spawn(unit), commands.spawn([position, score, tag]), commands.spawn([score, tag, position]));
+        });
+        await run(commands => { spawners.push(commands.spawn(unit)); });
+        expect(spawners[1]).toBe(spawners[0]);
+        expect(spawners[2]).toBe(spawners[0]);
+        expect(spawners[4]).toBe(spawners[0]);
+        // A list in another order names the same components.
+        expect(spawners[3]).toBe(spawners[0]);
+        const another = withCommands();
+        await another.run(commands => { spawners.push(commands.spawn(unit)); });
+        expect(spawners[5]).not.toBe(spawners[0]);
+        await Promise.all([world.dispose(), another.world.dispose()]);
+    });
+    it("spawns into more archetypes than spawns cache, each with its values", async () => {
+        const { world, run } = withCommands();
+        const lists = Array.from({ length: 16 }, (_, set): (typeof score | (typeof bits)[number])[] => [score, ...bits.filter((_, bit) => (set & (1 << bit)) !== 0)]);
+        const archetypes = lists.map(list => [...list] as const);
+        const spawned: Entity[] = [];
+        await run(commands => {
+            for (let i = 0; i < 64; i++) spawned.push(commands.spawn(i % 2 === 0 ? archetypes[i % 16] : [...lists[i % 16]])({ [score]: i }));
+        });
+        for (let i = 0; i < 64; i++) {
+            expect(Object.getOwnPropertySymbols(await components(world, spawned[i])).length).toBe(1 + bits.filter((_, bit) => ((i % 16) & (1 << bit)) !== 0).length);
+            expect(await read(world, spawned[i], score)).toBe(i);
+        }
+        await world.dispose();
+    });
+    it("throws at first use for a key that isn't a registered component a command may add, or one listed twice", async () => {
+        const { world, run } = withCommands();
+        const tried = (list: readonly unknown[]) => run(commands => { Reflect.apply(commands.spawn, commands, [list]); });
+        await expect(tried([score, unregistered])).rejects.toThrow(`"commandsTest/unregistered" has no registered schema`);
+        await expect(tried([score, slot])).rejects.toThrow("is derived, so only rules add and remove it");
+        await expect(tried([level])).rejects.toThrow(`"commandsTest/level" is a resource, not a component`);
+        await expect(tried([score, score])).rejects.toThrow(`lists "commandsTest/score" twice`);
+        await expect(tried(["commandsTest/score"])).rejects.toThrow("a component's key is a symbol");
+        // Nothing spawned.
+        expect(await count(world, {})).toBe(0);
+        await world.dispose();
+    });
+});
+
+describe("literal values in a system's body", () => {
+    it("spawn and add through one site over several lists, starting what they leave out", async () => {
+        const world = createWorld({ [workers]: 0 });
+        literals.length = 0;
+        await world.run(spawnLiterals);
+        expect(await Promise.all(literals.map(entity => components(world, entity)))).toEqual([0, 1, 2, 3, 4, 5].map(i =>
+            i % 3 === 0 ? { [score]: i, [label]: null, [tag]: true } : i % 3 === 1 ? { [score]: i, [tag]: true } : { [score]: i, [label]: null }));
+        await world.run(addLiterals);
+        expect(await Promise.all(literals.map(entity => readEntity(world, entity, [score, health, label])))).toEqual([0, 1, 2, 3, 4, 5].map(i => ({ [score]: i, [health]: 5, [label]: "x" })));
+        await world.dispose();
+    });
+});
+
+/** Three adds of one component to each row, by systems ordered first to third, the second adding twice. */
+const first = System.create({ kernel: true, components: { with: [position] } }, (row, { commands }) => {
+    commands.add(row.entity, score, 1);
+});
+const second = System.create({ components: { with: [position] }, after: [first] }, (row, { commands }) => {
+    commands.add(row.entity, score, 2);
+    commands.add(row.entity, score, 3);
+});
+const third = System.create({ kernel: true, components: { with: [position] }, after: [second] }, (row, { commands }) => {
+    commands.add(row.entity, score, 4);
+});
+
+describe("add and remove", () => {
+    it("add one component with its value, a tag without one, or a list with its values and defaults", async () => {
+        const { world, run } = withCommands();
+        let entity = Entity.none;
+        await run(commands => { entity = commands.spawn([position])({ [position]: [0, 0, 0] }); });
+        await run(commands => {
+            commands.add(entity, score, 2);
+            commands.add(entity, tag);
+            commands.add(entity, [health, label, other], { [health]: 100 });
+        });
+        expect(await components(world, entity)).toEqual({ [position]: [0, 0, 0], [score]: 2, [tag]: true, [health]: 100, [label]: null, [other]: true, [slot]: 0 });
+        await run(commands => { commands.add(entity, [score, health], { [score]: 3, [health]: 4 }); });
+        expect(await readEntity(world, entity, [score, health])).toEqual({ [score]: 3, [health]: 4 });
+        await world.dispose();
+    });
+    it("apply in the order issued: of systems in schedule order, and in each by row, so a later add of a component wins", async () => {
+        const { world, run } = withCommands();
+        let entity = Entity.none;
+        await run(commands => { entity = commands.spawn([position, score])({ [position]: [0, 0, 0], [score]: 0 }); });
+        await world.run(System.create([third, first, second]));
+        expect(await read(world, entity, score)).toBe(4);
+        await world.run(System.create([second, first]));
+        expect(await read(world, entity, score)).toBe(3);
+        await world.dispose();
+    });
+    it("remove one component or a list", async () => {
+        const { world, run } = withCommands();
+        let entity = Entity.none;
+        await run(commands => { entity = commands.spawn([position, score, tag, other, health])({ [position]: [0, 0, 0], [score]: 1, [health]: 100 }); });
+        await run(commands => { commands.remove(entity, tag); });
+        expect(await components(world, entity)).toEqual({ [position]: [0, 0, 0], [score]: 1, [other]: true, [health]: 100, [slot]: 0 });
+        await run(commands => { commands.remove(entity, [other, health]); });
+        expect(await components(world, entity)).toEqual({ [position]: [0, 0, 0], [score]: 1 });
+        await world.dispose();
+    });
+    it("throw at first use for a key that isn't a component a command may add", async () => {
+        const { world, run } = withCommands();
+        let entity = Entity.none;
+        await run(commands => { entity = commands.spawn([score])({ [score]: 1 }); });
+        await expect(run(commands => { Reflect.apply(commands.add, commands, [entity, slot, 1]); })).rejects.toThrow("is derived");
+        await expect(run(commands => { Reflect.apply(commands.add, commands, [entity, [score, unregistered], {}]); })).rejects.toThrow("has no registered schema");
+        await expect(run(commands => { Reflect.apply(commands.remove, commands, [entity, [level]]); })).rejects.toThrow("is a resource, not a component");
+        // A kernel's command names a list declared in another module as if it were one component.
+        await expect(run(commands => { Reflect.apply(commands.remove, commands, [entity, [[score]]]); })).rejects.toThrow("A command names a list of components where one component's symbol goes.");
+        expect(await components(world, entity)).toEqual({ [score]: 1 });
+        await world.dispose();
+    });
+    it("move rows from several source archetypes in one sync point, keeping values, and stamping only what changed", async () => {
+        const { world, run } = withCommands();
+        const spawned: Entity[] = [];
+        await run(commands => {
+            for (let i = 0; i < 40; i++) spawned.push(commands.spawn(i % 2 === 0 ? [position, score] : [position, score, other])({ [position]: [i, i, i], [score]: i }));
+        });
+        const added: Entity[] = [];
+        const changed: Entity[] = [];
+        const watchAdded = System.create({ components: { with: [score], added: [tag] } }, row => { added.push(row.entity); });
+        const watchChanged = System.create({ components: { with: [score], changed: [position] } }, row => { changed.push(row.entity); });
+        const watch = System.create({ systems: [watchAdded, watchChanged] });
+        await world.run(watch);
+        added.length = changed.length = 0;
+        await run(commands => {
+            for (let i = 0; i < 40; i++) {
+                if (i % 4 < 2) commands.add(spawned[i], tag);
+                if (i % 4 === 3) commands.add(spawned[i], position, [-i, -i, -i]);
+                if (i % 5 === 0) commands.remove(spawned[i], [score]);
+            }
+        });
+        await world.run(watch);
+        const expected = spawned.filter((_, i) => i % 4 < 2 && i % 5 !== 0);
+        expect([...added].sort((a, b) => a - b)).toEqual(expected);
+        expect([...changed].sort((a, b) => a - b)).toEqual(spawned.filter((_, i) => i % 4 === 3 && i % 5 !== 0));
+        for (let i = 0; i < 40; i++) {
+            expect(await read(world, spawned[i], position)).toEqual(i % 4 === 3 ? [-i, -i, -i] : [i, i, i]);
+            expect(await read(world, spawned[i], score)).toBe(i % 5 === 0 ? null : i);
+            expect(await read(world, spawned[i], tag)).toBe(i % 4 < 2 ? true : null);
+        }
+        expect(await select(world, { required: [tag, other] })).toEqual(expect.arrayContaining(spawned.filter((_, i) => i % 4 === 1)));
+        await world.dispose();
+    });
+});
+
+describe("spawners where code can't be generated", () => {
+    it("loop over the values", 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 {
+            const { world, run } = withCommands();
+            const spawned: Entity[] = [];
+            await run(commands => {
+                for (let i = 0; i < 3; i++) spawned.push(commands.spawn([position, score, label, bit3])({ [position]: [i, i, i], [score]: i }));
+                const values = { [score]: 9, [label]: "a" };
+                spawned.push(commands.spawn([score, label])(values));
+            });
+            // A spawn with literal values in a system's body, which the plugin passes positionally.
+            const literal = System.create({}, ({ commands }) => {
+                spawned.push(commands.spawn([score, bit2, label])({ [label]: "b", [score]: 8 }));
+            });
+            await world.run(literal);
+            expect(await Promise.all(spawned.map(entity => components(world, entity)))).toEqual([
+                ...[0, 1, 2].map(i => ({ [position]: [i, i, i], [score]: i, [label]: null, [bit3]: true })),
+                { [score]: 9, [label]: "a" },
+                { [score]: 8, [label]: "b", [bit2]: true },
+            ]);
+            await world.dispose();
+        }
+        finally {
+            globalThis.Function = generate;
+        }
+    });
+});
+
+describe("kernels", () => {
+    it("spawn, add and remove through lists declared as const", async () => {
+        const { world, run } = withCommands();
+        await run(commands => { for (let i = 0; i < 3; i++) commands.spawn([score])({ [score]: i }); });
+        await world.run(spawnFrom);
+        const spawned = await select(world, { required: [score, tag] });
+        expect(await Promise.all(spawned.map(entity => components(world, entity)))).toEqual([10, 11, 12].map(value => ({ [score]: value, [tag]: true })));
+        await world.run(mark);
+        expect(await Promise.all(spawned.map(entity => components(world, entity)))).toEqual([10, 11, 12].map(value => ({ [score]: value, [tag]: true, [other]: true, [label]: null, [slot]: 0 })));
+        await world.run(unmark);
+        expect(await count(world, { required: [other] })).toBe(0);
+        expect(await count(world, { required: [tag, score] })).toBe(3);
+        await world.dispose();
+    });
+});

package/src/implementation/world/commands.ts

@@ -0,0 +1,100 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Commands } from '../../interface/system/commands.js';
+import { addCommand, despawnCommand, pushCommand, pushComponent, removeCommand, type CommandBuffer } from './buffer.js';
+import { listShapeOf, presetSpawnerOf, spawnerOf, type ListShape } from './lists.js';
+import { commandIdOf, idOf, storedShared, type Key, type State } from './state.js';
+
+const collect = (state: State, buffer: CommandBuffer, key: Key, value: unknown): void => {
+    if (value !== undefined) pushComponent(buffer, idOf(state, key), value);
+};
+
+/**
+ * Appends a command naming each own symbol key of `values` whose value isn't `undefined`, for the world's own changes
+ * to the resource entity. Ids are resolved first, so an unregistered key throws before anything is appended.
+ */
+export const pushValues = (state: State, buffer: CommandBuffer, kind: number, entity: number, values: object): void => {
+    const { count, named } = buffer;
+    pushCommand(buffer, kind, entity);
+    try {
+        const keys = Object.getOwnPropertySymbols(values);
+        for (let k = 0; k < keys.length; k++) collect(state, buffer, keys[k], Reflect.get(values, keys[k]));
+    }
+    catch (error) {
+        buffer.count = count;
+        buffer.named = named;
+        throw error;
+    }
+};
+
+/** Where a world's commands queue: on the commands object under a symbol, so prepared sites find it in one read. */
+export const commandsTarget = Symbol("commandsTarget");
+
+export type CommandsTarget = { readonly state: State; readonly target: { readonly buffer: CommandBuffer } };
+
+/** A list add naming shared components: each value checked and interned first, so one not of its type queues nothing. */
+const addShared = (state: State, buffer: CommandBuffer, entity: number, shape: ListShape, given: object): void => {
+    const { keys, ids, starts } = shape;
+    const values = keys.map((key, k) => {
+        const value: unknown = Reflect.get(given, key);
+        const start = value === undefined ? starts[k] : value;
+        return state.shared[ids[k]] === undefined ? start : storedShared(state, ids[k], start);
+    });
+    pushCommand(buffer, addCommand, entity);
+    buffer.shapes[buffer.count - 1] = shape.index;
+    for (let k = 0; k < keys.length; k++) pushComponent(buffer, ids[k], values[k]);
+};
+
+/** Values of a list add given none, which only an untyped caller does. */
+const empty = {};
+
+/**
+ * Commands that queue for the next sync point. A key that isn't a component commands may name throws here, inside the
+ * issuing system, before anything is queued. Values are immutable by convention, so they aren't copied.
+ */
+export const createCommands = (state: State, target: { readonly buffer: CommandBuffer }): Commands & { readonly [commandsTarget]: CommandsTarget } => ({
+    [commandsTarget]: { state, target },
+    // A second parameter rather than a rest one, which would allocate an array each call.
+    spawn: (components: readonly symbol[], preset?: unknown) => {
+        const shape = listShapeOf(state, components);
+        return typeof preset === "object" && preset !== null ? presetSpawnerOf(state, shape, preset) : spawnerOf(state, shape);
+    },
+    despawn: entity => {
+        pushCommand(target.buffer, despawnCommand, entity);
+    },
+    add: (entity: number, components: symbol | readonly symbol[], values?: unknown) => {
+        const { buffer } = target;
+        if (typeof components === "symbol") {
+            const id = commandIdOf(state, components);
+            const value = values === undefined ? state.starts[id] : values;
+            // A shared value chooses the archetype: one not of its type fails this system, queuing nothing.
+            const stored = state.shared[id] === undefined ? value : storedShared(state, id, value);
+            pushCommand(buffer, addCommand, entity);
+            pushComponent(buffer, id, stored);
+            return;
+        }
+        const shape = listShapeOf(state, components);
+        const { keys, ids, starts } = shape;
+        const given = typeof values === "object" && values !== null ? values : empty;
+        if (shape.shared.length > 0) return addShared(state, buffer, entity, shape, given);
+        pushCommand(buffer, addCommand, entity);
+        buffer.shapes[buffer.count - 1] = shape.index;
+        for (let k = 0; k < keys.length; k++) {
+            const value: unknown = Reflect.get(given, keys[k]);
+            pushComponent(buffer, ids[k], value === undefined ? starts[k] : value);
+        }
+    },
+    remove: (entity: number, components: symbol | readonly symbol[]) => {
+        const { buffer } = target;
+        if (typeof components === "symbol") {
+            const id = commandIdOf(state, components);
+            pushCommand(buffer, removeCommand, entity);
+            pushComponent(buffer, id, undefined);
+            return;
+        }
+        const shape = listShapeOf(state, components);
+        const { ids } = shape;
+        pushCommand(buffer, removeCommand, entity);
+        buffer.shapes[buffer.count - 1] = shape.index;
+        for (let k = 0; k < ids.length; k++) pushComponent(buffer, ids[k], undefined);
+    },
+});