@adobe/ecs 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,254 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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 { catchOutOfBand, runReported } from "./outcomes.test-helper.js";
+
+/** Resources of the world's thread, each added once the thread joined, so the resource entity moves to another archetype. */
+const later = Symbol("remoteFinalizersTest/later");
+const second = Symbol("remoteFinalizersTest/second");
+const third = Symbol("remoteFinalizersTest/third");
+declare module "@adobe/ecs" {
+    export interface Resources {
+        [later]: { type: number };
+        [second]: { type: number };
+        [third]: { type: number };
+    }
+}
+const bump = System.create({}, ({ resources }) => {
+    resources[later] += 1;
+});
+const bumpSecond = System.create({}, ({ resources }) => {
+    resources[second] += 1;
+});
+const bumpThird = System.create({}, ({ resources }) => {
+    resources[third] += 1;
+});
+
+// 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: "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();
+    const shared = world.share(channel.port1);
+    const remote = await join(channel.port2, { threads: ["remoteFinalizersTest"] });
+    await shared;
+    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({}, 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({}, "remoteFinalizersTest#check"), ({ commands }, input: { readonly serial: number }) => {
+            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 reported out of band on the world's thread, which hears of it by message", async () => {
+        reset();
+        using reported = catchOutOfBand();
+        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);
+        const error = await reported.until(() => true);
+        expect(error.message).toMatch(/^Finalizer "release" .*failed: remoteFinalizersTest: 1 throws$/);
+        expect(error.cause instanceof Error && error.cause.message).toBe("remoteFinalizersTest: 1 throws");
+        expect((await runReported(world, despawn, { serials: [] })).failures).toEqual([]);
+        expect(reported.errors).toHaveLength(1);
+        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]);
+    });
+    it("read their thread's object resource as the thread holds it, from the first sync point after joining and once the resource entity moved before they ran", async () => {
+        reset();
+        const { world, remote } = await joined();
+        // Stops the thread runs as it first rebuilds, before it holds any row.
+        await world.run(spawn, { from: 0, count: 3 });
+        await world.run(despawn, { serials: [0] });
+        expect(await eventually(() => released.length === 1)).toBe(true);
+        await world.run(retone, { tone: "soft" });
+        // Not awaited: the resource entity moves to another archetype before the thread replays the stop's sync.
+        await Promise.all([world.run(despawn, { serials: [1] }), world.run(bump)]);
+        expect(await eventually(() => released.length === 2)).toBe(true);
+        expect(released.map(stop => [stop.serial, stop.tone])).toEqual([[0, "quiet"], [1, "soft"]]);
+        await remote.dispose();
+        await world.dispose();
+    });
+    it("read their thread's object resource where the resource entity moved since it was last found, before a later write applies", async () => {
+        reset();
+        const { world, remote } = await joined();
+        await world.run(spawn, { from: 0, count: 3 });
+        await world.run(despawn, { serials: [0] });
+        expect(await eventually(() => released.length === 1)).toBe(true);
+        // Replayed, not rebuilt: the resource entity is found in the mirror.
+        await world.run(despawn, { serials: [1] });
+        expect(await eventually(() => released.length === 2)).toBe(true);
+        await world.run(bump);
+        await world.run(retone, { tone: "soft" });
+        // The write after the stop's sync is a task the thread runs once it replayed that sync.
+        await Promise.all([world.run(despawn, { serials: [2] }), world.run(retone, { tone: "loud" })]);
+        expect(await eventually(() => released.length === 3)).toBe(true);
+        expect(released.map(stop => [stop.serial, stop.tone])).toEqual([[0, "quiet"], [1, "quiet"], [2, "soft"]]);
+        await remote.dispose();
+        await world.dispose();
+    });
+    it("read their thread's object resource once the resource entity moved twice before the thread replayed", async () => {
+        reset();
+        const { world, remote } = await joined();
+        await world.run(spawn, { from: 0, count: 2 });
+        await world.run(despawn, { serials: [0] });
+        expect(await eventually(() => released.length === 1)).toBe(true);
+        await world.run(retone, { tone: "soft" });
+        await Promise.all([world.run(despawn, { serials: [1] }), world.run(bumpSecond), world.run(bumpThird)]);
+        expect(await eventually(() => released.length === 2)).toBe(true);
+        expect(released.map(stop => [stop.serial, stop.tone])).toEqual([[0, "quiet"], [1, "soft"]]);
+        await remote.dispose();
+        await world.dispose();
+    });
+    // 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({ components: { with: [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({ components: { with: [widget] } }, row => { void row[widget]; });
+        const first = await runReported(world, despawn, { serials: [0] });
+        expect(first.failures.map(failure => [failure.kind, failure.name, failure.message])).toEqual([["finalizer", expect.stringMatching(/^finalizer #\d+$/), expect.stringMatching(/^Finalizer "finalizer #\d+" 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({ components: { with: [serial], not: [widget] } }, "remoteFinalizersTest#heard"), (row, { resources }) => { heard.push(`${row[serial]}:${resources[tone].text}`); });
+        const plain = System.create({}, ({ 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,21 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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 = await 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,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+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,61 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+/// <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();
+    const shared = world.share(port1);
+    world.add(churn);
+    const reply = await worker.ask({ kind: "watch", port: port2, entity, count, observers }, [port2]);
+    await shared;
+    await worker.terminate();
+    await world.dispose();
+    driver.close();
+    return reply.kind === "watched" ? reply.watched : null;
+};

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

@@ -0,0 +1,106 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Entity } from "../../interface/entity/entity.js";
+import { System } from "../../interface/system/system.js";
+import type { World } from "../../interface/world/world.js";
+import { Observe } from "../../observe/index.js";
+
+// Keys and systems both threads of the remote objects fixtures import: objects of thread "remoteObjects", which a
+// joined worker fills, and what it sees of them while the world applies sync points back to back.
+
+export const serial = Symbol("remoteObjectsTest/serial");
+export const phase = Symbol("remoteObjectsTest/phase");
+export const flag = Symbol("remoteObjectsTest/flag");
+export const caption = Symbol("remoteObjectsTest/caption");
+declare module "@adobe/ecs" {
+    export interface Threads {
+        remoteObjects: true;
+    }
+    export interface Components {
+        [serial]: { type: number };
+        [phase]: { type: number };
+        [flag]: { type: true };
+        [caption]: { type: Caption; thread: "remoteObjects" };
+    }
+}
+/** The caption's start, which a command here gives it by this value. */
+const none = { text: "none" } as const;
+/** A caption, which starts as `none`, the value commands on other threads give it by identity. */
+type Caption = { readonly text: string } | null;
+const Caption = { default: none };
+
+/** A caption's text, null for none, as the watchers record it. */
+const textOf = (value: { readonly text: string } | null): string | null => value === null ? null : value.text;
+
+/** The watched entity, serial 0. */
+export const seed = System.create({}, ({ commands }) => {
+    commands.spawn([serial, phase, caption])({ [serial]: 0, [phase]: 0 });
+});
+
+/**
+ * Every tick: the watched entity's phase moves on, and its caption and flag follow it at the sync point, null and
+ * flagged when it's odd, so it moves archetype every tick; the other entities despawn, and four more spawn into its
+ * archetypes, so rows swap into the holes they leave.
+ */
+export const churn = System.create({ components: { with: [serial, phase] } }, (row, { commands }) => {
+    if (row[serial] !== 0) {
+        commands.despawn(row.entity);
+        return;
+    }
+    const next = row[phase] + 1;
+    row[phase] = next;
+    if (next % 2 === 1) {
+        commands.add(row.entity, flag);
+        commands.add(row.entity, caption, null);
+    }
+    else {
+        commands.remove(row.entity, flag);
+        commands.add(row.entity, caption, none);
+    }
+    for (let k = 1; k <= 4; k++) {
+        if (k % 2 === 0) commands.spawn([serial, phase, caption])({ [serial]: k, [phase]: 0, [caption]: null });
+        else commands.spawn([serial, phase, caption, flag])({ [serial]: k, [phase]: 0 });
+    }
+});
+
+/** What a joined thread saw of the watched entity's objects: values, those whose objects disagreed with its structs, and captions seen. */
+export type Watched = { readonly values: number; readonly inconsistent: number; readonly captions: readonly (string | null)[] };
+
+/** What watches: the observer factories on the joined thread's world, or an observer system it added. */
+export type Observers = "factory" | "observer";
+
+/** The entity `observerWatch` watches, and what it's told of each value. */
+const observer: { entity: Entity | null; seen: ((odd: boolean, held: boolean, text: string | null | undefined) => void) | null } = { entity: null, seen: null };
+
+/** After each sync point, on the joined thread: the watched entity's phase and caption, and whether it's flagged. */
+export const observerWatch = System.create({ observer: true, lookup: { values: { with: [phase, caption] }, flagged: { with: [flag] } } }, ({ lookup }) => {
+    if (observer.entity === null) return;
+    const row = lookup.values(observer.entity);
+    if (row === null) return;
+    observer.seen?.(row[phase] % 2 === 1, lookup.flagged(observer.entity) !== null, textOf(row[caption]));
+});
+
+/** Watches `entity` until `count` values came, checking each value's objects agree with its structs. */
+export const watch = (remote: World, entity: Entity, count: number, observers: Observers): Promise<Watched> => new Promise(resolve => {
+    let values = 0;
+    let inconsistent = 0;
+    const captions = new Set<string | null>();
+    const stops: (() => void)[] = [];
+    const seen = (odd: boolean, held: boolean, text: string | null | undefined): void => {
+        values++;
+        if (text !== undefined) captions.add(text);
+        if (held !== odd || text !== (odd ? null : "none")) inconsistent++;
+        if (values !== count) return;
+        queueMicrotask(() => { for (const stop of stops) stop(); });
+        resolve({ values, inconsistent, captions: [...captions].sort() });
+    };
+    if (observers === "observer") {
+        observer.entity = entity;
+        observer.seen = (odd, held, text) => { if (values < count) seen(odd, held, text); };
+        remote.add(observerWatch);
+        stops.push(() => remote.remove(observerWatch));
+        return;
+    }
+    stops.push(Observe.entity(remote, entity, { required: [phase, caption], optional: [flag] })(value => {
+        if (value !== null && values < count) seen(value[phase] % 2 === 1, value[flag] === true, textOf(value[caption]));
+    }));
+});