@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/world/observe-ticks-cases.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, it } from "vitest";
+import { Component, Resource, System, always, cadence, clock, wake, workers } from "../../index.js";
+import type { World } from "../../interface/world/world.js";
+import { createWorld } from "./create.js";
+import { Observe } from "../../observe/index.js";
+import { followReports, reportOf, runReported } from "./reports.test-helper.js";
+
+// Ticks and tick stamps, read through the observer factories of `src/observe`.
+
+const frames = Symbol("observeTicksCasesTest/frames");
+const seen = Symbol("observeTicksCasesTest/seen");
+const value = Symbol("observeTicksCasesTest/value");
+const watched = Symbol("observeTicksCasesTest/watched");
+const flag = Symbol("observeTicksCasesTest/flag");
+declare module "@adobe/ecs" {
+    interface Resources {
+        [frames]: { type: number };
+        [seen]: { type: number };
+    }
+    interface Components {
+        [value]: { type: number };
+        [watched]: { type: number };
+        [flag]: { type: true };
+    }
+}
+Resource.register(frames, { type: { type: "number", default: 0 } });
+Resource.register(seen, { type: { type: "number", default: -1 } });
+Component.register(value, { type: { type: "number", precision: 1 } });
+Component.register(watched, { type: { type: "number", precision: 1 } });
+Component.register(flag, { type: { const: true } });
+
+const count = System.create({ name: "observeTicksCasesTest/count", resources: { write: [frames] } }, ({ resources }) => { resources[frames] += 1; });
+const watch = System.create({ name: "observeTicksCasesTest/watch", resources: { read: [clock], write: [seen] } }, ({ resources }) => { resources[seen] = resources[clock].tick; });
+const fail = System.create({ name: "observeTicksCasesTest/fail" }, () => { throw new Error("tick failed"); });
+const nothing = System.create({ name: "observeTicksCasesTest/nothing" }, () => {});
+const idle = System.create({ name: "observeTicksCasesTest/idle", observer: true }, () => {});
+const fast = System.create({ name: "observeTicksCasesTest/fast", resources: { write: [cadence, always] } }, ({ resources }) => {
+    resources[cadence] = { kind: "fixed", step: 1 };
+    resources[always] = true;
+});
+const calm = System.create({ name: "observeTicksCasesTest/calm", resources: { write: [always] } }, ({ resources }) => { resources[always] = false; });
+const later = System.create({ name: "observeTicksCasesTest/later", resources: { read: [clock] }, reduce: { [wake]: "min" } }, ({ resources, reduce }) => {
+    if (resources[clock].tick === 0) reduce[wake](resources[clock].now + 20);
+});
+
+const seed = System.create({ name: "observeTicksCasesTest/seed" }, ({ commands }) => {
+    for (let i = 0; i < 3000; i++) commands.spawn([value, watched])({ [value]: i, [watched]: 0 });
+});
+/** Writes every value: until something observes `value`, its stamps are muted. */
+const bump = System.create({ name: "observeTicksCasesTest/bump", kernel: "cpu", components: { write: [value] } }, row => {
+    row[value] = row[value] + 1;
+});
+const watchChanged = System.create({ name: "observeTicksCasesTest/watchChanged", kernel: "cpu", components: { write: [watched], changed: [value] }, after: [bump] }, row => {
+    row[watched] = row[watched] + 1;
+});
+/** Counts rows whose `value` was added since it last ran. */
+const fresh = System.create({ name: "observeTicksCasesTest/fresh", components: { write: [watched], added: [value] } }, row => {
+    row[watched] = row[watched] + 1;
+});
+const flagAll = System.create({ name: "observeTicksCasesTest/flagAll", components: { has: [value] } }, (row, { commands }) => {
+    commands.add(row.entity, flag, true);
+});
+const spawnOne = System.create({ name: "observeTicksCasesTest/spawnOne" }, ({ commands }) => {
+    commands.spawn([value, watched])({ [value]: -1, [watched]: 0 });
+});
+
+const pause = (milliseconds: number): Promise<void> => new Promise(resolve => setTimeout(resolve, milliseconds));
+
+const { resource, entity, select, toPromise } = Observe;
+
+/** The resource's value once `done` holds of it. */
+const until = <T>(observe: (notify: (value: T) => void) => () => void, done: (value: T) => boolean): Promise<T> => new Promise(resolve => {
+    let stop: (() => void) | null = null;
+    let finished = false;
+    stop = observe(next => {
+        if (finished || !done(next)) return;
+        finished = true;
+        resolve(next);
+        stop?.();
+    });
+    if (finished) stop();
+});
+
+/** Every entity's `watched`, through the observers. */
+const watchedOf = async (world: World): Promise<number[]> => {
+    const entities = await toPromise(select(world, { required: [watched] }));
+    return Promise.all(entities.map(async each => (await toPromise(entity(world, each, { required: [watched] })))?.[watched] ?? -1));
+};
+
+describe("ticks", () => {
+    it("run the added systems on the beat after a run arrives, with the clock, and only while one is added", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        await world.run(nothing);
+        await pause(40);
+        expect(await toPromise(resource(world, frames))).toBe(0);
+        world.add(count);
+        world.add(watch);
+        await pause(40);
+        // A quiet loop runs no tick until a run arrives, and reading doesn't make it.
+        expect(await toPromise(resource(world, frames))).toBe(0);
+        await world.run(nothing);
+        expect(await until(resource(world, frames), next => next === 1)).toBe(1);
+        expect(await toPromise(resource(world, seen))).toBe(0);
+        const { tick, delta } = await toPromise(resource(world, clock));
+        expect([tick, delta]).toEqual([0, 0]);
+        await pause(40);
+        expect(await toPromise(resource(world, frames))).toBe(1);
+    });
+
+    it("keep ticking while always is set, at the cadence's step, and stop when it's cleared or the world is disposed", async () => {
+        const world = createWorld({ [workers]: 0 });
+        world.add(count);
+        await world.run(fast);
+        expect(await until(resource(world, frames), next => next >= 5)).toBeGreaterThanOrEqual(5);
+        expect((await toPromise(resource(world, clock))).delta).toBe(1);
+        await world.run(calm);
+        await pause(10);
+        const stopped = await toPromise(resource(world, frames));
+        await pause(20);
+        expect(await toPromise(resource(world, frames))).toBe(stopped);
+        const values: number[] = [];
+        const stop = resource(world, frames)(next => values.push(next));
+        await world.run(fast);
+        await until(resource(world, frames), next => next > stopped);
+        await world.dispose();
+        const disposed = values.length;
+        await pause(20);
+        expect(values.length).toBe(disposed);
+        stop();
+    });
+
+    it("tick again at the wake time a system asks for", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        world.add(later);
+        world.add(count);
+        await world.run(nothing);
+        expect(await until(resource(world, frames), next => next === 2)).toBe(2);
+        await pause(40);
+        expect(await toPromise(resource(world, frames))).toBe(2);
+    });
+
+    it("spawn a failing tick's report", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        const reports = followReports(world);
+        world.add(fail);
+        await world.run(nothing);
+        const last = await reports.until(next => next.failures.length > 0);
+        expect(last.failures.map(({ kind, name, message }) => [kind, name, message])).toEqual([["system", "observeTicksCasesTest/fail", "tick failed"]]);
+    });
+
+    it("put what an observer throws on a tick's values in a later run's report, once", async () => {
+        await using world = createWorld({ [workers]: 0 });
+        const reports = followReports(world);
+        world.add(count);
+        let counts = 0;
+        const stopFrames = resource(world, frames)(() => {
+            if (++counts === 2) throw new Error("frames observer failed");
+        });
+        await world.run(nothing);
+        await until(resource(world, frames), next => next === 1);
+        // A run of observer systems alone, which ticks nothing, so its report holds what the tick's pass threw.
+        await world.run(idle);
+        const thrown = await reports.until(report => report.failures.length > 0);
+        expect(thrown.failures.map(({ kind, message }) => [kind, message])).toEqual([["system", "frames observer failed"]]);
+        await world.run(idle);
+        expect(reports.seen.filter(report => report.failures.length > 0)).toHaveLength(1);
+        stopFrames();
+    });
+
+    it("start the loop's resources at their defaults, workers at null for the platform's choice", async () => {
+        await using world = createWorld();
+        expect(await toPromise(resource(world, cadence))).toEqual({ kind: "frame" });
+        expect(await toPromise(resource(world, always))).toBe(false);
+        expect(await toPromise(resource(world, wake))).toBe(Infinity);
+        expect(await toPromise(resource(world, workers))).toBe(null);
+    });
+});
+
+describe("tick stamps only where observed", () => {
+    it("keep `added` from the moment an observer registers, across archetype moves", async () => {
+        const world = createWorld();
+        await world.run(seed);
+        // Rows that existed before count as added once.
+        await world.run(fresh);
+        await world.run(fresh);
+        expect(new Set(await watchedOf(world))).toEqual(new Set([1]));
+        // Moving archetype keeps a row's `added` tick: old rows aren't added again, and a new row still is.
+        await world.run(spawnOne);
+        await world.run(flagAll);
+        await world.run(fresh);
+        await world.run(fresh);
+        expect((await watchedOf(world)).filter(each => each === 1).length).toBe(3001);
+        await world.dispose();
+    });
+
+    for (const wasm of [false, true]) {
+        it(`start once an observer registers (${wasm ? "WASM" : "JS"} kernels)`, async () => {
+            const world = createWorld({ [workers]: 0 }, { wasm });
+            await world.run(seed);
+            await world.run(bump);
+            // New observers see everything once.
+            await world.run(watchChanged);
+            await world.run(watchChanged);
+            expect(new Set(await watchedOf(world))).toEqual(new Set([1]));
+            // Writes after registering are stamped, so the observer sees each exactly once.
+            await world.run(bump);
+            await world.run(watchChanged);
+            await world.run(watchChanged);
+            expect(new Set(await watchedOf(world))).toEqual(new Set([2]));
+            await world.dispose();
+        });
+    }
+});

