@adobe/ecs 0.1.0 → 0.2.0

package/src/implementation/world/index-joined.test.ts

@@ -1,5 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, it } from "vitest";
-import { Component } from "../../interface/component/component.js";
 import type { Entity } from "../../interface/entity/entity.js";
 import { Index } from "../../interface/indexes/index-type.js";
 import { Observe } from "../../observe/index.js";
@@ -10,7 +10,8 @@ import { System } from "../../interface/system/system.js";
 import type { World } from "../../interface/world/world.js";
 import { createWorld, join, type CreatedWorld } from "./create.js";
 import { backToBack } from "./loop.js";
-import { dropReports, runReported } from "./reports.test-helper.js";
+import { runReported } from "./outcomes.test-helper.js";
+import type { U32, Vec2 } from "../../interface/math/index.js";
 
 // Systems on a joined thread looking up through the world's indexes, the world and the thread on this one, against a
 // world running them itself.
@@ -24,45 +25,103 @@ const rank = Symbol("indexJoinedTest/rank");
 const label = Symbol("indexJoinedTest/label");
 const name = Symbol("indexJoinedTest/name");
 const title = Symbol("indexJoinedTest/title");
+const band = Symbol("indexJoinedTest/band");
+const bandReader = Symbol("indexJoinedTest/bandReader");
+const marked = Symbol("indexJoinedTest/marked");
 
 declare module "@adobe/ecs" {
     export interface Threads {
         indexJoinedTest: true;
     }
     interface Components {
-        [cell]: { type: readonly [number, number] };
+        [cell]: { type: Vec2.I32 };
         [weight]: { type: number };
-        [serial]: { type: number };
-        [target]: { type: number };
-        [lane]: { type: number };
+        [serial]: { type: U32 };
+        [target]: { type: U32 };
+        [lane]: { type: U32 };
         [rank]: { type: number };
-        [label]: { type: { readonly text: string }; thread: "indexJoinedTest" };
+        [label]: { type: Label; thread: "indexJoinedTest" };
         [name]: { type: { readonly text: string }; thread: "indexJoinedTest" };
         [title]: { type: string };
+        [band]: { type: U32 };
+        [bandReader]: { type: true };
+        [marked]: { type: true };
     }
 }
-Component.register(cell, { type: { type: "array", items: { type: "integer", minimum: -1000, maximum: 1000 }, minItems: 2, maxItems: 2 } });
-Component.register(weight, { type: { type: "number" } });
-Component.register(serial, { type: { type: "integer", minimum: 0, maximum: 1000000 } });
-Component.register(target, { type: { type: "integer", minimum: 0, maximum: 1000000 } });
-Component.register(lane, { type: { type: "integer", minimum: 0, maximum: 1000 } });
-Component.register(rank, { type: { type: "number" } });
 const text = { type: "object", properties: { text: { type: "string" } } } as const;
 /** A label's start, which a command here gives it by this value. */
-const blank = { text: "" };
-Component.register(label, { type: { ...text, default: blank }, thread: "indexJoinedTest" });
-Component.register(name, { type: text, thread: "indexJoinedTest" });
-Component.register(title, { type: { type: "string" } });
+const blank = { text: "" } as const;
+/** A label, which starts as `blank`, the value commands on other threads give it by identity. */
+type Label = { readonly text: string };
+const Label = { default: blank };
 
