@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/world/tail-blocks.ts

@@ -0,0 +1,74 @@
+import { lineWords } from './protocol.js';
+
+// What the world's thread and a joined thread share to run a tail (threads.md, "Tails"): a block per tail system, of
+// three lines of words, and the snapshot the world copies its reads into when a writer is ready before it finished.
+//
+// A tail's work is numbered: position 0 is its head, which checks its conditions and resolves its resources, and
+// positions from 1 are the rows of its matched archetypes in order. The tail claims positions in chunks by adding to
+// its progress word; the world exchanges that word for `snapshotted` once it copied the passing rows from the position
+// it read, so a claim that returns `snapshotted` or more reads the rest from the copy.
+
+/** The positions the tail claimed, which it adds to and the world exchanges; and the end of its work, 1 plus its rows. */
+export const progressWord = 0;
+export const endWord = 1;
+/** The position the tail finished reading through, which it stores after each chunk; whether the world waits for it. */
+export const doneWord = lineWords;
+export const waitingWord = lineWords + 1;
+/** The snapshot: its offset, rows, the position it starts from, and its head's flags (`ranFlag`, `executedFlag`). */
+export const snapshotOffsetWord = 2 * lineWords;
+export const snapshotRowsWord = 2 * lineWords + 1;
+export const snapshotStartWord = 2 * lineWords + 2;
+export const snapshotFlagsWord = 2 * lineWords + 3;
+/** Where the resource entity was as of the tail's sync, for its objects there: its archetype and row. */
+export const snapshotResourceArchetypeWord = 2 * lineWords + 4;
+export const snapshotResourceRowWord = 2 * lineWords + 5;
+/** The rows the snapshot is laid out for, at least its rows. */
+export const snapshotCapacityWord = 2 * lineWords + 6;
+export const tailBlockWords = 3 * lineWords;
+export const tailBlockBytes = tailBlockWords * 4;
+
+/** What the progress word holds once the world copied the rest: claims add to it and stay past it. */
+export const snapshotted = 0x40000000;
+/** Positions a claim takes: the most the world waits for once a writer is ready. */
+export const tailChunk = 64;
+
+/** The snapshot's head flags: its conditions held, and it ran its rows or its body. */
+export const headExecuted = 1;
+export const headRan = 2;
+
+const align = (bytes: number): number => (bytes + 7) & ~7;
+
+/**
+ * Where a snapshot of `rows` rows keeps each column, past its offset, each on 8 bytes: every row's position,
+ * archetype and row (u32), entity (f64), then each linear component read of `strides` bytes, then each linear resource
+ * read's value of `resourceStrides` bytes; and its bytes in all.
+ */
+export type SnapshotLayout = {
+    readonly positions: number;
+    readonly archetypes: number;
+    readonly rows: number;
+    readonly entities: number;
+    readonly columns: readonly number[];
+    readonly resources: readonly number[];
+    readonly bytes: number;
+};
+
+export const snapshotLayout = (rows: number, strides: readonly number[], resourceStrides: readonly number[]): SnapshotLayout => {
+    const words = align(4 * rows);
+    const positions = 0;
+    const archetypes = words;
+    const rowsAt = 2 * words;
+    const entities = 3 * words;
+    let at = entities + 8 * rows;
+    const columns: number[] = [];
+    for (const stride of strides) {
+        columns.push(at);
+        at += align(stride * rows);
+    }
+    const resources: number[] = [];
+    for (const stride of resourceStrides) {
+        resources.push(at);
+        at += align(stride);
+    }
+    return { positions, archetypes, rows: rowsAt, entities, columns, resources, bytes: Math.max(at, 8) };
+};

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

