@adobe/ecs 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,186 @@
+import { describe, expect, it } from "vitest";
+import { Component } from "../../interface/component/component.js";
+import type { Entity } from "../../interface/entity/entity.js";
+import { Finalizer } from "../../interface/finalizer/finalizer.js";
+import { Observe } from "../../observe/index.js";
+import { workers } from "../../interface/resources/workers.js";
+import { System } from "../../interface/system/system.js";
+import type { World } from "../../interface/world/world.js";
+import { createWorld, join, type CreatedWorld } from "./create.js";
+import { runReported } from "./reports.test-helper.js";
+
+// Objects a joined thread fills, with the world and the thread on this one, joined through a MessageChannel.
+
+const point = Symbol("remoteTest/point");
+const caption = Symbol("remoteTest/caption");
+const widget = Symbol("remoteTest/widget");
+const kept = Symbol("remoteTest/kept");
+const guarded = Symbol("remoteTest/guarded");
+const handle = Symbol("remoteTest/handle");
+declare module "@adobe/ecs" {
+    export interface Threads {
+        remoteTest: true;
+        remoteTestFinalized: true;
+    }
+    export interface Components {
+        [point]: { type: number };
+        [caption]: { type: { readonly text: string } | null; thread: "remoteTest" };
+        [widget]: { type: Widget | null; thread: "remoteTest" };
+        [kept]: { type: string };
+        [guarded]: { type: Widget | null; thread: "remoteTestFinalized" };
+        [handle]: { type: Widget | number | null; thread: "remoteTest" };
+    }
+}
+/** A value that isn't data. */
+type Widget = { readonly draw: () => string };
+Component.register(point, { type: { type: "number" } });
+/** The caption's start, which a command here gives it by this value. */
+const none = { text: "none" };
+Component.register(caption, { type: { anyOf: [{ type: "object", properties: { text: { type: "string" } } }, { type: "null" }], default: none }, thread: "remoteTest" });
+Component.register(widget, { thread: "remoteTest" });
+Component.register(kept, { type: { type: "string" } });
+/** A widget, or the number a kernel gives one, which only the world's thread could hold. */
+Component.register(handle, { thread: "remoteTest" });
+Component.register(guarded, { thread: "remoteTestFinalized" });
+
+const spawn = System.create({ name: "remoteTest/spawn", input: { type: "object", properties: { x: { type: "number" } } } }, ({ input, commands }) => {
+    commands.spawn([point, caption, widget, kept])({ [point]: input.x, [kept]: `k${input.x}`, [widget]: null });
+});
+const nullCaptions = System.create({ name: "remoteTest/nullCaptions", components: { has: [caption, point] } }, (row, { commands }) => {
+    commands.add(row.entity, caption, null);
+});
+const restartCaptions = System.create({ name: "remoteTest/restartCaptions", components: { has: [caption, point] } }, (row, { commands }) => {
+    commands.add(row.entity, caption, none);
+});
+const dropCaptions = System.create({ name: "remoteTest/dropCaptions", components: { has: [caption] } }, (row, { commands }) => {
+    commands.remove(row.entity, caption);
+});
+const giveCaption = System.create({ name: "remoteTest/giveCaption", components: { has: [point] } }, (row, { commands }) => {
+    commands.add(row.entity, caption, { text: "a caption only the thread gives" });
+});
+const spawnCaptioned = System.create({ name: "remoteTest/spawnCaptioned" }, ({ commands }) => {
+    commands.spawn([point, caption])({ [point]: 1, [caption]: { text: "a caption only the thread gives" } });
+});
+/** A kernel giving the thread's objects null, which they take, and a number, which they don't. */
+const nullCaptionsKernel = System.create({ name: "remoteTest/nullCaptionsKernel", kernel: "cpu", components: { has: [caption], read: [point] } }, (row, { commands }) => {
+    if (row[point] > 0) commands.add(row.entity, caption, null);
+});
+const numberHandlesKernel = System.create({ name: "remoteTest/numberHandlesKernel", kernel: "cpu", components: { read: [point] } }, (row, { commands }) => {
+    commands.add(row.entity, handle, row[point]);
+});
+/** Reaches its commands, so it isn't terminal: its tier blocks rather than running as a tail. */
+const readCaptions = System.create({ name: "remoteTest/readCaptions", components: { read: [caption] } }, (row, { commands }) => {
+    if (row[caption]?.text === "never") commands.despawn(row.entity);
+});
+const idle = System.create({ name: "remoteTest/idle" }, () => {});
+const after = System.create({ name: "remoteTest/after" }, () => {});
+Finalizer.create({ name: "remoteTest/releaseGuarded", components: { read: [guarded] } }, () => {});
+
+/** A world shared with a thread on this one, which claims `threads`. */
+const joined = (threads: readonly ("remoteTest" | "remoteTestFinalized")[] = ["remoteTest"]): { readonly world: CreatedWorld; readonly remote: World } => {
+    const world = createWorld({ [workers]: 0 });
+    const channel = new MessageChannel();
+    world.share(channel.port1);
+    const remote = join(channel.port2, { threads });
+    return { world, remote };
+};
+
+/** The first value an observer gives that `accept` takes. */
+const until = <T>(observe: Observe<T>, accept: (value: T) => boolean): Promise<T> => new Promise(resolve => {
+    let done = false;
+    const stop = observe(value => {
+        if (done || !accept(value)) return;
+        done = true;
+        queueMicrotask(() => stop());
+        resolve(value);
+    });
+});
+
+/** Once the thread shared last has status `status`. */
+const statusOf = (world: CreatedWorld, status: "joined" | "gone") =>
+    until(world.threads, threads => threads.at(-1)?.status === status);
+
+/** The entity a run of `spawn` spawned. */
+const spawnOne = async (world: World, x: number): Promise<Entity> => {
+    await world.run(spawn, { x });
+    const [entity] = await Observe.toPromise(Observe.select(world, { required: [point], where: { [point]: x } }));
+    return entity;
+};
+
+describe("objects a joined thread fills", () => {
+    // The cases of observers reading them are in `observe-joined-cases.test.ts`.
+    it("take from the world's thread only their start or null, in commands and spawns", async () => {
+        const { world, remote } = joined();
+        await statusOf(world, "joined");
+        await spawnOne(world, 2);
+        const message = '"remoteTest/caption" lives on thread "remoteTest", which a joined thread fills, so a command here gives it only its start or null.';
+        expect((await runReported(world, giveCaption)).failures.map(failure => failure.message)).toEqual([message]);
+        expect((await runReported(world, spawnCaptioned)).failures.map(failure => failure.message)).toEqual([message]);
+        expect(await Observe.toPromise(Observe.count(world, { required: [caption] }))).toBe(1);
+        await remote.dispose();
+        await world.dispose();
+    });
+    it("take from a kernel only their start or null, its command giving another dropping and its system failing", async () => {
+        const { world, remote } = joined();
+        await statusOf(world, "joined");
+        const entity = await spawnOne(world, 6);
+        const listed = Observe.entity(remote, entity, { required: [caption, widget] });
+        expect(await until(listed, value => value !== null)).toEqual({ [caption]: none, [widget]: null });
+        expect((await runReported(world, nullCaptionsKernel)).failures).toEqual([]);
+        expect(await until(listed, value => value?.[caption] === null)).toEqual({ [caption]: null, [widget]: null });
+        const report = await runReported(world, numberHandlesKernel);
+        expect(report.failures.map(failure => [failure.name, failure.message])).toEqual([["remoteTest/numberHandlesKernel", '"remoteTest/handle" lives on thread "remoteTest", which a joined thread fills, so a command here gives it only its start or null.']]);
+        expect(report.dropped).toBe(1);
+        await remote.dispose();
+        await world.dispose();
+    });
+    it("are read by systems that run on the thread, their tiers warned of", async () => {
+        const { world, remote } = joined();
+        await statusOf(world, "joined");
+        await spawnOne(world, 3);
+        expect(await runReported(world, readCaptions)).toEqual({
+            failures: [], skipped: [], dropped: 0,
+            warnings: [{ kind: "blocking", name: "remoteTest/readCaptions", message: 'System "remoteTest/readCaptions" runs on thread "remoteTest", which a joined thread fills, so its tier waits for that thread.' }],
+        });
+        await remote.dispose();
+        await world.dispose();
+    });
+    it("come back to the world's thread when the thread that filled them is gone, as the start or null each held", async () => {
+        const { world, remote } = joined();
+        await statusOf(world, "joined");
+        const first = await spawnOne(world, 4);
+        await world.run(nullCaptions);
+        const second = await spawnOne(world, 5);
+        await remote.dispose();
+        await statusOf(world, "gone");
+        await world.run(after);
+        expect(await Observe.toPromise(Observe.entity(world, first, { required: [caption, widget] }))).toEqual({ [caption]: null, [widget]: null });
+        expect(await Observe.toPromise(Observe.entity(world, second, { required: [caption] }))).toEqual({ [caption]: none });
+        expect((await runReported(world, readCaptions)).failures).toEqual([]);
+        await world.dispose();
+    });
+    it("refuse a claim of a thread whose finalizers or systems the joined thread can't run, and take one whose systems it imported", async () => {
+        const world = createWorld({ [workers]: 0 });
+        await world.run(readCaptions);
+        const taken = joined();
+        await statusOf(taken.world, "joined");
+        expect((await runReported(taken.world, readCaptions)).warnings.map(warning => warning.name)).toEqual(["remoteTest/readCaptions"]);
+        await taken.remote.dispose();
+        await taken.world.dispose();
+        // Declared in a function, so the build gives it no id, and another thread can't name it.
+        const unnamed = System.create({ name: "remoteTest/unnamed", components: { read: [caption] } }, row => { void row[caption]; });
+        await world.run(unnamed);
+        const channel = new MessageChannel();
+        world.share(channel.port1);
+        const remote = join(channel.port2, { threads: ["remoteTest"] });
+        await expect(remote.run(idle)).rejects.toThrow('System "remoteTest/unnamed" runs on thread "remoteTest" and has no id, so a joined thread can\'t run it');
+        await statusOf(world, "gone");
+        await remote.dispose();
+        const other = joined(["remoteTestFinalized"]);
+        // Declared without a binding, so the build gives it no id.
+        await expect(other.remote.run(idle)).rejects.toThrow('Finalizer "remoteTest/releaseGuarded" runs on thread "remoteTestFinalized" and has no id, so a joined thread can\'t run it');
+        await other.remote.dispose();
+        await other.world.dispose();
+        await world.dispose();
+    });
+});

