@adobe/ecs 0.1.0 → 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

@@ -1,5 +1,6 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { expect, it } from "vitest";
-import { Component, Finalizer, Resource, System, World } from "../../index.js";
+import { Finalizer, System, World } from "../../index.js";
 import { Observe } from "../../observe/index.js";
 import { createWorld } from "../index.js";
 
@@ -13,24 +14,21 @@ declare module "@adobe/ecs" {
         [score]: { type: number };
     }
     interface Resources {
-        [journal]: { type: readonly string[] };
+        [journal]: { type: readonly string[]; default: [] };
     }
 }
 
-Component.register(name, { type: { type: "string" } });
-Component.register(score, { type: { type: "number" } });
-Resource.register(journal, { type: { type: "array", items: { type: "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({ name: "changesFinalizers/save", watch: [name, score], resources: { write: [journal] } }, (changes, { resources }) => {
+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({ name: "changesFinalizers/spawn" }, ({ commands }) => { commands.spawn([name, score])({ [name]: "ada", [score]: 3 }); });
-const retire = System.create({ name: "changesFinalizers/retire", components: { has: [score] } }, (row, { commands }) => { commands.remove(row.entity, score); });
+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();

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

@@ -1,4 +1,5 @@
-import { declarationOf, labelOf, labelOfItem } from '../../interface/registry/index.js';
+// © 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';
@@ -24,63 +25,76 @@ const exactly = (layout: Layout | null, leaves: readonly Path[]): boolean => {
 };
 
 /**
- * Checks a compiled kernel against its declaration and the registered schemas, which 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. Throws with the first mismatch.
+ * 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 checkKernel = (leaf: Leaf, description: KernelDescription): void => {
-    const { lookup, components: query, resources, up, reduce } = leaf.declaration;
-    const fail = (message: string): never => { throw new Error(`Kernel "${labelOfItem(leaf)}": ${message}`); };
+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)) fail(`reads resource "${labelOf(key)}", which isn't in resources.read.`);
+    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)) fail(`"${labelOf(column.component)}" isn't in its components' read or write.`);
-        if (column.kind === "changed" || column.kind === "chunks") {
-            if (!written.has(column.component)) fail(`writes "${labelOf(column.component)}", which isn't in its components' write.`);
+        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") fail(`"${labelOf(column.component)}" isn't stored in linear memory.`);
-        if (!hasLeaf(layout, column.path)) fail(`"${labelOf(column.component)}" has no scalar at [${column.path.join(", ")}]; destructure tuples and structs or index their fields.`);
+        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)) fail(`writes "${labelOf(shape.component)}", which isn't in its components' write.`);
-        if (!exactly(layoutOfKey(shape.component), shape.leaves)) fail(`a whole-value write of "${labelOf(shape.component)}" doesn't match its schema.`);
+        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) fail(`unknown lookup "${lookupName}".`);
-    if ((description.up === true) !== (up !== undefined)) fail(description.up === true ? "reads up, which its declaration doesn't declare." : "its declaration declares up, which it doesn't read.");
+    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)) fail(`reads "${labelOf(column.kind === "field" ? column.component : column.kind)}" through up, which isn't in up.read.`);
-        if (column.kind !== "field") continue;
+        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") fail(`up reads "${labelOf(column.component)}", which isn't stored in linear memory.`);
-        if (!hasLeaf(layout, column.path)) fail(`"${labelOf(column.component)}" has no scalar at [${column.path.join(", ")}]; destructure tuples and structs or index their fields.`);
+        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 (Reflect.get(reduce ?? {}, reduced.resource) !== reduced.operator) fail(`reduces "${labelOf(reduced.resource)}" with "${reduced.operator}", which its reduce doesn't declare.`);
-        if (!hasLeaf(layoutOfKey(reduced.resource), reduced.path)) fail(`contributes to "${labelOf(reduced.resource)}" at [${reduced.path.join(", ")}], which isn't a scalar of its value; destructure tuples and structs or build them.`);
+        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) {
-        list.forEach((k, position) => {
-            if (!Number.isInteger(k) || k < 0 || k >= description.keys.length) fail(`spawns a list naming component ${k} of its ${description.keys.length} keys.`);
-            if (list.findIndex(other => description.keys[other] === description.keys[k]) < position) fail(`spawns a list naming "${labelOf(description.keys[k])}" twice.`);
-        });
+        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") fail(`gives "${labelOf(key)}" a tuple or struct, which only a component stored in linear memory takes.`);
+        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 (Reflect.get(reduce ?? {}, shape.component) === undefined || !exactly(layoutOfKey(shape.component), shape.leaves)) {
-            fail(`contributes a value to "${labelOf(shape.component)}" that doesn't match its schema.`);
+        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

@@ -1,3 +1,4 @@
+// © 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";

package/src/implementation/world/claims.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { lineWords } from './protocol.js';
 
 /**

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

@@ -1,3 +1,4 @@
+// © 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";

package/src/implementation/world/closure.ts

@@ -1,3 +1,4 @@
+// © 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

package/src/implementation/world/command-ring.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { viewsOf, type Layout, type Views } from '../../interface/registry/layout.js';
 import { emptyViews } from './arrays.js';
 import { writeF32, writeF32Lanes, writeF64, writeI32, writeOf, writeU32 } from './archetype.js';
@@ -376,7 +377,7 @@ const decodeBatch = (views: Views, at: number, layouts: readonly Layout[], start
         }
         return { id, layout, ...writeOf(layout), stride, views: columnViews, values, remote: null };
     });
-    return { batch: { ids, archetype: null, columns, entities, count, capacity: count }, end: next };
+    return { batch: { ids, shared: [], archetype: null, columns, entities, count, capacity: count, revive: null, generation: 0 }, end: next };
 };
 
 /** Read-only by every drained buffer: no command names a list. Grown to the most commands one segment held. */

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

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, it } from "vitest";
 import type * as Fixture from "./command-rings.fixture.js";
 
@@ -17,8 +18,10 @@ export const commandRingsCases = (load: () => Promise<typeof Fixture>) => descri
     it("apply a failed task's commands and spawns from before its failure", async () => {
         const fixture = await load();
         const alone = await fixture.failed(0);
-        const { failures, weights, extents, spawned } = alone;
-        expect(failures).toEqual(["commandRingsTest/failing"]);
+        const { failures, rejected, weights, extents, spawned } = alone;
+        expect(failures).toEqual(["failing"]);
+        // The run rejects, naming the kernel, whichever thread it failed on.
+        expect(rejected).toMatch(/^System "failing" .*failed: /);
         // Every row but the first, which has no target, added its weight and spawned before reading its target; only
         // the last one's target is none.
         expect(weights).toEqual([null, ...Array.from({ length: 999 }, (_, i) => i + 1)]);

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

@@ -1,4 +1,4 @@
-import { Component } from "../../interface/component/component.js";
+// © 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";
@@ -7,7 +7,8 @@ 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 { runReported } from "./reports.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. */
 
@@ -25,30 +26,21 @@ const tally = Symbol("commandRingsTest/tally");
 
 declare module "@adobe/ecs" {
     export interface Components {
-        [index]: { type: number };
+        [index]: { type: U32 };
         [weight]: { type: number };
-        [extent]: { type: readonly [number, number, number, number] };
-        [made]: { type: number };
+        [extent]: { type: Vec4 };
+        [made]: { type: U32 };
         [doomed]: { type: true };
         [target]: { type: Entity };
-        [name]: { type: string | null };
+        [name]: { type: string | null; default: "unnamed" };
         [maybe]: { type: string | null };
         [tally]: { type: number | null };
     }
 }
 
-Component.register(index, { type: { type: "integer", minimum: 0, maximum: 0xFFFFFFFF } });
-Component.register(weight, { type: { type: "number" } });
-Component.register(extent, { type: vec4 });
-Component.register(made, { type: { type: "integer", minimum: 0, maximum: 0xFFFFFFFF } });
-Component.register(doomed, { type: { const: true } });
-Component.register(target, { type: Entity.schema });
 /** Objects: a nullable string starting at "unnamed", a nullable string, and a nullable number. */
-Component.register(name, { type: { anyOf: [{ type: "string" }, { type: "null" }], default: "unnamed" } });
-Component.register(maybe, { type: { anyOf: [{ type: "string" }, { type: "null" }] } });
-Component.register(tally, { type: { anyOf: [{ type: "number" }, { type: "null" }] } });
 
-const seed = System.create({ name: "commandRingsTest/seed", input: { type: "object", properties: { count: { type: "integer" } } } }, ({ input, commands }) => {
+const seed = System.create({}, ({ commands }, input: { readonly count: number }) => {
     for (let i = 0; i < input.count; i++) commands.spawn([index])({ [index]: i });
 });
 
@@ -57,11 +49,9 @@ const seed = System.create({ name: "commandRingsTest/seed", input: { type: "obje
  * of every seventh spawn's row, so a run of a few thousand rows overflows a worker's ring.
  */
 const burst = System.create({
-    name: "commandRingsTest/burst",
-    kernel: "cpu",
-    input: { type: "object", properties: { shift: { type: "number" } } },
-    components: { read: [index] },
-}, (row, { input, commands }) => {
+    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);
@@ -105,17 +95,16 @@ export const overflow = (count: number): Promise<{ readonly rows: readonly strin
 };
 
 /** Rows targeting a live entity, but for the last, whose target never lived. */
-const targets = System.create({ name: "commandRingsTest/targets", input: { type: "object", properties: { count: { type: "integer" } } } }, ({ input, commands }) => {
+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({
-    name: "commandRingsTest/failing",
-    kernel: "cpu",
-    components: { read: [index, target] },
-    lookup: { targets: { read: [index] } },
+    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]);
@@ -124,16 +113,20 @@ const failing = System.create({
     commands.add(row.entity, extent, [other[index], 0, 0, 0]);
 });
 
-type Failed = { readonly failures: readonly string[]; readonly weights: readonly unknown[]; readonly extents: readonly string[]; readonly spawned: readonly unknown[] };
+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, then every row's weight and extent, and the spawns, after `failing` throws at its last row. */
+/**
+ * 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 report = await runReported(world, failing);
+    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)),
@@ -142,14 +135,13 @@ export const failed = (count: number): Promise<Failed> => using(createWorld({ [w
 
 /** A spawn for every 64th row: each chunk uses one position of its block of eight and returns the rest. */
 const sparse = System.create({
-    name: "commandRingsTest/sparse",
-    kernel: "cpu",
-    components: { read: [index], not: [made] },
+    kernel: true,
+    components: { with: [index], not: [made] },
 }, (row, { commands }) => {
     if (row[index] % 64 === 0) commands.spawn([made])({ [made]: row[index] });
 });
 
-const many = System.create({ name: "commandRingsTest/many" }, ({ commands }) => {
+const many = System.create({}, ({ commands }) => {
     for (let i = 0; i < 5_000; i++) commands.spawn([made])({ [made]: 1_000_000 + i });
 });
 
@@ -167,9 +159,8 @@ export const returned = (count: number): Promise<{ readonly spawned: number; rea
 
 /** Object components from a kernel: left out, null, and a number, by add and by spawn. */
 const objects = System.create({
-    name: "commandRingsTest/objects",
-    kernel: "cpu",
-    components: { read: [index] },
+    kernel: true,
+    components: { with: [index] },
 }, (row, { commands }) => {
     const i = row[index];
     commands.add(row.entity, [name, maybe, tally], { [maybe]: null, [tally]: i });