@adobe/ecs 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,15 @@
+// © 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";
+import { join } from "./create.js";
+
+// Node's ports are ports too: a worker_threads MessagePort, Worker and parentPort.
+declare const port: NodeMessagePort;
+declare const worker: NodeWorker;
+declare const world: World;
+world.share(port);
+world.share(worker);
+join(port, { threads: ["main"] });
+const parent: NodeMessagePort | null = globalThis.process.getBuiltinModule("node:worker_threads").parentPort;
+if (parent !== null) join(parent);

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

@@ -0,0 +1,96 @@
+// © 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. */
+export const maximumArguments = 16;
+
+/** How many arguments a shape passes. */
+const countOf = (shape: Shape): number => {
+    let count = 0;
+    for (const form of shape) {
+        if (typeof form === "number") count += Math.max(1, form);
+        else for (const [, operand] of form) count += Math.max(1, operand);
+    }
+    return count;
+};
+
+/** The arguments a call with literals would have passed, built back from the values a shape flattened them into. */
+const argumentsOf = (shape: Shape, values: readonly unknown[]): unknown[] => {
+    const built: unknown[] = [];
+    let next = 0;
+    const operand = (form: number): unknown => {
+        if (form === 0) return values[next++];
+        const tuple = values.slice(next, next + form);
+        next += form;
+        return tuple;
+    };
+    for (const form of shape) {
+        if (typeof form === "number") built.push(operand(form));
+        else {
+            const comparison: { [operator: string]: unknown } = {};
+            for (const [operator, count] of form) comparison[operator] = operand(count);
+            built.push(comparison);
+        }
+    }
+    return built;
+};
+
+/**
+ * One index lookup call site of a main-thread body, for code the plugin emits: `find(lookup, ...values)` takes the
+ * key as `shape` flattened it, so a literal tuple or comparison builds nothing, and returns the site's own list, or row
+ * for a unique index, reused each time it runs. A function that isn't an index lookup is called as written.
+ */
+export const prepareLookup = (shape: Shape) => {
+    const count = countOf(shape);
+    let last: unknown = null;
+    let site: Site | null = null;
+    const sites = new WeakMap<object, Site>();
+    /** The site for `lookup`, or null for a function that isn't an index lookup. */
+    const siteOf = (lookup: unknown): Site | null => {
+        const found = indexLookupOf(lookup);
+        if (found === undefined || typeof lookup !== "function") return null;
+        const made = sites.get(lookup) ?? createSite(found, shape);
+        sites.set(lookup, made);
+        last = lookup;
+        site = made;
+        return made;
+    };
+    /** A call of a function that isn't an index lookup, with the arguments a call with literals would have passed. */
+    const asWritten = (lookup: unknown, values: readonly unknown[]): unknown =>
+        typeof lookup === "function" ? Reflect.apply(lookup, undefined, argumentsOf(shape, values)) : undefined;
+    // The commonest counts take exactly their arguments, so a call passes nothing more.
+    switch (count) {
+        case 0: return {
+            find: (lookup: unknown): unknown => {
+                const current = lookup === last ? site : siteOf(lookup);
+                return current === null ? asWritten(lookup, []) : current.find();
+            },
+        };
+        case 1: return {
+            find: (lookup: unknown, a0: unknown): unknown => {
+                const current = lookup === last ? site : siteOf(lookup);
+                return current === null ? asWritten(lookup, [a0]) : current.find(a0);
+            },
+        };
+        case 2: return {
+            find: (lookup: unknown, a0: unknown, a1: unknown): unknown => {
+                const current = lookup === last ? site : siteOf(lookup);
+                return current === null ? asWritten(lookup, [a0, a1]) : current.find(a0, a1);
+            },
+        };
+        case 3: return {
+            find: (lookup: unknown, a0: unknown, a1: unknown, a2: unknown): unknown => {
+                const current = lookup === last ? site : siteOf(lookup);
+                return current === null ? asWritten(lookup, [a0, a1, a2]) : current.find(a0, a1, a2);
+            },
+        };
+        default: return {
+            find: (lookup: unknown, a0?: unknown, a1?: unknown, a2?: unknown, a3?: unknown, a4?: unknown, a5?: unknown, a6?: unknown, a7?: unknown,
+                a8?: unknown, a9?: unknown, a10?: unknown, a11?: unknown, a12?: unknown, a13?: unknown, a14?: unknown, a15?: unknown): unknown => {
+                const current = lookup === last ? site : siteOf(lookup);
+                if (current === null) return asWritten(lookup, [a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13, a14, a15].slice(0, count));
+                return current.find(a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, a10, a11, a12, a13, a14, a15);
+            },
+        };
+    }
+};

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

