@adobe/ecs 0.0.0-stage → 0.2.0

package/src/implementation/world/pool.ts

@@ -0,0 +1,324 @@
+// © 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';
+import { maximumPieces, startRanges } from './claims.js';
+import { controlWords, splitCount, done, epoch, lineWords, posted, ringBase, ringCapacity, ringCursor, ringNeeded, ringSize, signal, taskFields, taskWords, type ToWorker, type WorkerError } from './protocol.js';
+import type { MergeTag, Segment } from './command-ring.js';
+import type { WorkerPort } from './worker-platform.js';
+
+type Task = Extract<ToWorker, { task: number }>;
+type Request = Task extends infer T ? T extends Task ? Omit<T, "task"> : never : never;
+
+/**
+ * A task's commands, plus its error if it failed partway; what it issued before the error still applies. A message
+ * task's commands and spawns are its segment of its worker's command ring, which the world drains.
+ */
+export type TaskResult = { readonly commands: CommandBuffer; readonly segment?: Segment; readonly error?: Error; readonly kernels?: number };
+
+/** A WASM kernel task: everything is a number, so it travels through shared memory instead of a message. */
+export type FastTask = {
+    readonly kernel: number;
+    readonly archetype: number;
+    readonly start: number;
+    readonly end: number;
+    readonly tick: number;
+    readonly lastRun: number;
+    readonly scalars: readonly number[];
+    /**
+     * The byte address of the task's first reduction partials, or -1 without reductions; they follow the scalars, and
+     * count against `maximumScalars`. A worker running claimed pieces folds piece `p` into the partials `p * partialBytes` past it.
+     */
+    readonly partials: number;
+    readonly partialBytes: number;
+};
+
+/**
+ * Workers sharing the world's memory, one per port. Messages to one worker are handled in the order they're posted.
+ * `claimed` tasks go through a ring in shared memory while workers wait on it in a window, which costs one message to
+ * open; a message, a broadcast or `close` ends the window, after the tasks already posted.
+ */
+export type Pool = {
+    readonly size: number;
+    readonly broadcast: (message: Exclude<ToWorker, { task: number }>) => void;
+    /** Posts a task to one worker. Never rejects: a failed task or a dead worker resolves with an error. */
+    readonly request: (worker: number, message: Request) => Promise<TaskResult>;
+    /**
+     * Posts one task to each of `workers` workers from `first`, which claim `grain`-row pieces of the task's range:
+     * each from its own home range first, then from others' (`claims.ts`), so faster workers take more and a worker
+     * mapped to the same range each tier finds its rows in cache. With no room for claims, splits the range evenly.
+     */
+    readonly claimed: (first: number, workers: number, task: FastTask, grain: number) => Promise<TaskResult>[];
+    /** How many workers were posted a task since the last call, which starts the count again. */
+    readonly takePosted: () => number;
+    readonly close: () => void;
+    /**
+     * At a sync point, once its segments are drained and while no task runs: empties every command ring, growing each
+     * one a task overflowed to what its tasks needed.
+     */
+    readonly rewind: () => void;
+    /**
+     * Ends the workers, through their ports, then releases the pool's control state to the arena once every worker that waited on it has
+     * left its window, as each acknowledges a message. One that doesn't within `releaseTimeout`, or that died with a
+     * window open, may still touch it, so it's kept.
+     */
+    readonly terminate: () => Promise<void>;
+};
+
+/** How long `terminate` waits for workers to leave their windows before keeping the control state. */
+const releaseTimeout = 1000;
+/** A command ring's first size in bytes; a sync point grows it to what a run's tasks needed. */
+const initialRingBytes = 1 << 16;
+
+const errorOf = ({ name, message, stack }: WorkerError): Error => Object.assign(new Error(message), { name, stack });
+
+/** A task waiting for its completion, with the merge tag of a run's segment, or null for one that writes none. */
+type Pending = { readonly settle: (result: TaskResult) => void; readonly tag: MergeTag | null };
+
+type Slot = {
+    readonly port: WorkerPort;
+    readonly pending: Map<number, Pending>;
+    /** Set once the worker fails to load, crashes or exits; it gets no more tasks. */
+    dead: Error | null;
+};
+
+type Block = { readonly offset: number; readonly bytes: number };
+
+/** Zeroed Int32 words starting on a cache line, so a block of whole lines shares none with other arrays; `blocks` records the block. */
+const allocateLines = (arena: Memory, words: number, blocks: Block[]): Int32Array => {
+    const lineBytes = lineWords * 4;
+    const bytes = words * 4 + lineBytes;
+    const offset = arena.allocate(bytes);
+    blocks.push({ offset, bytes });
+    return new Int32Array(arena.memory.buffer, Math.ceil(offset / lineBytes) * lineBytes, words).fill(0);
+};
+
+export const createPool = (ports: readonly WorkerPort[], arena: Memory): Pool => {
+    const { memory } = arena;
+    const size = ports.length;
+    let nextTask = 0;
+    const lines: Block[] = [];
+    const control = allocateLines(arena, size * controlWords, lines);
+    const statuses = allocateLines(arena, size * ringSize, lines);
+    const payloads = allocateArray(arena, Float64Array, size * ringSize * taskWords);
+    const claims = allocateLines(arena, splitCount * size * lineWords, lines);
+    /** Splits' claim slots no split in flight uses: one is reused only once every task of its split is done. */
+    const freeSplits = Array.from({ length: splitCount }, (_, split) => split);
+    const open = new Array<boolean>(size).fill(false);
+    /** Whether each worker was ever given a window or a run, and so may touch the control state. */
+    const windowed = new Array<boolean>(size).fill(false);
+    const sent = new Array<number>(size).fill(0);
+    /** Writes held back by a full ring, chained so they stay in order. */
+    const waiting = new Array<number>(size).fill(0);
+    const chains = Array.from({ length: size }, (): Promise<void> => Promise.resolve());
+    /** Each worker's command ring, in the memory. */
+    const rings: Block[] = Array.from({ length: size }, () => {
+        const bytes = initialRingBytes;
+        return { offset: arena.allocate(bytes), bytes };
+    });
+    const placeRing = (worker: number): void => {
+        const base = worker * controlWords;
+        Atomics.store(control, base + ringBase, rings[worker].offset);
+        Atomics.store(control, base + ringCapacity, rings[worker].bytes);
+        Atomics.store(control, base + ringCursor, 0);
+        Atomics.store(control, base + ringNeeded, 0);
+    };
+    for (let worker = 0; worker < size; worker++) placeRing(worker);
+    /** Whether a task wrote into a command ring since the last rewind. */
+    let written = false;
+    /** The workers posted a task since `takePosted` last ran, and how many. */
+    const postedTo = new Uint8Array(size);
+    let postedCount = 0;
+    const markPosted = (worker: number): void => {
+        if (postedTo[worker] !== 0) return;
+        postedTo[worker] = 1;
+        postedCount++;
+    };
+    const kill =(slot: Slot, error: Error): void => {
+        slot.dead ??= error;
+        for (const { settle } of slot.pending.values()) settle({ commands: emptyBuffer, error: slot.dead });
+        slot.pending.clear();
+    };
+    const slots: Slot[] = ports.map((port, worker) => {
+        const slot: Slot = { port, pending: new Map(), dead: null };
+        port.onMessage(message => {
+            const pending = slot.pending.get(message.task);
+            slot.pending.delete(message.task);
+            if (pending === undefined) return;
+            if (message.kind === "tables") return pending.settle({ commands: emptyBuffer, kernels: message.kernels });
+            const { start, end, spill } = message;
+            const wrote = end > start || spill !== null;
+            if (wrote) written = true;
+            // The ring moves only at a rewind, which waits for every task.
+            const segment = wrote && pending.tag !== null ? { bytes: spill ?? new Uint8Array(memory.buffer, rings[worker].offset + start, end - start), tag: pending.tag } : undefined;
+            pending.settle(message.kind === "done" ? { commands: emptyBuffer, segment } : { commands: emptyBuffer, segment, error: errorOf(message.error) });
+        });
+        port.onDeath(error => kill(slot, error));
+        port.post({ kind: "memory", memory, header: arena.header.byteOffset, control: control.byteOffset + worker * controlWords * 4 });
+        return slot;
+    });
+    const wake = (worker: number): void => {
+        Atomics.add(control, worker * controlWords + signal, 1);
+        Atomics.notify(control, worker * controlWords + signal);
+    };
+
+    const close = (): void => {
+        for (let worker = 0; worker < size; worker++) {
+            if (!open[worker]) continue;
+            open[worker] = false;
+            Atomics.add(control, worker * controlWords + epoch, 1);
+            wake(worker);
+        }
+    };
+
+    /** Opens a worker's window for the current epoch, after any messages already posted to it. */
+    const ensureOpen = (worker: number): void => {
+        if (open[worker]) return;
+        open[worker] = true;
+        windowed[worker] = true;
+        const current = Atomics.load(control, worker * controlWords + epoch);
+        slots[worker].port.post({ kind: "window", control: control.byteOffset, statuses: statuses.byteOffset, payloads: payloads.byteOffset, claims: claims.byteOffset, worker, epoch: current });
+    };
+
+    /** One brief spin for all waiters of a batch of tasks, which are short, before waiting without blocking. */
+    let spinUntil = 0;
+    /** Resolves once the worker has done `count` tasks. */
+    const whenDone = async (worker: number, count: number): Promise<void> => {
+        const index = worker * controlWords + done;
+        while (Atomics.load(control, index) < count) {
+            if (slots[worker].dead !== null) return;
+            if (performance.now() < spinUntil) continue;
+            const current = Atomics.load(control, index);
+            if (current >= count) return;
+            const waited = Atomics.waitAsync(control, index, current, 50);
+            if (waited.async) await waited.value;
+        }
+    };
+
+    const post = (worker: number, task: FastTask, line: number, grain: number, self: number, participants: number): Promise<TaskResult> => {
+        markPosted(worker);
+        const slot = slots[worker];
+        if (slot.dead !== null) return Promise.resolve({ commands: emptyBuffer, error: slot.dead });
+        const count = ++sent[worker];
+        const ring = (count - 1) % ringSize;
+        spinUntil = performance.now() + 2;
+        const write = (): void => {
+            // A write held back past a close reopens the window, behind the messages posted since.
+            ensureOpen(worker);
+            const current = Atomics.load(control, worker * controlWords + epoch);
+            const base = (worker * ringSize + ring) * taskWords;
+            payloads.set([task.kernel, task.archetype, task.start, task.end, task.tick, task.lastRun, current, task.scalars.length, line, grain, self, participants], base);
+            payloads.set(task.partials < 0 ? task.scalars : [...task.scalars, task.partials, task.partialBytes], base + taskFields);
+            Atomics.store(control, worker * controlWords + posted, count);
+            wake(worker);
+        };
+        // Written now when there's room, so the worker starts at once; otherwise in order, once the worker frees a slot.
+        let written: Promise<void>;
+        if (waiting[worker] === 0 && count - Atomics.load(control, worker * controlWords + done) <= ringSize) {
+            write();
+            written = Promise.resolve();
+        }
+        else {
+            waiting[worker]++;
+            written = chains[worker] = chains[worker].then(async () => {
+                await whenDone(worker, count - ringSize);
+                write();
+                waiting[worker]--;
+            });
+        }
+        return (async (): Promise<TaskResult> => {
+            await written;
+            await whenDone(worker, count);
+            if (slot.dead !== null) return { commands: emptyBuffer, error: slot.dead };
+            // The worker records each task's number, negated if it failed, so a reused slot can't hide a failure.
+            const failed = Atomics.load(statuses, worker * ringSize + ring) === -count;
+            return failed ? { commands: emptyBuffer, error: new Error("A world worker's kernel failed.") } : { commands: emptyBuffer };
+        })();
+    };
+
+    const claimed = (first: number, workers: number, task: FastTask, grain: number): Promise<TaskResult>[] => {
+        const pieces = Math.ceil((task.end - task.start) / grain);
+        const split = pieces <= maximumPieces ? freeSplits.pop() : undefined;
+        if (split === undefined) {
+            const share = Math.ceil((task.end - task.start) / workers / grain) * grain;
+            // Each share runs as the grain-row pieces it holds, into those pieces' partials, as claims would.
+            return Array.from({ length: workers }, (_, i) =>
+                post((first + i) % size, {
+                    ...task, start: task.start + i * share, end: Math.min(task.end, task.start + (i + 1) * share),
+                    partials: task.partials < 0 ? -1 : task.partials + (i * share / grain) * task.partialBytes,
+                }, -1, grain, 0, 0));
+        }
+        const line = split * size;
+        startRanges(claims.subarray(line * lineWords, (line + workers) * lineWords), workers, pieces);
+        const results = Array.from({ length: workers }, (_, i) => post((first + i) % size, task, line, grain, i, workers));
+        void Promise.all(results).then(() => freeSplits.push(split));
+        return results;
+    };
+
+    return {
+        size,
+        claimed,
+        takePosted: () => {
+            const count = postedCount;
+            if (count !== 0) {
+                postedTo.fill(0);
+                postedCount = 0;
+            }
+            return count;
+        },
+        broadcast: message => {
+            close();
+            for (const slot of slots) if (slot.dead === null) slot.port.post(message);
+        },
+        close,
+        rewind: () => {
+            if (!written) return;
+            written = false;
+            for (let worker = 0; worker < size; worker++) {
+                // A dead worker gets no more tasks, but may still be writing, so its ring is left to it.
+                if (slots[worker].dead !== null) continue;
+                const needed = Atomics.load(control, worker * controlWords + ringNeeded);
+                const ring = rings[worker];
+                if (needed > ring.bytes) {
+                    arena.free(ring.offset, ring.bytes);
+                    const bytes = Math.max(needed, 2 * ring.bytes);
+                    rings[worker] = { offset: arena.allocate(bytes), bytes };
+                }
+                placeRing(worker);
+            }
+        },
+        request: (worker, message) => new Promise(settle => {
+            close();
+            markPosted(worker);
+            const slot = slots[worker];
+            if (slot.dead !== null) return settle({ commands: emptyBuffer, error: slot.dead });
+            const task = nextTask++;
+            // Its command ring is in the control state, so `terminate` waits for it to leave, as for a window.
+            windowed[worker] = true;
+            slot.pending.set(task, { settle, tag: message.kind === "run" ? { tick: message.tick, archetype: message.archetype, start: message.start } : null });
+            slot.port.post({ ...message, task });
+        }),
+        terminate: async () => {
+            close();
+            // A worker handles messages only outside its window, so its reply means it has left and won't enter again.
+            const left = slots.map((slot, worker) => !windowed[worker] ? Promise.resolve(true)
+                : slot.dead !== null ? Promise.resolve(false)
+                : new Promise<boolean>(settle => {
+                    const task = nextTask++;
+                    slot.pending.set(task, { settle: result => settle(result.error === undefined), tag: null });
+                    slot.port.post({ kind: "kernels", kernels: [], task });
+                }));
+            let timer: ReturnType<typeof setTimeout> | undefined;
+            const timeout = new Promise<boolean>(settle => { timer = setTimeout(() => settle(false), releaseTimeout); });
+            const released = await Promise.race([Promise.all(left).then(all => all.every(Boolean)), timeout]);
+            clearTimeout(timer);
+            const disposed = new Error("The world is disposed.");
+            for (const slot of slots) kill(slot, disposed);
+            await Promise.all(slots.map(slot => slot.port.terminate()));
+            if (!released) return;
+            for (const { offset, bytes } of lines) arena.free(offset, bytes);
+            for (const { offset, bytes } of rings) arena.free(offset, bytes);
+            freeArray(arena, payloads);
+        },
+    };
+};

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