@@ -0,0 +1,66 @@
+import type { MessagePort as NodeMessagePort } from "node:worker_threads";
+import { requireDefinition } from "../../interface/registry/index.js";
+import { workers } from "../../interface/resources/workers.js";
+import { createWorld, join } from "./create.js";
+import { scopeChannel } from "./port.js";
+import { changed, gate, seed, seen, tailSystems, ticked, type Seen } from "./tails.test-helper.js";
+import { tailSnapshots } from "./thread-systems.js";
+import { reportOf, runReported } from "./reports.test-helper.js";
+
+/**
+ * A thread joining a world through the port it's sent, claiming "tailsTest", whose systems it imports: it tells what
+ * its tails saw, and how often they read from a snapshot, when asked. Or one holding both a world and the thread
+ * joining it, which leaves while two runs of its tails are queued: it tells what each reported, once both settled and
+ * the world placed the tails here again.
+ */
+
+type Port = MessagePort | NodeMessagePort;
+export type ToTailsWorker = { readonly kind: "join"; readonly port: Port } | { readonly kind: "seen" } | { readonly kind: "leave queued" } | { readonly kind: "gate"; readonly words: Int32Array };
+export type FromTailsWorker =
+    | { readonly kind: "joined" }
+    | { readonly kind: "gated" }
+    | { readonly kind: "left"; readonly skipped: readonly (readonly string[])[]; readonly after: number }
+    | { readonly kind: "seen"; readonly seen: readonly Seen[]; readonly changed: readonly (readonly [number, number])[]; readonly late: number; readonly switched: number };
+
+const channel = scopeChannel<FromTailsWorker, ToTailsWorker>();
+/**
+ * The world and the joined thread on this one: the thread leaves while two runs are queued, so the second posts its
+ * tails to a thread already gone. Then a run waits for every tail in flight, as the world placing them here again does.
+ */
+const leaveQueued = async (): Promise<FromTailsWorker> => {
+    const world = createWorld({ [workers]: 0 });
+    const { port1, port2 } = new MessageChannel();
+    world.share(port1);
+    const remote = join(port2, { threads: ["tailsTest"] });
+    await new Promise<void>(resolve => {
+        const stop = world.threads(threads => {
+            if (threads[0]?.status !== "joined") return;
+            queueMicrotask(() => stop());
+            resolve();
+        });
+    });
+    await world.run(seed, { count: 10 });
+    await world.run(ticked);
+    const leaving = remote.dispose();
+    const runs = [world.run(ticked), world.run(ticked)];
+    const reports = await Promise.all((await Promise.all(runs)).map(run => reportOf(world, run)));
+    await leaving;
+    const after = await runReported(world, ticked);
+    await world.dispose();
+    return { kind: "left", skipped: reports.map(report => report.skipped), after: after.failures.length };
+};
+
+channel.onMessage(async message => {
+    if ("protocol" in message) return;
+    if (message.kind === "leave queued") channel.post(await leaveQueued());
+    else if (message.kind === "join") {
+        for (const system of tailSystems) requireDefinition(system);
+        join(message.port, { threads: ["tailsTest"] });
+        channel.post({ kind: "joined" });
+    }
+    else if (message.kind === "gate") {
+        gate.words = message.words;
+        channel.post({ kind: "gated" });
+    }
+    else channel.post({ kind: "seen", seen, changed: [...changed], late: tailSnapshots.late, switched: tailSnapshots.switched });
+});

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

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import type * as Fixture from "./tails.fixture.js";
+
+/** Tails on a joined worker: the cases, over the fixture built for node or from source. */
+export const tailsCases = (load: () => Promise<typeof Fixture>) => describe("tails on a joined worker", () => {
+    it("see one tick's values in every run while the world ticks on: in place, from a snapshot when late, and both across a switch at a chunk", async () => {
+        const fixture = await load();
+        const seen = await fixture.continuous();
+        expect({ wrong: seen.wrong, labels: seen.labels, fewest: seen.fewest, most: seen.most }).toEqual({ wrong: 0, labels: 0, fewest: 1000, most: 1000 });
+        expect(seen.late).toBeGreaterThan(0);
+        expect(seen.switched).toBeGreaterThan(0);
+    }, 30000);
+    it("see one tick's values in every run, never from a snapshot, when writers wait for them instead", async () => {
+        const fixture = await load();
+        const seen = await fixture.waiting();
+        expect({ wrong: seen.wrong, labels: seen.labels, fewest: seen.fewest, most: seen.most, late: seen.late, switched: seen.switched }).toEqual({ wrong: 0, labels: 0, fewest: 1000, most: 1000, late: 0, switched: 0 });
+    }, 30000);
+    it("never snapshot when prompt", async () => {
+        const fixture = await load();
+        const seen = await fixture.prompt();
+        expect({ runs: seen.runs, wrong: seen.wrong, labels: seen.labels, late: seen.late, switched: seen.switched }).toEqual({ runs: 30, wrong: 0, labels: 0, late: 0, switched: 0 });
+    }, 30000);
+    it("read a snapshot taken before a sync point grows what they read, what they write from it stamped as changed", async () => {
+        const fixture = await load();
+        const seen = await fixture.growing();
+        expect({ wrong: seen.wrong, labels: seen.labels, fewest: seen.fewest, most: seen.most, uncounted: seen.uncounted }).toEqual({ wrong: 0, labels: 0, fewest: 1000, most: 21000, uncounted: 0 });
+        expect(seen.late).toBeGreaterThan(0);
+        expect(seen.counted).toBeGreaterThan(10);
+    }, 30000);
+    it("read the strings of their tick when runs after it would free and reuse their records, since those runs wait for them", async () => {
+        const fixture = await load();
+        const seen = await fixture.spanning();
+        expect({ runs: seen.runs, wrong: seen.wrong, fewest: seen.fewest, most: seen.most }).toEqual({ runs: 1, wrong: 0, fewest: 1000, most: 1000 });
+    }, 30000);
+    it("aren't waited for by a sync point when they read only their thread's objects", async () => {
+        const fixture = await load();
+        expect(await fixture.heldBody()).toBe(true);
+    }, 30000);
+    it("are skipped in every run queued when their thread left, and nothing waits for a tail on a thread that's gone", async () => {
+        const fixture = await load();
+        const skipped = ["tailsTest/lead", "tailsTest/watch"];
+        expect(await fixture.leaveQueued()).toEqual({ skipped: [skipped, skipped], after: 0 });
+    }, 30000);
+});

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