@@ -0,0 +1,165 @@
+// © 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 { listIndexOf, listShapeOf, positionalOf, type ListShape, type Positional } from './lists.js';
+import type { Key, State } from './state.js';
+
+type TargetedCommands = Commands & { readonly [commandsTarget]: CommandsTarget };
+
+const isTargeted = (commands: Commands): commands is TargetedCommands => commandsTarget in commands;
+
+/** The values object a site would have built, for calls the site can't take positionally. */
+const valuesOf = (keys: readonly Key[], values: readonly unknown[]): { [key: string | symbol]: unknown } => {
+    const object: { [key: string | symbol]: unknown } = {};
+    keys.forEach((key, k) => { object[key] = values[k]; });
+    return object;
+};
+
+/** What a site resolved for a world and shape. */
+type Planned = { readonly state: State; readonly shape: ListShape };
+
+/** 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: [] });
+
+/**
+ * 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 = 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);
+};
+
+/** 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[shape.index];
+    if (plan === undefined || plan.shape !== shape) {
+        plan = make(state, shape, site);
+        plans.byShape[shape.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;
+};
+
+/** What a spawn site resolved for a world and list: the spawns of its shape taking the site's values in its key order. */
+type SpawnPlan = Planned & { readonly spawn: Positional };
+
+const spawnPlanOf = (state: State, shape: ListShape, site: readonly Key[]): SpawnPlan => ({ state, shape, spawn: positionalOf(state, shape, site) });
+
+/**
+ * One spawn site's staging, for code the compiler emits for `commands.spawn(components)({ ... })` with literal keys:
+ * `begin(commands, components)` returns the function spawning with the site's values in its key order, generated for
+ * the shape so its stores are specialized, or null when the spawn must go through `fallback`.
+ */
+export type PreparedSpawn = {
+    readonly begin: (commands: Commands, components: readonly Essential[]) => Positional | null;
+    readonly fallback: (commands: Commands, components: readonly Essential[], values: readonly unknown[]) => Entity;
+};
+
+/**
+ * The compiler's hook for a main-thread spawn site with literal keys: the call becomes a per-site function taking the
+ * values in key order, so no value object is built and nothing is read by key. `keys` is called on first use, after
+ * the module's key constants are initialized. Commands it didn't make go through `commands.spawn` as written.
+ */
+export const prepareSpawn = (keys: () => readonly Key[]): PreparedSpawn => {
+    let resolved: readonly Key[] | null = null;
+    /** A key named twice means the later value wins, as in the object literal: such sites use `commands.spawn`. */
+    let distinct = false;
+    const plans = createPlans<SpawnPlan>();
+    return {
+        begin: (commands, components) => {
+            if (resolved === null) {
+                resolved = keys();
+                distinct = new Set(resolved).size === resolved.length;
+            }
+            if (!distinct || !isTargeted(commands)) return null;
+            return planFor(plans, commands[commandsTarget].state, components, resolved, spawnPlanOf).spawn;
+        },
+        // Commands this world didn't make, or keys named twice, which only an untyped values object can carry.
+        fallback: (commands, components, values) => Reflect.apply(commands.spawn(components), undefined, [valuesOf(resolved ?? keys(), values)]),
+    };
+};
+
+/**
+ * What an add site resolved for a world and list: its values' component ids, -1 for one the list doesn't name, with
+ * their starts, and the list's other components with theirs.
+ */
+type AddPlan = Planned & { readonly ids: readonly number[]; readonly given: readonly unknown[]; readonly missing: readonly number[]; readonly starts: readonly unknown[] };
+
+const addPlanOf = (state: State, shape: ListShape, site: readonly Key[]): AddPlan => {
+    const named = shape.keys.flatMap((key, k) => site.includes(key) ? [] : [k]);
+    const at = site.map(key => typeof key === "symbol" ? shape.keys.indexOf(key) : -1);
+    return {
+        state,
+        shape,
+        ids: at.map(k => k < 0 ? -1 : shape.ids[k]),
+        given: at.map(k => k < 0 ? undefined : shape.starts[k]),
+        missing: named.map(k => shape.ids[k]),
+        starts: named.map(k => shape.starts[k]),
+    };
+};
+
+/**
+ * One add site's command, for code the compiler emits for `commands.add(entity, components, { ... })` with literal
+ * keys: `begin(commands, entity, components)` appends the add command and returns true, or false when the add must go
+ * through `fallback`; then `value(k, value)` appends value `k`, `undefined` as its start; `end()` appends the starts of
+ * the components the site gives no value.
+ */
+export type PreparedAdd = {
+    readonly begin: (commands: Commands, entity: Entity, components: readonly Essential[]) => boolean;
+    readonly value: (k: number, value: unknown) => void;
+    readonly end: () => void;
+    readonly fallback: (commands: Commands, entity: Entity, components: readonly Essential[], values: readonly unknown[]) => void;
+};
+
+/**
+ * The compiler's hook for a main-thread add site with literal keys: the call becomes a per-site function taking the
+ * entity and values in key order, so no value object is built and nothing is read by key. Ids are resolved once per
+ * world and list, so a key that isn't a component commands may add throws before anything is appended, as
+ * `commands.add` does. Commands it didn't make go through `commands.add` as written.
+ */
+export const prepareAdd = (keys: () => readonly Key[]): PreparedAdd => {
+    let resolved: readonly Key[] | null = null;
+    let distinct = false;
+    const plans = createPlans<AddPlan>();
+    let plan: AddPlan | null = null;
+    let buffer: CommandBuffer | null = null;
+    return {
+        begin: (commands, entity, components) => {
+            if (resolved === null) {
+                resolved = keys();
+                distinct = new Set(resolved).size === resolved.length;
+            }
+            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;
+            return true;
+        },
+        value: (k, value) => {
+            const id = plan === null ? -1 : plan.ids[k];
+            if (buffer === null || plan === null || id < 0) return;
+            pushComponent(buffer, id, value === undefined ? plan.given[k] : value);
+        },
+        end: () => {
+            if (buffer === null || plan === null) return;
+            const { missing, starts } = plan;
+            for (let k = 0; k < missing.length; k++) pushComponent(buffer, missing[k], starts[k]);
+        },
+        fallback: (commands, entity, components, values) => Reflect.apply(commands.add, commands, [entity, components, valuesOf(resolved ?? keys(), values)]),
+    };
+};

