@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/world/remote-finalizers.fixture.ts

@@ -0,0 +1,140 @@
+/// <reference types="node" />
+import type { Entity } from "../../interface/entity/entity.js";
+import { Observe } from "../../observe/index.js";
+import { workers } from "../../interface/resources/workers.js";
+import { createWorld, type CreatedWorld } from "./create.js";
+import { indexOf } from "./entities.js";
+import type { FromRemoteFinalizersWorker, ToRemoteFinalizersWorker } from "./remote-finalizers-worker.fixture.js";
+import { despawn, released, retitle, scenario, serial, sorted, spawn, spawnTitled, type Released } from "./remote-finalizers.test-helper.js";
+import { fillReports, runReported } from "./reports.test-helper.js";
+
+/**
+ * Scenarios of finalizers on a joined worker, run built in node and from source in chromium: the same stops as an
+ * inline world's, and a worker that never yields holding the indexes of entities it hasn't finalized until it's ended.
+ */
+
+type Worker = { readonly ask: (message: ToRemoteFinalizersWorker, transfer?: readonly unknown[]) => Promise<FromRemoteFinalizersWorker>; readonly terminate: () => Promise<void> };
+
+const workerFile = "./remote-finalizers-worker.fixture.js";
+
+const start = (): Worker => {
+    if (typeof globalThis.Worker === "function") {
+        const worker = new globalThis.Worker(new URL("./remote-finalizers-worker.fixture.js", import.meta.url), { type: "module" });
+        return {
+            ask: (message, transfer = []) => new Promise(resolve => {
+                worker.onmessage = (event: MessageEvent<FromRemoteFinalizersWorker>) => { 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: FromRemoteFinalizersWorker): 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(); },
+    };
+};
+
+/** 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);
+    });
+});
+
+/** A world shared with a worker that joins it claiming "remoteFinalizersTest", once it joined. */
+const joined = async (world: CreatedWorld): Promise<{ readonly worker: Worker }> => {
+    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");
+    return { worker };
+};
+
+/** What the worker's finalizer saw. */
+const releasedThere = async (worker: Worker): Promise<readonly Released[]> => {
+    const reply = await worker.ask({ kind: "released" });
+    return reply.kind === "released" ? reply.released : [];
+};
+
+/** The scenario's stops, inline and with the joined worker running the finalizer, in order by serial. */
+export const sameStops = async () => {
+    released.length = 0;
+    const inline = createWorld({ [workers]: 0 });
+    const counts = await scenario(inline, () => released.length);
+    const expected = sorted(released);
+    await inline.dispose();
+    const world = createWorld({ [workers]: 0 });
+    const { worker } = await joined(world);
+    const seen = await scenario(world, async () => (await releasedThere(worker)).length, counts);
+    const actual = sorted(await releasedThere(worker));
+    await worker.terminate();
+    await world.dispose();
+    return { expected: { counts, stops: expected }, actual: { counts: seen, stops: actual } };
+};
+
+/**
+ * A worker that never yields, so it acknowledges no stop: the indexes of the entities despawned stay held while it
+ * lives, and once it's ended they're reused, the stops it never finalized reported.
+ */
+export const diesHolding = async () => {
+    const world = createWorld({ [workers]: 0 });
+    // Past the runs that spawn reports, whose entities would take the released indexes first.
+    await fillReports(world);
+    const { worker } = await joined(world);
+    await world.run(spawn, { from: 0, count: 4 });
+    const stopped: Entity[] = [];
+    for (const value of [0, 1, 2]) stopped.push(...await Observe.toPromise(Observe.select(world, { required: [serial], where: { [serial]: value } })));
+    const despawned = new Set(stopped.map(indexOf));
+    /** Live entities at the indexes of those despawned. */
+    const reused = async (): Promise<number> => (await Observe.toPromise(Observe.select(world, { required: [serial] }))).filter(entity => despawned.has(indexOf(entity))).length;
+    await worker.ask({ kind: "spin" });
+    await world.run(despawn, { serials: [0, 1, 2] });
+    // Spawns while it lives take other indexes.
+    await world.run(spawn, { from: 10, count: 6 });
+    const whileHeld = await reused();
+    await worker.terminate();
+    await until(world.threads, threads => threads.at(-1)?.status === "gone");
+    const report = await runReported(world, spawn, { from: 20, count: 0 });
+    await world.run(spawn, { from: 30, count: 6 });
+    const after = await reused();
+    await world.dispose();
+    return { held: despawned.size, whileHeld, failures: report.failures.map(failure => [failure.kind, failure.name, failure.message]), after };
+};
+
+/**
+ * Titled rows despawned while the worker runs nothing, then the world's thread rewriting the titles of others six
+ * times, so the records the despawned rows' titles were in are freed and reused before the worker finalizes them:
+ * the titles its finalizer read.
+ */
+export const titledStops = async () => {
+    const world = createWorld({ [workers]: 0 });
+    const { worker } = await joined(world);
+    await world.run(spawnTitled, { from: 0, count: 50 });
+    await worker.ask({ kind: "pause", milliseconds: 300 });
+    await world.run(despawn, { serials: Array.from({ length: 50 }, (_, k) => k) });
+    await world.run(spawnTitled, { from: 100, count: 50 });
+    for (let round = 0; round < 6; round++) await world.run(retitle, { round });
+    let seen: readonly { readonly serial: number; readonly title: string }[] = [];
+    for (let k = 0; k < 200 && seen.length < 50; k++) {
+        const reply = await worker.ask({ kind: "entitled" });
+        seen = reply.kind === "entitled" ? reply.entitled : [];
+    }
+    await worker.terminate();
+    await world.dispose();
+    return [...seen].sort((a, b) => a.serial - b.serial);
+};

package/src/implementation/world/remote-finalizers.test-helper.ts

@@ -0,0 +1,160 @@
+import { Component } from "../../interface/component/component.js";
+import type { Entity } from "../../interface/entity/entity.js";
+import { Finalizer } from "../../interface/finalizer/finalizer.js";
+import { Resource } from "../../interface/resource/resource.js";
+import { System } from "../../interface/system/system.js";
+import type { World } from "../../interface/world/world.js";
+
+// Keys, systems and a finalizer both threads of the remote finalizers tests import: a finalizer on thread
+// "remoteFinalizersTest", which a joined thread fills, reading structs, a constant, that thread's objects and its
+// object resource, and what it saw, on the thread it ran on.
+
+export const serial = Symbol("remoteFinalizersTest/serial");
+export const place = Symbol("remoteFinalizersTest/place");
+export const marked = Symbol("remoteFinalizersTest/marked");
+export const flagged = Symbol("remoteFinalizersTest/flagged");
+export const widget = Symbol("remoteFinalizersTest/widget");
+export const label = Symbol("remoteFinalizersTest/label");
+export const tone = Symbol("remoteFinalizersTest/tone");
+export const title = Symbol("remoteFinalizersTest/title");
+declare module "@adobe/ecs" {
+    export interface Threads {
+        remoteFinalizersTest: true;
+    }
+    export interface Components {
+        [serial]: { type: number };
+        [place]: { type: readonly [number, number] };
+        [marked]: { type: true };
+        [flagged]: { type: true };
+        [widget]: { type: Widget | null; thread: "remoteFinalizersTest" };
+        [label]: { type: { readonly text: string } | null; thread: "remoteFinalizersTest" };
+        [title]: { type: string };
+    }
+    export interface Resources {
+        [tone]: { type: { readonly text: string }; thread: "remoteFinalizersTest" };
+    }
+}
+/** A value that isn't data, which only its thread holds. */
+type Widget = { readonly tag: string; readonly draw: () => string };
+Component.register(serial, { type: { type: "integer" } });
+Component.register(place, { type: { type: "array", items: { type: "number" }, minItems: 2, maxItems: 2 } });
+Component.register(marked, { type: { const: true } });
+Component.register(flagged, { type: { const: true } });
+Component.register(widget, { thread: "remoteFinalizersTest" });
+const text = { type: "object", properties: { text: { type: "string" } } } as const;
+Component.register(label, { type: { anyOf: [text, { type: "null" }], default: { text: "none" } }, thread: "remoteFinalizersTest" });
+Resource.register(tone, { type: { ...text, default: { text: "quiet" } }, thread: "remoteFinalizersTest" });
+/** A string, in shared memory, which the world's thread writes and the finalizer on the thread reads. */
+Component.register(title, { type: { type: "string" } });
+
+/** A stop as the finalizer saw it, on the thread it ran on. */
+export type Released = { readonly serial: number; readonly place: readonly number[]; readonly marked: boolean; readonly widget: string | null; readonly label: string | null; readonly tone: string };
+
+/** Every stop finalized on this thread, in order, with the entity each was. */
+export const released: Released[] = [];
+export const finalized: Entity[] = [];
+/** Serials whose stops throw. */
+export const throwing = new Set<number>();
+
+/** On the finalizers' thread: what each stop held there, its structs before the sync point applied. */
+export const release = Finalizer.create({ name: "remoteFinalizersTest/release", components: { read: [serial, place, marked, widget, label] }, resources: { read: [tone] } }, (row, { resources }) => {
+    finalized.push(row.entity);
+    released.push({ serial: row[serial], place: [...row[place]], marked: row[marked], widget: row[widget]?.tag ?? null, label: row[label]?.text ?? null, tone: resources[tone]?.text });
+    if (throwing.has(row[serial])) throw new Error(`remoteFinalizersTest: ${row[serial]} throws`);
+});
+
+/** Every titled stop finalized on this thread, in order, with the title it read. */
+export const entitled: { readonly serial: number; readonly title: string }[] = [];
+
+/** On the finalizers' thread: what each titled stop's title was before its sync point applied. */
+export const entitle = Finalizer.create({ name: "remoteFinalizersTest/entitle", components: { read: [serial, title, widget] } }, row => {
+    entitled.push({ serial: row[serial], title: row[title] });
+});
+
+/** Spawns titled rows from the world's thread, with the thread's widget at null. */
+export const spawnTitled = System.create({ name: "remoteFinalizersTest/spawnTitled", input: { type: "object", properties: { from: { type: "integer" }, count: { type: "integer" } } } }, ({ input, commands }) => {
+    for (let k = input.from; k < input.from + input.count; k++) commands.spawn([serial, title, widget])({ [serial]: k, [title]: `t${k}`, [widget]: null });
+});
+/** From the world's thread: every title as another of the same size, so the records of titles let go are reused. */
+export const retitle = System.create({ name: "remoteFinalizersTest/retitle", input: { type: "object", properties: { round: { type: "integer" } } }, components: { write: [title] } }, (row, { input }) => {
+    row[title] = `r${input.round}`;
+});
+
+/** Spawns from the world's thread: structs, the thread's objects at null and their start. */
+export const spawn = System.create({ name: "remoteFinalizersTest/spawn", input: { type: "object", properties: { from: { type: "integer" }, count: { type: "integer" } } } }, ({ input, commands }) => {
+    for (let k = input.from; k < input.from + input.count; k++) commands.spawn([serial, place, marked, widget, label])({ [serial]: k, [place]: [k, -k], [widget]: null });
+});
+/** On the thread: widgets written in place. */
+export const attach = System.create({ name: "remoteFinalizersTest/attach", components: { read: [serial], write: [widget] } }, row => {
+    const tag = `w${row[serial]}`;
+    row[widget] = { tag, draw: () => tag };
+});
+/** On the thread: labels given by command, staged there, for odd serials. */
+export const relabel = System.create({ name: "remoteFinalizersTest/relabel", components: { read: [serial, label] } }, (row, { commands }) => {
+    const relabelled = { text: `l${row[serial]}${row[label]?.text === "none" ? "" : "+"}` };
+    if (row[serial] % 2 === 1) commands.add(row.entity, label, relabelled);
+});
+/** On the thread: its object resource. */
+export const retone = System.create({ name: "remoteFinalizersTest/retone", input: { type: "object", properties: { tone: { type: "string" } } }, resources: { write: [tone] } }, ({ input, resources }) => {
+    resources[tone] = { text: input.tone };
+});
+/** From the world's thread: places move, so a stop's values are those before the sync point applies. */
+export const shift = System.create({ name: "remoteFinalizersTest/shift", components: { write: [place] } }, row => {
+    row[place] = [row[place][0] + 100, row[place][1]];
+});
+/** From the world's thread: despawns these serials. */
+export const despawn = System.create({ name: "remoteFinalizersTest/despawn", input: { type: "object", properties: { serials: { type: "array", items: { type: "integer" } } } }, components: { read: [serial] } }, (row, { input, commands }) => {
+    if (input.serials.includes(row[serial])) commands.despawn(row.entity);
+});
+/** From the world's thread: removes widgets of these serials, a stop that despawns nothing. */
+export const strip = System.create({ name: "remoteFinalizersTest/strip", input: { type: "object", properties: { serials: { type: "array", items: { type: "integer" } } } }, components: { read: [serial], has: [widget] } }, (row, { input, commands }) => {
+    if (input.serials.includes(row[serial])) commands.remove(row.entity, widget);
+});
+/** From the world's thread: every row moves archetype, flagged on one run and not on the next. */
+export const flag = System.create({ name: "remoteFinalizersTest/flag", components: { has: [serial], not: [flagged] } }, (row, { commands }) => {
+    commands.add(row.entity, flagged);
+});
+export const unflag = System.create({ name: "remoteFinalizersTest/unflag", components: { has: [serial, flagged] } }, (row, { commands }) => {
+    commands.remove(row.entity, flagged);
+});
+
+/** Waits until `done` holds, letting other tasks run, for at most `milliseconds`. */
+export const eventually = async (done: () => boolean | Promise<boolean>, milliseconds = 20000): Promise<boolean> => {
+    const deadline = performance.now() + milliseconds;
+    while (!await done() && performance.now() < deadline) await new Promise(resolve => setTimeout(resolve, 1));
+    return done();
+};
+
+/** Stops in a comparable order: by serial, then as they came. */
+export const sorted = (stops: readonly Released[]): readonly Released[] => stops.map((stop, k) => [stop, k] as const).sort((a, b) => a[0].serial - b[0].serial || a[1] - b[1]).map(([stop]) => stop);
+
+/**
+ * The runs both worlds take: spawns, widgets and labels given on the finalizers' thread, despawns and a removal in
+ * sync points that move other rows into the stopped ones, a crowd moved past what a joined thread's log holds before
+ * its despawns, and its object resource changed. `stops` is how many stops the finalizer has seen, wherever it runs;
+ * each step waits until it saw `expected` of them, with what an inline world saw first.
+ */
+export const scenario = async (world: World, stops: () => number | Promise<number>, expected: readonly number[] = []): Promise<readonly number[]> => {
+    const seen: number[] = [];
+    const step = async (run: Promise<unknown>): Promise<void> => {
+        await run;
+        const wanted = expected[seen.length];
+        if (wanted !== undefined) await eventually(async () => await stops() >= wanted);
+        seen.push(await stops());
+    };
+    await step(world.run(spawn, { from: 0, count: 12 }));
+    await step(world.run(attach));
+    await step(world.run(relabel));
+    await step(world.run(shift));
+    await step(world.run(despawn, { serials: [1, 2, 5, 11] }));
+    await step(world.run(strip, { serials: [3] }));
+    await step(world.run(retone, { tone: "loud" }));
+    await step(world.run(despawn, { serials: [3, 4] }));
+    await step(world.run(spawn, { from: 100, count: 300 }));
+    await step(world.run(attach));
+    await step(world.run(relabel));
+    for (let k = 0; k < 30; k++) await step(world.run(k % 2 === 0 ? flag : unflag));
+    await step(world.run(despawn, { serials: [100, 101, 150, 299] }));
+    await step(world.run(despawn, { serials: [6, 7] }));
+    return seen;
+};

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

@@ -0,0 +1,188 @@
+import { describe, expect, it } from "vitest";
+import type { Entity } from "../../interface/entity/entity.js";
+import { Finalizer } from "../../interface/finalizer/finalizer.js";
+import { Observe } from "../../observe/index.js";
+import { identify } from "../../interface/registry/ids.test-helper.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 { indexOf } from "./entities.js";
+import { attach, despawn, eventually, finalized, marked, place, released, retone, scenario, serial, sorted, spawn, throwing, tone, widget } from "./remote-finalizers.test-helper.js";
+import { runReported } from "./reports.test-helper.js";
+
+// Finalizers on a joined thread, with the world and the thread on this one, joined through a MessageChannel.
+
+/** 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);
+
+/** A world shared with a thread on this one, which claims the finalizers' thread. */
+const joined = async (): Promise<{ 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: ["remoteFinalizersTest"] });
+    await statusOf(world, "joined");
+    return { world, remote };
+};
+
+const reset = (): void => {
+    released.length = 0;
+    finalized.length = 0;
+    throwing.clear();
+};
+
+describe("finalizers on a joined thread", () => {
+    it("leave a joined thread's objects out of a changes finalizer watching everything here, as whole-entity observers do", async () => {
+        reset();
+        const seen: (readonly symbol[] | null)[][] = [];
+        let watching = false;
+        Finalizer.changes({ name: "remoteFinalizersTest/everything" }, changes => {
+            if (watching) for (const group of changes.groups) seen.push([group.to, group.added]);
+        });
+        const { world, remote } = await joined();
+        watching = true;
+        await world.run(spawn, { from: 0, count: 1 });
+        watching = false;
+        expect(seen).toEqual([[[serial, place, marked], [serial, place, marked]]]);
+        await remote.dispose();
+        await world.dispose();
+    });
+    it("run once per stop there, as an inline world's do: structs before the sync point applies, the thread's objects at their starts, null, written or staged, after its log lapped too", async () => {
+        reset();
+        const inline = createWorld({ [workers]: 0 });
+        const expected = await scenario(inline, () => released.length);
+        await inline.dispose();
+        const inlineStops = sorted(released);
+        reset();
+        const { world, remote } = await joined();
+        const seen = await scenario(world, () => released.length, expected);
+        expect(seen).toEqual(expected);
+        await world.dispose();
+        expect(await eventually(() => released.length === inlineStops.length)).toBe(true);
+        expect(sorted(released)).toEqual(inlineStops);
+        expect(released.find(stop => stop.serial === 1)).toEqual({ serial: 1, place: [101, -1], marked: true, widget: "w1", label: "l1", tone: "quiet" });
+        expect(released.find(stop => stop.serial === 2)).toEqual({ serial: 2, place: [102, -2], marked: true, widget: "w2", label: "none", tone: "quiet" });
+        // Removing a widget stops it there, which a despawn later doesn't again.
+        expect(released.filter(stop => stop.serial === 3)).toEqual([{ serial: 3, place: [103, -3], marked: true, widget: "w3", label: "l3", tone: "quiet" }]);
+        expect(released.find(stop => stop.serial === 299)).toEqual({ serial: 299, place: [299, -299], marked: true, widget: "w299", label: "l299", tone: "loud" });
+        await remote.dispose();
+    });
+    it("run before the index of an entity they stopped is reused", async () => {
+        reset();
+        const { world, remote } = await joined();
+        await world.run(spawn, { from: 0, count: 20 });
+        const stopped = new Map<number, Entity>();
+        let reusedEarly = 0;
+        let reused = 0;
+        // Spawns check each entity they reserve: an index whose last entity stopped is reused only once it was finalized.
+        const check = System.create(identify({ name: "remoteFinalizersTest/check", input: { type: "object", properties: { serial: { type: "integer" } } } }, "remoteFinalizersTest#check"), ({ input, commands }) => {
+            const entity = commands.spawn([serial, place, marked, widget])({ [serial]: input.serial, [place]: [0, 0], [widget]: null });
+            const before = stopped.get(indexOf(entity));
+            if (before === undefined) return;
+            reused++;
+            if (!finalized.includes(before)) reusedEarly++;
+        });
+        const entities = await Observe.toPromise(Observe.select(world, { required: [serial] }));
+        for (const entity of entities) stopped.set(indexOf(entity), entity);
+        const runs: Promise<unknown>[] = [];
+        for (let k = 0; k < 20; k++) {
+            // Not awaited: the next run starts before the thread had a turn to finalize.
+            runs.push(world.run(despawn, { serials: [k] }), world.run(check, { serial: 1000 + k }));
+        }
+        await Promise.all(runs);
+        expect(await eventually(() => finalized.length === 20)).toBe(true);
+        for (let k = 0; k < 20; k++) await world.run(check, { serial: 2000 + k });
+        expect(reusedEarly).toBe(0);
+        expect(reused).toBeGreaterThan(0);
+        await remote.dispose();
+        await world.dispose();
+    });
+    it("that throw are in a later run's report", async () => {
+        reset();
+        const { world, remote } = await joined();
+        await world.run(spawn, { from: 0, count: 3 });
+        throwing.add(1);
+        await world.run(despawn, { serials: [0, 1, 2] });
+        expect(await eventually(() => released.length === 3)).toBe(true);
+        // Its failure reaches the world by message, in time for a later run.
+        let report = await runReported(world, despawn, { serials: [] });
+        for (let k = 0; k < 100 && report.failures.length === 0; k++) {
+            await new Promise(resolve => setTimeout(resolve, 1));
+            report = await runReported(world, despawn, { serials: [] });
+        }
+        expect(report.failures.map(failure => [failure.kind, failure.name, failure.message])).toEqual([["finalizer", "remoteFinalizersTest/release", "remoteFinalizersTest: 1 throws"]]);
+        expect((await runReported(world, despawn, { serials: [] })).failures).toEqual([]);
+        await remote.dispose();
+        await world.dispose();
+    });
+    it("run there for every entity they match once the world is disposed, after the stops published", async () => {
+        reset();
+        const { world, remote } = await joined();
+        await world.run(spawn, { from: 0, count: 5 });
+        await world.run(attach);
+        await world.run(despawn, { serials: [4] });
+        await world.dispose();
+        expect(await eventually(() => released.length === 5)).toBe(true);
+        expect(released.map(stop => [stop.serial, stop.widget])).toEqual([[4, "w4"], [0, "w0"], [1, "w1"], [2, "w2"], [3, "w3"]]);
+        await remote.dispose();
+    });
+    it("finalize what was published when their thread leaves, and run on the world's thread once it's gone", async () => {
+        reset();
+        const { world, remote } = await joined();
+        await world.run(spawn, { from: 0, count: 3 });
+        await world.run(attach);
+        await world.run(despawn, { serials: [0] });
+        await remote.dispose();
+        await statusOf(world, "gone");
+        expect(released.map(stop => [stop.serial, stop.widget])).toEqual([[0, "w0"]]);
+        // Its objects came back as their starts, with the thread's values its own.
+        const report = await runReported(world, despawn, { serials: [1] });
+        expect(report.failures).toEqual([]);
+        expect(released.map(stop => [stop.serial, stop.widget])).toEqual([[0, "w0"], [1, null]]);
+        await world.dispose();
+        expect(released.map(stop => stop.serial)).toEqual([0, 1, 2]);
+    });
+    // Last: the finalizers it creates stay in the program.
+    it("created after the claim run there; one the thread can't name doesn't activate, reported once", async () => {
+        reset();
+        const { world, remote } = await joined();
+        await world.run(spawn, { from: 0, count: 2 });
+        const late: string[] = [];
+        Finalizer.create(identify({ name: "remoteFinalizersTest/late", components: { read: [widget, serial] } }, "remoteFinalizersTest#late"), row => { late.push(`${row[serial]}:${String(row[widget])}`); });
+        // Declared in a function, so the build gives it no id.
+        Finalizer.create({ name: "remoteFinalizersTest/unnamed", components: { read: [widget] } }, () => {});
+        const first = await runReported(world, despawn, { serials: [0] });
+        expect(first.failures.map(failure => [failure.kind, failure.name, failure.message])).toEqual([["finalizer", "remoteFinalizersTest/unnamed", 'Finalizer "remoteFinalizersTest/unnamed" runs on thread "remoteFinalizersTest", which a joined thread fills, and has no id, so that thread can\'t name it; the build gives top-level finalizers one.']]);
+        expect(await eventually(() => late.length === 1)).toBe(true);
+        expect((await runReported(world, despawn, { serials: [1] })).failures).toEqual([]);
+        expect(await eventually(() => late.length === 2)).toBe(true);
+        expect(late).toEqual(["0:null", "1:null"]);
+        // Placed there by the thread's object resource alone: stops of rows holding none of its objects, which its log
+        // has no entries for, run there too.
+        const heard: string[] = [];
+        Finalizer.create(identify({ name: "remoteFinalizersTest/heard", components: { read: [serial], not: [widget] }, resources: { read: [tone] } }, "remoteFinalizersTest#heard"), (row, { resources }) => { heard.push(`${row[serial]}:${resources[tone].text}`); });
+        const plain = System.create({ name: "remoteFinalizersTest/plain" }, ({ commands }) => {
+            for (let k = 0; k < 3; k++) commands.spawn([serial, place])({ [serial]: 50 + k, [place]: [0, 0] });
+        });
+        await world.run(plain);
+        await world.run(retone, { tone: "soft" });
+        expect((await runReported(world, despawn, { serials: [50, 52] })).failures).toEqual([]);
+        expect(await eventually(() => heard.length === 2)).toBe(true);
+        expect(heard).toEqual(["50:soft", "52:soft"]);
+        await remote.dispose();
+        await world.dispose();
+    });
+});