@@ -0,0 +1,254 @@
+/// <reference types="node" />
+import { Observe } from "../../observe/index.js";
+import { always } from "../../interface/resources/always.js";
+import { workers } from "../../interface/resources/workers.js";
+import type { World } from "../../interface/world/world.js";
+import { createWorld, type CreatedWorld } from "./create.js";
+import { backToBack } from "./loop.js";
+import { tailWriters } from "./tails.js";
+import type { FromTailsWorker, ToTailsWorker } from "./tails-worker.fixture.js";
+import { counter, heldTick, noStall, reword, seed, setSpawning, setStall, stallAtChunk, stallBefore, tallied, ticked } from "./tails.test-helper.js";
+
+/**
+ * Scenarios of tails on a joined worker, run built in node and from source in chromium: a terminal system there over
+ * every row while the world ticks on, reading them where they are, from a snapshot when it's late, or both across a
+ * switch at a chunk; a prompt one that never needs a snapshot; and a sync point growing what a late one reads.
+ */
+
+type Worker = { readonly ask: (message: ToTailsWorker, transfer?: readonly unknown[]) => Promise<FromTailsWorker>; readonly terminate: () => Promise<void> };
+
+const workerFile = "./tails-worker.fixture.js";
+
+const start = (): Worker => {
+    if (typeof globalThis.Worker === "function") {
+        const worker = new globalThis.Worker(new URL("./tails-worker.fixture.js", import.meta.url), { type: "module" });
+        return {
+            ask: (message, transfer = []) => new Promise(resolve => {
+                worker.onmessage = (event: MessageEvent<FromTailsWorker>) => { 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: FromTailsWorker): void => {
+                if ("protocol" in data) return;
+                worker.off("message", reply);
+                resolve(data);
+            };
+            worker.on("message", reply);
+            worker.postMessage(message, transfer.filter(port => port instanceof threads.MessagePort));
+        }),
+        terminate: async () => { await worker.terminate(); },
+    };
+};
+
+const until = <T>(observe: Observe<T>, accept: (value: T) => boolean): Promise<T> => new Promise(resolve => {
+    let done = false;
+    const stop = observe(value => {
+        if (done || !accept(value)) return;
+        done = true;
+        queueMicrotask(() => stop());
+        resolve(value);
+    });
+});
+
+const 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 };
+};
+
+/** Ticks on until the counter passed `ticks` more. */
+const ticks = async (world: World, more: number): Promise<void> => {
+    const now = await until(Observe.resource(world, counter), () => true);
+    await until(Observe.resource(world, counter), value => value >= now + more);
+};
+
+/** What the worker's tails saw: their runs, those that saw another tick's structs or labels, the fewest rows, and snapshots. */
+const summary = async (worker: Worker) => {
+    const reply = await worker.ask({ kind: "seen" });
+    if (reply.kind !== "seen") throw new Error("tails: the worker didn't say what it saw.");
+    const { seen } = reply;
+    return {
+        runs: seen.length,
+        wrong: seen.reduce((sum, run) => sum + run.wrong, 0),
+        labels: seen.reduce((sum, run) => sum + run.labels, 0),
+        fewest: Math.min(...seen.map(run => run.rows)),
+        most: Math.max(...seen.map(run => run.rows)),
+        late: reply.late,
+        switched: reply.switched,
+        // Each run of `tally` after the first counts every row the watcher wrote the tick before.
+        uncounted: reply.changed.filter(([value, rows]) => value > 2 && rows !== seen.find(run => run.counter === value - 1)?.rows).length,
+        counted: reply.changed.length,
+    };
+};
+
+const within = <T>(promise: Promise<T>, milliseconds: number, otherwise: T): Promise<T> =>
+    Promise.race([promise, new Promise<T>(resolve => setTimeout(() => resolve(otherwise), milliseconds))]);
+
+/**
+ * A world and its joined thread on the worker, the thread leaving with two runs of its tails queued: what they
+ * reported, or null when the worker never answered, as when its world waits forever for a gone thread's tail.
+ */
+export const leaveQueued = async () => {
+    const worker = start();
+    const reply = await within(worker.ask({ kind: "leave queued" }), 20000, null);
+    await worker.terminate();
+    return reply !== null && reply.kind === "left" ? { skipped: reply.skipped, after: reply.after } : null;
+};
+
+/** 1,000 rows while the world ticks back to back: prompt, then stalling at the end of a chunk, then late. */
+export const continuous = async () => {
+    const driver = backToBack();
+    const world = createWorld({ [workers]: 0, [always]: true }, { loop: driver });
+    const { worker } = await joined(world);
+    await world.run(seed, { count: 1000 });
+    world.add(ticked);
+    await ticks(world, 30);
+    await world.run(setStall, { mode: stallAtChunk, pause: 3 });
+    await ticks(world, 30);
+    await world.run(setStall, { mode: stallBefore, pause: 3 });
+    await ticks(world, 30);
+    await world.run(setStall, { mode: noStall, pause: 0 });
+    await ticks(world, 10);
+    await world.dispose();
+    const seen = await summary(worker);
+    await worker.terminate();
+    driver.close();
+    return seen;
+};
+
+/** As `continuous`, with writers waiting until each tail is done rather than copying what it hasn't read. */
+export const waiting = async () => {
+    tailWriters.wait = true;
+    try {
+        return await continuous();
+    }
+    finally {
+        tailWriters.wait = false;
+    }
+};
+
+/**
+ * Frames the caller gives one at a time: `next` resolves once the loop asked for its next beat and runs it, so a tick
+ * starts only when the caller says, however slowly the machine runs.
+ */
+const gatedFrames = () => {
+    let pending: ((time: number) => void) | null = null;
+    let requested: (() => void) | null = null;
+    return {
+        frame: (callback: (time: number) => void): (() => void) => {
+            pending = callback;
+            requested?.();
+            requested = null;
+            return () => {
+                if (pending === callback) pending = null;
+            };
+        },
+        next: async (): Promise<void> => {
+            if (pending === null) await new Promise<void>(resolve => { requested = resolve; });
+            const callback = pending;
+            pending = null;
+            callback?.(performance.now());
+        },
+    };
+};
+
+/** Asks what the worker's tails saw until the watcher's run for `value` read every one of `rows` rows. */
+const watched = async (worker: Worker, value: number, rows: number): Promise<void> => {
+    for (;;) {
+        const reply = await worker.ask({ kind: "seen" });
+        if (reply.kind === "seen" && reply.seen.some(run => run.counter === value && run.rows === rows)) return;
+    }
+};
+
+/**
+ * 1,000 rows, each tick starting only once the last one's tail on the worker read them all: the tail finished before
+ * the next tick writes, however slowly either thread runs.
+ */
+export const prompt = async () => {
+    const frames = gatedFrames();
+    const world = createWorld({ [workers]: 0, [always]: true }, { loop: frames });
+    const { worker } = await joined(world);
+    await world.run(seed, { count: 1000 });
+    world.add(ticked);
+    for (let tick = 1; tick <= 30; tick++) {
+        await frames.next();
+        await until(Observe.resource(world, counter), value => value >= tick);
+        await watched(worker, tick, 1000);
+    }
+    await world.dispose();
+    const seen = await summary(worker);
+    await worker.terminate();
+    return seen;
+};
+
+/** A late tail while a sync point spawns 20,000 rows into the archetype it reads, growing it and the move log. */
+export const growing = async () => {
+    const driver = backToBack();
+    const world = createWorld({ [workers]: 0, [always]: true }, { loop: driver });
+    const { worker } = await joined(world);
+    await world.run(seed, { count: 1000 });
+    await world.run(setStall, { mode: stallBefore, pause: 3 });
+    world.add(tallied);
+    await ticks(world, 5);
+    await world.run(setSpawning, { count: 20000 });
+    await ticks(world, 10);
+    await world.run(setStall, { mode: noStall, pause: 0 });
+    await ticks(world, 5);
+    await world.dispose();
+    const seen = await summary(worker);
+    await worker.terminate();
+    driver.close();
+    return seen;
+};
+
+/**
+ * A tail stalled before it reads the words of its tick while the world's runs rewrite every word six times, which
+ * would free and reuse the records it reads were the runs not to wait for it.
+ */
+export const spanning = async () => {
+    const frames = gatedFrames();
+    const world = createWorld({ [workers]: 0, [always]: true }, { loop: frames });
+    const { worker } = await joined(world);
+    await world.run(seed, { count: 1000 });
+    await world.run(setStall, { mode: stallBefore, pause: 200 });
+    world.add(ticked);
+    await frames.next();
+    await until(Observe.resource(world, counter), value => value >= 1);
+    for (let round = 0; round < 6; round++) await world.run(reword, { round });
+    await watched(worker, 1, 1000);
+    await world.dispose();
+    const seen = await summary(worker);
+    await worker.terminate();
+    return seen;
+};
+
+/**
+ * A tail reading only its thread's objects, held in its body, while a run spawns rows: whether the run finished before
+ * the tail was let go, as its sync point writes nothing the tail reads.
+ */
+export const heldBody = async (): Promise<boolean> => {
+    const frames = gatedFrames();
+    const world = createWorld({ [workers]: 0, [always]: true }, { loop: frames });
+    const { worker } = await joined(world);
+    const words = new Int32Array(new SharedArrayBuffer(8));
+    await worker.ask({ kind: "gate", words });
+    await world.run(seed, { count: 10 });
+    world.add(heldTick);
+    await frames.next();
+    while (Atomics.load(words, 1) === 0) await new Promise(resolve => setTimeout(resolve, 1));
+    const ran = await within(world.run(seed, { count: 10 }).then(() => true), 5000, false);
+    Atomics.store(words, 0, 1);
+    Atomics.notify(words, 0);
+    await world.dispose();
+    await worker.terminate();
+    return ran;
+};

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

