@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/world/reductions.ts

@@ -0,0 +1,105 @@
+import type { Reduction } from '../../interface/resource/reduction.js';
+import type { Declaration } from '../../interface/system/declaration.js';
+import { isReduction } from '../../interface/registry/reduction.js';
+import type { Layout, Path, View } from '../../interface/registry/layout.js';
+import { stampChanged } from './archetype.js';
+import { readCell, writeCell } from './cells.js';
+import { resourceCell } from './resources.js';
+import { idOf, type Key, type State } from './state.js';
+import { labelOf } from '../../interface/registry/index.js';
+
+/** A resource a system reduces into: its operator, and the scalar leaves of its value. */
+export type ReductionTarget = {
+    readonly key: Key;
+    readonly operator: Reduction;
+    readonly leaves: readonly { readonly path: Path; readonly view: View; readonly boolean: boolean }[];
+};
+
+const bitwise: ReadonlySet<Reduction> = new Set(["&", "|", "^"]);
+
+
+/**
+ * The resources a declaration reduces into, with their layouts' leaves. Creating the system checked each against its
+ * `reduce` trait, which registering the resource checked against its schema, so a throw here is an invariant broken.
+ */
+export const reductionTargets = (state: State, declaration: Pick<Declaration, "name" | "reduce">): readonly ReductionTarget[] =>
+    reductionTargetsOf(key => state.layouts[idOf(state, key)], declaration);
+
+/** The resources a declaration reduces into, by `layoutFor`, each resource's layout. */
+export const reductionTargetsOf = (layoutFor: (key: Key) => Layout | undefined, { name, reduce }: Pick<Declaration, "name" | "reduce">): readonly ReductionTarget[] => {
+    if (reduce === undefined) return [];
+    return Object.getOwnPropertySymbols(reduce).flatMap((key): ReductionTarget[] => {
+        const operator: unknown = Reflect.get(reduce, key);
+        if (operator === undefined) return [];
+        if (!isReduction(operator)) throw new Error(`System "${name}" reduces "${labelOf(key)}" with "${labelOf(operator)}", which isn't an operator.`);
+        const layout = layoutFor(key);
+        if (layout?.kind !== "linear") throw new Error(`System "${name}" reduces "${labelOf(key)}", which isn't stored in linear memory.`);
+        const leaves = layout.leaves.map(leaf => ({ path: leaf.path, view: leaf.view, boolean: leaf.scalar === "boolean" }));
+        if (leaves.some(leaf => leaf.boolean) && !bitwise.has(operator)) {
+            throw new Error(`System "${name}" reduces "${labelOf(key)}", which has boolean values, with "${operator}"; booleans reduce with "&", "|" or "^".`);
+        }
+        return [{ key, operator, leaves }];
+    });
+};
+
+/** Each operator's identity, as a fold starts from it, and what an empty fold gives. */
+export const identityOf = (operator: Reduction): number => {
+    switch (operator) {
+        case "+": case "|": case "^": return 0;
+        case "*": return 1;
+        case "&": return -1;
+        case "min": return Infinity;
+        case "max": return -Infinity;
+    }
+};
+
+/** One step of a fold, with JS semantics. Partials are f64; a result rounds or wraps once, when it's stored. */
+export const combine = (operator: Reduction, a: number, b: number): number => {
+    switch (operator) {
+        case "+": return a + b;
+        case "*": return a * b;
+        case "&": return a & b;
+        case "|": return a | b;
+        case "^": return a ^ b;
+        case "min": return Math.min(a, b);
+        case "max": return Math.max(a, b);
+    }
+};
+
+const integerRange: { readonly [V in View]?: readonly [number, number] } = {
+    u8: [0, 255], i32: [-(2 ** 31), 2 ** 31 - 1], u32: [0, 2 ** 32 - 1],
+};
+
+/** A folded leaf in its stored form: a boolean, or an empty `min` or `max` of integers as the type's own extreme. */
+const stored = (value: number, operator: Reduction, view: View, boolean: boolean): number | boolean => {
+    if (boolean) return (value & 1) !== 0;
+    const range = integerRange[view];
+    const empty = (operator === "min" && value === Infinity) || (operator === "max" && value === -Infinity);
+    return range !== undefined && empty ? (value > 0 ? range[1] : range[0]) : value;
+};
+
+const withLeaf = (value: unknown, path: Path, leaf: unknown): unknown => {
+    const [first, ...rest] = path;
+    if (first === undefined) return leaf;
+    const copy: unknown = Array.isArray(value) ? [...value] : { ...Object(value) };
+    Reflect.set(Object(copy), first, withLeaf(Reflect.get(Object(value), first), rest, leaf));
+    return copy;
+};
+
+const leafOf = (value: unknown, path: Path): unknown => path.reduce<unknown>((item, key) => Reflect.get(Object(item), key), value);
+
+/** The value a fold contributes to a leaf: booleans as 0 or 1. */
+export const contributed = (value: unknown, path: Path): number => Number(leafOf(value, path));
+
+/**
+ * Writes a target's folded leaves, `values[offset + i]` for leaf `i`, and stamps the resource changed at `tick` only
+ * if a stored leaf differs, so readers filtering on it run only when it does.
+ */
+export const writeReduction = (state: State, target: ReductionTarget, values: ArrayLike<number>, offset: number, tick: number): void => {
+    const { storage, row } = resourceCell(state, target.key);
+    const before = readCell(storage, row);
+    const next = target.leaves.reduce<unknown>((value, leaf, i) => withLeaf(value, leaf.path, stored(values[offset + i] ?? NaN, target.operator, leaf.view, leaf.boolean)), before);
+    writeCell(storage, row, next);
+    const after = readCell(storage, row);
+    if (target.leaves.some(leaf => !Object.is(leafOf(before, leaf.path), leafOf(after, leaf.path)))) stampChanged(storage, row, tick);
+};

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

