@adobe/ecs 0.1.0 → 0.2.0

package/src/implementation/world/pool-size.fixture.ts

@@ -1,26 +1,41 @@
-import { Component } from "../../interface/component/component.js";
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { workers } from "../../interface/resources/workers.js";
 import { System } from "../../interface/system/system.js";
 import { readEach, select } from "./reads.test-helper.js";
 import { createWorld } from "./create.js";
 import { Observe } from "../../observe/index.js";
 import { countingWorkers } from "./platforms.test-helper.js";
+import { catchOutOfBand } from "./outcomes.test-helper.js";
+import type { WorkerPlatform } from "./worker-platform.js";
+import type { F32 } from "../../interface/math/index.js";
 
 /** Scenarios of the `workers` resource sizing the pool, run built in node and from source in chromium. */
 
 const value = Symbol("poolSizeTest/value");
 declare module "@adobe/ecs" {
     export interface Components {
-        [value]: { type: number };
+        [value]: { type: F32 };
     }
 }
-Component.register(value, { type: { type: "number", precision: 1 } });
 
-const seed = System.create({ name: "poolSizeTest/seed" }, ({ commands }) => {
+const other = Symbol("poolSizeTest/other");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [other]: { type: F32 };
+    }
+}
+const others = System.create({}, ({ commands }) => {
+    for (let i = 0; i < 4096; i++) commands.spawn([other])({ [other]: i });
+});
+
+const seed = System.create({}, ({ commands }) => {
     for (let i = 0; i < 4096; i++) commands.spawn([value])({ [value]: i });
 });