package/src/implementation/world/remote-objects-worker.fixture.ts

@@ -0,0 +1,20 @@
+import type { MessagePort as NodeMessagePort } from "node:worker_threads";
+import { asEntity } from "./entities.js";
+import { join } from "./create.js";
+import { scopeChannel } from "./port.js";
+import { watch, type Observers, type Watched } from "./remote-objects.test-helper.js";
+
+/** A thread joining a world through the port it's sent, claiming "remoteObjects", and watching an entity there. */
+
+type Port = MessagePort | NodeMessagePort;
+export type ToRemoteObjectsWorker = { readonly kind: "watch"; readonly port: Port; readonly entity: number; readonly count: number; readonly observers: Observers };
+export type FromRemoteObjectsWorker = { readonly kind: "watched"; readonly watched: Watched };
+
+const channel = scopeChannel<FromRemoteObjectsWorker, ToRemoteObjectsWorker>();
+channel.onMessage(async message => {
+    if ("protocol" in message) return;
+    const remote = join(message.port, { threads: ["remoteObjects"] });
+    const watched = await watch(remote, asEntity(message.entity), message.count, message.observers);
+    await remote.dispose();
+    channel.post({ kind: "watched", watched });
+});

package/src/implementation/world/remote-objects.cases.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import type * as Fixture from "./remote-objects.fixture.js";
+
+/** Objects a joined worker fills: the cases, over the fixture built for node or from source. */
+export const remoteObjectsCases = (load: () => Promise<typeof Fixture>) => describe("objects a joined thread fills", () => {
+    it("give the observer factories on a joined worker its objects as of the struct values they're read with, through the structure epoch while the world applies", async () => {
+        const fixture = await load();
+        const watched = await fixture.watchedWhileApplying(400, "factory");
+        expect(watched).toEqual({ values: 400, inconsistent: 0, captions: ["none", null] });
+    }, 30000);
+    it("give a joined worker's observer systems its objects as of the struct values they look up with", async () => {
+        const fixture = await load();
+        const watched = await fixture.watchedWhileApplying(400, "observer");
+        expect(watched).toEqual({ values: 400, inconsistent: 0, captions: ["none", null] });
+    }, 30000);
+});