-const grid = Index.create({ name: "indexJoinedTest/grid", key: [cell], components: { has: [weight] } });
-const serials = Index.create({ name: "indexJoinedTest/serials", key: [serial], unique: true, components: { has: [weight] } });
-const lanes = Index.create({ name: "indexJoinedTest/lanes", key: [lane, rank], sorted: true });
-const names = Index.create({ name: "indexJoinedTest/names", key: [name] });
-const titles = Index.create({ name: "indexJoinedTest/titles", key: [title] });
-const weighted = Index.create({ name: "indexJoinedTest/weighted", key: [], components: { has: [weight] } });
+const grid = Index.create({ key: [cell], components: { with: [weight] } });
+const serials = Index.create({ key: [serial], unique: true, components: { with: [weight] } });
+const lanes = Index.create({ key: [lane, rank], sorted: true });
+const names = Index.create({ key: [name] });
+const titles = Index.create({ key: [title] });
+const weighted = Index.create({ key: [], components: { with: [weight] } });
+/** Two long buckets, which changes leave unsorted until a list is read by position. */
+const bands = Index.create({ key: [band], components: { with: [serial] } });
+
+/** On the joined thread: the serials of a band's rows, in entity order. */
+const describeBand = System.create({
+    components: { with: [target, label, bandReader] },
+    lookup: { inBand: { index: bands } },
+}, (row, { lookup }) => {
+    const list = lookup.inBand(row[target]);
+    const serials: number[] = [];
+    for (let i = 0; i < list.length; i++) serials.push(list.at(i)[serial]);
+    row[label] = { text: `${row[target]}:${serials.join(",")}` };
+});
+const seedBands = System.create({}, ({ commands }) => {
+    for (let k = 0; k < 300; k++) commands.spawn([band, serial])({ [band]: k % 2, [serial]: k });
+    for (let k = 0; k < 2; k++) commands.spawn([target, label, bandReader])({ [target]: k, [label]: blank });
+});
+/** Moves some entities to the other band, despawns some and spawns others. */
+const stirBands = System.create({ components: { with: [serial, band] } }, (row, { commands }, input: { readonly round: number }) => {
+    if ((row[serial] + input.round) % 7 === 0) row[band] = 1 - row[band];
+    if ((row[serial] + input.round) % 29 === 0) commands.despawn(row.entity);
+    if (row[serial] % 31 === input.round) commands.spawn([band, serial])({ [band]: row[serial] % 2, [serial]: 1000 + row[serial] * 10 + input.round });
+});
+/** An observer system of the joined thread's labels: the serials of each reader's band, in entity order, by reader. */
+let observedBands: string[] = [];
+const observeBands = System.create({
+    observer: true,
+    components: { with: [target, bandReader, label] },
+    lookup: { inBand: { index: bands } },
+}, (row, { lookup }) => {
+    const list = lookup.inBand(row[target]);
+    const serials: number[] = [];
+    for (let i = 0; i < list.length; i++) serials.push(list.at(i)[serial]);
+    observedBands[row[target]] = serials.join(",");
+});
+/** Seeds the bands, then observes them where `holder` runs observer systems, around changes; what it saw each time. */
+const observedBandScenario = async (world: CreatedWorld, holder: World): Promise<readonly (readonly string[])[]> => {
+    const seen: (readonly string[])[] = [];
+    await world.run(seedBands);
+    for (let round = 0; round < 6; round++) {
+        await world.run(stirBands, { round });
+        observedBands = [];
+        await holder.run(observeBands);
+        seen.push([...observedBands]);
+    }
+    return seen;
+};
+/** Seeds the bands, then reads them on the thread around changes; every label after each read. */
+const bandScenario = async (world: CreatedWorld, holder: World): Promise<readonly (readonly string[])[]> => {
+    const seen: (readonly string[])[] = [];
+    await world.run(seedBands);
+    for (let round = 0; round < 6; round++) {
+        await world.run(describeBand);
+        seen.push(await labels(holder, world));
+        await world.run(stirBands, { round });
+    }
+    return seen;
+};
 
 /** On the joined thread, in the tier before the lookups, so a task of consecutive tiers there would see the index before it: moves some cells. */