package/src/implementation/world/remote.ts

@@ -0,0 +1,125 @@
+import { declarationOf, labelOf, threadOfDeclaration } from '../../interface/registry/index.js';
+import { makeLocal, makeRemote } from './archetype.js';
+import type { CommandBuffer } from './buffer.js';
+import { flushBetween } from './layout-directory.js';
+import { nullTag, tagOf, type MoveLog } from './move-log.js';
+import { startTicking, type State } from './state.js';
+
+// Objects a joined thread fills: the world's storages for them hold each row's tag in place of its value, and the
+// archetypes holding them append their moves to the thread's log (`move-log.ts`).
+
+/** The logical thread a component's or resource's objects live on, or null for a struct. */
+const threadOfComponent = (state: State, id: number): string | null => {
+    const declaration = declarationOf(state.keys[id]);
+    return declaration === undefined ? null : threadOfDeclaration(declaration);
+};
+
+/** Gives a component a joined thread fills to its log, in every archetype and batch holding it. */
+const give = (state: State, id: number, log: MoveLog): void => {
+    state.remote[id] = log;
+    startTicking(state, [id]);
+    for (const archetype of state.archetypes) {
+        const storage = archetype.storageById[id];
+        if (storage !== undefined) makeRemote(state.memory, archetype, storage, log);
+    }
+    for (const batch of state.batches) for (const column of batch.columns) if (column.id === id) column.remote = remoteError(state, id).message;
+    log.announce(id);
+};
+
+/**
+ * A component the world just met, whose logical thread a joined thread claims: its objects are that thread's. No
+ * archetype holds it yet, so nothing allocates.
+ */
+export const claimComponent = (state: State, id: number): void => {
+    const thread = threadOfComponent(state, id);
+    const log = thread === null ? undefined : state.claims.get(thread);
+    if (log === undefined) return;
+    state.remote[id] = log;
+    state.ticked.add(id);
+    log.announce(id);
+};
+
+/**
+ * Between runs: a joined thread claims logical threads, so their components' objects are its own. Rows holding them
+ * start there at their starts; the world's values are released. Their ticks are kept, so the thread rebuilds them.
+ */
+export const claimThreads = (state: State, log: MoveLog, threads: readonly string[]): void => {
+    for (const thread of threads) state.claims.set(thread, log);
+    state.logs.push(log);
+    state.claimed = true;
+    state.counting = true;
+    for (let id = 0; id < state.keys.length; id++) {
+        const thread = threadOfComponent(state, id);
+        if (thread !== null && state.claims.get(thread) === log) give(state, id, log);
+    }
+    if (state.directory !== null) state.directory.guarded = true;
+    flushBetween(state.directory, state.bumped, state.archetypes, state.entities, state.resourceEntity, state.counted);
+};
+
+/**
+ * Between runs: a joined thread that's gone gives back the logical threads it claimed. Rows hold the value each tag
+ * names, `null` or the start: a staged value was the thread's own.
+ */
+export const releaseThreads = (state: State, log: MoveLog): void => {
+    const index = state.logs.indexOf(log);
+    if (index < 0) return;
+    state.logs.splice(index, 1);
+    for (const [thread, owner] of [...state.claims]) if (owner === log) state.claims.delete(thread);
+    for (let id = 0; id < state.remote.length; id++) {
+        if (state.remote[id] !== log) continue;
+        state.remote[id] = undefined;
+        for (const archetype of [...log.archetypes]) {
+            const storage = archetype.storageById[id];
+            if (storage !== undefined) makeLocal(state.memory, archetype, storage, state.starts[id]);
+        }
+        for (const batch of state.batches) for (const column of batch.columns) if (column.id === id) column.remote = null;
+    }
+    state.claimed = state.logs.length > 0;
+    state.counting = state.claimed || state.observer.count > 0;
+    if (state.directory !== null) state.directory.guarded = state.claimed;
+    // Finalizers on the threads it gave back activate again.
+    state.unplacedSeen.clear();
+    state.activation.met = true;
+    flushBetween(state.directory, state.bumped, state.archetypes, state.entities, state.resourceEntity, state.counted);
+};
+
+export const remoteError = (state: State, id: number): Error =>
+    new Error(`"${labelOf(state.keys[id])}" lives on thread "${threadOfComponent(state, id) ?? "world"}", which a joined thread fills, so a command here gives it only its start or null.`);
+
+/**
+ * For a system's commands, once a joined thread fills objects: the first error of a value another thread's object can't
+ * take, with each such command dropped, by naming no entity, and each such staged spawn's value its start. Commands of
+ * the joined thread whose log is `own` give its own objects slots it staged.
+ */
+export const checkCommands = (state: State, buffer: CommandBuffer, own: MoveLog | null = null): Error | undefined => {
+    let error: Error | undefined;
+    const { ids, values, starts, entities } = buffer;
+    for (let command = 0; command < buffer.count; command++) {
+        const end = command + 1 < buffer.count ? starts[command + 1] : buffer.named;
+        for (let k = starts[command]; k < end; k++) {
+            const id = ids[k];
+            const log = state.remote[id];
+            if (log === undefined) continue;
+            const tag = tagOf(values[k], state.starts[id]);
+            if (tag >= 0 && (tag <= nullTag || log === own)) continue;
+            error ??= remoteError(state, id);
+            entities[command] = 0;
+            break;
+        }
+    }
+    for (let s = 0; s < buffer.stagedCount; s++) {
+        const { batch, start, end } = buffer.staged[s];
+        for (const column of batch.columns) {
+            const log = state.remote[column.id];
+            if (log === undefined) continue;
+            const begin = state.starts[column.id];
+            for (let row = start; row < end; row++) {
+                const tag = tagOf(column.values[row], begin);
+                if (tag >= 0 && (tag <= nullTag || log === own)) continue;
+                error ??= remoteError(state, column.id);
+                column.values[row] = begin;
+            }
+        }
+    }
+    return error;
+};

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