@@ -0,0 +1,16 @@
+import { Component, System } from "../../index.js";
+
+// A module the identity example evaluates twice, as a dev server does after an edit.
+export const score = Symbol("reevaluation/score");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [score]: { type: number };
+    }
+}
+
+Component.register(score, { type: { type: "number" } });
+
+export const bump = System.create({ name: "reevaluation/bump", components: { write: [score] } }, row => {
+    row[score] += 1;
+});

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

@@ -0,0 +1,32 @@
+import { expect, it } from "vitest";
+import { System } from "../../index.js";
+import { Observe } from "../../observe/index.js";
+import { bump, score } from "./reevaluation.test-helper.js";
+import { createWorld } from "../index.js";
+import { runReported } from "./reports.test-helper.js";
+
+const spawn = System.create({ name: "reevaluation/spawn" }, ({ commands }) => { commands.spawn([score])({ [score]: 0 }); });
+
+// A name is a label, so other code may use it too: this isn't 20-score.ts's `bump`, and reports label the two apart.
+const broken = System.create({ name: "reevaluation/bump" }, () => {
+    throw new Error("offline");
+});
+
+it("labels systems that share a name by their ids", async () => {
+    await using world = createWorld();
+    const { failures } = await runReported(world, broken);
+    expect(failures.map(({ name }) => name)).toEqual(["reevaluation/bump (@adobe/ecs/src/implementation/world/reevaluation.test.ts#broken)"]);
+});
+
+it("matches the keys and systems of a module evaluated again by id", async () => {
+    await using world = createWorld();
+    await world.run(spawn);
+    await world.run(bump);
+    // A query makes the module evaluate again, under the same ids, as an edit on a dev server does.
+    const path = "./reevaluation.test-helper.js?again";
+    const again: typeof import("./reevaluation.test-helper.js") = await import(/* @vite-ignore */ path);
+    // Its key is the same component, and its system the same system, so a composite holds it once.
+    await world.run(System.create({ name: "reevaluation/both", systems: [bump, again.bump] }));
+    const [entity] = await Observe.toPromise(Observe.select(world, { required: [again.score] }));
+    expect((await Observe.toPromise(Observe.entity(world, entity, { required: [again.score] })))?.[again.score]).toBe(2);
+});

package/src/implementation/world/register.ts

