@adobe/ecs 0.0.0-stage → 0.2.0

package/src/implementation/world/thread-tasks.ts

@@ -0,0 +1,80 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { lineWords } from './protocol.js';
+
+// What the world's thread and a joined thread filling objects share to run that thread's systems (threads.md, "Systems
+// on other threads"): a task block of control words, the task's payload and its completion, and a command ring the
+// thread's systems write their segments into, as a pool worker's tasks do (`command-ring.ts`).
+//
+// One task is in flight per thread at a time: the world posts a task, the systems of one tier or of consecutive tiers
+// all on that thread, and waits for it before the next tier, or the sync point, starts.
+
+/**
+ * The task block's words, each group on a line of its own by the thread writing it: the task the world posted last,
+ * then the task the thread finished last and the last it failed whole, running none of it, as when it couldn't view
+ * the memory, whose message says why; then the command ring's base and capacity in bytes and the payload's and
+ * completion's offsets and capacities, which the world sets while no task runs; then the ring's write cursor past its
+ * base, which the thread stores at each segment's end and the world resets at sync points, and the bytes its segments
+ * needed since, spills included, which the next sync point grows the ring to.
+ */
+export const taskPostedWord = 0;
+export const taskDoneWord = lineWords;
+export const taskFailedWord = lineWords + 1;
+export const ringBaseWord = 2 * lineWords;
+export const ringCapacityWord = 2 * lineWords + 1;
+export const payloadOffsetWord = 2 * lineWords + 2;
+export const payloadCapacityWord = 2 * lineWords + 3;
+export const completionOffsetWord = 2 * lineWords + 4;
+export const completionCapacityWord = 2 * lineWords + 5;
+export const ringCursorWord = 3 * lineWords;
+export const ringNeededWord = 3 * lineWords + 1;
+export const taskBlockWords = 4 * lineWords;
+
+/**
+ * A task's payload, f64 words: its sequence; the sync the thread replays through before it runs; how many systems it
+ * runs; whether its input comes by message; then per system, in schedule order, its index on the thread, the tick it
+ * takes when it runs, its `lastRun`, its tier within the task, where its folds start in the completion, for a
+ * tail the byte offset of its block (`tail-blocks.ts`), else 0, and 1 when the run resolves to its body's value, which
+ * it then gives back, else 0. A task is all tails or none.
+ */
+export const payloadSequence = 0;
+export const payloadSync = 1;
+export const payloadCount = 2;
+export const payloadInput = 3;
+export const payloadSystems = 4;
+export const systemFields = 7;
+export const systemIndex = 0;
+export const systemTick = 1;
+export const systemLastRun = 2;
+export const systemTier = 3;
+export const systemFolds = 4;
+export const systemTail = 5;
+export const systemValued = 6;
+
+/** f64 words of a payload for `count` systems. */
+export const payloadWords = (count: number): number => payloadSystems + count * systemFields;
+
+/**
+ * A task's completion, f64 words: whether a message follows it, with failures, spilled segments, the thread's numbers
+ * for keys its commands named for the first time, or the rows a tail wrote from its snapshot; then per system its
+ * flags and its segment's start and end past the ring's base; then the systems' folds, at the offsets the payload gives.
+ */
+export const completionMessage = 0;
+export const completionSystems = 1;
+export const resultFields = 3;
+export const resultFlags = 0;
+export const resultStart = 1;
+export const resultEnd = 2;
+
+/** f64 words of a completion for `count` systems folding `folds` leaves in all. */
+export const completionWords = (count: number, folds: number): number => completionSystems + count * resultFields + folds;
+
+/**
+ * A system's result flags: it took its tick, its conditions holding; it ran its rows, so its folds count; it failed,
+ * its error in the message; its segment is in the message, past the ring's size; its body returned a value, in the
+ * message.
+ */
+export const executedFlag = 1;
+export const ranFlag = 2;
+export const failedFlag = 4;
+export const spilledFlag = 8;
+export const valuedFlag = 16;

package/src/implementation/world/threads.browser.test.ts