package/src/implementation/world/observe.test-helper.ts

@@ -0,0 +1,13 @@
+import { System } from "../../interface/system/system.js";
+import type { World } from "../../interface/world/world.js";
+
+const settled = System.create({ name: "observeTest/settled", observer: true }, () => {});
+
+/**
+ * Resolves once every observer factory subscribed before it had its first value: after the factories' flush, which the
+ * end of this task starts, and a run queued after the runs it makes, which changes nothing.
+ */
+export const settle = async (world: World): Promise<void> => {
+    await Promise.resolve();
+    await world.run(settled);
+};

package/src/implementation/world/observed-workers.cases.ts

@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import type * as Fixture from "./observed-workers.fixture.js";
+
+/** Tick stamps start on workers once observed: the cases, over the fixture built for node or from source. */
+export const observedWorkersCases = (load: () => Promise<typeof Fixture>) => describe("tick stamps only where observed, on workers", () => {
+    for (const wasm of [false, true]) {
+        it(`start once an observer registers (${wasm ? "WASM" : "JS"} kernels)`, async () => {
+            const fixture = await load();
+            expect(await fixture.observedOnWorkers(wasm)).toEqual([[1], [2]]);
+        });
+    }
+});

package/src/implementation/world/observed-workers.fixture.ts

@@ -0,0 +1,55 @@
+import { Component } from "../../interface/component/component.js";
+import { System } from "../../interface/system/system.js";
+import { readEach, select } from "./reads.test-helper.js";
+import { createWorld } from "./create.js";
+import { workers } from "../../interface/resources/workers.js";
+
+/** Scenarios of tick stamps on workers, run built in node and from source in chromium. */
+
+const value = Symbol("observedWorkersTest/value");
+const seen = Symbol("observedWorkersTest/seen");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [value]: { type: number };
+        [seen]: { type: number };
+    }
+}
+
+Component.register(value, { type: { type: "number", precision: 1 } });
+Component.register(seen, { type: { type: "number", precision: 1 } });
+
+const seed = System.create({ name: "observedWorkersTest/seed" }, ({ commands }) => {
+    for (let i = 0; i < 3000; i++) commands.spawn([value, seen])({ [value]: i, [seen]: 0 });
+});
+
+/** Writes every value: until something observes `value`, its stamps are muted. */
+const bump = System.create({ name: "observedWorkersTest/bump", kernel: "cpu", components: { write: [value] } }, row => {
+    row[value] = row[value] + 1;
+});
+
+const watch = System.create({ name: "observedWorkersTest/watch", kernel: "cpu", components: { write: [seen], changed: [value] }, after: [bump] }, row => {
+    row[seen] = row[seen] + 1;
+});
+
+/** The distinct counts each row's observer saw: after it registered, and after one more write. */
+export const observedOnWorkers = async (wasm: boolean): Promise<readonly (readonly number[])[]> => {
+    const world = createWorld({ [workers]: 2 }, { wasm, minimumChunk: 64 });
+    try {
+        await world.run(seed);
+        await world.run(bump);
+        const seenAll = async (): Promise<number[]> => [...new Set((await readEach(world, await select(world, { required: [seen] }), seen)).map(each => each ?? -1))];
+        // New observers see everything once.
+        await world.run(watch);
+        await world.run(watch);
+        const first = await seenAll();
+        // Writes after registering are stamped, so the observer sees each exactly once.
+        await world.run(bump);
+        await world.run(watch);
+        await world.run(watch);
+        return [first, await seenAll()];
+    }
+    finally {
+        await world.dispose();
+    }
+};