@@ -0,0 +1,412 @@
+import type { Leaf } from '../../interface/system/leaf.js';
+import { idOfItem, idOfKey, labelOf, requireDefinition, threadOf, type Definition } from '../../interface/registry/index.js';
+import { createRemoteRunner, unplaceable } from './remote-systems.js';
+import { createJoinedObserverRunner, type ObserverTarget } from './joined-observer.js';
+import { createRunner, releaseHoldings, removedRunner, stopHoldings, type Holdings, type Runner } from './runner.js';
+import { isLeaf, reducedBy, scheduleOf, type Schedule } from '../../interface/registry/schedule.js';
+import { idOf, observe, unobserve, type Key, type State } from './state.js';
+import { labelOfItem, orderKeysOf } from '../../interface/registry/index.js';
+import { entityWatchesOf, indexWatchesOf, lookupComponentsOf, orderComponentsOf } from './lookup-keys.js';
+
+/** What a registration still has to do asynchronously: add resources, then load kernels; `rollback` undoes it if that fails. */
+/**
+ * `ticked`: components the new systems filter on or hold GPU copies of, which must keep ticks before they run;
+ * `resident`: those they hold GPU copies of.
+ */
+export type Registration = { readonly resources: readonly Key[]; readonly ticked: readonly number[]; readonly resident: readonly number[]; readonly kernels: readonly Runner[]; readonly rollback: () => void };
+
+export type Registrar = {
+    /** Validates and records a system with all its members. Throws without recording anything on failure. */
+    readonly register: (system: Definition) => Registration;
+    /** A registered system's schedule; undefined for one not registered, or holding a system forgotten since. */
+    readonly registered: (system: Definition) => Schedule | undefined;
+    /** A leaf's runner, or one that runs nothing for a leaf not registered, as a system removed during a run is. */
+    readonly runnerOf: (leaf: Leaf) => Runner;
+    /**
+     * Forgets systems, as removing them does: their schedules, and leaves' runners, which no run calls again once this
+     * returns. Returns what releases what the runners held, for once no run in progress uses them.
+     */
+    readonly forget: (systems: readonly Definition[]) => () => void;
+    /** Every system in a tree, the root included. */
+    readonly systemsOf: (root: Definition) => readonly Definition[];
+    /** A kernel runner's index, as workers know it. */
+    readonly kernelIndexOf: (runner: Runner) => number;
+    /** Every registered kernel runner. */
+    readonly kernels: () => readonly Runner[];
+    /** Rebuilds the runners of `kernel: "gpu"` systems for the world's current device, or for the CPU without one; returns them to load. */
+    readonly placeGpuKernels: () => readonly Runner[];
+    /**
+     * Why a joined thread that imported the systems of ids `imported` can't claim `threads`: a registered system on one
+     * it didn't import, or one without an id, or naming a key without one, or one that can't run on a joined thread;
+     * null when every one can run there.
+     */
+    readonly crossing: (threads: readonly string[], imported: ReadonlySet<string>) => string | null;
+    /** Places each registered system again, as claims were made or released: on its joined thread, or here. */
+    readonly place: () => void;
+    /**
+     * Registers a forgotten observer leaf again at once, with the runner it had, run again as a new runner would be:
+     * registering it before found every key and resource it names, so nothing is left to do asynchronously. False when
+     * it can't, as for one never registered, or whose runner a run in progress may still read as removed.
+     */
+    readonly reregister: (leaf: Leaf) => boolean;
+    /** For tests of what a world holds: how many schedules, runners and kernel indexes it keeps. */
+    readonly sizes: () => { readonly schedules: number; readonly runners: number; readonly kernels: number };
+};
+
+/** Every system in a tree, the root included. */
+const systemsOf = (root: Definition): Definition[] => {
+    const all = new Set<Definition>();
+    const visit = (system: Definition): void => {
+        if (all.has(system)) return;
+        all.add(system);
+        if (!isLeaf(system)) for (const member of system.declaration.systems) visit(requireDefinition(member));
+    };
+    visit(root);
+    return [...all];
+};
+
+/** Every component and resource a leaf names, so missing schemas throw at registration. */
+const keysOf = (leaf: Leaf): { readonly components: readonly Key[]; readonly resources: readonly Key[] } => {
+    const { components: access, lookup, resources } = leaf.declaration;
+    const components = [...access?.read ?? [], ...access?.write ?? [], ...access?.has ?? [], ...access?.not ?? [], ...access?.added ?? [], ...access?.changed ?? []];
+    for (const name in lookup) components.push(...lookupComponentsOf(lookup[name]));
+    const { up } = leaf.declaration;
+    if (up !== undefined) components.push(up.through, ...up.read ?? []);
+    components.push(...orderComponentsOf(leaf.declaration));
+    return { components, resources: [...resources?.read ?? [], ...resources?.write ?? [], ...resources?.changed ?? [], ...resources?.is ?? [], ...resources?.not ?? [], ...reducedBy(leaf)] };
+};
+
+/** For a filtered `up` leaf: its parent reference and what it reads of its parent, whose changes also pass a row. */
+const upObserved = (leaf: Leaf): readonly Key[] => {
+    const { components, resources, up } = leaf.declaration;
+    const filtered = (components?.added?.length ?? 0) + (components?.changed?.length ?? 0) + (resources?.changed?.length ?? 0) > 0;
+    return up === undefined || !filtered ? [] : [up.through, ...up.read ?? []];
+};
+
+/**
+ * The components whose changes a leaf's lookups report: the key parts of indexes it looks up through or orders by,
+ * and what its lookups watch.
+ */
+const lookupObserved = (leaf: Leaf): readonly Key[] => {
+    const ordered = orderKeysOf(leaf.declaration);
+    const looked = indexWatchesOf(leaf.declaration.lookup);
+    const watched = entityWatchesOf(leaf.declaration.lookup);
+    return ordered.length + watched.length === 0 ? looked : [...looked, ...watched, ...ordered];
+};
+
+/** The components a leaf needs ticks on: those it filters on, and those `upObserved` and `lookupObserved` give. */
+const tickedBy = (leaf: Leaf): readonly Key[] =>
+    [...leaf.declaration.components?.added ?? [], ...leaf.declaration.components?.changed ?? [], ...upObserved(leaf), ...lookupObserved(leaf)];
+
+/** The components whose GPU copies a leaf uses: a render system's accessors, and a GPU kernel's columns and what it reads through `up`. */
+const residentBy = (leaf: Leaf): readonly Key[] => {
+    const { declaration } = leaf;
+    if (leaf.kind === "render") return Object.values(declaration.shader?.accessors ?? {});
+    if (declaration.kernel !== "gpu") return [];
+    return [...declaration.components?.read ?? [], ...declaration.components?.write ?? [], ...declaration.up?.read ?? []];
+};
+
+/** The components whose `changed` stamps a leaf reads, so kernels writing them must keep their stamps. */
+const observedBy = (leaf: Leaf): readonly Key[] => {
+    const indexed = lookupObserved(leaf);
+    const observed = [...leaf.declaration.components?.changed ?? [], ...upObserved(leaf)];
+    return indexed.length === 0 ? observed : [...new Set([...observed, ...indexed])];
+};
+
+/** Every key a leaf names, as `keysOf` gives them, flattened. */
+const allKeysOf = (leaf: Leaf): readonly Key[] => {
+    const { components, resources } = keysOf(leaf);
+    return [...components, ...resources];
+};
+
+/**
+ * The joined thread an observer leaf runs on: the one that added it, or the one filling its thread; undefined for one
+ * that runs here.
+ */
+const observerTargetOf = (state: State, leaf: Leaf): ObserverTarget | undefined => {
+    const { proxies, targets } = state.observer;
+    const target = proxies.get(leaf)?.target ?? (targets.size === 0 ? undefined : targets.get(threadOf(leaf.declaration, "System", leaf.name) ?? "world"));
+    return target === undefined || target.ended ? undefined : target;
+};
+
+/** A runner for a leaf where it runs now: on the joined thread filling its thread, or that added it, or here. */
+const placedRunner = (state: State, leaf: Leaf, since = 0): Runner => {
+    if (leaf.declaration.observer === true) {
+        const target = observerTargetOf(state, leaf);
+        return target === undefined ? createRunner(state, leaf, since) : createJoinedObserverRunner(state, leaf, target, since);
+    }
+    const thread = threadOf(leaf.declaration, "System", leaf.name);
+    const channel = thread === null ? undefined : state.threadTasks.get(thread);
+    return channel === undefined ? createRunner(state, leaf, since) : createRemoteRunner(state, leaf, channel, since);
+};
+
+/**
+ * A registered leaf, which lives only as long as its system: its system held weakly, what its runner holds, and the
+ * components whose changes it counts as watching.
+ */
+type Entry = { readonly leaf: WeakRef<Leaf>; holdings: Holdings; readonly observed: readonly number[]; released: boolean };
+
+/**
+ * What the finalization registry keeps of a system until it's collected, holding nothing of it: whether it's registered
+ * now, as one rolled back or forgotten isn't, and for a leaf its entry.
+ */
+type Registered = { entry: Entry | null; registered: boolean };
+
+/**
+ * What the registrar keeps of a system it registered, by the system: its record in the registry, its schedule, and the
+ * count of forgettings it was last found whole at. Kept across forgetting, so registering it again records nothing
+ * more. For a forgotten leaf whose runner registering it again runs again (`Runner.restart`), `parked` is its entry
+ * then, the runner kept as its leaf's, stopped: adding an observer system again costs no new runner.
+ */
+type Kept = { readonly held: Registered; schedule: Schedule | null; checked: number; parked: Entry | null };
+
+/**
+ * What a world keeps of each system it registered lives as long as the system's value: schedules and runners by
+ * system, held weakly, so a system nothing references any more is collected, and with it its runner, its command
+ * buffers and its `lastRun`. What a runner holds beyond its JS values is released once its system is collected.
+ */
+export const createRegistrar = (state: State): Registrar => {
+    const records = new WeakMap<Definition, Kept>();
+    const runners = new WeakMap<Leaf, Runner>();
+    /** Moves on whenever systems are forgotten, so a composite holding one is found to need registering again. */
+    let forgettings = 0;
+    /** Every registered leaf, for what goes over every runner: rare, at placements, device changes and kernel loads. */
+    const live = new Set<Entry>();
+    let scheduleCount = 0;
+
+    const release = (entry: Entry): void => {
+        if (entry.released) return;
+        entry.released = true;
+        live.delete(entry);
+        releaseHoldings(state, entry.holdings);
+        for (const id of entry.observed) unobserve(state, id);
+    };
+    /**
+     * Called once a registered system is collected, with its record: a leaf's entry, or null for a composite, and
+     * whether it's still registered, as a rolled-back one isn't, so no unregister token is kept per registration.
+     */
+    const collected = new FinalizationRegistry<Registered>(record => {
+        if (!record.registered) return;
+        record.registered = false;
+        scheduleCount--;
+        if (record.entry !== null) release(record.entry);
+    });
+
+    /** Each live leaf with its runner. */
+    const eachRunner = (visit: (leaf: Leaf, runner: Runner, entry: Entry) => void): void => {
+        for (const entry of live) {
+            const leaf = entry.leaf.deref();
+            const runner = leaf === undefined ? undefined : runners.get(leaf);
+            if (leaf !== undefined && runner !== undefined) visit(leaf, runner, entry);
+        }
+    };
+
+    /** Puts a new runner in an entry's place, releasing what the one it replaces held. */
+    const replace = (leaf: Leaf, entry: Entry, old: Runner, runner: Runner): void => {
+        runners.set(leaf, runner);
+        state.runnersVersion++;
+        releaseHoldings(state, old.holdings);
+        entry.holdings = runner.holdings;
+        if (runner.holdings.afterSync !== null) state.afterSync.add(runner.holdings.afterSync);
+    };
+
+    const register = (root: Definition): Registration => {
+        const added: { readonly system: Definition; readonly schedule: Schedule; readonly entry: Entry | null; readonly runner: Runner | null }[] = [];
+        const resources = new Set<Key>();
+        for (const system of systemsOf(root)) {
+            if (records.get(system)?.held.registered === true) continue;
+            const schedule = scheduleOf(system);
+            if (!isLeaf(system)) {
+                added.push({ system, schedule, entry: null, runner: null });
+                continue;
+            }
+            // Creating the system checked its declaration; registering it gives its keys ids in this world.
+            const keys = keysOf(system);
+            for (const key of keys.components) idOf(state, key);
+            for (const key of keys.resources) {
+                idOf(state, key);
+                resources.add(key);
+            }
+            const runner = parkedRunner(system) ?? placedRunner(state, system);
+            const entry: Entry = { leaf: new WeakRef(system), holdings: runner.holdings, observed: observedBy(system).map(key => idOf(state, key)), released: false };
+            added.push({ system, schedule, entry, runner });
+        }
+        let observing = false;
+        const kernels: Runner[] = [];
+        for (const { system, schedule, entry, runner } of added) {
+            const record = records.get(system);
+            if (record === undefined) {
+                const held: Registered = { entry, registered: true };
+                records.set(system, { held, schedule, checked: forgettings, parked: null });
+                collected.register(system, held);
+            }
+            else {
+                Object.assign(record.held, { entry, registered: true });
+                record.schedule = schedule;
+                record.checked = forgettings;
+                // Runs that read a removed runner for it read the new one.
+                if (runner !== null) state.runnersVersion++;
+            }
+            scheduleCount++;
+            if (runner === null || entry === null || !isLeaf(system)) continue;
+            runners.set(system, runner);
+            live.add(entry);
+            if (runner.holdings.afterSync !== null) state.afterSync.add(runner.holdings.afterSync);
+            if (runner.kernel !== null) kernels.push(runner);
+            for (const id of entry.observed) {
+                if (!state.observed.has(id)) observing = true;
+                observe(state, id);
+            }
+        }
+        // Lists of observer systems read before it registered, holding it as removed, read their runners again.
+        if (added.some(({ runner }) => runner !== null)) state.runnersVersion++;
+        // New `changed` filters observe more components, so kernels that muted their stamps must load again.
+        if (observing) eachRunner((_, runner) => { if (runner.kernel?.stale() === true && !kernels.includes(runner)) kernels.push(runner); });
+        const rollback = (): void => {
+            for (const { system, entry, runner } of added) {
+                const record = records.get(system);
+                if (record !== undefined) {
+                    Object.assign(record.held, { entry: null, registered: false });
+                    record.schedule = null;
+                }
+                scheduleCount--;
+                if (runner === null || entry === null || !isLeaf(system)) continue;
+                runners.delete(system);
+                release(entry);
+            }
+            state.runnersVersion++;
+        };
+        const resident = added.flatMap(({ system }) => isLeaf(system) ? residentBy(system).map(key => idOf(state, key)) : []);
+        const ticked = added.flatMap(({ system }) => isLeaf(system) ? tickedBy(system).map(key => idOf(state, key)) : []);
+        return { resources: [...resources], ticked: resident.length === 0 ? ticked : [...ticked, ...resident], resident, kernels, rollback };
+    };
+
+    /**
+     * A forgotten leaf's runner, run again as a new runner would be, where it would still run: here. Only once what it
+     * held was released, so no run in progress still reads it as removed.
+     */
+    const parkedRunner = (leaf: Leaf): Runner | null => {
+        const record = records.get(leaf);
+        const entry = record?.parked ?? null;
+        if (record === undefined || entry === null) return null;
+        record.parked = null;
+        const runner = runners.get(leaf);
+        if (runner === undefined || runner.restart === null || !entry.released || observerTargetOf(state, leaf) !== undefined) return null;
+        runner.restart(0);
+        return runner;
+    };
+
+    const reregister = (leaf: Leaf): boolean => {
+        const record = records.get(leaf);
+        const old = record?.parked ?? null;
+        if (record === undefined || old === null || record.held.registered) return false;
+        // Components it starts observing make kernels that muted their stamps load again, asynchronously.
+        for (const id of old.observed) if (!state.observed.has(id)) return false;
+        const runner = parkedRunner(leaf);
+        if (runner === null) return false;
+        const entry: Entry = { leaf: old.leaf, holdings: runner.holdings, observed: old.observed, released: false };
+        record.held.entry = entry;
+        record.held.registered = true;
+        record.schedule = scheduleOf(leaf);
+        record.checked = forgettings;
+        scheduleCount++;
+        live.add(entry);
+        for (const id of entry.observed) observe(state, id);
+        state.runnersVersion++;
+        return true;
+    };
+
+    const registered = (system: Definition): Schedule | undefined => {
+        const record = records.get(system);
+        if (record === undefined || !record.held.registered || record.schedule === null) return undefined;
+        if (record.checked !== forgettings) {
+            // A composite holding a system forgotten since registers again, its other members keeping their runners.
+            for (const tier of record.schedule.tiers) for (const leaf of tier) if (!runners.has(leaf)) return undefined;
+            record.checked = forgettings;
+        }
+        return record.schedule;
+    };
+
+    /** A leaf's runner; for one forgotten, as a removed system is, one that runs nothing: stopped, or `removedRunner`. */
+    const runnerOf = (leaf: Leaf): Runner => runners.get(leaf) ?? removedRunner;
+
+    const forget = (systems: readonly Definition[]): (() => void) => {
+        const stopped: Entry[] = [];
+        for (const system of systems) {
+            const record = records.get(system);
+            if (record === undefined || !record.held.registered) continue;
+            const { entry } = record.held;
+            Object.assign(record.held, { entry: null, registered: false });
+            record.schedule = null;
+            scheduleCount--;
+            if (entry === null || !isLeaf(system)) continue;
+            const runner = runners.get(system);
+            live.delete(entry);
+            // No run calls its body again from here, on any thread; what it holds goes once no run uses it.
+            stopHoldings(entry.holdings);
+            stopped.push(entry);
+            if (runner !== undefined && runner.restart !== null && runner.joined === null) record.parked = entry;
+            else runners.delete(system);
+        }
+        forgettings++;
+        state.runnersVersion++;
+        state.placement++;
+        return () => { for (const entry of stopped) release(entry); };
+    };
+
+    const kernels = (): readonly Runner[] => {
+        const found: Runner[] = [];
+        eachRunner((_, runner) => { if (runner.kernel !== null) found.push(runner); });
+        return found;
+    };
+
+    const placeGpuKernels = (): readonly Runner[] => {
+        const placed: Runner[] = [];
+        eachRunner((leaf, old, entry) => {
+            if (leaf.declaration.kernel !== "gpu") return;
+            const runner = createRunner(state, leaf);
+            replace(leaf, entry, old, runner);
+            placed.push(runner);
+        });
+        return placed;
+    };
+
+    const crossing = (threads: readonly string[], imported: ReadonlySet<string>): string | null => {
+        let problem: string | null = null;
+        eachRunner(leaf => {
+            if (problem !== null) return;
+            const thread = threadOf(leaf.declaration, "System", leaf.name);
+            if (thread === null || !threads.includes(thread)) return;
+            const label = labelOfItem(leaf);
+            const id = idOfItem(leaf);
+            if (id === undefined) problem = `System "${label}" runs on thread "${thread}" and has no id, so a joined thread can't run it; the build gives top-level systems one.`;
+            else if (!imported.has(id)) problem = `System "${label}" runs on thread "${thread}", which the joined thread claiming it never imported.`;
+            else {
+                const unnamed = allKeysOf(leaf).find(key => typeof key !== "symbol" || idOfKey(key) === undefined);
+                problem = unnamed !== undefined
+                    ? `System "${label}" runs on thread "${thread}" and names "${labelOf(unnamed)}", which has no id, so a joined thread can't name it; the build gives top-level keys one.`
+                    : unplaceable(leaf, thread);
+            }
+        });
+        return problem;
+    };
+
+    const place = (): void => {
+        eachRunner((leaf, old, entry) => {
+            if (leaf.declaration.observer === true) {
+                if (observerTargetOf(state, leaf) === old.joined?.target) return;
+                replace(leaf, entry, old, placedRunner(state, leaf, old.lastRun()));
+                return;
+            }
+            const thread = threadOf(leaf.declaration, "System", leaf.name);
+            const channel = thread === null ? undefined : state.threadTasks.get(thread);
+            if (channel === undefined ? old.remote === null : old.remote?.channel === channel) return;
+            replace(leaf, entry, old, placedRunner(state, leaf, old.lastRun()));
+        });
+        state.placement++;
+    };
+
+    const sizes = () => ({ schedules: scheduleCount, runners: live.size, kernels: state.kernelIndexes.size });
+
+    return { register, registered, runnerOf, forget, reregister, systemsOf, kernelIndexOf: runner => runner.kernel?.index ?? -1, kernels, placeGpuKernels, crossing, place, sizes };
+};

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