@@ -0,0 +1,51 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { workersCases } from "./workers.cases.js";
+import { layoutDirectoryCases } from "./layout-directory.cases.js";
+import { poolCases } from "./pool.cases.js";
+import { poolSizeCases } from "./pool-size.cases.js";
+import { dispatchCases } from "./dispatch.cases.js";
+import { reductionsCases } from "./reductions.cases.js";
+import { observedWorkersCases } from "./observed-workers.cases.js";
+import { changeBlocksCases } from "./change-blocks.cases.js";
+import { upWorkersCases } from "./up-workers.cases.js";
+import { portsCases } from "./ports.cases.js";
+import { commandRingsCases } from "./command-rings.cases.js";
+import { joiningCases } from "./joining.cases.js";
+import { remoteObjectsCases } from "./remote-objects.cases.js";
+import { threadSystemsCases } from "./thread-systems.cases.js";
+import { remoteFinalizersCases } from "./remote-finalizers.cases.js";
+import { tailsCases } from "./tails.cases.js";
+import { transfersCases } from "./transfers.cases.js";
+import { lifetimeCases } from "./lifetime.cases.js";
+import { removalCases } from "./removal.cases.js";
+import { indexWorkersCases } from "./index-workers.cases.js";
+import { indexBuildCases } from "./index-build.cases.js";
+import { entityLookupWorkersCases } from "./entity-lookup-workers.cases.js";
+import { observerJoinedCases } from "./observer-joined.cases.js";
+import { sharedWorkersCases } from "./shared-workers.cases.js";
+
+// Real workers in chromium: the cases over the fixtures' sources, as node runs them built.
+workersCases(() => import("./workers.fixture.js"));
+layoutDirectoryCases(() => import("./layout-directory.fixture.js"));
+poolCases(() => import("./pool.fixture.js"));
+poolSizeCases(() => import("./pool-size.fixture.js"));
+dispatchCases(() => import("./dispatch.fixture.js"));
+reductionsCases(() => import("./reductions.fixture.js"));
+observedWorkersCases(() => import("./observed-workers.fixture.js"));
+changeBlocksCases(() => import("./change-blocks.fixture.js"));
+upWorkersCases(() => import("./up-workers.fixture.js"));
+portsCases(() => import("./ports.fixture.js"));
+commandRingsCases(() => import("./command-rings.fixture.js"));
+joiningCases(() => import("./joining.fixture.js"));
+remoteObjectsCases(() => import("./remote-objects.fixture.js"));
+threadSystemsCases(() => import("./thread-systems.fixture.js"));
+remoteFinalizersCases(() => import("./remote-finalizers.fixture.js"));
+tailsCases(() => import("./tails.fixture.js"));
+transfersCases(() => import("./transfers.fixture.js"));
+lifetimeCases(() => import("./lifetime.fixture.js"));
+removalCases(() => import("./removal.fixture.js"));
+indexWorkersCases(() => import("./index-workers.fixture.js"));
+indexBuildCases(() => import("./index-build.fixture.js"));
+entityLookupWorkersCases(() => import("./entity-lookup-workers.fixture.js"));
+observerJoinedCases(() => import("./observer-joined.fixture.js"));
+sharedWorkersCases(() => import("./shared-workers.fixture.js"));

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