@@ -0,0 +1,148 @@
+// © 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`. */
+    readonly post: (message: Send, transfer?: ArrayBuffer[]) => void;
+    /** Sets the one handler for messages. */
+    readonly onMessage: (handler: (message: Receive) => void) => void;
+};
+
+/**
+ * A thread as another sees it: over a browser `Worker`, a node `worker_threads` worker, or a `MessagePort` another
+ * thread lent, whose owner reports its death and ends it.
+ */
+export type Port<Send, Receive> = Channel<Send, Receive> & {
+    /** Sets the one handler for the thread's death: a load failure, a crash or an exit. It's called at most once. */
+    readonly onDeath: (handler: (error: Error) => void) => void;
+    /** Ends the thread; resolves once it's gone, or once its owner has ended it. */
+    readonly terminate: () => Promise<void>;
+};
+
+/**
+ * A `MessagePort` of either platform, as both use it. A message's data is what the other end posted, typed by the
+ * channel it crosses, as the platforms' own `MessageEvent` types leave it.
+ */
+export type Endpoint = {
+    readonly postMessage: (message: unknown, transfer: ArrayBuffer[]) => void;
+    readonly addEventListener: (type: "message" | "close", listener: (event: { readonly data?: any }) => void) => void;
+    readonly start: () => void;
+    readonly close: () => void;
+};
+
+/**
+ * A worker another thread owns, lent to this one: `port` reaches the worker, and `owner` its owner, which reports the
+ * worker's death on it and ends the worker when asked. `P` is the platform's `MessagePort`, which transfers.
+ */
+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. `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 } => {
+    let error: Error | null = null;
+    let handler: ((error: Error) => void) | null = null;
+    return {
+        die: reason => {
+            if (error !== null) return;
+            error = reason;
+            handler?.(reason);
+        },
+        onDeath: next => {
+            handler = next;
+            if (error !== null) next(error);
+        },
+    };
+};
+
+const noTransfer: ArrayBuffer[] = [];
+
+/** A `MessagePort` as a channel. */
+export const endpointChannel = <Send, Receive>(endpoint: Endpoint): Channel<Send, Receive> => ({
+    post: (message, transfer = noTransfer) => endpoint.postMessage(message, transfer),
+    onMessage: handler => {
+        endpoint.addEventListener("message", event => handler(event.data));
+        endpoint.start();
+    },
+});
+
+/**
+ * A worker's own scope as a channel: node's `parentPort`, or a browser worker's `self`.
+ */
+export const scopeChannel = <Send, Receive>(): Channel<Send, Receive> => {
+    const parent = globalThis.process?.getBuiltinModule?.("node:worker_threads")?.parentPort ?? null;
+    if (parent !== null) return endpointChannel(parent);
+    return {
+        post: (message, transfer) => self.postMessage(message, { transfer }),
+        onMessage: handler => { self.onmessage = (event: MessageEvent<Receive>) => handler(event.data); },
+    };
+};
+
+/**
+ * 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. 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);
+    const death = createDeath();
+    const control = endpointChannel<ToOwner, FromOwner>(owner);
+    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", () => 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."));
+        terminated?.();
+    });
+    return {
+        ...channel,
+        onDeath: death.onDeath,
+        terminate: () => new Promise<void>(resolve => {
+            terminated = () => {
+                terminated = null;
+                port.close();
+                owner.close();
+                resolve();
+            };
+            control.post({ kind: "terminate" });
+        }),
+    };
+};
+
+/**
+ * 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 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);
+    let gone = false;
+    worker.onDeath(error => {
+        if (gone) return;
+        gone = true;
+        control.post({ kind: "death", message: error.message });
+    });
+    const end = async (): Promise<void> => {
+        // 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;
+        await worker.terminate();
+    };
+    control.onMessage(async message => {
+        if (message.kind === "closed") return control.post({ kind: "closed" });
+        gone = true;
+        await worker.terminate();
+        control.post({ kind: "terminated" });
+        owner.close();
+    });
+    return { terminate: end };
+};

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

@@ -0,0 +1,37 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import type * as Fixture from "./ports.fixture.js";
+
+/** Workers that die, are lent, or serve a world on a worker: the cases, over the fixture built for node or from source. */
+export const portsCases = (load: () => Promise<typeof Fixture>) => describe("thread ports", () => {
+    // A browser `Worker` ended from outside reports nothing, so there it's killed by the owner that lent it.
+    const ways: readonly ("exit" | "owner")[] = typeof Worker === "function" ? ["owner"] : ["exit", "owner"];
+    for (const by of ways) for (const wasm of [true, false]) {
+        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);
+            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);
+            for (const message of second) expect(message).toMatch(death);
+            expect(disposed).toBe(true);
+        }, 30000);
+    }
+
+    it("serve a world on a worker as its nested workers, with the main thread's results", async () => {
+        const fixture = await load();
+        const alone = await fixture.simulate(0, false);
+        const nested = await fixture.nested();
+        expect(nested.rows).toEqual(alone.rows);
+        expect(nested.tasks).toBeGreaterThanOrEqual(12 * 3);
+    }, 30000);
+
+    it("serve a world on a worker as workers the main thread lent it, with the main thread's results", async () => {
+        const fixture = await load();
+        const alone = await fixture.simulate(0, false);
+        const lent = await fixture.lent();
+        expect(lent.rows).toEqual(alone.rows);
+        expect(lent.tasks).toBeGreaterThanOrEqual(12 * 3);
+    }, 30000);
+});

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

@@ -0,0 +1,106 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/// <reference types="node" />
+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 "./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. */
+
+const value = Symbol("portsTest/value");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [value]: { type: number };
+    }
+}
+
+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({ 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;
+});
+
+/** Lends `count` of the platform's workers from this thread, as the main thread lends them to a world on a worker. */
+const lend = (count: number) => typeof Worker === "function" ? lendBrowserWorkers(count) : lendNodeWorkers(count);
+
+/**
+ * A heavy kernel's run on one worker, killed from outside the pool right after its task is posted: by ending the
+ * worker itself (`"exit"`, where the platform reports it) or by the owner that lent it (`"owner"`). The failures of
+ * that run and of the next, whose task can only fail, and whether `dispose` then finishes.
+ */
+export const killedMidTask = async (by: "exit" | "owner", wasm: boolean): Promise<{ readonly first: readonly string[]; readonly second: readonly string[]; readonly disposed: boolean }> => {
+    const lending = by === "owner" ? lend(1) : [];
+    const base = by === "owner" ? lentWorkers(lending.map(each => each.lent)) : platformWorkers();
+    if (base === null) throw new Error("This platform has no workers.");
+    const trigger = wasm ? "window" : "run";
+    let killed = false;
+    const platform: WorkerPlatform = {
+        count: 1,
+        start: () => {
+            const port = base.start();
+            if (port === null) return null;
+            return {
+                ...port,
+                post: (message, transfer) => {
+                    port.post(message, transfer);
+                    if (killed || message.kind !== trigger) return;
+                    killed = true;
+                    // From outside the pool: the worker itself, or its owner.
+                    void (by === "owner" ? lending[0].terminate() : port.terminate());
+                },
+            };
+        },
+    };
+    const world = createWorld({ [workers]: 1 }, { minimumChunk: 64, wasm, pool: platform });
+    await world.run(seed);
+    const first = (await runReported(world, heavy)).failures.map(failure => failure.message);
+    const second = (await runReported(world, heavy)).failures.map(failure => failure.message);
+    const disposed = await Promise.race([world.dispose().then(() => true), new Promise<boolean>(resolve => setTimeout(() => resolve(false), 20000))]);
+    return { first, second, disposed };
+};
+
+/** The host worker's messages: run `simulate` with its own nested workers, or with workers this thread lent it. */
+export type ToHost = { readonly kind: "nested" } | { readonly kind: "lent"; readonly lent: readonly Lent[] };
+export type FromHost = Awaited<ReturnType<typeof simulate>>;
+
+const hostFile = "./world-host.fixture.js";
+
+/** Starts the host worker, posts it one message with these ports to transfer, and resolves with its reply. */
+const askHost = (message: ToHost, browserPorts: readonly MessagePort[], nodePorts: readonly import("node:worker_threads").MessagePort[]): Promise<FromHost> => new Promise((resolve, reject) => {
+    if (typeof Worker === "function") {
+        const host = new Worker(new URL("./world-host.fixture.js", import.meta.url), { type: "module" });
+        host.onmessage = (event: MessageEvent<FromHost>) => { host.terminate(); resolve(event.data); };
+        host.onerror = event => reject(new Error(event.message));
+        host.postMessage(message, [...browserPorts]);
+        return;
+    }
+    const threads = globalThis.process.getBuiltinModule("node:worker_threads");
+    const host = new threads.Worker(new URL(hostFile, import.meta.url));
+    host.on("message", (reply: FromHost) => { void host.terminate(); resolve(reply); });
+    host.on("error", reject);
+    host.postMessage(message, [...nodePorts]);
+});
+
+/** `simulate(3)` on a world on a worker, its pool workers nested in it. */
+export const nested = (): Promise<FromHost> => askHost({ kind: "nested" }, [], []);
+
+/** `simulate(3)` on a world on a worker, its pool three workers this thread lent it. */
+export const lent = (): Promise<FromHost> => {
+    if (typeof Worker === "function") {
+        const lending = lendBrowserWorkers(3);
+        return askHost({ kind: "lent", lent: lending.map(each => each.lent) }, lending.flatMap(({ lent }) => [lent.port, lent.owner]), []);
+    }
+    const lending = lendNodeWorkers(3);
+    return askHost({ kind: "lent", lent: lending.map(each => each.lent) }, [], lending.flatMap(({ lent }) => [lent.port, lent.owner]));
+};
+
+/** `simulate` on this thread, for comparison. */
+export { simulate };