@adobe/ecs 0.0.0-stage → 0.2.0

package/src/implementation/world/joining.ts

@@ -0,0 +1,387 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { World } from '../../interface/world/world.js';
+import type { WorkerError } from './protocol.js';
+import type { Schema } from '../../interface/schema/schema.js';
+import { layoutOf, viewsOf, type Layout, type Views } from '../../interface/registry/layout.js';
+import { lineWords } from './protocol.js';
+
+// What a world's thread and a thread that joined it share: their messages, the joined thread's control words and run
+// slots in shared memory, and how a run's input is written into a slot.
+
+/** Marks this channel's messages, so a port that carries others too, such as a worker's scope, can share it. */
+export const protocolName = "@adobe/ecs/join@1";
+
+/** An index without an id, by its declaration, its keys by a joined thread's numbers: the world makes one like it. */
+export type ObserverIndex = {
+    readonly name: string;
+    readonly key: readonly number[];
+    readonly has: readonly number[];
+    readonly not: readonly number[];
+    readonly sorted: boolean;
+    readonly unique: boolean;
+};
+
+/** A lookup of an observer system a joined thread declares: its keys by that thread's numbers, its index by id or declaration. */
+export type ObserverLookup = {
+    readonly name: string;
+    readonly read: readonly number[];
+    readonly has: readonly number[];
+    readonly optional: readonly number[];
+    readonly not: readonly number[];
+    /** Null where it doesn't declare `changed`. */
+    readonly changed: readonly number[] | null;
+    readonly index: string | ObserverIndex | null;
+};
+
+/** What an observer system a joined thread declares reads, by that thread's numbers for its keys. */
+export type ObserverDeclaration = {
+    /**
+     * Its components' lists, and whether it has `where`, which runs on its thread: the world posts one with `where` and
+     * change filters after every sync point, since it keeps a point per archetype there.
+     */
+    readonly components: { readonly read: readonly number[]; readonly has: readonly number[]; readonly optional: readonly number[]; readonly not: readonly number[]; readonly added: readonly number[]; readonly changed: readonly number[]; readonly where: boolean } | null;
+    readonly resources: { readonly read: readonly number[]; readonly changed: readonly number[]; readonly is: readonly number[]; readonly not: readonly number[] } | null;
+    readonly lookup: readonly ObserverLookup[];
+};
+
+/** An observer system the world places on a joined thread: its index there, the thread's own by its number or one by its id, and its block. */
+export type ObserverSetup = {
+    readonly index: number;
+    readonly local: number | null;
+    readonly id: string | null;
+    readonly keys: readonly (readonly [number, string])[];
+    /** The byte offset of its block (`joined-observer.ts`). */
+    readonly block: number;
+    /**
+     * For one reading only struct resources, the byte offset of a second block: its posts, in either, hold copies of
+     * what they read, so it runs them without this thread's objects.
+     */
+    readonly spare: number | null;
+    readonly indexes: readonly (readonly [string, number])[];
+};
+
+/** From a joined thread to the world's: messages are handled in the order they're posted. */
+export type ToWorld = { readonly protocol: typeof protocolName } & (
+    /**
+     * First: the logical threads it claims; whether it can wait without blocking, so it's woken without a message; and
+     * the name of a Web Lock it holds while it lives, where the platform has them, which the world then requests, so
+     * it's granted when the thread ends however it ends.
+     */
+    | {
+        readonly kind: "join"; readonly threads: readonly string[]; readonly waits: boolean; readonly lock: string | null;
+        /** With claims: the ids of the systems and finalizers this thread imported, so the world checks those it places here. */
+        readonly imported: readonly string[];
+    }
+    /** The id of a key or system it numbers `number`, posted before the first use of that number. */
+    | { readonly kind: "name"; readonly number: number; readonly id: string; readonly item: boolean }
+    /** The input of run `sequence`, which its slot says comes by message. */
+    | { readonly kind: "input"; readonly sequence: number; readonly input: unknown }
+    /**
+     * The input of run `sequence` of joined thread `from`, which its slot says moved to this thread, arrived here: the
+     * world starts that run once this arrives.
+     */
+    | { readonly kind: "received"; readonly from: number; readonly sequence: number }
+    /** Where the world can't wait without blocking: runs were posted. */
+    | { readonly kind: "wake" }
+    /**
+     * Once it joined, on its first turn of its event loop after: what it did as its join resolved, observer systems it
+     * added included, came before, so the world's `share` resolves.
+     */
+    | { readonly kind: "ready" }
+    | { readonly kind: "leave" }
+    /**
+     * After task `sequence` is done, when its completion says a message follows: its systems' errors and spilled
+     * segments, by position in the task; posted after the thread's numbers for keys its commands named first. `stamps`
+     * are the objects tails wrote from their snapshots, as position in the task, entity and component, which the world
+     * stamps changed at their tick. `values` are what bodies of systems without components returned, but undefined.
+     */
+    | {
+        readonly kind: "completed"; readonly sequence: number;
+        readonly errors: readonly (readonly [number, WorkerError])[]; readonly spills: readonly (readonly [number, Uint8Array])[];
+        readonly stamps?: readonly number[];
+        readonly values?: readonly (readonly [number, unknown])[];
+    }
+    /** What its finalizers threw, by their index on this thread, which the world reports out of band. */
+    | { readonly kind: "finalized"; readonly errors: readonly (readonly [number, WorkerError])[] }
+    /** It dropped what it held for the systems unplaced at these indexes, which the world may place again. */
+    | { readonly kind: "unplaced"; readonly indexes: readonly number[] }
+    /**
+     * An observer system of its own, by its number for it, which no other of its messages uses, with its label and what
+     * it reads; added to ticks with `added`.
+     */
+    | { readonly kind: "observer"; readonly number: number; readonly name: string; readonly declaration: ObserverDeclaration; readonly added: boolean }
+    /** Its observer system `number` is added to ticks, removed from them, or no longer needed, its value collected. */
+    | { readonly kind: "observer add" | "observer remove" | "observer drop"; readonly number: number }
+    /** What observer systems placed on it threw, by their indexes there, which the world reports out of band. */
+    | { readonly kind: "observer failed"; readonly errors: readonly (readonly [number, WorkerError])[] }
+    /**
+     * Posts owed to runs of the world's ran there, by the indexes of their systems there: what each body returned, or
+     * what it threw, which those runs resolve to or reject with.
+     */
+    | { readonly kind: "observer ran"; readonly results: readonly (readonly [number, unknown, WorkerError | null])[] }
+    /** It dropped the observer systems at these indexes, which the world unplaced. */
+    | { readonly kind: "observer dropped"; readonly indexes: readonly number[] }
+    /** A post it claimed and couldn't run yet, owed to a run: the world posts it again between runs. */
+    | { readonly kind: "observer again" }
+);
+
+/** From the world's thread to a joined one. */
+export type ToJoined = { readonly protocol: typeof protocolName } & (
+    /**
+     * The memory, and the byte offset of the thread's control words; whether the world can wait without blocking; the
+     * byte offsets of its move log's header and its task block (`thread-tasks.ts`), null without claims; and its
+     * number, which storage flags name.
+     */
+    | {
+        readonly kind: "joined"; readonly memory: WebAssembly.Memory; readonly control: number; readonly waits: boolean; readonly log: number | null;
+        readonly tasks: number | null; readonly thread: number;
+    }
+    /**
+     * Systems the world places on the thread, each by its index there and its id, with the world's numbers for its keys
+     * and the byte offset of its removed word, which the thread checks before it runs the system.
+     */
+    | { readonly kind: "systems"; readonly systems: readonly { readonly index: number; readonly id: string; readonly keys: readonly (readonly [number, string])[]; readonly removed: number; readonly indexes: readonly (readonly [string, number])[] }[] }
+    /**
+     * Systems the world removed, by their indexes there, whose removed words are set: the thread drops what it holds
+     * for them once it finished task `sequence`, the last posted before, and says so.
+     */
+    | { readonly kind: "unplace"; readonly indexes: readonly number[]; readonly sequence: number }
+    /** Observer systems the world places on the thread, which run there after sync points. */
+    | { readonly kind: "observer"; readonly systems: readonly ObserverSetup[] }
+    /** Observer systems the world removed, by their indexes there, whose removed words are set: the thread drops them and says so. */
+    | { readonly kind: "unplace observers"; readonly indexes: readonly number[] }
+    /** Finalizers the world places on the thread, as systems are: each one's index there, its id, and the world's numbers for its keys. */
+    | { readonly kind: "finalizers"; readonly finalizers: readonly { readonly index: number; readonly id: string; readonly keys: readonly (readonly [number, string])[] }[] }
+    /**
+     * The input of task `sequence`, which its payload says comes by message; or, with `held`, the input of run
+     * `held[1]` of joined thread `held[0]`, which moved here when it was run.
+     */
+    | { readonly kind: "task input"; readonly sequence: number; readonly input: unknown; readonly held?: readonly [number, number] }
+    /**
+     * A channel to joined thread `thread`, claiming `threads`, through `port`: a run there of a system on one of them
+     * moves the Transferable values of its input here through it, and one here moves them there.
+     */
+    | { readonly kind: "peer"; readonly thread: number; readonly threads: readonly string[]; readonly port: Parameters<World["share"]>[0] }
+    /** Joined thread `thread` is gone: its channel closes, and its threads are the world's again. */
+    | { readonly kind: "unpeer"; readonly thread: number }
+    /** Run `sequence` of joined thread `from`, whose input moved here, finished: what of it no task took is released. */
+    | { readonly kind: "release"; readonly from: number; readonly sequence: number }
+    /** A component whose objects the thread fills, by the world's number, with its id: null for one without. */
+    | { readonly kind: "component"; readonly component: number; readonly id: string | null }
+    | { readonly kind: "refused"; readonly message: string }
+    /** The name of the Web Lock the world's thread holds while it lives (`threadLock`), posted as it's shared and as it's asked to join. */
+    | { readonly kind: "thread lock"; readonly lock: string }
+    | { readonly kind: "rejected"; readonly sequence: number; readonly message: string }
+    /** Run `sequence` resolved to `value`, a value but undefined. */
+    | { readonly kind: "resolved"; readonly sequence: number; readonly value: unknown }
+    /** Where the joined thread can't wait without blocking: runs completed, or a task or observer post waits for it. */
+    | { readonly kind: "wake" }
+    | { readonly kind: "disposed" }
+);
+
+/** From a joined thread to another, through their channel: the input of run `sequence`, moved from that thread. */
+export type ToPeer = { readonly protocol: typeof protocolName; readonly kind: "transfer"; readonly sequence: number; readonly input: unknown };
+
+/** A joined thread's channel to the world, or the world's to it, over the port it was given; or a joined thread's to another. */
+export type ThreadChannel<Send, Receive> = {
+    /** Posts a message, moving the Transferable values `transfer` lists; throws for a value that can't be posted. */
+    readonly post: (message: Send, transfer?: readonly object[]) => void;
+    /** Sets the one handler for this protocol's messages; others are ignored. */
+    readonly onMessage: (handler: (message: Receive) => void) => void;
+    /** Sets the one handler for the other end's end: a `MessagePort`'s close, or a node worker's exit. */
+    readonly onClose: (handler: () => void) => void;
+    /**
+     * Sets the one handler for a `Worker`'s `error` or `messageerror`, with its message: a worker that failed to start
+     * or threw, or a message that couldn't be read. Nothing for other ports, whose `error` is this thread's own.
+     */
+    readonly onFailure: (handler: (message: string) => void) => void;
+    /**
+     * Whether the port's other end is already closed, once `onMessage` is set: a node `MessagePort` that a listener
+     * doesn't keep alive is closed, its `close` already past. False wherever the platform doesn't tell.
+     */
+    readonly closed: () => boolean;
+    /** Closes a `MessagePort`; a worker or a worker's scope stays as it is, its owner's to end. */
+    readonly close: () => void;
+};
+
+/** Whether a port is a `MessagePort` this thread may close: not a worker, nor its scope, whose `close` ends the worker. */
+const isMessagePort = (port: Parameters<World["share"]>[0]): boolean =>
+    typeof globalThis.MessagePort === "function" && port instanceof globalThis.MessagePort
+    && port !== globalThis.process?.getBuiltinModule?.("node:worker_threads")?.parentPort;
+
+/** Whether a port is a `Worker`, of the browser or node, whose `error` is that worker's. */
+const isWorker = (port: Parameters<World["share"]>[0]): boolean => {
+    const browser = globalThis.Worker;
+    const node = globalThis.process?.getBuiltinModule?.("node:worker_threads")?.Worker;
+    return (typeof browser === "function" && port instanceof browser) || (typeof node === "function" && port instanceof node);
+};
+
+/** What an `error` or `messageerror` says: an `ErrorEvent`'s message, an `Error`'s, or what a message couldn't be read as. */
+const failureMessage = (value: unknown): string => {
+    const message: unknown = typeof value === "object" && value !== null ? Reflect.get(value, "message") : undefined;
+    return typeof message === "string" && message !== "" ? message : "a message couldn't be read";
+};
+
+const isOurs = (data: unknown): boolean => typeof data === "object" && data !== null && Reflect.get(data, "protocol") === protocolName;
+
+/**
+ * A port as a channel: a browser `MessagePort`, `Worker` or worker scope through `addEventListener`, and a node
+ * `MessagePort`, `Worker` or `parentPort` through `on`.
+ */
+export const threadChannel = <Send, Receive>(port: Parameters<World["share"]>[0]): ThreadChannel<Send, Receive> => {
+    const on: unknown = Reflect.get(port, "on");
+    const listen: unknown = Reflect.get(port, "addEventListener");
+    const close: unknown = Reflect.get(port, "close");
+    const start: unknown = Reflect.get(port, "start");
+    const postMessage: unknown = Reflect.get(port, "postMessage");
+    const subscribe = (event: string, listener: (value: unknown) => void): void => {
+        if (typeof on === "function") Reflect.apply(on, port, [event, listener]);
+        else if (typeof listen === "function") Reflect.apply(listen, port, [event, listener]);
+    };
+    return {
+        post: (message, transfer) => {
+            if (typeof postMessage === "function") Reflect.apply(postMessage, port, transfer === undefined || transfer.length === 0 ? [message] : [message, transfer]);
+        },
+        onMessage: handler => {
+            // Node gives the data itself; the browser, an event holding it.
+            const node = typeof on === "function";
+            subscribe("message", value => {
+                const data: unknown = node ? value : typeof value === "object" && value !== null ? Reflect.get(value, "data") : undefined;
+                // A message marked with the protocol is one the other end posted as `Receive`.
+                if (isOurs(data)) handler(data as Receive);
+            });
+            if (!node && typeof start === "function") Reflect.apply(start, port, []);
+        },
+        onClose: handler => {
+            let closed = false;
+            const once = (): void => {
+                if (closed) return;
+                closed = true;
+                handler();
+            };
+            subscribe("close", once);
+            if (typeof on === "function") subscribe("exit", once);
+        },
+        onFailure: handler => {
+            if (!isWorker(port)) return;
+            subscribe("error", value => handler(failureMessage(value)));
+            subscribe("messageerror", value => handler(failureMessage(value)));
+        },
+        closed: () => {
+            const hasRef: unknown = Reflect.get(port, "hasRef");
+            return isMessagePort(port) && typeof on === "function" && typeof hasRef === "function" && Reflect.apply(hasRef, port, []) === false;
+        },
+        close: () => { if (isMessagePort(port) && typeof close === "function") Reflect.apply(close, port, []); },
+    };
+};
+
+/**
+ * A joined thread's control words, each on a line of its own: the signal it waits on, which the world bumps when runs
+ * complete or a task or observer post waits for it, beside whether a wake is unread, which the thread clears before it
+ * reads what's new, so the world notifies only a thread that has read every earlier wake; the last run it posted; and
+ * the last run the world completed. Then its run slots.
+ */
+export const signalWord = 0;
+export const unreadWord = 1;
+export const postedWord = lineWords;
+export const completedWord = 2 * lineWords;
+export const slotsWord = 3 * lineWords;
+
+/**
+ * Runs in flight a joined thread holds room for, each in slot `(sequence - 1) % runSlots`: its status and the run's
+ * number, which the world writes before completing it, the system's number, and its input's length in bytes, then the
+ * input.
+ */
+export const runSlots = 64;
+export const slotWords = 64;
+export const slotStatus = 0;
+export const slotNumber = 1;
+export const slotInput = 2;
+/** The input starts on an 8-byte boundary, as f64 views of it need. */
+export const slotPayload = 4;
+export const controlBytes = (slotsWord + runSlots * slotWords) * 4;
+/** Input written in its slot, at most this many bytes. */
+export const inlineInputBytes = (slotWords - slotPayload) * 4;
+/**
+ * A slot's input length for none, for an input posted as a message, and for one moved to the joined thread its system
+ * runs on, whose number is the slot's first payload word.
+ */
+export const noInput = -1;
+export const inputByMessage = -2;
+export const inputMoved = -3;
+/** A slot's system number for a run whose input couldn't be posted, which the world completes without running. */
+export const unposted = -1;
+/** Slot statuses: in flight; done, to nothing; rejected, the rejection posted; resolved, its value posted. */
+export const pending = 0;
+export const done = 1;
+export const rejected = 2;
+export const resolved = 3;
+
+/** The schema with every number widened to f64, so a run's input crosses exactly as given. */
+const widened = (schema: Schema): Schema => {
+    if (!("type" in schema)) return schema;
+    switch (schema.type) {
+        case "number":
+        case "integer": return { type: "number" };
+        case "array": return { ...schema, items: widened(schema.items) };
+        case "object": {
+            const properties: { [name: string]: Schema } = {};
+            for (const name of Object.keys(schema.properties)) properties[name] = widened(schema.properties[name]);
+            return { ...schema, properties };
+        }
+        default: return schema;
+    }
+};
+
+const inputLayouts = new WeakMap<object, Layout | null>();
+
+/**
+ * How a system's input is written into a slot: a struct schema of at most `inlineInputBytes`, with every number an
+ * f64; null for any other, whose input is posted. Both threads compute it from the same declaration.
+ */
+export const inputLayoutOf = (system: object, schema: Schema | undefined): Layout | null => {
+    const known = inputLayouts.get(system);
+    if (known !== undefined) return known;
+    const layout = schema === undefined ? null : layoutOf(widened(schema));
+    const inline = layout !== null && layout.kind === "linear" && layout.stride <= inlineInputBytes ? layout : null;
+    inputLayouts.set(system, inline);
+    return inline;
+};
+
+/** Whether a value has every field a struct input's schema names, so writing it into a slot loses nothing. */
+export const fitsInline = (schema: Schema | undefined, value: unknown): boolean => {
+    if (schema === undefined || !("type" in schema) || schema.type !== "object" || typeof value !== "object" || value === null) return false;
+    for (const name of Object.keys(schema.properties)) if (!Object.hasOwn(value, name)) return false;
+    return true;
+};
+
+/** Views of each slot's input, made once per buffer: the control words never move, and memory only grows. */
+export const slotViews = (buffer: ArrayBufferLike, control: number): readonly Views[] =>
+    Array.from({ length: runSlots }, (_, slot) => viewsOf(buffer, control + (slotsWord + slot * slotWords + slotPayload) * 4, inlineInputBytes));
+
+/** The platform's Web Locks, where it has them, by which a thread that ends however it ends releases what it held. */
+export const platformLocks = (): LockManager | null => globalThis.navigator?.locks ?? null;
+
+/** A name for a Web Lock of this protocol, unique to the thread holding it. */
+export const lockName = (): string => `${protocolName}#${globalThis.crypto?.randomUUID?.() ?? String(Math.random()).slice(2)}`;
+
+let threadLockHeld: Promise<string | null> | null = null;
+
+/**
+ * The name of a Web Lock this thread holds for as long as it lives, once it holds it, where the platform's ports don't
+ * report a thread's end: a browser's. A world tells the threads joining it, which request it, so they hear of its
+ * thread's end however it ends. Null in node, whose ports close as a thread ends, and where a worker waiting for a lock
+ * the world's thread holds stalls while that thread waits for one of the worker's tasks; and where there are no locks.
+ */
+export const threadLock = (): Promise<string | null> => {
+    if (threadLockHeld !== null) return threadLockHeld;
+    const locks = globalThis.process?.versions?.node === undefined ? platformLocks() : null;
+    threadLockHeld = locks === null ? Promise.resolve(null) : new Promise(resolve => {
+        const name = lockName();
+        void locks.request(name, () => {
+            resolve(name);
+            return new Promise<void>(() => {});
+        });
+    });
+    return threadLockHeld;
+};