@@ -0,0 +1,83 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { builtFixture } from "./fixtures.test-helper.js";
+import type * as Workers from "./workers.fixture.js";
+import { workersCases } from "./workers.cases.js";
+import type * as LayoutDirectory from "./layout-directory.fixture.js";
+import { layoutDirectoryCases } from "./layout-directory.cases.js";
+import type * as Pool from "./pool.fixture.js";
+import { poolCases } from "./pool.cases.js";
+import type * as PoolSize from "./pool-size.fixture.js";
+import { poolSizeCases } from "./pool-size.cases.js";
+import type * as Dispatch from "./dispatch.fixture.js";
+import { dispatchCases } from "./dispatch.cases.js";
+import type * as Reductions from "./reductions.fixture.js";
+import { reductionsCases } from "./reductions.cases.js";
+import type * as ObservedWorkers from "./observed-workers.fixture.js";
+import { observedWorkersCases } from "./observed-workers.cases.js";
+import type * as ChangeBlocks from "./change-blocks.fixture.js";
+import { changeBlocksCases } from "./change-blocks.cases.js";
+import type * as UpWorkers from "./up-workers.fixture.js";
+import { upWorkersCases } from "./up-workers.cases.js";
+import type * as Ports from "./ports.fixture.js";
+import { portsCases } from "./ports.cases.js";
+import type * as CommandRings from "./command-rings.fixture.js";
+import { commandRingsCases } from "./command-rings.cases.js";
+import type * as Joining from "./joining.fixture.js";
+import { joiningCases } from "./joining.cases.js";
+import type * as RemoteObjects from "./remote-objects.fixture.js";
+import { remoteObjectsCases } from "./remote-objects.cases.js";
+import type * as ThreadSystems from "./thread-systems.fixture.js";
+import { threadSystemsCases } from "./thread-systems.cases.js";
+import type * as RemoteFinalizers from "./remote-finalizers.fixture.js";
+import { remoteFinalizersCases } from "./remote-finalizers.cases.js";
+import type * as Tails from "./tails.fixture.js";
+import { tailsCases } from "./tails.cases.js";
+import type * as Transfers from "./transfers.fixture.js";
+import { transfersCases } from "./transfers.cases.js";
+import type * as Lifetime from "./lifetime.fixture.js";
+import { lifetimeCases } from "./lifetime.cases.js";
+import type * as Removal from "./removal.fixture.js";
+import { removalCases } from "./removal.cases.js";
+import type * as IndexWorkers from "./index-workers.fixture.js";
+import { indexWorkersCases } from "./index-workers.cases.js";
+import type * as IndexBuild from "./index-build.fixture.js";
+import { indexBuildCases } from "./index-build.cases.js";
+import type * as EntityLookupWorkers from "./entity-lookup-workers.fixture.js";
+import { entityLookupWorkersCases } from "./entity-lookup-workers.cases.js";
+import type * as ObserverJoined from "./observer-joined.fixture.js";
+import { observerJoinedCases } from "./observer-joined.cases.js";
+import type * as ObserverContained from "./observer-contained.fixture.js";
+import { observerContainedCases } from "./observer-contained.cases.js";
+import type * as OptionalWorkers from "./optional-workers.fixture.js";
+import { optionalWorkersCases } from "./optional-workers.cases.js";
+import type * as SharedWorkers from "./shared-workers.fixture.js";
+import { sharedWorkersCases } from "./shared-workers.cases.js";
+
+// Real worker threads in node: the cases over fixtures `vitest.fixtures.ts` built, each typed as its source, which it's
+// built from.
+workersCases((): Promise<typeof Workers> => builtFixture("workers"));
+layoutDirectoryCases((): Promise<typeof LayoutDirectory> => builtFixture("layout-directory"));
+poolCases((): Promise<typeof Pool> => builtFixture("pool"));
+poolSizeCases((): Promise<typeof PoolSize> => builtFixture("pool-size"));
+dispatchCases((): Promise<typeof Dispatch> => builtFixture("dispatch"));
+reductionsCases((): Promise<typeof Reductions> => builtFixture("reductions"));
+observedWorkersCases((): Promise<typeof ObservedWorkers> => builtFixture("observed-workers"));
+changeBlocksCases((): Promise<typeof ChangeBlocks> => builtFixture("change-blocks"));
+upWorkersCases((): Promise<typeof UpWorkers> => builtFixture("up-workers"));
+portsCases((): Promise<typeof Ports> => builtFixture("ports"));
+commandRingsCases((): Promise<typeof CommandRings> => builtFixture("command-rings"));
+joiningCases((): Promise<typeof Joining> => builtFixture("joining"));
+remoteObjectsCases((): Promise<typeof RemoteObjects> => builtFixture("remote-objects"));
+threadSystemsCases((): Promise<typeof ThreadSystems> => builtFixture("thread-systems"));
+remoteFinalizersCases((): Promise<typeof RemoteFinalizers> => builtFixture("remote-finalizers"));
+tailsCases((): Promise<typeof Tails> => builtFixture("tails"));
+transfersCases((): Promise<typeof Transfers> => builtFixture("transfers"));
+lifetimeCases((): Promise<typeof Lifetime> => builtFixture("lifetime"));
+removalCases((): Promise<typeof Removal> => builtFixture("removal"));
+indexWorkersCases((): Promise<typeof IndexWorkers> => builtFixture("index-workers"));
+indexBuildCases((): Promise<typeof IndexBuild> => builtFixture("index-build"));
+entityLookupWorkersCases((): Promise<typeof EntityLookupWorkers> => builtFixture("entity-lookup-workers"));
+observerJoinedCases((): Promise<typeof ObserverJoined> => builtFixture("observer-joined"));
+observerContainedCases((): Promise<typeof ObserverContained> => builtFixture("observer-contained"));
+optionalWorkersCases((): Promise<typeof OptionalWorkers> => builtFixture("optional-workers"));
+sharedWorkersCases((): Promise<typeof SharedWorkers> => builtFixture("shared-workers"));