-const double = System.create({ name: "poolSizeTest/double", kernel: "cpu", components: { write: [value] } }, row => { row[value] = row[value] * 2; });
-const resize = System.create({ name: "poolSizeTest/resize", input: { type: "object", properties: { size: { anyOf: [{ type: "integer" }, { type: "null" }] } } }, resources: { write: [workers] } }, ({ input, resources }) => {
+const few = System.create({}, ({ commands }) => {
+    for (let i = 0; i < 16; i++) commands.spawn([value])({ [value]: i });
+});
+const double = System.create({ kernel: true, components: { with: [value] } }, row => { row[value] = row[value] * 2; });
+const resize = System.create({}, ({ resources }, input: { readonly size: number | null }) => {
     resources[workers] = input.size;
 });
 
@@ -64,3 +79,80 @@ export const resized = async (initial: number, sizes: readonly (number | null)[]
         await world.dispose();
     }
 };
+
+/**
+ * Workers started after a kernel runs over fewer rows than a piece for a worker, then after it runs over enough, and
+ * the first values it doubled.
+ */
+export const whenWarranted = async (): Promise<{ readonly started: readonly number[]; readonly values: readonly (number | null)[] }> => {
+    const counting = countingWorkers();
+    const world = createWorld({}, { minimumChunk: 64, pool: counting.platform });
+    try {
+        await world.run(few);
+        await world.run(double);
+        const started = [counting.started()];
+        await world.run(seed);
+        await world.run(double);
+        started.push(counting.started());
+        return { started, values: (await readEach(world, await select(world, { required: [value] }), value)).slice(0, 4) };
+    }
+    finally {
+        await world.dispose();
+    }
+};
+
+/** The platform's workers, failing every kernel load: each kernel's module is one that throws. */
+const failingLoads = (): { readonly platform: WorkerPlatform; readonly loads: () => number } => {
+    const counting = countingWorkers();
+    const broken = "data:text/javascript,throw new Error('no kernel here')";
+    const start = () => {
+        const port = counting.platform.start();
+        if (port === null) return null;
+        return { ...port, post: ((message, transfer) => port.post(message.kind === "kernels" ? { ...message, kernels: message.kernels.map(kernel => ({ ...kernel, url: broken })) } : message, transfer)) satisfies typeof port.post };
+    };
+    return { platform: { count: counting.platform.count, start }, loads: () => counting.posted("kernels") };
+};
+
+/**
+ * A kernel whose load fails on workers when the pool starts: the failures of that run's report and of the next, the
+ * kernel loads posted after each, and the values its runs doubled, here.
+ */
+export const failedLoad = async (): Promise<{ readonly failures: readonly (readonly string[])[]; readonly loads: readonly number[]; readonly values: readonly (number | null)[] }> => {
+    const failing = failingLoads();
+    const world = createWorld({ [workers]: 2 }, { minimumChunk: 64, pool: failing.platform });
+    try {
+        // Registered while no archetype warrants workers, so the pool starts in a later run.
+        await world.run(double);
+        await world.run(seed);
+        const failures: string[][] = [];
+        const loads: number[] = [];
+        // Workers failing to load are reported out of band.
+        using reported = catchOutOfBand();
+        for (let i = 0; i < 2; i++) {
+            const before = reported.errors.length;
+            await world.run(double);
+            failures.push(reported.messages().slice(before));
+            loads.push(failing.loads());
+        }
+        return { failures, loads, values: (await readEach(world, await select(world, { required: [value] }), value)).slice(0, 4) };
+    }
+    finally {
+        await world.dispose();
+    }
+};
+
+/** Workers started after a kernel runs over few rows in a world whose largest archetype no kernel matches. */
+export const unmatched = async (): Promise<number> => {
+    const counting = countingWorkers();
+    const world = createWorld({}, { minimumChunk: 64, pool: counting.platform });
+    try {
+        await world.run(others);
+        await world.run(few);
+        await world.run(double);
+        await world.run(double);
+        return counting.started();
+    }
+    finally {
+        await world.dispose();
+    }
+};

package/src/implementation/world/pool.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 "./pool.fixture.js";
 

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

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { createMemory, pageBytes, pagesWord, type Memory } from "./memory.js";
 import { createPool } from "./pool.js";
 import { idleKernel } from "./protocol.js";

package/src/implementation/world/pool.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { allocateArray, freeArray } from './arrays.js';
 import { emptyBuffer, type CommandBuffer } from './buffer.js';
 import type { Memory } from './memory.js';

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

@@ -0,0 +1,45 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { lentPort, serveLent } from "./port.js";
+
+describe("a lent worker's owner", () => {
+    it("reports a worker it ends as terminated by its owner, though the worker's own end is heard of first", async () => {
+        let died: ((error: Error) => void) | null = null;
+        // As a node worker's `exit` can be, before its `terminate` resolves.
+        const worker = {
+            onDeath: (handler: (error: Error) => void) => { died = handler; },
+            terminate: async () => { died?.(new Error("A world worker exited with code 1.")); },
+        };
+        const { port1, port2 } = new MessageChannel();
+        const reported = new Promise<unknown>(resolve => {
+            port2.addEventListener("message", event => resolve(event.data));
+            port2.start();
+        });
+        await serveLent(worker, port1).terminate();
+        expect(await reported).toEqual({ kind: "death", message: "A world worker was terminated by its owner." });
+        port1.close();
+        port2.close();
+    });
+});
+
+describe("a lent worker", () => {
+    it("is reported terminated by its owner when its owner ends it, though its port's close is heard of first", async () => {
+        const data = new MessageChannel();
+        const control = new MessageChannel();
+        const lent = lentPort<unknown, unknown>({ port: data.port2, owner: control.port2 });
+        const reported = new Promise<string>(resolve => lent.onDeath(error => resolve(error.message)));
+        const portClosed = new Promise<void>(resolve => data.port2.addEventListener("close", () => resolve()));
+        // Ending the worker closes its port, and the thread it's lent to hears of that before `terminate` resolves.
+        const worker = {
+            onDeath: () => {},
+            terminate: async () => {
+                data.port1.close();
+                await portClosed;
+            },
+        };
+        await serveLent(worker, control.port1).terminate();
+        expect(await reported).toBe("A world worker was terminated by its owner.");
+        control.port1.close();
+        control.port2.close();
+    });
+});

package/src/implementation/world/port.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 /** One end of a channel between threads: messages each way, in the order they were posted. */
 export type Channel<Send, Receive> = {
     /** Posts a message, moving the buffers in `transfer`. */
@@ -34,9 +35,12 @@ export type Endpoint = {
  */
 export type Lent<P extends Endpoint = Endpoint> = { readonly port: P; readonly owner: P };
 
-/** Between a lent worker's owner and the thread it's lent to. */
-type ToOwner = { readonly kind: "terminate" };
-type FromOwner = { readonly kind: "death"; readonly message: string } | { readonly kind: "terminated" };
+/**
+ * Between a lent worker's owner and the thread it's lent to. `closed` tells the owner the worker's port closed; the
+ * owner answers it in order with what it posts, so a death it reported first arrives first.
+ */
+type ToOwner = { readonly kind: "terminate" } | { readonly kind: "closed" };
+type FromOwner = { readonly kind: "death"; readonly message: string } | { readonly kind: "terminated" } | { readonly kind: "closed" };
 
 /** A death to report once: the first error wins, and a handler set after it still hears it. */
 export const createDeath = (): { readonly die: (error: Error) => void; readonly onDeath: (handler: (error: Error) => void) => void } => {
@@ -80,8 +84,9 @@ export const scopeChannel = <Send, Receive>(): Channel<Send, Receive> => {
 
 /**
  * The thread a lent worker runs on, as the thread it's lent to sees it: its death is what its owner reports, or either
- * port's `close` where the platform has it; `terminate` asks the owner, and closes both ports once it has, or once the
- * owner's port closed.
+ * port's `close` where the platform has it. The worker's port closing is reported once its owner answers that it
+ * reported nothing before, so an owner's report wins over the close its ending causes. `terminate` asks the owner, and
+ * closes both ports once it has, or once the owner's port closed.
  */
 export const lentPort = <Send, Receive>({ port, owner }: Lent): Port<Send, Receive> => {
     const channel = endpointChannel<Send, Receive>(port);
@@ -90,9 +95,10 @@ export const lentPort = <Send, Receive>({ port, owner }: Lent): Port<Send, Recei
     let terminated: (() => void) | null = null;
     control.onMessage(message => {
         if (message.kind === "death") death.die(new Error(message.message));
+        else if (message.kind === "closed") death.die(new Error("A world worker's port closed."));
         else terminated?.();
     });
-    port.addEventListener("close", () => death.die(new Error("A world worker's port closed.")));
+    port.addEventListener("close", () => control.post({ kind: "closed" }));
     // An owner whose thread is gone can't answer; where the platform reports that, its worker is gone with it.
     owner.addEventListener("close", () => {
         death.die(new Error("A world worker's owner is gone."));
@@ -115,7 +121,7 @@ export const lentPort = <Send, Receive>({ port, owner }: Lent): Port<Send, Recei
 
 /**
  * On the owner's thread: serves a lent worker's owner end, forwarding the worker's death and ending it when the
- * thread it's lent to asks, or when `terminate` is called here, which reports it as a death there.
+ * thread it's lent to asks, or when `terminate` is called here, which reports it as a death there before ending it.
  */
 export const serveLent = (worker: Pick<Port<unknown, unknown>, "onDeath" | "terminate">, owner: Endpoint): { readonly terminate: () => Promise<void> } => {
     const control = endpointChannel<FromOwner, ToOwner>(owner);
@@ -126,12 +132,13 @@ export const serveLent = (worker: Pick<Port<unknown, unknown>, "onDeath" | "term
         control.post({ kind: "death", message: error.message });
     });
     const end = async (): Promise<void> => {
-        await worker.terminate();
-        if (gone) return;
+        // Reported before it's ended, so it comes before the worker's end it causes, here and as its port's close there.
+        if (!gone) control.post({ kind: "death", message: "A world worker was terminated by its owner." });
         gone = true;
-        control.post({ kind: "death", message: "A world worker was terminated by its owner." });
+        await worker.terminate();
     };
-    control.onMessage(async () => {
+    control.onMessage(async message => {
+        if (message.kind === "closed") return control.post({ kind: "closed" });
         gone = true;
         await worker.terminate();
         control.post({ kind: "terminated" });

package/src/implementation/world/ports.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 "./ports.fixture.js";
 
@@ -9,8 +10,7 @@ export const portsCases = (load: () => Promise<typeof Fixture>) => describe("thr
         it(`fail the run whose ${wasm ? "WASM" : "JS"} task's worker is killed from outside mid-task, by ${by === "exit" ? "ending it" : "its owner"}, and every later task on it`, async () => {
             const fixture = await load();
             const { first, second, disposed } = await fixture.killedMidTask(by, wasm);
-            // A lent worker's death is what its owner reports, or its port's close where the platform has it, whichever comes first.
-            const death = by === "exit" ? /exited/ : /terminated by its owner|port closed/;
+            const death = by === "exit" ? /exited/ : /terminated by its owner/;
             expect(first.length).toBeGreaterThan(0);
             for (const message of first) expect(message).toMatch(death);
             expect(second.length).toBeGreaterThan(0);

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

@@ -1,12 +1,12 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 /// <reference types="node" />
-import { Component } from "../../interface/component/component.js";
 import { workers } from "../../interface/resources/workers.js";
 import { System } from "../../interface/system/system.js";
 import { createWorld } from "./create.js";
 import { lendBrowserWorkers, lendNodeWorkers, lentWorkers, platformWorkers, type WorkerPlatform } from "./worker-platform.js";
 import type { Lent } from "./port.js";
 import { simulate } from "./workers.fixture.js";
-import { runReported } from "./reports.test-helper.js";
+import { runReported } from "./outcomes.test-helper.js";
 
 /** Scenarios of workers that die, are lent, or serve a world on a worker, run built in node and from source in chromium. */
 
@@ -16,14 +16,13 @@ declare module "@adobe/ecs" {
         [value]: { type: number };
     }
 }
-Component.register(value, { type: { type: "number" } });
 
-const seed = System.create({ name: "portsTest/seed" }, ({ commands }) => {
+const seed = System.create({}, ({ commands }) => {
     for (let i = 0; i < 100_000; i++) commands.spawn([value])({ [value]: i });
 });
 
 /** Long enough per row that a task over 100,000 rows is still running when its worker is killed. */
-const heavy = System.create({ name: "portsTest/heavy", kernel: "cpu", components: { write: [value] } }, row => {
+const heavy = System.create({ kernel: true, components: { with: [value] } }, row => {
     let total = row[value];
     for (let k = 0; k < 2000; k++) total = total * 0.5 + k;
     row[value] = total;

package/src/implementation/world/ports.type-test.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 /// <reference types="node" />
 import type { MessagePort as NodeMessagePort, Worker as NodeWorker } from "node:worker_threads";
 import type { World } from "../../interface/world/world.js";

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

@@ -0,0 +1,174 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { expect, it } from "vitest";
+import { System } from "../../interface/system/system.js";
+import { workers } from "../../interface/resources/workers.js";
+import type { F32, Vec3 } from "../../interface/math/index.js";
+import { kernelOf } from "./attach-kernel.js";
+import { createWorld } from "./create.js";
+
+const a = Symbol("precisionTest/a");
+const c = Symbol("precisionTest/c");
+const difference = Symbol("precisionTest/difference");
+const position = Symbol("precisionTest/position");
+const velocity = Symbol("precisionTest/velocity");
+const phase = Symbol("precisionTest/phase");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [a]: { type: F32 };
+        [c]: { type: F32 };
+        [difference]: { type: F32 };
+        [position]: { type: Vec3 };
+        [velocity]: { type: Vec3 };
+    }
+    export interface Resources {
+        [phase]: { type: number; default: 0 };
+    }
+}
+
+// a * a is 1 + 2⁻²² + 2⁻⁴⁶, which f32 rounds to c, so only arithmetic at f64 keeps the 2⁻⁴⁶.
+const seed = System.create(({ commands }) => {
+    for (let i = 0; i < 64; i++) commands.spawn([a, c, difference])({ [a]: 1 + 2 ** -23, [c]: 1 + 2 ** -22, [difference]: 0 });
+});
+const tried = System.create({ components: { with: [a, c, difference] } }, row => {
+    row[difference] = row[a] * row[a] - row[c];
+});
+const written = System.create({ kernel: false, components: { with: [a, c, difference] } }, row => {
+    row[difference] = row[a] * row[a] - row[c];
+});
+const seen: number[] = [];
+const read = System.create({ kernel: false, components: { with: [difference] } }, row => {
+    seen.push(row[difference]);
+});
+
+const differenceAfter = async (system: typeof tried, wasm: boolean): Promise<number | undefined> => {
+    const world = createWorld({ [workers]: 0 }, { wasm });
+    try {
+        await world.run(seed);
+        await world.run(system);
+        seen.length = 0;
+        await world.run(read);
+        return seen[0];
+    }
+    finally {
+        await world.dispose();
+    }
+};
+
+it("computes an unflagged kernel at the precision the body as written does, in JS and WASM", async () => {
+    expect(kernelOf(tried)).toBeDefined();
+    const expected = await differenceAfter(written, true);
+    expect(expected).toBe(Math.fround(2 ** -46));
+    expect(await differenceAfter(tried, true)).toBe(expected);
+    expect(await differenceAfter(tried, false)).toBe(expected);
+});
+
+/** Values where f32 arithmetic loses what f64 keeps: cancellation, rounding at each step, NaN, infinities and -0. */
+const hard = (i: number): number => [1 + 2 ** -23, 1 + 2 ** -22, 3.4e38, -0, NaN, Infinity, 1e-45, 0.1, -7.25, 16777217][i % 10] * (1 + (i % 7) * 2 ** -20);
+// Rows that leave a partial group of lanes at the end.
+const rows = 1027;
+const seedMany = System.create(({ commands }) => {
+    for (let i = 0; i < rows; i++) commands.spawn([a, c, difference, position, velocity])({ [a]: hard(i), [c]: hard(i + 1), [difference]: 0, [position]: [hard(i + 2), hard(i + 3), hard(i + 4)], [velocity]: [hard(i + 5), hard(i + 6), hard(i)] });
+});
+const touch = System.create({ kernel: false, components: { with: [c] } }, row => {
+    if (row.entity % 3 === 0) row[c] = row[c] * 3;
+});
+const pairs = [
+    [
+        System.create({ components: { with: [a, c, difference] } }, row => { row[difference] = Math.sqrt(Math.abs(row[a])) / row[c] + Math.min(row[a], 0.75) * Math.fround(row[c]) - Math.floor(row[a]); }),
+        System.create({ kernel: false, components: { with: [a, c, difference] } }, row => { row[difference] = Math.sqrt(Math.abs(row[a])) / row[c] + Math.min(row[a], 0.75) * Math.fround(row[c]) - Math.floor(row[a]); }),
+    ],
+    [
+        System.create({ components: { with: [velocity, position] } }, row => { row[position] = [row[position][0] * row[velocity][0] - row[velocity][0] * 0.75, row[position][1] * row[velocity][1] - row[velocity][1] * 0.75, row[position][2] * row[velocity][2] - row[velocity][2] * 0.75]; }),
+        System.create({ kernel: false, components: { with: [velocity, position] } }, row => { row[position] = [row[position][0] * row[velocity][0] - row[velocity][0] * 0.75, row[position][1] * row[velocity][1] - row[velocity][1] * 0.75, row[position][2] * row[velocity][2] - row[velocity][2] * 0.75]; }),
+    ],
+    // Remainders by integer literals: of integers and of everything else, NaN, infinities and -0 among them.
+    [
+        System.create({ components: { with: [a, c, difference] } }, row => { row[difference] = row[a] < 0 ? Math.trunc(row[a] * -1e6) % 5 + row[c] % 2 : row[a] === 0 ? Math.trunc(row[a]) % 4 : row[a] % 3 + Math.floor(row[c] * 4096) % 7; }),
+        System.create({ kernel: false, components: { with: [a, c, difference] } }, row => { row[difference] = row[a] < 0 ? Math.trunc(row[a] * -1e6) % 5 + row[c] % 2 : row[a] === 0 ? Math.trunc(row[a]) % 4 : row[a] % 3 + Math.floor(row[c] * 4096) % 7; }),
+    ],
+    [
+        System.create({ components: { with: [a, c, difference], changed: [c] } }, row => { row[difference] = row[a] * row[a] - row[c]; }),
+        System.create({ kernel: false, components: { with: [a, c, difference], changed: [c] } }, row => { row[difference] = row[a] * row[a] - row[c]; }),
+    ],
+] as const;
+const values: number[] = [];
+const readAll = System.create({ kernel: false, components: { with: [difference, position] } }, row => {
+    values.push(row[difference], ...row[position]);
+});
+
+/** A NaN's sign and payload are the platform's, x86's and ARM's differing; every NaN reads as the one. */
+const quietNaN = 0x7fc00000;
+
+/** f32 values as bits, so -0 and every other value compare exactly, and each NaN as a NaN. */
+const bitsOf = (values: readonly number[]): readonly number[] =>
+    [...new Uint32Array(new Float32Array(values).buffer)].map(bits => (bits & 0x7f800000) === 0x7f800000 && (bits & 0x7fffff) !== 0 ? quietNaN : bits);
+
+it("reads x86's NaN, sign set, and ARM's as one NaN, while -0 stays apart from 0", () => {
+    const x86 = new Float32Array(new Uint32Array([0xffc00000]).buffer)[0] ?? 0;
+    expect(bitsOf([x86, NaN, -0, 0])).toEqual([quietNaN, quietNaN, 0x80000000, 0]);
+});
+
+/** Every value after a seed, a change to some rows and `system`, as bits. */
+const bitsAfter = async (system: (typeof pairs)[number][number], wasm: boolean): Promise<readonly number[]> => {
+    const world = createWorld({ [workers]: 0 }, { wasm });
+    try {
+        await world.run(seedMany);
+        await world.run(system);
+        await world.run(touch);
+        await world.run(system);
+        values.length = 0;
+        await world.run(readAll);
+        return bitsOf(values);
+    }
+    finally {
+        await world.dispose();
+    }
+};
+
+it("gives an unflagged kernel's results bit for bit as written, for dense columns, whole elements and change filters", async () => {
+    for (const [index, [tried, written]] of pairs.entries()) {
+        expect([index, kernelOf(tried) !== undefined]).toEqual([index, true]);
+        const expected = await bitsAfter(written, true);
+        expect([index, "wasm", await bitsAfter(tried, true)]).toEqual([index, "wasm", expected]);
+        expect([index, "js", await bitsAfter(tried, false)]).toEqual([index, "js", expected]);
+    }
+});
+
+// Values the same for every row, of resources through `%`, `**` and `Math.sin`, which WASM imports: once a call there.
+const phased = System.create({ components: { with: [a, c, difference] } }, (row, { resources }) => {
+    if (resources[phase] % 2 > 1) row[difference] = row[a] * (resources[phase] % 0.7) + Math.sin(resources[phase] * 3) - row[c] ** (resources[phase] % 3);
+    else row[difference] = row[c] - resources[phase] ** 0.5;
+});
+const phasedWritten = System.create({ kernel: false, components: { with: [a, c, difference] } }, (row, { resources }) => {
+    if (resources[phase] % 2 > 1) row[difference] = row[a] * (resources[phase] % 0.7) + Math.sin(resources[phase] * 3) - row[c] ** (resources[phase] % 3);
+    else row[difference] = row[c] - resources[phase] ** 0.5;
+});
+const setPhase = System.create({}, ({ resources }, input: { readonly value: number }) => {
+    resources[phase] = input.value;
+});
+
+it("gives a kernel's values that are the same for every row bit for bit as written, as the resources they read change", async () => {
+    expect(kernelOf(phased)).toBeDefined();
+    const bits = async (system: typeof phased, wasm: boolean): Promise<readonly number[]> => {
+        const world = createWorld({ [workers]: 0 }, { wasm });
+        try {
+            await world.run(seedMany);
+            const seen: number[] = [];
+            for (const value of [7.25, 4.5, -3.75, 1e300, NaN]) {
+                await world.run(setPhase, { value });
+                await world.run(system);
+                values.length = 0;
+                await world.run(readAll);
+                seen.push(...values);
+            }
+            return bitsOf(seen);
+        }
+        finally {
+            await world.dispose();
+        }
+    };
+    const expected = await bits(phasedWritten, true);
+    expect(await bits(phased, true)).toEqual(expected);
+    expect(await bits(phased, false)).toEqual(expected);
+});

package/src/implementation/world/prepared-lookup.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import { createSite, indexLookupOf, type Shape, type Site } from './index-lookups.js';
 
 /** Arguments a site passes at most: its key's scalars, flattened from literals. */

package/src/implementation/world/prepared-spawn.ts

@@ -1,11 +1,11 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Commands } from '../../interface/system/commands.js';
 import type { Essential } from '../../interface/component/value.js';
 import type { Entity } from '../../interface/entity/entity.js';
 import { addCommand, pushCommand, pushComponent, type CommandBuffer } from './buffer.js';
 import { commandsTarget, type CommandsTarget } from './commands.js';
-import { listShapeOf, positionalOf, type ListShape, type Positional } from './lists.js';
+import { listIndexOf, listShapeOf, positionalOf, type ListShape, type Positional } from './lists.js';
 import type { Key, State } from './state.js';
-import { archetypeIndexOf } from '../../interface/registry/index.js';
 
 type TargetedCommands = Commands & { readonly [commandsTarget]: CommandsTarget };
 
@@ -21,17 +21,17 @@ const valuesOf = (keys: readonly Key[], values: readonly unknown[]): { [key: str
 /** What a site resolved for a world and shape. */
 type Planned = { readonly state: State; readonly shape: ListShape };
 
-/** A site's plans: by archetype index, for the world that last used it, and by shape, which belongs to one world and is held only while it lives. */
-type Plans<P> = { readonly byIndex: (P | undefined)[]; readonly byShape: WeakMap<ListShape, P> };
+/** A site's plans, each for the world that last used it: by its list's index, and by its shape's index in that world. */
+type Plans<P> = { readonly byIndex: (P | undefined)[]; readonly byShape: (P | undefined)[] };
 
-const createPlans = <P>(): Plans<P> => ({ byIndex: [], byShape: new WeakMap() });
+const createPlans = <P>(): Plans<P> => ({ byIndex: [], byShape: [] });
 
 /**
  * A site's plan for a world and list: a kept one, else one `make` makes for its shape and the site's keys, kept from
  * then on. `make` is one function per kind of site, so finding a plan allocates nothing.
  */
 const planFor = <P extends Planned>(plans: Plans<P>, state: State, list: readonly unknown[], site: readonly Key[], make: (state: State, shape: ListShape, site: readonly Key[]) => P): P => {
-    const index = archetypeIndexOf(list);
+    const index = listIndexOf(list);
     const indexed = index >= 0 ? plans.byIndex[index] : undefined;
     // Kept small, so it inlines into the systems spawning and adding: the rest is outlined.
     return indexed !== undefined && indexed.state === state ? indexed : planned(plans, state, list, site, make, index);
@@ -40,12 +40,14 @@ const planFor = <P extends Planned>(plans: Plans<P>, state: State, list: readonl
 /** A site's plan other than one kept by archetype index for this world. */
 const planned = <P extends Planned>(plans: Plans<P>, state: State, list: readonly unknown[], site: readonly Key[], make: (state: State, shape: ListShape, site: readonly Key[]) => P, index: number): P => {
     const shape = listShapeOf(state, list);
-    let plan = plans.byShape.get(shape);
-    if (plan === undefined) {
+    let plan = plans.byShape[shape.index];
+    if (plan === undefined || plan.shape !== shape) {
         plan = make(state, shape, site);
-        plans.byShape.set(shape, plan);
+        plans.byShape[shape.index] = plan;
     }
-    if (index >= 0) plans.byIndex[index] = plan;
+    // A list made at runtime has an index once resolved.
+    const kept = index >= 0 ? index : listIndexOf(list);
+    if (kept >= 0) plans.byIndex[kept] = plan;
     return plan;
 };
 
@@ -141,6 +143,8 @@ export const prepareAdd = (keys: () => readonly Key[]): PreparedAdd => {
             if (!distinct || !isTargeted(commands)) return false;
             const { state, target } = commands[commandsTarget];
             plan = planFor(plans, state, components, resolved, addPlanOf);
+            // Shared values are checked before anything is queued, which `commands.add` does.
+            if (plan.shape.shared.length > 0) return false;
             buffer = target.buffer;
             pushCommand(buffer, addCommand, entity);
             buffer.shapes[buffer.count - 1] = plan.shape.index;

package/src/implementation/world/program.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Finalizer } from '../../interface/finalizer/created.js';
 import type { Rule } from '../../interface/rule/created.js';
 import type { Key } from './state.js';

package/src/implementation/world/protocol.ts

@@ -1,13 +1,14 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Schema } from '../../interface/schema/schema.js';
 import type { Endpoint } from './port.js';
 import type { WasmScalar } from './wasm.js';
 import type { IndexReaderSetup } from './index-readers.js';
 
 /** Where a kernel column comes from in any archetype it matches. */
-export type Source = { readonly kind: "entity" } | { readonly kind: "field" | "changed" | "chunks"; readonly id: number; readonly leaf: number };
+export type Source = { readonly kind: "entity" } | { readonly kind: "field" | "changed" | "chunks" | "blocks" | "present"; readonly id: number; readonly leaf: number };
 
 /** Component ids of one lookup, and for a lookup by entity with `changed`, those it watches. */
-export type LookupSetup = { readonly read: readonly number[]; readonly has: readonly number[]; readonly not: readonly number[]; readonly changed: readonly number[] | null };
+export type LookupSetup = { readonly read: readonly number[]; readonly has: readonly number[]; readonly optional: readonly number[]; readonly not: readonly number[]; readonly changed: readonly number[] | null };
 
 export type KernelSetup = {
     readonly index: number;
@@ -23,6 +24,10 @@ export type KernelSetup = {
     readonly indexes: readonly { readonly lookup: number; readonly reader: IndexReaderSetup; readonly watched: number }[];
     /** Component ids, used as `keys` so command values name components by id. */
     readonly keys: readonly number[];
+    /** By key index, each component's label, which a failing write of an optional component names. */
+    readonly labels: readonly string[];
+    /** Optional components' ids: an archetype without one gives its columns empty. */
+    readonly optional: readonly number[];
     /** By key index: what each component stored in linear memory starts at, for a spawn leaving it out; null for the rest, whose start the world resolves. */
     readonly starts: readonly unknown[];
     /** The component ids of each list the kernel spawns, in the order its spawner takes values. */
@@ -71,6 +76,8 @@ export type ToWorker =
         /** A WASM kernel's lookup parameters, and its lookups through indexes', which JS kernels' readers read too. */
         readonly lookups: readonly number[];
         readonly indexes: readonly number[];
+        /** The archetype's values of the shared components the kernel reads, which each call takes. */
+        readonly shared: readonly unknown[];
     };
 
 export type WorkerError = { readonly name: string; readonly message: string; readonly stack?: string };

package/src/implementation/world/publish.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Schema } from '../../interface/schema/schema.js';
 import { schemaOf } from '../../interface/registry/index.js';
 import { flushBetween } from './layout-directory.js';