@@ -0,0 +1,20 @@
+import type { MessagePort as NodeMessagePort } from "node:worker_threads";
+import { join } from "./create.js";
+import { scopeChannel } from "./port.js";
+import { first, firstTail, second, secondTail, setPause, ticking } from "./remove.test-helper.js";
+
+/** A thread joining a world through the port it's sent, claiming "removeTest", whose systems it imports. */
+
+/** Named, so the bundle keeps the module declaring them: the package is free of side effects. */
+const imported = [first, second, firstTail, secondTail, ticking, setPause];
+
+type Port = MessagePort | NodeMessagePort;
+export type ToRemovalWorker = { readonly kind: "join"; readonly port: Port };
+export type FromRemovalWorker = { readonly kind: "joined"; readonly systems: number };
+
+const channel = scopeChannel<FromRemovalWorker, ToRemovalWorker>();
+channel.onMessage(message => {
+    if ("protocol" in message) return;
+    join(message.port, { threads: ["removeTest"] });
+    channel.post({ kind: "joined", systems: imported.length });
+});

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

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import type * as Fixture from "./removal.fixture.js";
+
+/** Removing systems placed on a joined worker: the cases, over the fixture built for node or from source. */
+export const removalCases = (load: () => Promise<typeof Fixture>) => describe("removing systems on a joined worker", () => {
+    it("never runs a system removed while the worker runs a task holding it, and both threads drop it", async () => {
+        const fixture = await load();
+        const { atRemove, after, placed, left, none } = await fixture.removedMidTask();
+        expect(atRemove).toBeGreaterThanOrEqual(2);
+        // The task in flight held `second` after `first`, which the worker ran no more of once its word was set.
+        expect(after).toBe(atRemove);
+        expect(placed).toEqual([2]);
+        expect(left).toEqual([1]);
+        expect(none).toEqual([0]);
+    }, 30000);
+});

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