package/src/implementation/world/ticks.browser.test.ts

@@ -0,0 +1,43 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { always } from "../../interface/resources/always.js";
+import { clock } from "../../interface/resources/clock.js";
+import { System } from "../../interface/system/system.js";
+import { createWorld } from "./create.js";
+import { readResource } from "./reads.test-helper.js";
+import { workers } from "../../interface/resources/workers.js";
+
+const frames = Symbol("ticksBrowserTest/frames");
+declare module "@adobe/ecs" {
+    export interface Resources {
+        [frames]: { type: number };
+    }
+}
+
+const count = System.create({}, ({ resources }) => { resources[frames] += 1; });
+const start = System.create({}, ({ resources }) => { resources[always] = true; });
+
+describe("a frame cadence", () => {
+    it("ticks on animation frames, with their time", async () => {
+        const original = globalThis.requestAnimationFrame;
+        let requested = 0;
+        globalThis.requestAnimationFrame = callback => {
+            requested++;
+            return original(callback);
+        };
+        const world = createWorld({ [workers]: 0 });
+        try {
+            world.add(count);
+            await world.run(start);
+            while (await readResource(world, frames) < 3) await new Promise(resolve => original(resolve));
+            expect(requested).toBeGreaterThanOrEqual(3);
+            const { now, delta } = await readResource(world, clock);
+            expect(now).toBeGreaterThan(0);
+            expect(delta).toBeGreaterThan(0);
+        }
+        finally {
+            globalThis.requestAnimationFrame = original;
+            await world.dispose();
+        }
+    });
+});

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

@@ -0,0 +1,34 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { System, clock, workers } from "../../index.js";
+import { createWorld } from "./create.js";
+
+// The cases of ticks that read through observers are in `observe-ticks-cases.test.ts`.
+
+const frames = Symbol("ticksTest/frames");
+declare module "@adobe/ecs" {
+    interface Resources {
+        [frames]: { type: number };
+    }
+}
+
+const count = System.create({}, ({ resources }) => { resources[frames] += 1; });
+
+describe("ticks", () => {
+    it("reject a system that conflicts with one added with no order between them, and one with input", async () => {
+        const other = System.create({}, ({ resources }) => { resources[frames] = 0; });
+        const withInput = System.create({}, (_context, input: { readonly by: number }) => {});
+        await using world = createWorld({ [workers]: 0 });
+        world.add(count);
+        expect(() => world.add(other)).toThrow('both access "ticksTest/frames"');
+        // @ts-expect-error a system with input can't be added
+        expect(() => world.add(withInput)).toThrow("takes input");
+    });
+});
+
+describe("World.create", () => {
+    it("rejects starting a resource only the world writes", () => {
+        // @ts-expect-error clock is written only by the world
+        expect(() => createWorld({ [clock]: { now: 0, delta: 0, tick: 0 } })).toThrow('"clock" is written only by the world');
+    });
+});

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