package/src/implementation/world/observer-contained-worker.fixture.ts

@@ -0,0 +1,40 @@
+import type { MessagePort as NodeMessagePort } from "node:worker_threads";
+import { System } from "../../interface/system/system.js";
+import type { World } from "../../interface/world/world.js";
+import { join } from "./create.js";
+import { scopeChannel } from "./port.js";
+import { gate, tallies, watchTally } from "./observer-contained.test-helper.js";
+
+/**
+ * A thread joining a world through the port it's sent, which adds the watcher with the gate it's sent, and tells what
+ * it saw. It says it added the watcher once a run of its own resolved: sent after the add through the same port, so the
+ * world placed the watcher by that run's sync point, which posts the watcher's first run.
+ */
+
+type Port = MessagePort | NodeMessagePort;
+export type ToContainedWorker =
+    | { readonly kind: "join"; readonly port: Port }
+    | { readonly kind: "add"; readonly gate: Int32Array }
+    | { readonly kind: "seen" };
+export type FromContainedWorker =
+    | { readonly kind: "joined" }
+    | { readonly kind: "added" }
+    | { readonly kind: "seen"; readonly tallies: readonly number[] };
+
+const channel = scopeChannel<FromContainedWorker, ToContainedWorker>();
+let remote: World | null = null;
+const placed = System.create({ name: "observerContainedTest/placed", observer: true }, () => {});
+
+channel.onMessage(message => {
+    if ("protocol" in message) return;
+    if (message.kind === "join") {
+        remote = join(message.port, {});
+        channel.post({ kind: "joined" });
+    }
+    else if (message.kind === "add") {
+        gate.words = message.gate;
+        remote?.add(watchTally);
+        void remote?.run(placed).then(() => channel.post({ kind: "added" }));
+    }
+    else channel.post({ kind: "seen", tallies: [...tallies] });
+});