@@ -0,0 +1,95 @@
+/// <reference types="node" />
+import { Observe } from "../../observe/index.js";
+import { always } from "../../interface/resources/always.js";
+import { clock } from "../../interface/resources/clock.js";
+import { workers } from "../../interface/resources/workers.js";
+import { createWorld, type CreatedWorld } from "./create.js";
+import type { FromRemovalWorker, ToRemovalWorker } from "./removal-worker.fixture.js";
+import { first, second, secondRuns, setPause, ticking } from "./remove.test-helper.js";
+
+/** Scenarios of removing systems placed on a joined worker, run built in node and from source in chromium. */
+
+type Worker = { readonly ask: (message: ToRemovalWorker, transfer: readonly unknown[]) => Promise<FromRemovalWorker>; readonly terminate: () => Promise<void> };
+
+const workerFile = "./removal-worker.fixture.js";
+
+const start = (): Worker => {
+    if (typeof globalThis.Worker === "function") {
+        const worker = new globalThis.Worker(new URL("./removal-worker.fixture.js", import.meta.url), { type: "module" });
+        return {
+            ask: (message, transfer) => new Promise(resolve => {
+                worker.onmessage = (event: MessageEvent<FromRemovalWorker>) => { if (!("protocol" in event.data)) 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 => {
+            const reply = (data: FromRemovalWorker): void => {
+                if ("protocol" in data) return;
+                worker.off("message", reply);
+                resolve(data);
+            };
+            worker.on("message", reply);
+            worker.postMessage(message, transfer.filter(port => port instanceof threads.MessagePort));
+        }),
+        terminate: async () => { await worker.terminate(); },
+    };
+};
+
+const until = <T>(observe: Observe<T>, accept: (value: T) => boolean): Promise<T> => new Promise(resolve => {
+    let done = false;
+    const stop = observe(value => {
+        if (done || !accept(value)) return;
+        done = true;
+        queueMicrotask(() => stop());
+        resolve(value);
+    });
+});
+
+const later = (milliseconds: number): Promise<void> => new Promise(resolve => setTimeout(resolve, milliseconds));
+
+/**
+ * Removes `second` from the world's thread while the joined worker runs `first`, whose task holds `second` too:
+ * `second`'s runs when `remove` returned and once ticks went on, and the indexes the world holds on the worker before
+ * removing, after, and once `first` is removed too.
+ */
+export const removedMidTask = async () => {
+    const world: CreatedWorld = createWorld({ [workers]: 0, [always]: true });
+    const { port1, port2 } = new MessageChannel();
+    world.share(port1);
+    const worker = start();
+    await worker.ask({ kind: "join", port: port2 }, [port2]);
+    await until(world.threads, threads => threads.at(-1)?.status === "joined");
+    try {
+        world.add(first);
+        world.add(second);
+        world.add(ticking);
+        await until(Observe.resource(world, secondRuns), runs => runs >= 2);
+        const placed = (await world.tables()).joined;
+        // `first` spins for 200 ms in each task from the next tick on; 50 ms into the first of them, `second` is removed.
+        await world.run(setPause, { milliseconds: 200 });
+        const removed = new Promise<number>(resolve => setTimeout(() => {
+            world.remove(second);
+            resolve(Observe.toPromise(Observe.resource(world, secondRuns)));
+        }, 50));
+        const atRemove = await removed;
+        await world.run(setPause, { milliseconds: 0 });
+        const tick = (await Observe.toPromise(Observe.resource(world, clock))).tick;
+        await until(Observe.resource(world, clock), value => value.tick >= tick + 10);
+        const after = await Observe.toPromise(Observe.resource(world, secondRuns));
+        let left = (await world.tables()).joined;
+        for (let k = 0; k < 100 && left[0] !== 1; k++) left = (await later(10), await world.tables()).joined;
+        world.remove(first);
+        let none = (await world.tables()).joined;
+        for (let k = 0; k < 100 && none[0] !== 0; k++) none = (await later(10), await world.tables()).joined;
+        return { atRemove, after, placed, left, none };
+    }
+    finally {
+        await worker.terminate();
+        await world.dispose();
+    }
+};

package/src/implementation/world/remove-joined.test.ts

@@ -0,0 +1,181 @@
+import { describe, expect, it } from "vitest";
+import { Observe } from "../../observe/index.js";
+import { always } from "../../interface/resources/always.js";
+import { clock } from "../../interface/resources/clock.js";
+import { workers } from "../../interface/resources/workers.js";
+import type { System } from "../../interface/system/system.js";
+import type { World } from "../../interface/world/world.js";
+import { createWorld, join, type CreatedWorld } from "./create.js";
+import { tablesOf } from "./join.js";
+import type { LoopPlatform } from "./loop.js";
+import { calls, first, firstTail, removal, removerTail, second, secondTail, ticking } from "./remove.test-helper.js";
+
+// Removing systems placed on a joined thread, with the world and the thread on this one, joined through a MessageChannel.
+
+const until = <T>(observe: Observe<T>, accept: (value: T) => boolean): Promise<T> => new Promise(resolve => {
+    let done = false;
+    const stop = observe(value => {
+        if (done || !accept(value)) return;
+        done = true;
+        queueMicrotask(() => stop());
+        resolve(value);
+    });
+});
+
+/**
+ * Frames a millisecond apart, on timers, so messages between the threads, on ports of this one, are handled between
+ * ticks: back to back, through a port, ticks would hold every other port's messages until they pause.
+ */
+const timerFrames = { frame: (callback: (time: number) => void) => {
+    const handle = setTimeout(() => callback(performance.now()), 1);
+    return () => clearTimeout(handle);
+} };
+
+/**
+ * Timer frames until `immediate` is set, then each frame as soon as the last tick ends, before the thread on this one
+ * runs that tick's tails: the next tick waits for them, and their bodies run while it does.
+ */
+const switchableFrames = (): { immediate: boolean; readonly frame: LoopPlatform["frame"] } => {
+    const frames = {
+        immediate: false,
+        frame: (callback: (time: number) => void): (() => void) => {
+            if (!frames.immediate) return timerFrames.frame(callback);
+            let cancelled = false;
+            queueMicrotask(() => {
+                if (!cancelled) callback(performance.now());
+            });
+            return () => { cancelled = true; };
+        },
+    };
+    return frames;
+};
+
+/** A world ticking on `frames`, a millisecond apart by default, shared with a thread on this one claiming "removeTest". */
+const joined = async (frames: Pick<LoopPlatform, "frame"> = timerFrames): Promise<{ readonly world: CreatedWorld; readonly remote: World; readonly ticks: (count: number) => Promise<void>; readonly close: () => Promise<void> }> => {
+    const world = createWorld({ [workers]: 0, [always]: true }, { loop: frames });
+    const channel = new MessageChannel();
+    world.share(channel.port1);
+    const remote = join(channel.port2, { threads: ["removeTest"] });
+    await until(world.threads, threads => threads.at(-1)?.status === "joined");
+    removal.world = world;
+    world.add(ticking);
+    const ticks = async (count: number): Promise<void> => {
+        const from = (await Observe.toPromise(Observe.resource(world, clock))).tick;
+        await until(Observe.resource(world, clock), ({ tick }) => tick >= from + count);
+    };
+    const close = async (): Promise<void> => {
+        removal.world = null;
+        removal.armed = false;
+        removal.target = null;
+        await remote.dispose();
+        await world.dispose();
+    };
+    return { world, remote, ticks, close };
+};
+
+/** What both threads hold of systems placed on the joined one: the world's indexes there, and the thread's systems. */
+const held = async (world: CreatedWorld, remote: World): Promise<readonly [number, number]> =>
+    [(await world.tables()).joined[0] ?? 0, tablesOf.get(remote)?.().systems ?? -1];
+
+/**
+ * What both threads hold once they agree on `expected`, or after 200 ticks: the thread drops a removed system as its
+ * message arrives, and the world places its index again once the thread's answer does.
+ */
+const settled = async (world: CreatedWorld, remote: World, ticks: (count: number) => Promise<void>, expected: readonly [number, number]): Promise<readonly [number, number]> => {
+    for (let tick = 0; tick < 200; tick++) {
+        const now = await held(world, remote);
+        if (now[0] === expected[0] && now[1] === expected[1]) return now;
+        await ticks(1);
+    }
+    return held(world, remote);
+};
+
+describe("removing systems on a joined thread", () => {
+    for (const [kind, one, two, ran] of [
+        ["a blocking tier's", first, second, () => [calls.first, calls.second]],
+        ["a tail's", firstTail, secondTail, () => [calls.firstTail, calls.secondTail]],
+    ] as const satisfies readonly (readonly [string, System, System, () => readonly number[]])[]) {
+        it(`never runs ${kind} body once removed, a task already posted with it included, and both threads drop what they held`, async () => {
+            const { world, remote, ticks, close } = await joined();
+            world.add(one);
+            world.add(two);
+            await ticks(3);
+            expect(await held(world, remote)).toEqual([2, 2]);
+            const [ranOne, ranTwo] = ran();
+            expect(ranTwo).toBeGreaterThan(0);
+            // The first removes the second from the task both are in, which the thread then runs no more of.
+            removal.armed = true;
+            await ticks(4);
+            removal.armed = false;
+            const [laterOne, laterTwo] = ran();
+            expect(laterOne).toBeGreaterThan(ranOne);
+            expect(laterTwo).toBe(ranTwo);
+            expect(await settled(world, remote, ticks, [1, 1])).toEqual([1, 1]);
+            world.remove(one);
+            expect(await settled(world, remote, ticks, [0, 0])).toEqual([0, 0]);
+            await close();
+        });
+    }
+
+    it("posts no task naming a tail removed while the next tick waited for its thread to finish the last", async () => {
+        const frames = switchableFrames();
+        const { world, remote, ticks, close } = await joined(frames);
+        world.add(firstTail);
+        world.add(secondTail);
+        await ticks(3);
+        expect(await held(world, remote)).toEqual([2, 2]);
+        // From the next tick on, each starts as the last ends and waits for the last's tails, which run meanwhile: the
+        // tails of the tick `ticks` sees now are still posted, and the first of them removes the second.
+        frames.immediate = true;
+        await ticks(1);
+        const ran = calls.secondTail;
+        removal.armed = true;
+        await ticks(3);
+        removal.armed = false;
+        frames.immediate = false;
+        expect(calls.secondTail).toBe(ran);
+        expect(await settled(world, remote, ticks, [1, 1])).toEqual([1, 1]);
+        world.remove(firstTail);
+        expect(await settled(world, remote, ticks, [0, 0])).toEqual([0, 0]);
+        await close();
+    });
+
+    it("posts no task naming a blocking tier's system removed while the next tick waited for its thread to finish the last", async () => {
+        const frames = switchableFrames();
+        const { world, remote, ticks, close } = await joined(frames);
+        world.add(first);
+        world.add(second);
+        world.add(removerTail);
+        await ticks(3);
+        expect(await held(world, remote)).toEqual([3, 3]);
+        // As above: the next tick waits for the tail of the tick seen now, which removes `second`, before it posts the
+        // task its tiers are one of.
+        frames.immediate = true;
+        await ticks(1);
+        const ran = calls.second;
+        removal.target = second;
+        await ticks(3);
+        frames.immediate = false;
+        expect(removal.target).toBe(null);
+        expect(calls.second).toBe(ran);
+        expect(await settled(world, remote, ticks, [2, 2])).toEqual([2, 2]);
+        world.remove(first);
+        world.remove(removerTail);
+        expect(await settled(world, remote, ticks, [0, 0])).toEqual([0, 0]);
+        await close();
+    });
+
+    it("places an index again only once the thread dropped what it held for it", async () => {
+        const { world, remote, ticks, close } = await joined();
+        world.add(first);
+        for (let k = 0; k < 20; k++) {
+            world.add(second);
+            await ticks(1);
+            world.remove(second);
+            await ticks(1);
+        }
+        expect(await settled(world, remote, ticks, [1, 1])).toEqual([1, 1]);
+        expect(() => remote.remove(first)).toThrow("on the world's thread");
+        await close();
+    });
+});