@@ -0,0 +1,62 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Entity } from "../../interface/entity/entity.js";
+import { System } from "../../interface/system/system.js";
+import { count, read } from "./reads.test-helper.js";
+import { createWorld } from "./create.js";
+import { workers } from "../../interface/resources/workers.js";
+
+const score = Symbol("traitsTest/score");
+const slot = Symbol("traitsTest/slot");
+const ready = Symbol("traitsTest/ready");
+const parent = Symbol("traitsTest/parent");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [score]: { type: number };
+        [slot]: { type: number; derived: true };
+        [ready]: { type: true; within: typeof slot };
+        [parent]: { type: Entity; reference: "owner" };
+    }
+}
+
+
+describe("traits", () => {
+    it("keep derived components out of commands, for untyped callers too", async () => {
+        const errors: string[] = [];
+        const derived = System.create({}, ({ commands }) => {
+            const entity = commands.spawn([score])({ [score]: 1 });
+            const attempts = [
+                // @ts-expect-error derived components are added only by rules
+                () => commands.spawn([slot])({ [slot]: 1 }),
+                // @ts-expect-error derived components are added only by rules
+                () => commands.add(entity, slot, 1),
+                // @ts-expect-error derived components are removed only by rules
+                () => commands.remove(entity, slot),
+            ];
+            for (const attempt of attempts) {
+                try { attempt(); }
+                catch (error) { errors.push(error instanceof Error ? error.message : String(error)); }
+            }
+        });
+        const world = createWorld({ [workers]: 0 });
+        await world.run(derived);
+        expect(errors).toEqual(Array.from({ length: 3 }, () => `"traitsTest/slot" is derived, so only rules add and remove it.`));
+        expect(await count(world, { required: [score] })).toBe(1);
+        await world.dispose();
+    });
+
+    it("leave index 0 to Entity.none, which no lookup finds", async () => {
+        let first = Entity.none;
+        let found: unknown = undefined;
+        const spawn = System.create({}, ({ commands }) => { first = commands.spawn([score])({ [score]: 1 }); });
+        const lookup = System.create({ lookup: { scores: { with: [score] } } }, ({ lookup: { scores } }) => { found = scores(Entity.none); });
+        const world = createWorld({ [workers]: 0 });
+        await world.run(spawn);
+        await world.run(lookup);
+        expect(first).not.toBe(Entity.none);
+        expect(found).toBeNull();
+        expect(await read(world, Entity.none, score)).toBeNull();
+        await world.dispose();
+    });
+});

package/src/implementation/world/transfers-worker.fixture.ts