@@ -0,0 +1,44 @@
+import type { MessagePort as NodeMessagePort } from "node:worker_threads";
+import { join } from "./create.js";
+import { scopeChannel } from "./port.js";
+import { entitled, released, type Released } from "./remote-finalizers.test-helper.js";
+
+/**
+ * A thread joining a world through the port it's sent, claiming "remoteFinalizersTest", whose finalizer it imports: it
+ * tells what its finalizers saw when asked, or spins, without yielding, for a while or for good.
+ */
+
+type Port = MessagePort | NodeMessagePort;
+export type ToRemoteFinalizersWorker =
+    | { readonly kind: "join"; readonly port: Port }
+    | { readonly kind: "released" }
+    | { readonly kind: "entitled" }
+    | { readonly kind: "pause"; readonly milliseconds: number }
+    | { readonly kind: "spin" };
+export type FromRemoteFinalizersWorker =
+    | { readonly kind: "joined" }
+    | { readonly kind: "released"; readonly released: readonly Released[] }
+    | { readonly kind: "entitled"; readonly entitled: readonly { readonly serial: number; readonly title: string }[] }
+    | { readonly kind: "spinning" };
+
+const channel = scopeChannel<FromRemoteFinalizersWorker, ToRemoteFinalizersWorker>();
+channel.onMessage(message => {
+    if ("protocol" in message) return;
+    if (message.kind === "join") {
+        join(message.port, { threads: ["remoteFinalizersTest"] });
+        channel.post({ kind: "joined" });
+    }
+    else if (message.kind === "released") channel.post({ kind: "released", released });
+    else if (message.kind === "entitled") channel.post({ kind: "entitled", entitled });
+    else if (message.kind === "pause") {
+        channel.post({ kind: "spinning" });
+        // Runs nothing meanwhile, finalizers included, then goes on.
+        const until = performance.now() + message.milliseconds;
+        while (performance.now() < until) { /* busy */ }
+    }
+    else {
+        channel.post({ kind: "spinning" });
+        // Never yields again, from before the world stops anything, so nothing here runs: no finalizer, no acknowledgement.
+        for (;;) { /* never yields */ }
+    }
+});

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