package/src/implementation/world/journal.ts

@@ -0,0 +1,40 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/**
+ * Entity indexes whose archetype or references sync points changed: spawned, despawned, moved to another archetype,
+ * or written a reference. Kept only while some reader, an `up` system or an index, needs it. Positions count every
+ * index ever appended, so each reader keeps its own; a position before `first` lost entries, which a reader then
+ * rebuilds from.
+ */
+export type Journal = {
+    indexes: Int32Array;
+    length: number;
+    /** The position of `indexes[0]`. */
+    first: number;
+    readers: number;
+};
+
+export const createJournal = (): Journal => ({ indexes: new Int32Array(0), length: 0, first: 0, readers: 0 });
+
+/** The position after the last entry. */
+export const journalEnd = (journal: Journal): number => journal.first + journal.length;
+
+/**
+ * Appends an entity index, once some reader exists. Past `limit` entries the journal drops the older half, so a reader
+ * within half of it of the end, as one current at the last sync point usually is, reads on; a reader further behind
+ * rebuilds, which costs about what reading that many entries would.
+ */
+export const record = (journal: Journal, index: number, limit: number): void => {
+    if (journal.readers === 0) return;
+    if (journal.length >= Math.max(4096, limit)) {
+        const kept = journal.length >> 1;
+        journal.indexes.copyWithin(0, journal.length - kept, journal.length);
+        journal.first += journal.length - kept;
+        journal.length = kept;
+    }
+    if (journal.length === journal.indexes.length) {
+        const grown = new Int32Array(Math.max(1024, 2 * journal.indexes.length));
+        grown.set(journal.indexes);
+        journal.indexes = grown;
+    }
+    journal.indexes[journal.length++] = index;
+};