@@ -0,0 +1,119 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { MessagePort as NodeMessagePort } from "node:worker_threads";
+import { requireDefinition } from "../../interface/registry/index.js";
+import type { World } from "../../interface/world/world.js";
+import { join } from "./create.js";
+import { asEntity } from "./entities.js";
+import { peersOf } from "./join.js";
+import { scopeChannel } from "./port.js";
+import { attachHere, attachThere, greetThere, kept, mark, storeThere, stored, transferSystems } from "./transfers.test-helper.js";
+
+/**
+ * A thread joining a world through the port it's sent: the filler claims "transfersTest", whose systems run here, and
+ * the loader claims nothing and runs systems with Transferable input, moving it to their threads. The filler blocks
+ * its event loop when asked, until the asker sets the word it gave, so what the loader moves there waits to be received.
+ */
+
+type Port = MessagePort | NodeMessagePort;
+export type ToTransfersWorker =
+    | { readonly kind: "join"; readonly port: Port; readonly threads: readonly "transfersTest"[] }
+    | { readonly kind: "block"; readonly word: Int32Array<SharedArrayBuffer> }
+    | { readonly kind: "stored" }
+    | { readonly kind: "moves"; readonly count: number; readonly bytes: number }
+    | { readonly kind: "late" }
+    | { readonly kind: "settled" }
+    | { readonly kind: "drops" };
+export type FromTransfersWorker =
+    | { readonly kind: "joined" }
+    | { readonly kind: "blocking" }
+    | { readonly kind: "stored"; readonly stored: readonly (readonly [number, number, number])[]; readonly widths: readonly number[] }
+    | { readonly kind: "moved"; readonly detached: number; readonly greeted: unknown; readonly failures: number }
+    | { readonly kind: "posted"; readonly detached: boolean }
+    | { readonly kind: "settled"; readonly failures: number }
+    | { readonly kind: "dropped"; readonly closed: boolean; readonly widths: readonly number[] };
+
+const channel = scopeChannel<FromTransfersWorker, ToTransfersWorker>();
+let remote: World | null = null;
+let posted: Promise<void>[] = [];
+
+const later = (milliseconds = 0): Promise<void> => new Promise(resolve => setTimeout(resolve, milliseconds));
+
+/** How many of these runs rejected, as one whose system failed does. */
+const failuresOf = async (runs: readonly Promise<unknown>[]): Promise<number> =>
+    (await Promise.allSettled(runs)).filter(settled => settled.status === "rejected").length;
+
+const bufferOf = (first: number, bytes: number): ArrayBuffer => {
+    const buffer = new ArrayBuffer(bytes);
+    new Uint8Array(buffer)[0] = first;
+    return buffer;
+};
+
+/** Resolves once a port's other end closed, or with false after `milliseconds`. */
+const closed = (port: MessagePort, milliseconds = 20000): Promise<boolean> => new Promise(resolve => {
+    port.addEventListener("close", () => resolve(true));
+    port.start();
+    setTimeout(() => resolve(false), milliseconds);
+});
+
+/** A bitmap, where the platform has them: a browser's. */
+const bitmap = async (): Promise<ImageBitmap | null> =>
+    typeof createImageBitmap === "function" ? createImageBitmap(new ImageData(4, 4)) : null;
+
+const respond = async (message: Exclude<ToTransfersWorker, { readonly kind: "block" }>): Promise<FromTransfersWorker> => {
+    if (message.kind === "join") {
+        for (const system of transferSystems) requireDefinition(system);
+        remote = await join(message.port, { threads: message.threads });
+        // Joined once the world gave it a channel to the other joined thread.
+        while ((peersOf.get(remote)?.() ?? 0) === 0) await later(1);
+        return { kind: "joined" };
+    }
+    if (message.kind === "stored") {
+        return { kind: "stored", stored: stored.map(({ bytes, first, order }) => [bytes, first, order]), widths: kept.map(value => typeof ImageBitmap === "function" && value instanceof ImageBitmap ? value.width : -1) };
+    }
+    if (remote === null) throw new Error("transfers: the worker hasn't joined.");
+    const world = remote;
+    if (message.kind === "moves") {
+        const buffers = Array.from({ length: message.count }, (_, k) => bufferOf(k + 1, message.bytes));
+        const runs = buffers.map(buffer => world.run(storeThere, { buffer }));
+        const detached = buffers.filter(buffer => buffer.byteLength === 0).length;
+        const ports = new MessageChannel();
+        const greeted = new Promise<unknown>(resolve => {
+            ports.port2.onmessage = event => resolve(event.data);
+        });
+        runs.push(world.run(greetThere, { port: ports.port1 }));
+        const failures = await failuresOf(runs);
+        const greeting = await greeted;
+        ports.port2.close();
+        return { kind: "moved", detached, greeted: greeting, failures };
+    }
+    if (message.kind === "late") {
+        const buffer = bufferOf(9, 1 << 20);
+        posted = [world.run(storeThere, { buffer }), world.run(mark, { value: 1 }), world.run(mark, { value: 2 }), world.run(mark, { value: 3 })];
+        return { kind: "posted", detached: buffer.byteLength === 0 };
+    }
+    if (message.kind === "settled") {
+        return { kind: "settled", failures: await failuresOf(posted) };
+    }
+    // Commands giving a dead entity values: they drop, and each value is released on its thread.
+    const dead = asEntity(123456);
+    const ports = new MessageChannel();
+    const closing = closed(ports.port2);
+    await world.run(attachThere, { entity: dead, value: ports.port1 });
+    const there = await bitmap();
+    const here = await bitmap();
+    if (there !== null && here !== null) {
+        await world.run(attachThere, { entity: dead, value: there });
+        await world.run(attachHere, { entity: dead, value: here });
+    }
+    // Moved, so detached here: zero wide.
+    const widths = there === null || here === null ? [] : [there.width, here.width];
+    return { kind: "dropped", closed: await closing, widths };
+};
+
+channel.onMessage(async message => {
+    if ("protocol" in message) return;
+    if (message.kind !== "block") return channel.post(await respond(message));
+    // The reply goes out first; then this thread's event loop is blocked until the asker sets the word.
+    channel.post({ kind: "blocking" });
+    Atomics.wait(message.word, 0, 0);
+});

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