package/src/implementation/world/observer-contained.browser.test.ts

@@ -0,0 +1,4 @@
+import { observerContainedCases } from "./observer-contained.cases.js";
+
+// A real worker in chromium, over the fixture's source.
+observerContainedCases(() => import("./observer-contained.fixture.js"));

package/src/implementation/world/observer-contained.cases.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import type * as Fixture from "./observer-contained.fixture.js";
+
+/** A joined worker's observer system reading only resources: the cases, over the fixture built for node or from source in chromium. */
+export const observerContainedCases = (load: () => Promise<typeof Fixture>) => describe("observer systems reading only resources on a joined worker", () => {
+    it("never hold the world's runs while one runs there, take its tick as it will, and run once more for the newest", async () => {
+        const fixture = await load();
+        const seen = await fixture.heldWhileTheWorldRuns();
+        // The world ran on while the worker held its run, posting nothing it filters on: it ran once.
+        expect(seen.quiet).toBe(true);
+        expect(seen.first).toEqual([0, 1]);
+        // Bumped twice while it held its run of 2, it ran once more, for the newest.
+        expect(seen.bumped).toBe(true);
+        expect(seen.second).toEqual([0, 1, 2, 4]);
+    }, 30000);
+});

package/src/implementation/world/observer-contained.fixture.ts