-const shift = System.create({ name: "indexJoinedTest/shift", components: { read: [serial], write: [cell, label] } }, row => {
+const shift = System.create({ components: { with: [serial, cell, label] } }, row => {
     if (row[serial] % 17 !== 0) return;
     const [x, y] = row[cell];
     row[cell] = [(x + 1) % 13, y];
@@ -71,9 +130,8 @@ const shift = System.create({ name: "indexJoinedTest/shift", components: { read:
 
 /** On the joined thread: each cell's neighbors' count and weights, whether its list changed, and its serial's target's weight. */
 const describeCells = System.create({
-    name: "indexJoinedTest/describeCells",
-    components: { read: [cell, target], write: [label] },
-    lookup: { near: { index: grid, read: [weight], changed: [weight] }, bySerial: { index: serials, read: [weight] }, all: { index: weighted, read: [weight] } },
+    components: { with: [cell, target, label] },
+    lookup: { near: { index: grid, changed: [weight] }, bySerial: { index: serials }, all: { index: weighted } },
     after: [shift],
 }, (row, { lookup }) => {
     const [x, y] = row[cell];
@@ -95,9 +153,8 @@ const describeCells = System.create({
 
 /** On the joined thread: the rows of the row's lane within 5 of its rank, in key order. */
 const describeRanks = System.create({
-    name: "indexJoinedTest/describeRanks",
-    components: { read: [lane, rank], write: [label] },
-    lookup: { inLane: { index: lanes, read: [rank] } },
+    components: { with: [lane, rank, label] },
+    lookup: { inLane: { index: lanes } },
     after: [describeCells],
 }, (row, { lookup }) => {
     const r = row[rank];
@@ -107,29 +164,28 @@ const describeRanks = System.create({
     row[label] = { text: ranks.join(",") };
 });
 
-const tick = System.create({ name: "indexJoinedTest/tick", systems: [shift, describeCells, describeRanks] });
+const tick = System.create({ systems: [shift, describeCells, describeRanks] });
 
-const seed = System.create({ name: "indexJoinedTest/seed" }, ({ commands }) => {
+const seed = System.create({}, ({ commands }) => {
     for (let k = 0; k < 200; k++) commands.spawn([cell, weight, serial, target, label])({ [cell]: [k % 13, k % 7], [weight]: k % 5, [serial]: k, [target]: (k * 7) % 230, [label]: blank });
     for (let k = 0; k < 150; k++) commands.spawn([lane, rank, label])({ [lane]: k % 3, [rank]: (k * 37) % 97, [label]: blank });
 });
 
 /** Moves cells, changes weights and ranks, despawns some and spawns others. */
-const stir = System.create({ name: "indexJoinedTest/stir", input: { type: "object", properties: { round: { type: "integer" } } }, components: { read: [serial], write: [cell, weight] } }, (row, { input, commands }) => {
+const stir = System.create({ components: { with: [serial, cell, weight] } }, (row, { commands }, input: { readonly round: number }) => {
     const [x, y] = row[cell];
     if ((row[serial] + input.round) % 9 === 0) row[cell] = [(x + 1) % 13, y];
     if ((row[serial] + input.round) % 11 === 0) row[weight] = row[weight] + 1;
     if ((row[serial] + input.round) % 23 === 0) commands.despawn(row.entity);
     if (row[serial] % 50 === input.round) commands.spawn([cell, weight, serial, target, label])({ [cell]: [input.round, 3], [weight]: 2, [serial]: 1000 + row[serial], [target]: row[serial], [label]: blank });
 });
-const rerank = System.create({ name: "indexJoinedTest/rerank", input: { type: "object", properties: { round: { type: "integer" } } }, components: { write: [rank] } }, (row, { input }) => {
+const rerank = System.create({ components: { with: [rank] } }, (row, _context, input: { readonly round: number }) => {
     if ((row[rank] + input.round) % 5 === 0) row[rank] = (row[rank] * 3 + 1) % 97;
 });
 
 /** A system of the joined thread looking up through an index of its strings, which the world keeps on its own thread. */
 const byName = System.create({
-    name: "indexJoinedTest/byName",
-    components: { read: [name], write: [label] },
+    components: { with: [name, label] },
     lookup: { named: { index: names } },
 }, (row, { lookup }) => {
     row[label] = { text: String(lookup.named(row[name]).length) };
@@ -137,41 +193,40 @@ const byName = System.create({
 
 /** On the joined thread, added and removed: labels each cell by its bucket's length. */
 const counting = System.create({
-    name: "indexJoinedTest/counting",
-    components: { read: [cell], write: [label] },
+    components: { with: [cell, label] },
     lookup: { near: { index: grid, changed: [weight] } },
 }, (row, { lookup }) => {
     const [x, y] = row[cell];
     row[label] = { text: String(lookup.near([x, y]).length) };
 });
-const keepTicking = System.create({ name: "indexJoinedTest/keepTicking" }, () => {});
+const keepTicking = System.create({}, () => {});
 
-const ranks = Index.create({ name: "indexJoinedTest/ranks", key: [rank], sorted: true });
+const ranks = Index.create({ key: [rank], sorted: true });
 /** Systems of the joined thread writing a string, and looking up by strings, which only the world's thread does. */
-const writeTitle = System.create({ name: "indexJoinedTest/writeTitle", components: { read: [label], write: [title] } }, row => {
+const writeTitle = System.create({ components: { with: [label, title] } }, row => {
     row[title] = row[label].text;
 });
-const byTitle = System.create({ name: "indexJoinedTest/byTitle", components: { read: [title], write: [label] }, lookup: { titled: { index: titles } } }, (row, { lookup }) => {
+const byTitle = System.create({ components: { with: [title, label] }, lookup: { titled: { index: titles } } }, (row, { lookup }) => {
     row[label] = { text: String(lookup.titled(row[title]).length) };
 });
 
 /** A system of the joined thread whose rows are in an index's order, which runs only on the world's thread. */
-const inOrder = System.create({ name: "indexJoinedTest/inOrder", components: { read: [rank], write: [label] }, order: ranks }, row => {
+const inOrder = System.create({ components: { with: [rank, label] }, order: ranks }, row => {
     row[label] = { text: String(row[rank]) };
 });
 
 /** Systems on the joined thread and an observer system of its objects, each with an index as a change filter, which run only on the world's thread. */
-const countWhenMoved = System.create({ name: "indexJoinedTest/countWhenMoved", components: { read: [cell], write: [label] }, lookup: { near: { index: grid, changed: true } } }, (row, { lookup }) => {
+const countWhenMoved = System.create({ components: { with: [cell, label] }, lookup: { near: { index: grid, changed: true } } }, (row, { lookup }) => {
     row[label] = { text: String(lookup.near(row[cell]).length) };
 });
-const readWhenMoved = System.create({ name: "indexJoinedTest/readWhenMoved", observer: true, components: { read: [label] }, lookup: { near: { index: grid, changed: true } } }, row => {
+const readWhenMoved = System.create({ observer: true, components: { with: [label] }, lookup: { near: { index: grid, changed: true } } }, row => {
     void row[label];
 });
-const ownWhenMoved = System.create({ name: "indexJoinedTest/ownWhenMoved", observer: true, lookup: { near: { index: grid, changed: true } } }, () => {});
+const ownWhenMoved = System.create({ observer: true, lookup: { near: { index: grid, changed: true } } }, () => {});
 
 /** The entities `readLabels` reads, and their labels. */
 const reading: { entities: readonly Entity[]; labels: readonly string[] } = { entities: [], labels: [] };
-const readLabels = System.create({ name: "indexJoinedTest/readLabels", observer: true, lookup: { labeled: { read: [label] } } }, ({ lookup }) => {
+const readLabels = System.create({ observer: true, lookup: { labeled: { with: [label] } } }, ({ lookup }) => {
     reading.labels = reading.entities.map(entity => lookup.labeled(entity)?.[label].text ?? "missing");
 });
 
@@ -191,7 +246,6 @@ const scenario = async (world: CreatedWorld, holder: World): Promise<{ readonly
         const report = await runReported(world, tick);
         expect(report.failures).toEqual([]);
         warnings.push(report.warnings.map(warning => warning.name));
-        await world.run(dropReports);
         seen.push(await labels(holder, world));
         await world.run(stir, { round });
         await world.run(rerank, { round });
@@ -199,16 +253,78 @@ const scenario = async (world: CreatedWorld, holder: World): Promise<{ readonly
     return { labels: seen, warnings };
 };
 
-/** Once the last thread shared has joined. */
-const joinedStatus = (world: CreatedWorld): Promise<void> => new Promise(resolve => {
-    let done = false;
-    const stop = world.threads(threads => {
-        if (done || threads.at(-1)?.status !== "joined") return;
-        done = true;
-        queueMicrotask(() => stop());
-        resolve();
-    });
+/** Entities a keyless and a unique index hold, each with this thread's label and a string title. */
+const seedHeld = System.create({}, ({ commands }, input: { readonly from: number; readonly count: number }) => {
+    for (let k = input.from; k < input.from + input.count; k++) commands.spawn([serial, weight, label, title])({ [serial]: k, [weight]: k % 5, [label]: blank, [title]: `t${k}` });
+});
+/** On the joined thread: every label, by serial and round. */
+const relabelHeld = System.create({ components: { with: [serial, label, title] } }, (row, _context, input: { readonly round: number }) => {
+    row[label] = { text: `${row[serial]}.${input.round}` };
+});
+/** On the world's thread: every weight and title, by round. */
+const rewriteHeld = System.create({ components: { with: [serial, weight, title] } }, (row, _context, input: { readonly round: number }) => {
+    row[weight] = row[serial] * 10 + input.round;
+    row[title] = `t${row[serial]}.${input.round}`;
+});
+/** Moves every held entity to the other archetype, marked on one run and not on the next. */
+const markHeld = System.create({ components: { with: [title], not: [marked] } }, (row, { commands }) => {
+    commands.add(row.entity, marked);
+});
+const unmarkHeld = System.create({ components: { with: [title, marked] } }, (row, { commands }) => {
+    commands.remove(row.entity, marked);
+});
+const held = Index.create({ key: [], components: { with: [serial, weight, label, title] } });
+const heldSerials = Index.create({ key: [serial], unique: true, components: { with: [weight, label, title] } });
+/** What `observeHeld` read last. */
+let observedHeld = "";
+/** An observer system reading every held row through the keyless index, and serial 3's through the unique one. */
+const observeHeld = System.create({
+    observer: true,
+    lookup: { all: { index: held }, bySerial: { index: heldSerials } },
+}, ({ lookup }) => {
+    const all = lookup.all();
+    const read: string[] = [];
+    for (let i = 0; i < all.length; i++) {
+        const row = all.at(i);
+        read.push(`${row[serial]}:${row[weight]}:${row[label].text}:${row[title]}`);
+    }
+    const one = lookup.bySerial(3);
+    observedHeld = `${read.sort().join(",")}|${one === null ? "none" : `${one[weight]}:${one[label].text}:${one[title]}`}`;
 });
+/**
+ * Observes the held rows where `holder` runs observer systems, around what makes the rows a lookup gave stale: arrays
+ * grown, values and strings rewritten, the thread's labels rewritten, and every row moved past what its log holds.
+ */
+const heldScenario = async (world: CreatedWorld, holder: World): Promise<readonly string[]> => {
+    const seen: string[] = [];
+    const observe = async (): Promise<void> => {
+        await holder.run(observeHeld);
+        seen.push(observedHeld);
+    };
+    await world.run(seedHeld, { from: 0, count: 8 });
+    await world.run(relabelHeld, { round: 0 });
+    await observe();
+    // Past the archetype's capacity, without growing the memory.
+    await world.run(seedHeld, { from: 8, count: 12 });
+    await observe();
+    await world.run(rewriteHeld, { round: 1 });
+    await world.run(relabelHeld, { round: 1 });
+    await observe();
+    await world.run(seedHeld, { from: 20, count: 600 });
+    await observe();
+    // Both archetypes grown, so lapping the log again replaces no arrays: only the mirror's rebuild makes views again.
+    const lap = async (): Promise<void> => {
+        for (let k = 0; k < 30; k++) await world.run(k % 2 === 0 ? markHeld : unmarkHeld);
+    };
+    await lap();
+    await observe();
+    await lap();
+    await observe();
+    await world.run(relabelHeld, { round: 2 });
+    await world.run(rewriteHeld, { round: 2 });
+    await observe();
+    return seen;
+};
 
 describe("systems on a joined thread looking up through indexes", () => {
     it("find what the world's own systems find: hash buckets, unique rows, sorted ranges and changes", async () => {
@@ -217,25 +333,67 @@ describe("systems on a joined thread looking up through indexes", () => {
         await inline.dispose();
         const world = createWorld({ [workers]: 0 });
         const channel = new MessageChannel();
-        world.share(channel.port1);
-        const remote = join(channel.port2, { threads: ["indexJoinedTest"] });
-        await joinedStatus(world);
+        const shared = world.share(channel.port1);
+        const remote = await join(channel.port2, { threads: ["indexJoinedTest"] });
+        await shared;
         const there = await scenario(world, remote);
         expect(there.labels).toEqual(alone.labels);
         expect(alone.labels.flat().some(text => text.includes("true"))).toBe(true);
         // The systems ran there, their tiers waiting for the thread.
-        expect(there.warnings.every(names => names.includes("indexJoinedTest/describeCells"))).toBe(true);
+        expect(there.warnings.every(names => names.includes("describeCells"))).toBe(true);
         expect(alone.warnings.flat()).toEqual([]);
         await remote.dispose();
         await world.dispose();
     });
+    it("read a hash index's long buckets in entity order after changes left them unsorted, as the world's own systems do", async () => {
+        const inline = createWorld({ [workers]: 0 });
+        const alone = await bandScenario(inline, inline);
+        await inline.dispose();
+        const world = createWorld({ [workers]: 0 });
+        const channel = new MessageChannel();
+        const shared = world.share(channel.port1);
+        const remote = await join(channel.port2, { threads: ["indexJoinedTest"] });
+        await shared;
+        expect(await bandScenario(world, remote)).toEqual(alone);
+        expect(alone.every(round => round.length === 2 && round.every(text => text.split(",").length > 100))).toBe(true);
+        await remote.dispose();
+        await world.dispose();
+    });
+    it("observe a hash index's long buckets in entity order after changes left them unsorted, as the world's own observer systems do", async () => {
+        const inline = createWorld({ [workers]: 0 });
+        const alone = await observedBandScenario(inline, inline);
+        await inline.dispose();
+        const world = createWorld({ [workers]: 0 });
+        const channel = new MessageChannel();
+        const shared = world.share(channel.port1);
+        const remote = await join(channel.port2, { threads: ["indexJoinedTest"] });
+        await shared;
+        expect(await observedBandScenario(world, remote)).toEqual(alone);
+        expect(alone.every(round => round.length === 2 && round.every(text => text.split(",").length > 100))).toBe(true);
+        await remote.dispose();
+        await world.dispose();
+    });
+    it("read rows as of each run's sync point once arrays grew, values, strings and the thread's objects changed, and its log lapped", async () => {
+        const inline = createWorld({ [workers]: 0 });
+        const alone = await heldScenario(inline, inline);
+        await inline.dispose();
+        const world = createWorld({ [workers]: 0 });
+        const channel = new MessageChannel();
+        const shared = world.share(channel.port1);
+        const remote = await join(channel.port2, { threads: ["indexJoinedTest"] });
+        await shared;
+        expect(await heldScenario(world, remote)).toEqual(alone);
+        expect(alone.at(-1)).toContain("|32:3.2:t3.2");
+        await remote.dispose();
+        await world.dispose();
+    });
     it("release the index and its records once the last system using it there is removed", async () => {
         const driver = backToBack();
         const world = createWorld({ [workers]: 0, [always]: true }, { loop: driver });
         const channel = new MessageChannel();
-        world.share(channel.port1);
-        const remote = join(channel.port2, { threads: ["indexJoinedTest"] });
-        await joinedStatus(world);
+        const shared = world.share(channel.port1);
+        const remote = await join(channel.port2, { threads: ["indexJoinedTest"] });
+        await shared;
         await world.run(seed);
         /** Once `count` more ticks ran. */
         const ticks = async (count: number): Promise<void> => {
@@ -276,17 +434,17 @@ describe("systems on a joined thread looking up through indexes", () => {
     it("throw for an index with an object or string key part, which the world keeps on its own thread, for an order, for a string written, and for an index as a change filter", async () => {
         const world = createWorld({ [workers]: 0 });
         const channel = new MessageChannel();
-        world.share(channel.port1);
-        const remote = join(channel.port2, { threads: ["indexJoinedTest"] });
-        await joinedStatus(world);
-        await expect(world.run(byName)).rejects.toThrow('looks up through index "indexJoinedTest/names", whose key part "indexJoinedTest/name" is an object, so it runs only on the world\'s thread.');
+        const shared = world.share(channel.port1);
+        const remote = await join(channel.port2, { threads: ["indexJoinedTest"] });
+        await shared;
+        await expect(world.run(byName)).rejects.toThrow('looks up through index "names", whose key part "indexJoinedTest/name" is an object, so it runs only on the world\'s thread.');
         await expect(world.run(inOrder)).rejects.toThrow("orders its rows by an index, which runs only on the world's thread");
-        await expect(world.run(writeTitle)).rejects.toThrow(`System "indexJoinedTest/writeTitle" runs on thread "indexJoinedTest", which a joined thread fills, and writes "indexJoinedTest/title", a string, which only the world's thread writes.`);
-        await expect(world.run(byTitle)).rejects.toThrow('looks up through index "indexJoinedTest/titles", whose key part "indexJoinedTest/title" is a string, which the world\'s thread keeps keys of, so it runs only on the world\'s thread.');
-        const moved = `and when index "indexJoinedTest/grid" changed, a lookup's changed being true, which runs only on the world's thread.`;
-        await expect(world.run(countWhenMoved)).rejects.toThrow(`System "indexJoinedTest/countWhenMoved" runs on thread "indexJoinedTest", which a joined thread fills, ${moved}`);
-        await expect(world.run(readWhenMoved)).rejects.toThrow(`System "indexJoinedTest/readWhenMoved" runs on thread "indexJoinedTest", which a joined thread fills, ${moved}`);
-        expect(() => remote.add(ownWhenMoved)).toThrow(`Observer system "indexJoinedTest/ownWhenMoved" runs when index "indexJoinedTest/grid" changed, as its lookup "near"'s changed is true, so it runs only on the world's thread.`);
+        await expect(world.run(writeTitle)).rejects.toThrow(`runs on thread "indexJoinedTest", which a joined thread fills, and writes "indexJoinedTest/title", a string, which only the world's thread writes.`);
+        await expect(world.run(byTitle)).rejects.toThrow('looks up through index "titles", whose key part "indexJoinedTest/title" is a string, which the world\'s thread keeps keys of, so it runs only on the world\'s thread.');
+        const moved = `and when index "grid" changed, a lookup's changed being true, which runs only on the world's thread.`;
+        await expect(world.run(countWhenMoved)).rejects.toThrow(`runs on thread "indexJoinedTest", which a joined thread fills, ${moved}`);
+        await expect(world.run(readWhenMoved)).rejects.toThrow(`runs on thread "indexJoinedTest", which a joined thread fills, ${moved}`);
+        expect(() => remote.add(ownWhenMoved)).toThrow(`Observer system "ownWhenMoved" runs when index "grid" changed, as its lookup "near"'s changed is true, so it runs only on the world's thread.`);
         await remote.dispose();
         await world.dispose();
     });

package/src/implementation/world/index-kernels.test.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, it } from "vitest";
 import { Component } from "../../interface/component/component.js";
 import { Entity } from "../../interface/entity/entity.js";
@@ -6,6 +7,7 @@ import { Observe } from "../../observe/index.js";
 import { workers } from "../../interface/resources/workers.js";
 import { System } from "../../interface/system/system.js";
 import { createWorld, type CreatedWorld } from "./create.js";
+import type { F32, U32, Vec2 } from "../../interface/math/index.js";
 
 const cell = Symbol("indexKernelsTest/cell");
 const weight = Symbol("indexKernelsTest/weight");
@@ -21,40 +23,29 @@ const ranked = Symbol("indexKernelsTest/ranked");
 
 declare module "@adobe/ecs" {
     interface Components {
-        [cell]: { type: readonly [number, number] };
-        [weight]: { type: number };
+        [cell]: { type: Vec2.I32 };
+        [weight]: { type: F32 };
         [total]: { type: number };
         [count]: { type: number };
-        [lane]: { type: number };
+        [lane]: { type: U32 };
         [rank]: { type: number };
-        [serial]: { type: number };
-        [target]: { type: number };
+        [serial]: { type: U32 };
+        [target]: { type: U32 };
         [seen]: { type: Entity };
         [changes]: { type: number };
         [ranked]: { type: true };
     }
 }
-Component.register(cell, { type: { type: "array", items: { type: "integer", minimum: -1000, maximum: 1000 }, minItems: 2, maxItems: 2 } });
-Component.register(weight, { type: { type: "number", precision: 1 } });
-Component.register(total, { type: { type: "number" } });
-Component.register(count, { type: { type: "number" } });
-Component.register(lane, { type: { type: "integer", minimum: 0, maximum: 1000 } });
-Component.register(rank, { type: { type: "number" } });
-Component.register(serial, { type: { type: "integer", minimum: 0, maximum: 1000000 } });
-Component.register(target, { type: { type: "integer", minimum: 0, maximum: 1000000 } });
-Component.register(seen, { type: Entity.schema });
-Component.register(changes, { type: { type: "number" } });
-Component.register(ranked, { type: { const: true } });
 
-const grid = Index.create({ name: "indexKernelsTest/grid", key: [cell], components: { has: [weight] } });
-const lanes = Index.create({ name: "indexKernelsTest/lanes", key: [lane, rank], sorted: true, components: { has: [ranked] } });
-const serials = Index.create({ name: "indexKernelsTest/serials", key: [serial], unique: true, components: { has: [weight] } });
+const grid = Index.create({ key: [cell], components: { with: [weight] } });
+const lanes = Index.create({ key: [lane, rank], sorted: true, components: { with: [ranked] } });
+const serials = Index.create({ key: [serial], unique: true, components: { with: [weight] } });
 
 /** Each row's neighbors in the 3 by 3 cells around its own: how many, and their weights' sum. */
 const neighbors = System.create({
-    name: "indexKernelsTest/neighbors", kernel: "cpu",
-    components: { read: [cell], write: [total, count] },
-    lookup: { near: { index: grid, read: [weight] } },
+    kernel: true,
+    components: { with: [cell, total, count] },
+    lookup: { near: { index: grid } },
 }, (row, { lookup }) => {
     const [x, y] = row[cell];
     let sum = 0;
@@ -73,7 +64,7 @@ const neighbors = System.create({
 });
 
 /** The same, on the main thread, for comparison. */
-const neighborsByHand = System.create({ name: "indexKernelsTest/neighborsByHand", components: { read: [cell], write: [total, count] }, lookup: { near: { index: grid, read: [weight] } } }, (row, { lookup }) => {
+const neighborsByHand = System.create({ components: { with: [cell, total, count] }, lookup: { near: { index: grid } } }, (row, { lookup }) => {
     const [x, y] = row[cell];
     let sum = 0;
     let found = 0;
@@ -90,8 +81,8 @@ const neighborsByHand = System.create({ name: "indexKernelsTest/neighborsByHand"
 
 /** How many rows of the row's lane have a rank within 5 of its own, and the first of them, through a sorted range. */
 const window = System.create({
-    name: "indexKernelsTest/window", kernel: "cpu",
-    components: { read: [lane, rank], write: [count, seen] },
+    kernel: true,
+    components: { with: [lane, rank, count, seen] },
     lookup: { inLane: { index: lanes } },
 }, (row, { lookup }) => {
     const r = row[rank];
@@ -100,7 +91,7 @@ const window = System.create({
     row[seen] = near.at(0).entity;
 });
 
-const windowByHand = System.create({ name: "indexKernelsTest/windowByHand", components: { read: [lane, rank], write: [count, seen] }, lookup: { inLane: { index: lanes } } }, (row, { lookup }) => {
+const windowByHand = System.create({ components: { with: [lane, rank, count, seen] }, lookup: { inLane: { index: lanes } } }, (row, { lookup }) => {
     const r = row[rank];
     const near = lookup.inLane(row[lane], { ">=": r - 5, "<": r + 5 });
     row[count] = near.length;
@@ -109,9 +100,9 @@ const windowByHand = System.create({ name: "indexKernelsTest/windowByHand", comp
 
 /** The weight of the entity whose serial is the row's target, or -1. */
 const follow = System.create({
-    name: "indexKernelsTest/follow", kernel: "cpu",
-    components: { read: [target], write: [total] },
-    lookup: { bySerial: { index: serials, read: [weight] } },
+    kernel: true,
+    components: { with: [target, total] },
+    lookup: { bySerial: { index: serials } },
 }, (row, { lookup }) => {
     const found = lookup.bySerial(row[target]);
     row[total] = found === null ? -1 : found[weight];
@@ -119,18 +110,18 @@ const follow = System.create({
 
 /** Counts runs whose list of the row's cell changed. */
 const watch = System.create({
-    name: "indexKernelsTest/watch", kernel: "cpu",
-    components: { read: [cell], write: [changes] },
+    kernel: true,
+    components: { with: [cell, changes] },
     lookup: { near: { index: grid, changed: [weight] } },
 }, (row, { lookup }) => {
     if (lookup.near([row[cell][0], row[cell][1]]).changed) row[changes] = row[changes] + 1;
 });
 
-const spawnGrid = System.create({ name: "indexKernelsTest/spawnGrid", input: { type: "object", properties: { count: { type: "integer" } } } }, ({ input, commands }) => {
+const spawnGrid = System.create({}, ({ commands }, input: { readonly count: number }) => {
     for (let k = 0; k < input.count; k++) commands.spawn([cell, weight, total, count, changes, serial])({ [cell]: [(k * 7) % 5, (k * 3) % 4], [weight]: k % 9, [total]: 0, [count]: 0, [changes]: 0, [serial]: k });
 });
 
-const spawnLanes = System.create({ name: "indexKernelsTest/spawnLanes", input: { type: "object", properties: { count: { type: "integer" } } } }, ({ input, commands }) => {
+const spawnLanes = System.create({}, ({ commands }, input: { readonly count: number }) => {
     for (let k = 0; k < input.count; k++) commands.spawn([lane, rank, ranked, count, seen])({ [lane]: k % 3, [rank]: (k * 37) % 101, [ranked]: true, [count]: 0, [seen]: Entity.none });
 });
 
@@ -187,8 +178,8 @@ describe.each([[true], [false]])("kernels looking up through indexes, WASM %s",
 
 /** A comparison on a hash index. */
 const compared = System.create({
-    name: "indexKernelsTest/compared", kernel: "cpu",
-    components: { read: [serial], write: [count] },
+    kernel: true,
+    components: { with: [serial, count] },
     lookup: { bySerial: { index: serials } },
 }, (row, { lookup }) => {
     // @ts-expect-error a hash index takes whole keys