@@ -0,0 +1,31 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import type * as Fixture from "./transfers.fixture.js";
+
+/** Transfers between joined workers: the cases, over the fixture built for node or from source in chromium. */
+export const transfersCases = (load: () => Promise<typeof Fixture>) => describe("transfers between joined workers", () => {
+    it("move runs' Transferable input to the joined thread their system runs on, in call order", async () => {
+        const fixture = await load();
+        const { moved, received } = await fixture.moves(10, 1 << 20);
+        expect(moved).toEqual({ kind: "moved", detached: 10, greeted: "anchor", failures: 0 });
+        expect(received).toEqual(Array.from({ length: 10 }, (_, k) => [1 << 20, k + 1, k]));
+    }, 30000);
+    it("hold a run whose input hasn't been received yet, and that thread's later runs, while the world's own runs go on", async () => {
+        const fixture = await load();
+        const seen = await fixture.late();
+        expect(seen.posted).toEqual({ kind: "posted", detached: true });
+        expect(seen.worldRun).toBe("finished");
+        expect(seen.orderWhileBlocked).toBe(0);
+        expect(seen.settled).toEqual({ kind: "settled", failures: 0 });
+        expect({ stores: seen.stores, marks: seen.marks }).toEqual({ stores: [0], marks: [[1, 1], [2, 2], [3, 3]] });
+    }, 30000);
+    it("release a value whose command drops, on its thread", async () => {
+        const fixture = await load();
+        const { dropped, there, here } = await fixture.drops();
+        // Where the platform has bitmaps, a browser, one dropped there and one here, both closed; where it tells a port
+        // its other end closed, node, the port dropped there.
+        const bitmaps = there.length > 1;
+        expect(dropped).toEqual({ kind: "dropped", dropped: bitmaps ? [1, 1, 1] : [1], closed: bitmaps ? expect.any(Boolean) : true, widths: bitmaps ? [0, 0] : [] });
+        expect({ there, here }).toEqual(bitmaps ? { there: [-1, 0], here: [0] } : { there: [-1], here: [] });
+    }, 30000);
+});

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