package/src/implementation/world/program.ts

@@ -0,0 +1,14 @@
+// © 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';
+
+/**
+ * The components a world must have met before the item can match anything there: all of them, or for a changes
+ * finalizer any one it watches. Empty when it can match from the start.
+ */
+export const triggersOf = (item: Rule | Finalizer): { readonly keys: readonly Key[]; readonly any: boolean } => {
+    if (item.kind === "rule") return { keys: item.declaration.components.has ?? [], any: false };
+    if (item.kind === "finalizer") return { keys: [...item.declaration.components.read ?? [], ...item.declaration.components.has ?? []], any: false };
+    return { keys: item.declaration.watch ?? [], any: true };
+};

package/src/implementation/world/protocol.ts

@@ -0,0 +1,134 @@
+// © 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" | "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 optional: readonly number[]; readonly not: readonly number[]; readonly changed: readonly number[] | null };
+
+export type KernelSetup = {
+    readonly index: number;
+    readonly url: string;
+    readonly sources: readonly Source[];
+    readonly booleans: readonly boolean[];
+    readonly strides: readonly number[];
+    readonly offsets: readonly number[];
+    /** Tick columns nothing observes: they point at a dummy element. */
+    readonly muted: readonly boolean[];
+    readonly lookups: readonly LookupSetup[];
+    /** By lookup through an index: its lookup, how its JS reader reads it, and how many components it watches. */
+    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. */
+    readonly spawns: readonly (readonly number[])[];
+    readonly added: readonly number[];
+    readonly changed: readonly number[];
+    /** For a kernel reading `up`: each parent column's boolean flag, stride and offset, the same in every archetype. */
+    readonly up: { readonly booleans: readonly boolean[]; readonly strides: readonly number[]; readonly offsets: readonly number[] };
+    /** Whether the kernel reduces: its fast tasks then carry their partials' address and stride after the scalars. */
+    readonly reduces: boolean;
+    /** The compiled WASM version, which workers instantiate against the shared memory and prefer. */
+    readonly wasm: { readonly module: WebAssembly.Module; readonly scalars: readonly WasmScalar[]; readonly imports: readonly string[] } | null;
+};
+
+/**
+ * Messages are handled in order, so new components' schemas always arrive before the tasks that use them. Where
+ * archetypes and the entity table are in the memory, workers read from the layout directory, whose header is at byte
+ * `header` (`layout-directory.ts`).
+ */
+export type ToWorker =
+    /** From a lent worker's owner, first: the port every later message arrives on and every reply goes to. */
+    | { readonly kind: "port"; readonly port: Endpoint }
+    /** The memory, its layout directory's header, and the byte offset of this worker's control words, its command ring's among them. */
+    | { readonly kind: "memory"; readonly memory: WebAssembly.Memory; readonly header: number; readonly control: number }
+    /** Wait on this worker's task ring in shared memory until asked to leave. Offsets are bytes into the memory. */
+    | { readonly kind: "window"; readonly control: number; readonly statuses: number; readonly payloads: number; readonly claims: number; readonly worker: number; readonly epoch: number }
+    /** New components' schemas; none for a value that isn't data. */
+    | { readonly kind: "layout"; readonly schemas: readonly (readonly [number, Schema | undefined])[] }
+    | { readonly kind: "kernels"; readonly task: number; readonly kernels: readonly KernelSetup[] }
+    /** For tests of what a world holds: how many kernels this worker keeps. */
+    | { readonly kind: "tables"; readonly task: number }
+    | {
+        readonly kind: "run";
+        readonly task: number;
+        readonly kernel: number;
+        readonly archetype: number;
+        readonly start: number;
+        readonly end: number;
+        readonly tick: number;
+        /** Rows pass only if a filtered tick is newer than this; `-1` passes every row. */
+        readonly lastRun: number;
+        readonly resources: readonly unknown[];
+        readonly args: unknown;
+        /** The byte address of this chunk's reduction partials, or -1 for a kernel without reductions. */
+        readonly partials: number;
+        /** 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 };
+
+/**
+ * A task's completion: its segment of the worker's command ring, as start and end bytes past the ring's base, and what
+ * it wrote past the ring's size, or null (`command-ring.ts`). A failed task's segment holds what it issued before failing,
+ * which applies, as the main thread's would.
+ */
+export type FromWorker =
+    | { readonly kind: "done"; readonly task: number; readonly start: number; readonly end: number; readonly spill: Uint8Array | null }
+    | { readonly kind: "failed"; readonly task: number; readonly start: number; readonly end: number; readonly spill: Uint8Array | null; readonly error: WorkerError }
+    | { readonly kind: "tables"; readonly task: number; readonly kernels: number };
+
+/**
+ * Tasks a worker's ring holds, and f64 words per task: twelve fields, then scalars. The fields are kernel, archetype,
+ * start, end, tick, lastRun, the window epoch, the scalar count, then the split's claims: the line of its first range
+ * word (-1 for none), the grain, this worker's participant index and the participant count. Without claims the task
+ * runs `start` to `end`; with them it runs the `grain`-row pieces it claims (`claims.ts`).
+ */
+export const ringSize = 64;
+/** A ring task's kernel that runs nothing: a round trip to the worker and back, as the `wake` benchmark measures. */
+export const idleKernel = -1;
+export const taskWords = 32;
+export const taskFields = 12;
+export const maximumScalars = taskWords - taskFields;
+/**
+ * Int32 words per 128-byte cache line, the largest in use (Apple silicon). Words that different threads write each get
+ * a line of their own, so a store by one doesn't invalidate the line another is polling.
+ */
+export const lineWords = 32;
+/** Splits in flight with claims the pool holds room for: one range word per worker each, each on its own line. */
+export const splitCount = 256;
+/**
+ * Control words per worker: tasks posted, tasks done, the window epoch, and a signal bumped on every post or close,
+ * which the worker waits on, so a wake-up between its check and its wait isn't lost. Closing a window bumps the
+ * epoch; a worker leaves its window when the epoch moves on, and runs only tasks posted in its own window's epoch,
+ * so a task posted after a close waits until the worker has handled the messages sent before it.
+ */
+export const posted = 0;
+export const done = 1;
+export const epoch = 2;
+export const signal = 3;
+/**
+ * The worker's command ring: its base and capacity in bytes, which the world sets at sync points; its write cursor past
+ * the base, which the worker stores at each task's end and the world resets at sync points; and the bytes its tasks
+ * needed since, spills included, which the next sync point grows the ring to. The base reads as unsigned.
+ */
+export const ringBase = 4;
+export const ringCapacity = 5;
+export const ringCursor = 6;
+export const ringNeeded = 7;
+/** Each worker's control words take a whole line. */
+export const controlWords = lineWords;

package/src/implementation/world/publish.ts

@@ -0,0 +1,29 @@
+// © 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';
+import type { Pool } from './pool.js';
+import type { State } from './state.js';
+
+/**
+ * Returns a function that brings workers up to date with the shared memory's layout: it flushes the layout directory,
+ * where workers find archetypes and the entity table, and posts only new components' schemas. Called after every
+ * sync point and wherever registration changes layouts, so workers see them before the next run's tasks; allocates
+ * nothing when nothing is new.
+ */
+export const createPublisher = (state: State, pool: Pool): (() => void) => {
+    let schemasSent = 0;
+    return () => {
+        flushBetween(state.directory, state.bumped, state.archetypes, state.entities, state.resourceEntity, state.counted);
+        if (schemasSent === state.keys.length) return;
+        // Workers never touch resources, so their schemas, defaults included, stay on the world's thread.
+        // A value that isn't data has no schema; workers store it as an object they never touch.
+        const schemas: (readonly [number, Schema | undefined])[] = [];
+        for (let id = schemasSent; id < state.keys.length; id++) {
+            if (!state.resources.has(id)) schemas.push([id, schemaOf(state.keys[id])]);
+        }
+        if (schemas.length > 0) pool.broadcast({ kind: "layout", schemas });
+        // Only once sent, so a failed broadcast is retried after the next sync point.
+        schemasSent = state.keys.length;
+    };
+};