@@ -0,0 +1,125 @@
+/// <reference types="node" />
+import { workers } from "../../interface/resources/workers.js";
+import { createWorld, type CreatedWorld } from "./create.js";
+import type { FromContainedWorker, ToContainedWorker } from "./observer-contained-worker.fixture.js";
+import { bump, gateWords, nothing, reachedWord, releasedWord, setHolding } from "./observer-contained.test-helper.js";
+
+/**
+ * A joined worker's observer system reading only resources, held partway through a run while the world runs on: what
+ * the world's runs do meanwhile, and what the worker's runs saw once released. Run built in node, from source in
+ * chromium.
+ */
+
+type Worker = { readonly ask: (message: ToContainedWorker, transfer?: readonly unknown[]) => Promise<FromContainedWorker>; readonly terminate: () => Promise<void> };
+
+const workerFile = "./observer-contained-worker.fixture.js";
+
+const start = (): Worker => {
+    if (typeof globalThis.Worker === "function") {
+        const worker = new globalThis.Worker(new URL("./observer-contained-worker.fixture.js", import.meta.url), { type: "module" });
+        return {
+            ask: (message, transfer = []) => new Promise(resolve => {
+                worker.onmessage = (event: MessageEvent<FromContainedWorker>) => { 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: FromContainedWorker): 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 later = (milliseconds = 0): Promise<void> => new Promise(resolve => setTimeout(resolve, milliseconds));
+
+const joined = async (world: CreatedWorld): Promise<Worker> => {
+    const { port1, port2 } = new MessageChannel();
+    world.share(port1);
+    const worker = start();
+    await worker.ask({ kind: "join", port: port2 }, [port2]);
+    for (let turn = 0; turn < 2000; turn++) {
+        let status = "";
+        world.threads(progress => { status = progress.at(-1)?.status ?? ""; })();
+        if (status === "joined") break;
+        await later();
+    }
+    return worker;
+};
+
+/**
+ * Whether `work` settled while the worker still held its run, which only this thread releases: true once it settles,
+ * and never for one waiting on the held worker, which times the test out.
+ */
+const settles = async (words: Int32Array, value: number, work: Promise<unknown>): Promise<boolean> => {
+    await work;
+    return Atomics.load(words, releasedWord) < value;
+};
+
+/** Resolves once the held run reached `value`. */
+const reached = async (words: Int32Array, value: number): Promise<void> => {
+    while (Atomics.load(words, reachedWord) < value) await later(1);
+};
+
+const release = (words: Int32Array, value: number): void => {
+    Atomics.store(words, releasedWord, value);
+    Atomics.notify(words, releasedWord);
+};
+
+/**
+ * What the worker saw once it's seen `count` values: a post no later sync point replaces runs however late the thread
+ * claims it, so this waits as long as that takes.
+ */
+const seenOnce = async (worker: Worker, count: number): Promise<readonly number[]> => {
+    for (;;) {
+        const reply = await worker.ask({ kind: "seen" });
+        const tallies = reply.kind === "seen" ? reply.tallies : [];
+        if (tallies.length >= count) {
+            // A few more turns, for a run that shouldn't come to show it didn't.
+            await later(50);
+            const again = await worker.ask({ kind: "seen" });
+            return again.kind === "seen" ? again.tallies : [];
+        }
+        await later(5);
+    }
+};
+
+/**
+ * Once the watcher ran for the tally's first value, 0, it holds its run of 1 while the world runs twice, changing
+ * nothing it filters on; released, what it saw. Then it holds its run of 2 while the world bumps the tally twice more;
+ * released, what it saw then. And whether the world's runs settled while it held each time.
+ */
+export const heldWhileTheWorldRuns = async () => {
+    const world = createWorld({ [workers]: 0 });
+    const worker = await joined(world);
+    const words = new Int32Array(new SharedArrayBuffer(gateWords * 4));
+    // Its first run, which passes its filter, before any is held: posted at the sync point of the worker's run, and run
+    // before the world's next, which would replace it unclaimed.
+    await worker.ask({ kind: "add", gate: words });
+    await seenOnce(worker, 1);
+    await world.run(setHolding, { holding: -1 });
+    await world.run(bump);
+    await reached(words, 1);
+    const quiet = await settles(words, 1, Promise.all([world.run(nothing), world.run(setHolding, { holding: -1 })]));
+    release(words, 1);
+    const first = await seenOnce(worker, 2);
+    await world.run(bump);
+    await reached(words, 2);
+    const bumped = await settles(words, 2, Promise.all([world.run(bump), world.run(bump)]));
+    // Through the newest: the run it holds, and the one after, which holds once it reached it.
+    release(words, 4);
+    const second = await seenOnce(worker, 4);
+    await world.dispose();
+    await worker.terminate();
+    return { quiet, first, bumped, second };
+};

package/src/implementation/world/observer-contained.test-helper.ts

@@ -0,0 +1,43 @@
+import { Resource } from "../../interface/resource/resource.js";
+import { System } from "../../interface/system/system.js";
+
+// Keys and systems both threads of the observer-contained fixtures import: a counter the world bumps, and an observer
+// system reading only resources that a joined thread adds, which can hold its run until the world's thread releases it.
+
+export const tally = Symbol("observerContainedTest/tally");
+export const holding = Symbol("observerContainedTest/holding");
+declare module "@adobe/ecs" {
+    export interface Resources {
+        [tally]: { type: number };
+        [holding]: { type: number };
+    }
+}
+Resource.register(tally, { type: { type: "integer", default: 0 } });
+/** While negative, each run of the watcher says it reached its value and waits until the world's thread releases it. */
+Resource.register(holding, { type: { type: "number", default: 0 } });
+
+/** Shared words: the value a held run reached, and the value the world's thread released runs through. */
+export const reachedWord = 0;
+export const releasedWord = 1;
+export const gateWords = 2;
+/** The joined thread's view of the gate, once the world's thread sent it. */
+export const gate: { words: Int32Array | null } = { words: null };
+
+/** What the watcher's runs saw, in order. */
+export const tallies: number[] = [];
+
+export const bump = System.create({ name: "observerContainedTest/bump", resources: { write: [tally] } }, ({ resources }) => { resources[tally] += 1; });
+export const nothing = System.create({ name: "observerContainedTest/nothing" }, () => {});
+export const setHolding = System.create({ name: "observerContainedTest/setHolding", input: { type: "object", properties: { holding: { type: "number" } } }, resources: { write: [holding] } }, ({ input, resources }) => {
+    resources[holding] = input.holding;
+});
+
+/** After each sync point that changed the tally: notes it, and, while `holding` says so, waits there to be released. */
+export const watchTally = System.create({ name: "observerContainedTest/watchTally", observer: true, resources: { read: [tally, holding], changed: [tally] } }, ({ resources }) => {
+    const value = resources[tally];
+    tallies.push(value);
+    const { words } = gate;
+    if (resources[holding] >= 0 || words === null) return;
+    Atomics.store(words, reachedWord, value);
+    for (let released = Atomics.load(words, releasedWord); released < value; released = Atomics.load(words, releasedWord)) Atomics.wait(words, releasedWord, released);
+});

package/src/implementation/world/observer-contained.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from "vitest";
+import { Resource, System, workers } from "../../index.js";
+import { createWorld, join } from "./create.js";
+
+// Observer systems reading only resources on a joined thread, whose posts hold copies of what they read, with the world
+// and the thread on this one, joined through a MessageChannel.
+
+const wide = Symbol("observerContainedTest/wide");
+const paused = Symbol("observerContainedTest/paused");
+const steps = Symbol("observerContainedTest/steps");
+declare module "@adobe/ecs" {
+    interface Resources {
+        [wide]: { type: readonly [number, number, number, number, number, number, number, number, number, number, number, number] };
+        [paused]: { type: boolean };
+        [steps]: { type: number };
+    }
+}
+/** Twelve f64s: more than a post's block holds, so its posts copy them into a snapshot of their own. */
+Resource.register(wide, { type: { type: "array", items: { type: "number" }, minItems: 12, maxItems: 12, default: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0] } });
+Resource.register(paused, { type: { type: "boolean", default: false } });
+Resource.register(steps, { type: { type: "number", default: 0 } });
+
+const widen = System.create({ name: "observerContainedTest/widen", resources: { write: [wide] } }, ({ resources }) => {
+    const first = resources[wide][0] + 1;
+    const base = first * 100;
+    resources[wide] = [base, base + 1, base + 2, base + 3, base + 4, base + 5, base + 6, base + 7, base + 8, base + 9, base + 10, base + 11];
+});
+const step = System.create({ name: "observerContainedTest/step", resources: { write: [steps] } }, ({ resources }) => { resources[steps] += 1; });
+const pause = System.create({ name: "observerContainedTest/pause", input: { type: "object", properties: { paused: { type: "boolean" } } }, resources: { write: [paused] } }, ({ input, resources }) => {
+    resources[paused] = input.paused;
+});
+
+const seen: { wide: number[][]; steps: number[] } = { wide: [], steps: [] };
+const watchWide = System.create({ name: "observerContainedTest/watchWide", observer: true, resources: { read: [wide], changed: [wide] } }, ({ resources }) => {
+    seen.wide.push([...resources[wide]]);
+});
+const watchSteps = System.create({ name: "observerContainedTest/watchSteps", observer: true, resources: { read: [steps], not: [paused], changed: [steps] } }, ({ resources }) => {
+    seen.steps.push(resources[steps]);
+});
+
+const settled = async (done: () => boolean): Promise<void> => {
+    for (let turn = 0; turn < 2000 && !done(); turn++) await new Promise(resolve => setTimeout(resolve, 0));
+};
+const turns = async (count = 20): Promise<void> => {
+    for (let turn = 0; turn < count; turn++) await new Promise(resolve => setTimeout(resolve, 0));
+};
+
+const joined = async () => {
+    const world = createWorld({ [workers]: 0 });
+    const channel = new MessageChannel();
+    world.share(channel.port1);
+    const remote = join(channel.port2, {});
+    for (let turn = 0; turn < 2000; turn++) {
+        let status = "";
+        world.threads(progress => { status = progress.at(-1)?.status ?? ""; })();
+        if (status === "joined") break;
+        await new Promise(resolve => setTimeout(resolve, 0));
+    }
+    await remote.run(System.create({ name: "observerContainedTest/nothing", observer: true }, () => {}));
+    return { world, remote, close: async () => { await remote.dispose(); await world.dispose(); } };
+};
+
+describe("observer systems reading only resources on a joined thread", () => {
+    it("read resources larger than their block holds from a snapshot of their own", async () => {
+        seen.wide.length = 0;
+        const { world, remote, close } = await joined();
+        remote.add(watchWide);
+        await turns();
+        await world.run(widen);
+        await settled(() => seen.wide.at(-1)?.[0] === 100);
+        await world.run(widen);
+        await settled(() => seen.wide.at(-1)?.[0] === 10100);
+        expect(seen.wide.at(-2)).toEqual(Array.from({ length: 12 }, (_, k) => 100 + k));
+        expect(seen.wide.at(-1)).toEqual(Array.from({ length: 12 }, (_, k) => 10100 + k));
+        await close();
+    });
+
+    it("run for the newest sync point only, which its conditions may not hold at", async () => {
+        seen.steps.length = 0;
+        const { world, remote, close } = await joined();
+        remote.add(watchSteps);
+        await turns();
+        await world.run(step);
+        await settled(() => seen.steps.length === 1);
+        // Behind, the thread runs nothing for the step: paused at the newest.
+        await Promise.all([world.run(step), world.run(pause, { paused: true })]);
+        await turns();
+        expect(seen.steps).toEqual([1]);
+        // Unpaused, the step it hasn't run passes its filter.
+        await world.run(pause, { paused: false });
+        await settled(() => seen.steps.length === 2);
+        await turns();
+        expect(seen.steps).toEqual([1, 2]);
+        await close();
+    });
+});