@@ -0,0 +1,140 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/// <reference types="node" />
+import { Observe } from "../../observe/index.js";
+import { workers } from "../../interface/resources/workers.js";
+import { createWorld, recorderOf, type CreatedWorld, type Outcome } from "./create.js";
+import type { FromTransfersWorker, ToTransfersWorker } from "./transfers-worker.fixture.js";
+import { idle, kept, marks, order, stored } from "./transfers.test-helper.js";
+
+/**
+ * Scenarios of transfers between joined workers, run built in node and from source in chromium: the world here, a
+ * filler worker claiming "transfersTest" and a loader worker claiming nothing, which moves runs' Transferable input to
+ * the threads their systems run on.
+ */
+
+type Worker = { readonly ask: (message: ToTransfersWorker, transfer?: readonly unknown[]) => Promise<FromTransfersWorker>; readonly terminate: () => Promise<void> };
+
+const workerFile = "./transfers-worker.fixture.js";
+
+const start = (): Worker => {
+    if (typeof globalThis.Worker === "function") {
+        const worker = new globalThis.Worker(new URL("./transfers-worker.fixture.js", import.meta.url), { type: "module" });
+        return {
+            ask: (message, transfer = []) => new Promise(resolve => {
+                worker.onmessage = (event: MessageEvent<FromTransfersWorker>) => resolve(event.data);
+                worker.postMessage(message, { transfer: transfer.filter(port => port instanceof MessagePort) });
+            }),
+            terminate: async () => worker.terminate(),
+        };
+    }
+    const threads = globalThis.process.getBuiltinModule("node:worker_threads");
+    const worker = new threads.Worker(new URL(workerFile, import.meta.url));
+    return {
+        ask: (message, transfer = []) => new Promise(resolve => {
+            worker.once("message", resolve);
+            worker.postMessage(message, transfer.filter(port => port instanceof threads.MessagePort));
+        }),
+        terminate: async () => { await worker.terminate(); },
+    };
+};
+
+/** A port of a channel this world shares the other end of, and what its share resolves to once a thread joined through it. */
+const shared = (world: CreatedWorld) => {
+    if (typeof globalThis.Worker === "function") {
+        const { port1, port2 } = new MessageChannel();
+        return { port: port2, joined: world.share(port1) };
+    }
+    const { port1, port2 } = new (globalThis.process.getBuiltinModule("node:worker_threads").MessageChannel)();
+    return { port: port2, joined: world.share(port1) };
+};
+
+/** The world, its filler and its loader, each with a channel to the other. */
+const joined = async () => {
+    stored.length = marks.length = kept.length = 0;
+    const world = createWorld({ [workers]: 0 });
+    const filler = start();
+    const loader = start();
+    const loaderShared = shared(world);
+    const fillerShared = shared(world);
+    await Promise.all([
+        loader.ask({ kind: "join", port: loaderShared.port, threads: [] }, [loaderShared.port]),
+        filler.ask({ kind: "join", port: fillerShared.port, threads: ["transfersTest"] }, [fillerShared.port]),
+        loaderShared.joined,
+        fillerShared.joined,
+    ]);
+    const end = async (): Promise<void> => {
+        await world.dispose();
+        await Promise.all([filler.terminate(), loader.terminate()]);
+    };
+    return { world, filler, loader, end };
+};
+
+const storedOf = async (worker: Worker) => {
+    const reply = await worker.ask({ kind: "stored" });
+    if (reply.kind !== "stored") throw new Error("transfers: the filler didn't say what it stored.");
+    return reply;
+};
+
+/** The loader moving `count` buffers of `bytes` each, and a MessagePort, to the filler, whose systems take them. */
+export const moves = async (count: number, bytes: number) => {
+    const { filler, loader, end } = await joined();
+    const reply = await loader.ask({ kind: "moves", count, bytes });
+    if (reply.kind !== "moved") throw new Error("transfers: the loader didn't say what moved.");
+    const { failures, ...moved } = reply;
+    const { stored: received } = await storedOf(filler);
+    await end();
+    return { moved: { ...moved, failures }, received };
+};
+
+
+/** Resolves with what `promise` does, or `otherwise` after `milliseconds`. */
+const within = <T>(promise: Promise<T>, milliseconds: number, otherwise: T): Promise<T> => new Promise((resolve, reject) => {
+    const timer = setTimeout(() => resolve(otherwise), milliseconds);
+    promise.then(value => {
+        clearTimeout(timer);
+        resolve(value);
+    }, (error: unknown) => {
+        clearTimeout(timer);
+        reject(error);
+    });
+});
+
+/**
+ * The loader's run moving a buffer to the filler while the filler's event loop is blocked, until this releases it,
+ * then three runs of a system on the world's thread: whether the world's own run finished while the filler was
+ * blocked, rather than waiting for it, the order then, and the order each of the loader's runs saw once it wasn't.
+ */
+export const late = async () => {
+    const { world, filler, loader, end } = await joined();
+    const block = new Int32Array(new SharedArrayBuffer(4));
+    await filler.ask({ kind: "block", word: block });
+    const posted = await loader.ask({ kind: "late" });
+    // The filler stays blocked until it's released, so a world that waited for it never finishes this run in time.
+    const worldRun = await within(world.run(idle).then(() => "finished"), 10000, "waited");
+    // Time for the loader's held runs to run, wrongly, while the filler can't take its input.
+    await new Promise(resolve => setTimeout(resolve, 100));
+    const orderWhileBlocked = await Observe.toPromise(Observe.resource(world, order));
+    Atomics.store(block, 0, 1);
+    Atomics.notify(block, 0);
+    const reply = await loader.ask({ kind: "settled" });
+    if (reply.kind !== "settled") throw new Error("transfers: the loader didn't say how its runs settled.");
+    const settled = { kind: reply.kind, failures: reply.failures };
+    const { stored: received } = await storedOf(filler);
+    await end();
+    return { posted, worldRun, orderWhileBlocked, settled, stores: received.map(([, , seen]) => seen), marks: marks.map(({ value, order }) => [value, order]) };
+};
+
+/** Commands giving values the loader moved to a dead entity, on the filler and here: each released on its thread. */
+export const drops = async () => {
+    const { world, filler, loader, end } = await joined();
+    // The loader's runs, the world's only ones meanwhile, as the world's thread gathered them.
+    const outcomes: Outcome[] = [];
+    recorderOf(world).each.push(outcome => outcomes.push(outcome));
+    const reply = await loader.ask({ kind: "drops" });
+    if (reply.kind !== "dropped") throw new Error("transfers: the loader didn't say what dropped.");
+    const dropped = { ...reply, dropped: outcomes.map(outcome => outcome.dropped) };
+    const { widths } = await storedOf(filler);
+    const here = kept.map(value => typeof ImageBitmap === "function" && value instanceof ImageBitmap ? value.width : -1);
+    await end();
+    return { dropped, there: widths, here };
+};