@@ -0,0 +1,24 @@
+import { describe, expect, it } from "vitest";
+import type * as Fixture from "./remote-finalizers.fixture.js";
+
+/** Finalizers on a joined worker: the cases, over the fixture built for node or from source. */
+export const remoteFinalizersCases = (load: () => Promise<typeof Fixture>) => describe("finalizers on a joined worker", () => {
+    it("run once per stop there, as an inline world's do, with its objects and the structs before each sync point applied", async () => {
+        const fixture = await load();
+        const { expected, actual } = await fixture.sameStops();
+        expect(actual.counts).toEqual(expected.counts);
+        expect(actual.stops).toEqual(expected.stops);
+    }, 30000);
+    it("hold the indexes of entities they stopped until the worker finalizes them, which it never does once it's ended: they're reused, its stops reported", async () => {
+        const fixture = await load();
+        expect(await fixture.diesHolding()).toEqual({
+            held: 3, whileHeld: 0,
+            failures: [["thread", "remoteFinalizersTest/release", 'Thread "remoteFinalizersTest" is gone, so 3 stops of finalizer "remoteFinalizersTest/release" didn\'t run there.']],
+            after: 3,
+        });
+    }, 30000);
+    it("read the strings their stops held, which the stop lists copy, after the world freed and reused their records", async () => {
+        const fixture = await load();
+        expect(await fixture.titledStops()).toEqual(Array.from({ length: 50 }, (_, k) => ({ serial: k, title: `t${k}` })));
+    }, 30000);
+});