package/src/implementation/world/kernel-imports-sparks.test-helper.ts

@@ -0,0 +1,16 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Vec3 } from "../../index.js";
+
+export const position = Symbol("kernelImports/position");
+export const spark = Symbol("kernelImports/spark");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [position]: { type: Vec3 };
+        [spark]: { type: true };
+    }
+}
+
+
+/** A list a kernel imports: the build reads its components here, and compiles the kernel again when this module changes. */
+export const sparks = [position, spark] as const;

package/src/implementation/world/kernel-imports-steer.test-helper.ts

@@ -0,0 +1,10 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { Vec3 } from "../../index.js";
+
+/** A pure helper a kernel imports: the build inlines it, and it still runs as written everywhere else. */
+export const steer = (velocity: Vec3, toward: Vec3, limit: number): Vec3 => {
+    const desired = Vec3.subtract(toward, velocity);
+    const length = Vec3.length(desired);
+    if (length <= limit) return Vec3.add(velocity, desired);
+    return Vec3.add(velocity, Vec3.scale(desired, limit / length));
+};

package/src/implementation/world/kernel-imports.test.ts

@@ -0,0 +1,71 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { expect, it } from "vitest";
+import { Entity, System, Vec3, World } from "../../index.js";
+import { Observe } from "../../observe/index.js";
+import { position, spark, sparks } from "./kernel-imports-sparks.test-helper.js";
+import { steer } from "./kernel-imports-steer.test-helper.js";
+import { createWorld } from "../index.js";
+import { workers } from "../../interface/resources/workers.js";
+
+const velocity = Symbol("kernelImports/velocity");
+const target = Symbol("kernelImports/target");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [velocity]: { type: Vec3 };
+        [target]: { type: Entity };
+    }
+}
+
+
+const spawn = System.create({}, ({ commands }) => {
+    const leader = commands.spawn([position, velocity])({ [position]: [10, 0, 0], [velocity]: [0, 0, 0] });
+    commands.spawn([position, velocity, target])({ [position]: [0, 0, 0], [velocity]: [0, 0, 0], [target]: leader });
+});
+
+// `kernel: true` compiles the body at build time, to run in chunks across workers as WASM where it can.
+const integrate = System.create({ kernel: true, components: { with: [velocity, position] } }, row => {
+    row[position] = Vec3.add(row[position], row[velocity]);
+});
+
+// Kernels use lookups, imported pure functions, commands and imported lists too.
+const chase = System.create({
+    kernel: true,
+    components: { with: [position, target, velocity] },
+    lookup: { targets: { with: [position] } },
+}, (row, { lookup, commands }) => {
+    const other = lookup.targets(row[target]);
+    if (other === null) return;
+    row[velocity] = steer(row[velocity], Vec3.subtract(other[position], row[position]), 2);
+    // A kernel builds tuple values from their leaves.
+    const [x, y, z] = row[position];
+    if (Vec3.distance(other[position], row[position]) < 1) commands.spawn(sparks)({ [position]: [x, y, z] });
+});
+
+it("runs systems compiled as kernels", async () => {
+    await using world = createWorld({ [workers]: 0 });
+    await world.run(spawn);
+    for (let step = 0; step < 6; step++) {
+        await world.run(chase);
+        await world.run(integrate);
+    }
+    const [follower] = await Observe.toPromise(Observe.select(world, { required: [target] }));
+    expect((await Observe.toPromise(Observe.entity(world, follower, { required: [position] })))?.[position][0]).toBeGreaterThan(9);
+    expect(await Observe.toPromise(Observe.count(world, { required: [spark] }))).toBeGreaterThan(0);
+});
+
+// A kernel's `add` and `remove` take an imported `Symbol(...)` as one key, and an imported list as a list.
+const ignite = System.create({}, ({ commands }) => {
+    commands.spawn(sparks)({ [position]: [0, 0, 0] });
+});
+const settle = System.create({ kernel: true, components: { with: [spark] } }, (row, { commands }) => {
+    commands.remove(row.entity, spark);
+});
+
+it("removes an imported key in a kernel", async () => {
+    await using world = createWorld({ [workers]: 0 });
+    await world.run(ignite);
+    await world.run(settle);
+    expect(await Observe.toPromise(Observe.count(world, { required: [spark] }))).toBe(0);
+    expect(await Observe.toPromise(Observe.count(world, { required: [position] }))).toBe(1);
+});