@@ -0,0 +1,166 @@
+import { Component } from "../../interface/component/component.js";
+import { Resource } from "../../interface/resource/resource.js";
+import { System } from "../../interface/system/system.js";
+
+// Keys and systems both threads of the tails fixtures import: a world system writing every row's stamp each tick, and
+// terminal systems on thread "tailsTest", which a joined thread fills, running there as tails.
+
+export const stamp = Symbol("tailsTest/stamp");
+export const spot = Symbol("tailsTest/spot");
+export const label = Symbol("tailsTest/label");
+export const counter = Symbol("tailsTest/counter");
+export const stall = Symbol("tailsTest/stall");
+export const spawning = Symbol("tailsTest/spawning");
+export const failAt = Symbol("tailsTest/failAt");
+export const canvas = Symbol("tailsTest/canvas");
+export const word = Symbol("tailsTest/word");
+declare module "@adobe/ecs" {
+    export interface Threads {
+        tailsTest: true;
+    }
+    export interface Components {
+        [stamp]: { type: number };
+        [spot]: { type: readonly [number, number, number] };
+        [label]: { type: { readonly text: string } | null; thread: "tailsTest" };
+        [word]: { type: string };
+    }
+    export interface Resources {
+        [counter]: { type: number };
+        [stall]: { type: { readonly mode: number; readonly pause: number } };
+        [spawning]: { type: number };
+        [failAt]: { type: number };
+        [canvas]: { type: { readonly text: string }; thread: "tailsTest" };
+    }
+}
+Component.register(stamp, { type: { type: "integer" } });
+Component.register(spot, { type: { type: "array", items: { type: "number", precision: 1 }, minItems: 3, maxItems: 3 } });
+/** An object of the tail's thread, which the tail writes. */
+const text = { type: "object", properties: { text: { type: "string" } } } as const;
+Component.register(label, { type: { anyOf: [text, { type: "null" }], default: null }, thread: "tailsTest" });
+/** A string the world writes each tick, which lives in shared memory where the tail reads it. */
+Component.register(word, { type: { type: "string" } });
+Resource.register(counter, { type: { type: "integer", default: 0 } });
+/**
+ * How the tails stall, for milliseconds `pause`: `"none"`, `"chunk"` in the watcher at the end of its first chunk, so
+ * a writer is ready mid-way, or `"before"` in a tail ahead of it, so the watcher is late.
+ */
+Resource.register(stall, {
+    type: { type: "object", properties: { mode: { type: "integer" }, pause: { type: "number" } }, required: ["mode", "pause"], default: { mode: 0, pause: 0 } },
+});
+Resource.register(spawning, { type: { type: "integer", default: 0 } });
+Resource.register(failAt, { type: { type: "integer", default: -1 } });
+/** An object resource of the tail's thread, which places the systems reading it there. */
+Resource.register(canvas, { type: { ...text, default: { text: "canvas" } }, thread: "tailsTest" });
+
+export const noStall = 0;
+export const stallAtChunk = 1;
+export const stallBefore = 2;
+
+const spin = (milliseconds: number): void => {
+    const until = performance.now() + milliseconds;
+    while (performance.now() < until);
+};
+
+/** On the world's thread: the counter moves on once a tick. */
+export const count = System.create({ name: "tailsTest/count", resources: { write: [counter] } }, ({ resources }) => {
+    resources[counter] += 1;
+});
+/** A tick's word, of a length that varies with it, so records of every size are freed and reused. */
+export const wordOf = (value: number): string => `${"·".repeat(value % 37)}${value}`;
+
+/** On the world's thread: every row's stamp, spot and word take the counter. */
+export const advance = System.create({ name: "tailsTest/advance", components: { write: [stamp, spot, word] }, resources: { read: [counter] }, after: [count] }, (row, { resources }) => {
+    const value = resources[counter];
+    row[stamp] = value;
+    row[spot] = [value, -value, value];
+    row[word] = wordOf(value);
+});
+/** On the world's thread: every row's word as another, of the size of the first ticks', so their records are reused. */
+export const reword = System.create({ name: "tailsTest/reword", input: { type: "object", properties: { round: { type: "integer" } } }, components: { write: [word] } }, (row, { input }) => {
+    row[word] = `r${input.round}`;
+});
+/** On the world's thread: spawns rows stamped with this tick's counter, `spawning` of them, then no more. */
+export const grow = System.create({ name: "tailsTest/grow", resources: { read: [counter], write: [spawning] }, after: [count] }, ({ resources, commands }) => {
+    const value = resources[counter];
+    for (let k = 0; k < resources[spawning]; k++) commands.spawn([stamp, spot, label, word])({ [stamp]: value, [spot]: [value, -value, value], [word]: wordOf(value) });
+    resources[spawning] = 0;
+});
+/** Spawns `count` rows. */
+export const seed = System.create({ name: "tailsTest/seed", input: { type: "object", properties: { count: { type: "integer" } } } }, ({ input, commands }) => {
+    for (let k = 0; k < input.count; k++) commands.spawn([stamp, spot, label, word])({ [stamp]: 0, [spot]: [0, 0, 0], [word]: wordOf(0) });
+});
+export const setStall = System.create({ name: "tailsTest/setStall", input: { type: "object", properties: { mode: { type: "integer" }, pause: { type: "number" } } }, resources: { write: [stall] } }, ({ input, resources }) => {
+    resources[stall] = { mode: input.mode, pause: input.pause };
+});
+export const setSpawning = System.create({ name: "tailsTest/setSpawning", input: { type: "object", properties: { count: { type: "integer" } } }, resources: { write: [spawning] } }, ({ input, resources }) => {
+    resources[spawning] = input.count;
+});
+export const setFailAt = System.create({ name: "tailsTest/setFailAt", input: { type: "object", properties: { at: { type: "integer" } } }, resources: { write: [failAt] } }, ({ input, resources }) => {
+    resources[failAt] = input.at;
+});
+
+/** What each run of the watcher saw, by the counter it read: rows, and those whose structs, word or label weren't that tick's. */
+export type Seen = { counter: number; rows: number; wrong: number; labels: number };
+export const seen: Seen[] = [];
+
+/** On the tail's thread, ahead of the watcher: stalls it while `stall` says so, so it's late. */
+export const lead = System.create({ name: "tailsTest/lead", resources: { read: [stall, canvas] } }, ({ resources }) => {
+    if (resources[stall].mode === stallBefore && resources[canvas].text === "canvas") spin(resources[stall].pause);
+});
+
+/**
+ * A tail on thread "tailsTest": reads every row's structs, which must all be of one tick, and writes its label, which
+ * must be the last tick's where it wrote one.
+ */
+export const watch = System.create({
+    name: "tailsTest/watch", components: { read: [stamp, spot, word], write: [label] }, resources: { read: [counter, stall, failAt] }, after: [advance, grow, lead],
+}, (row, { resources }) => {
+    const value = resources[counter];
+    let last = seen.at(-1);
+    if (last === undefined || last.counter !== value) seen.push(last = { counter: value, rows: 0, wrong: 0, labels: 0 });
+    if (resources[failAt] === value) throw new Error(`tailsTest failure at ${value}`);
+    const [x, y, z] = row[spot];
+    if (row[stamp] !== value || x !== value || y !== -value || z !== value || row[word] !== wordOf(value)) last.wrong++;
+    const previous = row[label]?.text ?? null;
+    if (previous !== null && previous !== String(value - 1) && previous !== String(value)) last.labels++;
+    row[label] = { text: String(value) };
+    last.rows++;
+    if (last.rows === 63 && resources[stall].mode === stallAtChunk) spin(resources[stall].pause);
+});
+
+/** Not terminal: it reaches its commands, so its tier blocks. */
+export const blocking = System.create({ name: "tailsTest/blocking", components: { read: [label] } }, (row, { commands }) => {
+    if (row[label]?.text === "never") commands.despawn(row.entity);
+});
+
+/** By counter, rows whose label changed since `tally` last ran. */
+export const changed = new Map<number, number>();
+/**
+ * On the tail's thread, ahead of the watcher, reaching its commands, so its tier blocks: counts the labels the watcher
+ * wrote since it last ran, which it sees once the world stamped them, from the watcher's snapshot too.
+ */
+export const tally = System.create({ name: "tailsTest/tally", components: { read: [label], changed: [label] }, resources: { read: [counter] }, after: [count], before: [watch] }, (row, { resources, commands }) => {
+    if (row[label]?.text === "never") commands.despawn(row.entity);
+    changed.set(resources[counter], (changed.get(resources[counter]) ?? 0) + 1);
+});
+
+/** The words a held tail and the world share, once the world gives them: the gate opens at [0], the tail is held at [1]. */
+export const gate: { words: Int32Array | null } = { words: null };
+
+/** On the tail's thread, terminal, reading only that thread's objects: held in its body until the world opens the gate. */
+export const held = System.create({ name: "tailsTest/held", resources: { read: [canvas] } }, ({ resources }) => {
+    const { words } = gate;
+    if (words === null || resources[canvas].text !== "canvas") return;
+    Atomics.store(words, 1, 1);
+    Atomics.notify(words, 1);
+    Atomics.wait(words, 0, 0);
+});
+export const heldTick = System.create({ name: "tailsTest/heldTick", systems: [held] });
+
+/** Every tick: the world's systems, then the tails. */
+export const ticked = System.create({ name: "tailsTest/ticked", systems: [count, advance, grow, lead, watch] });
+/** The same, with `tally` counting what the watcher wrote. */
+export const tallied = System.create({ name: "tailsTest/tallied", systems: [count, advance, grow, lead, tally, watch] });
+
+/** Every system the joined thread runs, which it imports so the world can place them there. */
+export const tailSystems: readonly System<void>[] = [ticked, tallied, blocking, heldTick];