package/src/implementation/world/remote-objects.fixture.ts

@@ -0,0 +1,59 @@
+/// <reference types="node" />
+import { Observe } from "../../observe/index.js";
+import { always } from "../../interface/resources/always.js";
+import { workers } from "../../interface/resources/workers.js";
+import { createWorld } from "./create.js";
+import { backToBack } from "./loop.js";
+import type { FromRemoteObjectsWorker, ToRemoteObjectsWorker } from "./remote-objects-worker.fixture.js";
+import { churn, seed, serial, type Observers, type Watched } from "./remote-objects.test-helper.js";
+
+/**
+ * Scenarios of objects a joined worker fills, run built in node and from source in chromium: the worker watches an
+ * entity whose objects change and move every tick, while the world here applies sync points back to back.
+ */
+
+type Worker = { readonly ask: (message: ToRemoteObjectsWorker, transfer: readonly unknown[]) => Promise<FromRemoteObjectsWorker>; readonly terminate: () => Promise<void> };
+
+const workerFile = "./remote-objects-worker.fixture.js";
+
+const start = (): Worker => {
+    if (typeof globalThis.Worker === "function") {
+        const worker = new globalThis.Worker(new URL("./remote-objects-worker.fixture.js", import.meta.url), { type: "module" });
+        return {
+            ask: (message, transfer) => new Promise(resolve => {
+                worker.onmessage = (event: MessageEvent<FromRemoteObjectsWorker>) => 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 worker watching an entity's objects here, through `observers`, while the world ticks back to back, moving and
+ * changing them each tick.
+ */
+export const watchedWhileApplying = async (count: number, observers: Observers): Promise<Watched | null> => {
+    const driver = backToBack();
+    const world = createWorld({ [workers]: 0, [always]: true }, { loop: driver });
+    await world.run(seed);
+    const [entity] = await Observe.toPromise(Observe.select(world, { required: [serial], where: { [serial]: 0 } }));
+    const worker = start();
+    const { port1, port2 } = new MessageChannel();
+    world.share(port1);
+    world.add(churn);
+    const reply = await worker.ask({ kind: "watch", port: port2, entity, count, observers }, [port2]);
+    await worker.terminate();
+    await world.dispose();
+    driver.close();
+    return reply.kind === "watched" ? reply.watched : null;
+};