@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/compiler/transform.ts

@@ -0,0 +1,239 @@
+import type { Node, ObjectExpression, Program, SimpleCallExpression } from 'estree';
+import { compileKernel, type CompiledKernel } from './compile-kernel.js';
+import { children, isFunction } from './estree.js';
+import { fail, failureOf, type Failure } from './failure.js';
+import { isPending, type Link, type Linker } from './link.js';
+import { createModule, locateIn, type Module } from './module-scope.js';
+import { attachKernelPath, prepareLookupPath, prepareSpawnPath } from './paths.js';
+import { spawnSites } from './spawns.js';
+import { kernelOf } from './signature.js';
+import { usedBy } from './body-access.js';
+import { requireExact } from './exact.js';
+import { createLists } from './lists.js';
+import { neverReachesCommands } from './terminal.js';
+import { lookupSites } from './lookups.js';
+import { terminalBodiesName } from '../world/terminal.js';
+
+export type Parse = (code: string) => Program;
+/** Whether an import specifier, resolved from the module being transformed, is the package's, which exports `System` and `Finalizer`. */
+export type ResolveSystemImport = (source: string) => Promise<boolean>;
+/**
+ * The JS expression for kernel `index`'s module url. `identity` is everything the description and module are
+ * compiled to (the description without its url, plus the module source), so it can version the url.
+ */
+export type KernelUrl = (index: number, identity: string) => string;
+/**
+ * `kernels[i]` is the source of kernel `i`'s module, which exports `create`. `dependencies` are the other files
+ * whose functions and constants the kernels inline, or that compiling them read before failing.
+ */
+export type TransformResult =
+    | { readonly code: string; readonly kernels: readonly string[]; readonly dependencies: readonly string[] }
+    | { readonly failure: Failure; readonly dependencies: readonly string[] };
+
+type Edit = { readonly start: number; readonly end: number; readonly text: string };
+
+/** The local names of the package's `System` and `Finalizer` namespaces, by the namespace each names. */
+const systemLocals = async (program: Program, resolveSystemImport: ResolveSystemImport): Promise<ReadonlyMap<string, "System" | "Finalizer">> => {
+    const locals = new Map<string, "System" | "Finalizer">();
+    for (const statement of program.body) {
+        if (statement.type !== "ImportDeclaration" || typeof statement.source.value !== "string") continue;
+        const specifiers = statement.specifiers.flatMap(specifier => specifier.type === "ImportSpecifier" && specifier.imported.type === "Identifier"
+            && (specifier.imported.name === "System" || specifier.imported.name === "Finalizer") ? [{ local: specifier.local.name, imported: specifier.imported.name }] : []);
+        if (specifiers.length > 0 && await resolveSystemImport(statement.source.value)) {
+            for (const { local, imported } of specifiers) locals.set(local, imported === "System" ? "System" : "Finalizer");
+        }
+    }
+    return locals;
+};
+
+type Created = "system" | "finalizer" | "changes";
+
+/** `System.create`, or `Finalizer.create` or `Finalizer.changes`, whose bodies run on the main thread; null for any other call. */
+const createdBy = (node: SimpleCallExpression, locals: ReadonlyMap<string, "System" | "Finalizer">): Created | null => {
+    if (node.callee.type !== "MemberExpression" || node.callee.computed || node.callee.object.type !== "Identifier" || node.callee.property.type !== "Identifier") return null;
+    const namespace = locals.get(node.callee.object.name);
+    const method = node.callee.property.name;
+    if (namespace === "System") return method === "create" ? "system" : null;
+    return namespace === "Finalizer" && (method === "create" || method === "changes") ? (method === "create" ? "finalizer" : "changes") : null;
+};
+
+/** Which parameters are the row and the context: a system without `components` takes only its context, and a changes finalizer takes its changes first. */
+const positionsOf = (created: Created, declaration: ObjectExpression): { readonly row: number; readonly context: number } => {
+    if (created === "changes") return { row: -1, context: 1 };
+    const rowed = declaration.properties.some(property =>
+        property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === "components");
+    return rowed ? { row: 0, context: 1 } : { row: -1, context: 0 };
+};
+
+/**
+ * A spawn site's function: the components, then one parameter per value, so values pass without an object to a
+ * spawner generated for the site's key order and the list's shape (`PreparedSpawn` in `world/prepared-spawn.ts`).
+ * The keys are read in module scope, as the prepared spawn's argument, so no binding the function declares can capture
+ * one (`hygiene.test.ts`).
+ */
+const spawnFunction = (name: string, prepare: string, keys: readonly string[]): string => {
+    const values = keys.map((_, k) => `v${k}`).join(", ");
+    return [
+        `const ${name} = (p => (c, l${keys.length > 0 ? `, ${values}` : ""}) => {`,
+        "const s = p.begin(c, l);",
+        `return s === null ? p.fallback(c, l, [${values}]) : s(${values});`,
+        `})(${prepare}(() => [${keys.join(", ")}]));`,
+    ].join("\n");
+};
+
+/**
+ * An add site's function: the entity, the components, then one parameter per value, each appended straight to the
+ * commands' buffer (`PreparedAdd` in `world/prepared-spawn.ts`). Its keys are read in module scope, as a spawn site's are.
+ */
+const addFunction = (name: string, prepare: string, keys: readonly string[]): string => {
+    const values = keys.map((_, k) => `v${k}`);
+    return [
+        `const ${name} = (p => (c, e, l${values.map(value => `, ${value}`).join("")}) => {`,
+        `if (p.begin(c, e, l)) { ${values.map((value, k) => `p.value(${k}, ${value}); `).join("")}p.end(); }`,
+        `else p.fallback(c, e, l, [${values.join(", ")}]);`,
+        `})(${prepare}(() => [${keys.join(", ")}]));`,
+    ].join("\n");
+};
+
+const uniqueName = (code: string, base: string): string => {
+    let name = base;
+    for (let n = 1; code.includes(name); n++) name = `${base}${n}`;
+    return name;
+};
+
+/** Compiles a kernel, loading what it imports as compiling reaches it. */
+const compileLinked = async (declaration: ObjectExpression, body: Node, module: Module, target: "cpu" | "gpu", link: Link | null): Promise<CompiledKernel> => {
+    for (;;) {
+        try {
+            return compileKernel(declaration, body, module, target, link);
+        } catch (error) {
+            if (!isPending(error)) throw error;
+            await error.pending;
+        }
+    }
+};
+
+type KernelSite = { readonly node: SimpleCallExpression; readonly declaration: ObjectExpression; readonly body: Node; readonly target: "cpu" | "gpu" };
+
+/**
+ * Wraps each kernel `System.create(declaration, body)` call as `attachKernel(call, description)`, and returns each
+ * kernel's `create` as its own module, referenced by `description.url`. Functions and constants kernels import are
+ * inlined through `linker`.
+ * Also passes the values of main-thread spawns and adds of literal keys positionally (`spawns.ts`).
+ * Returns null when the module has neither, and a `Failure` when a kernel leaves the subset.
+ */
+export const transformKernels = async (
+    code: string, id: string, parse: Parse, resolveSystemImport: ResolveSystemImport, kernelUrl: KernelUrl, linker?: Linker,
+): Promise<TransformResult | null> => {
+    if ((!code.includes("System") && !code.includes("Finalizer")) || id.includes("\0")) return null;
+    const program = parse(code);
+    const locals = await systemLocals(program, resolveSystemImport);
+    if (locals.size === 0) return null;
+    const file = id.split("?")[0] ?? id;
+    const module = createModule(file, program, locateIn(code));
+    linker?.add(module);
+    const dependencies = new Set<string>();
+    /** Main-thread declarations are checked only against lists of their own module. */
+    const mainThreadLists = createLists(module, null, []);
+    const link: Link | null = linker === undefined ? null : {
+        module: dependency => {
+            if (dependency !== file) dependencies.add(dependency);
+            return linker.module(dependency);
+        },
+        resolve: linker.resolve,
+    };
+    const attach = uniqueName(code, "attachKernel$");
+    const prepare = uniqueName(code, "prepareSpawn$");
+    const prepareAddName = uniqueName(code, "prepareAdd$");
+    const spawnName = uniqueName(code, "spawn$");
+    const terminal = uniqueName(code, "terminal$");
+    const prepareLookupName = uniqueName(code, "prepareLookup$");
+    const lookupName = uniqueName(code, "lookup$");
+    let looking = false;
+    let terminals = false;
+    const edits: Edit[] = [];
+    const kernels: string[] = [];
+    const sites: KernelSite[] = [];
+    /** Module-scope declarations of prepared spawns, appended after everything they name is declared. */
+    const prepared: string[] = [];
+    let adding = false;
+    let spawning = false;
+    const visit = (node: Node, nested: boolean): void => {
+        const created = node.type === "CallExpression" ? createdBy(node, locals) : null;
+        const [first, second] = node.type === "CallExpression" ? node.arguments : [];
+        // One argument that isn't a body makes a composite, of a list or a declaration: never a kernel, nor checked.
+        const composite = created === "system" && first !== undefined && second === undefined && !isFunction(first);
+        if (node.type === "CallExpression" && created !== null && !composite) {
+            // A system that declares nothing is made from its body alone, which takes only its context.
+            const alone = created === "system" && first !== undefined && isFunction(first) && second === undefined;
+            const declaration = alone ? undefined : first;
+            const body = alone ? first : second;
+            const target = declaration?.type === "ObjectExpression" ? kernelOf(declaration) : null;
+            if (declaration?.type === "ObjectExpression" && target !== null) {
+                if (nested) fail(node, "kernel systems must be declared at module scope");
+                if (body === undefined || body.type === "SpreadElement") return fail(node, "a kernel needs an inline body");
+                sites.push({ node, declaration, body, target });
+                return;
+            }
+            const positions = alone ? { row: -1, context: 0 } : declaration?.type === "ObjectExpression" ? positionsOf(created, declaration) : null;
+            if (declaration?.type === "ObjectExpression" && positions !== null && body !== undefined && body.type !== "SpreadElement") {
+                requireExact(declaration, usedBy(declaration, body, module.bindings, positions), module.bindings, mainThreadLists);
+            }
+            // A system whose body never reaches its commands is terminal where its declaration allows (`world/tails.ts`).
+            if (created === "system" && positions !== null && body !== undefined && body.type !== "SpreadElement" && neverReachesCommands(body, positions.context)) {
+                terminals = true;
+                edits.push({ start: body.start, end: body.start, text: `${terminal}(` }, { start: body.end, end: body.end, text: ")" });
+            }
+            const spawns = positions === null || body === undefined || body.type === "SpreadElement" ? null : spawnSites(body, module.bindings, positions.context);
+            // Index lookups pass their key positionally, through a list of their own (`world/prepared-lookup.ts`).
+            const lookups = positions === null || body === undefined || body.type === "SpreadElement" || declaration?.type !== "ObjectExpression" ? [] : lookupSites(body, declaration, positions.context);
+            const spawned = spawns?.sites ?? [];
+            for (const site of lookups) {
+                if (spawned.some(other => other.start < site.end && site.start < other.end)) continue;
+                const name = `${lookupName}${prepared.length}`;
+                prepared.push(`const ${name} = ${prepareLookupName}(${JSON.stringify(site.shape)}).find;`);
+                looking = true;
+                const values = [site.callee, ...site.values].map(value => code.slice(value.start, value.end));
+                edits.push({ start: site.start, end: site.end, text: `${name}(${values.join(", ")})` });
+            }
+            if (spawns !== null && spawns.sites.length > 0) {
+                for (const site of spawns.sites) {
+                    const name = `${spawnName}${prepared.length}`;
+                    prepared.push(site.kind === "spawn" ? spawnFunction(name, prepare, site.keys) : addFunction(name, prepareAddName, site.keys));
+                    if (site.kind === "add") adding = true;
+                    else spawning = true;
+                    const values = [...site.entity === null ? [] : [site.entity], site.components, ...site.values].map(value => code.slice(value.start, value.end));
+                    edits.push({ start: site.start, end: site.end, text: `${name}(${[spawns.commands, ...values].join(", ")})` });
+                }
+                return;
+            }
+        }
+        const inner = nested || isFunction(node);
+        for (const child of children(node)) visit(child, inner);
+    };
+    try {
+        visit(program, false);
+        for (const { node, declaration, body, target } of sites) {
+            const compiled = await compileLinked(declaration, body, module, target, link);
+            const source = `export const create = ${compiled.create};\n`;
+            const description = compiled.description(kernelUrl(kernels.length, `${compiled.description("")}\n${source}`));
+            kernels.push(source);
+            edits.push({ start: node.start, end: node.end, text: `${attach}(${code.slice(node.start, node.end)}, ${description})` });
+        }
+    } catch (error) {
+        const failure = failureOf(error);
+        if (failure === undefined) throw error;
+        return { failure, dependencies: [...dependencies] };
+    }
+    if (edits.length === 0) return null;
+    let result = code;
+    for (const edit of [...edits].sort((a, b) => b.start - a.start)) result = result.slice(0, edit.start) + edit.text + result.slice(edit.end);
+    const imports = [
+        ...kernels.length > 0 ? [`import { attachKernel as ${attach} } from ${JSON.stringify(attachKernelPath)};`] : [],
+        ...spawning ? [`import { prepareSpawn as ${prepare} } from ${JSON.stringify(prepareSpawnPath)};`] : [],
+        ...adding ? [`import { prepareAdd as ${prepareAddName} } from ${JSON.stringify(prepareSpawnPath)};`] : [],
+        ...looking ? [`import { prepareLookup as ${prepareLookupName} } from ${JSON.stringify(prepareLookupPath)};`] : [],
+    ];
+    const marking = terminals ? [`function ${terminal}(body) { const set = Symbol.for(${JSON.stringify(terminalBodiesName)}); (globalThis[set] || (globalThis[set] = new WeakSet())).add(body); return body; }`] : [];
+    return { code: [...imports, result, ...prepared, ...marking].join("\n"), kernels, dependencies: [...dependencies] };
+};

package/src/implementation/compiler/unit.ts

@@ -0,0 +1,114 @@
+import type { Node } from 'estree';
+import type { Expression } from './ir.js';
+import type { Link } from './link.js';
+import type { Lists } from './lists.js';
+import type { Module } from './module-scope.js';
+import type { Out } from './out.js';
+import type { Scope } from './scope.js';
+import type { Signature } from './signature.js';
+import type { Value } from './value.js';
+
+export type ExpressionCompiler = (node: Node, scope: Scope, out: Out) => Value;
+export type StatementCompiler = (node: Node, scope: Scope, out: Out) => void;
+
+/**
+ * State for compiling one kernel. Compilers are injected so expression, call and statement modules
+ * don't import each other.
+ */
+export type Unit = {
+    readonly signature: Signature;
+    /** The module being transformed. */
+    readonly module: Module;
+    /** The kernel's lists of keys, wherever they are declared. */
+    readonly lists: Lists;
+    /** Other modules, for functions and constants the kernel imports. */
+    readonly link: Link | null;
+    /** GPU kernels emit intrinsic regions for calls to functions that match WGSL builtins. */
+    readonly target: "cpu" | "gpu";
+    /** Column descriptions as source text, in `columns` order, indexed by an identity key. */
+    readonly columns: string[];
+    readonly columnIndex: Map<string, number>;
+    /** Chunk columns: dense, indexed by `i >> chunkShift` rather than a strided row index. */
+    readonly chunks: Set<number>;
+    /** Chunk columns stamped once per call before the row loop, so their per-row stamps are dropped. */
+    readonly stampedPerCall: Set<number>;
+    /** Columns read where a boolean's identity is observable, so they need conversion. */
+    readonly booleans: Set<number>;
+    /** Every value assigned to each local, to propagate observation. */
+    readonly assignments: Map<number, Expression[]>;
+    /** Locals whose value reaches an observable position. */
+    readonly observed: Set<number>;
+    /** Source names of locals, for readable JS. */
+    readonly names: Map<number, string>;
+    /** Shape descriptions as source text. */
+    readonly shapes: Set<string>;
+    /** The shapes of values contributed to reductions, as source text. */
+    readonly reducedShapes: Set<string>;
+    readonly keys: string[];
+    /** The components a command or spawn gives a tuple or struct, by name. */
+    readonly structuredValues: Set<string>;
+    /** Each list the kernel spawns, as indexes into `keys`, listed once. */
+    readonly spawns: (readonly number[])[];
+    /** Each leaf a reduction folds into: its resource (an index into `Signature.reduced`), path and accumulator local. */
+    readonly accumulators: { readonly reduced: number; readonly path: readonly (number | string)[]; readonly local: number }[];
+    /** The components, resources and lookup results the body reads and writes, to check the declaration lists only those. */
+    readonly used: { readonly read: Set<string>; readonly write: Set<string>; readonly resources: Set<string>; readonly lookups: Map<string, Set<string>>; readonly up: Set<string> };
+    /** The local holding `up`, set once per call: non-null when the rows of the call have a parent. */
+    readonly up: number | null;
+    /** Columns of the parent's components that `up` reads, as source text, indexed by an identity key. */
+    readonly upColumns: string[];
+    readonly upColumnIndex: Map<string, number>;
+    /** Parent columns read where a boolean's identity is observable. */
+    readonly upBooleans: Set<number>;
+    /** Each call site of a lookup through an index, as `KernelDescription.probes` lists it, as source text. */
+    readonly probes: string[];
+    /** The row leaves bodies read, as `KernelDescription.rowLeaves` lists them, by `JSON.stringify` of each. */
+    readonly rowLeaves: string[];
+    /** Locals holding lists and rows of lookups through indexes, which are handles each kernel instance makes once. */
+    readonly handles: Set<number>;
+    /** Helpers and constants being inlined, to reject recursion. */
+    readonly active: Set<string>;
+    readonly next: () => number;
+    readonly expression: ExpressionCompiler;
+    readonly statement: StatementCompiler;
+};
+
+export const createUnit = (signature: Signature, module: Module, lists: Lists, expression: ExpressionCompiler, statement: StatementCompiler, link: Link | null = null, target: "cpu" | "gpu" = "cpu"): Unit => {
+    let counter = 0;
+    const names = new Map<number, string>();
+    const up = signature.up === null ? null : counter++;
+    if (up !== null) names.set(up, "up");
+    return {
+        signature, module, lists, link, target, columns: [], columnIndex: new Map(), chunks: new Set(), stampedPerCall: new Set(), booleans: new Set(), assignments: new Map(), observed: new Set(), names, shapes: new Set(), reducedShapes: new Set(), keys: [], structuredValues: new Set(), spawns: [], accumulators: [], active: new Set(),
+        used: { read: new Set(), write: new Set(), resources: new Set(), lookups: new Map(), up: new Set() },
+        up, upColumns: [], upColumnIndex: new Map(), upBooleans: new Set(), probes: [], rowLeaves: [], handles: new Set(),
+        next: () => counter++, expression, statement,
+    };
+};
+
+/** A fresh local, printed as `hint_n` so it never collides with fixed generated names. */
+export const fresh = (unit: Unit, hint: string): number => {
+    const local = unit.next();
+    unit.names.set(local, hint);
+    return local;
+};
+
+/** A fresh block or loop label. */
+export const label = (unit: Unit): number => unit.next();
+
+/** The `keys` index for a component named in a command. */
+export const keyIndex = (unit: Unit, name: string): number => {
+    const index = unit.keys.indexOf(name);
+    if (index >= 0) return index;
+    unit.keys.push(name);
+    return unit.keys.length - 1;
+};
+
+/** The `spawns` index for a list of components a kernel spawns. */
+export const spawnIndex = (unit: Unit, names: readonly string[]): number => {
+    const keys = names.map(name => keyIndex(unit, name));
+    const index = unit.spawns.findIndex(list => list.length === keys.length && list.every((key, k) => key === keys[k]));
+    if (index >= 0) return index;
+    unit.spawns.push(keys);
+    return unit.spawns.length - 1;
+};

package/src/implementation/compiler/value.ts

@@ -0,0 +1,60 @@
+import type { BlockStatement, Expression as SourceExpression, Pattern } from 'estree';
+import type { Path, Program } from '../world/kernel.js';
+import type { Expression } from './ir.js';
+import type { Module } from './module-scope.js';
+import type { Snapshot } from './snapshot.js';
+
+/**
+ * A compile-time value. `scalar` and `dynamic` hold an expression; `dynamic` is a plain JS value
+ * (resource, `args`, lookup element) that may be indexed at runtime. Tuples and structs are scalarized.
+ * `component` is an unread `row[component]` reference; `snapshot` is a local copy of one, read lazily per leaf.
+ */
+export type Value =
+    | { readonly kind: "scalar"; readonly expression: Expression }
+    | { readonly kind: "dynamic"; readonly expression: Expression }
+    | { readonly kind: "tuple"; readonly items: readonly Value[] }
+    | { readonly kind: "struct"; readonly fields: readonly (readonly [string, Value])[] }
+    /** With `up`, a component of the row's parent, read through `up`. */
+    | { readonly kind: "component"; readonly component: string; readonly path: Path; readonly up?: true }
+    | { readonly kind: "snapshot"; readonly snapshot: Snapshot; readonly path: Path }
+    | { readonly kind: "found"; readonly lookup: number; readonly expression: Expression }
+    | { readonly kind: "lookup"; readonly lookup: number }
+    /**
+     * What a call of a lookup through an index gave: its list, in local `list`, and its first row, in local `first`, which
+     * a unique index's result is read as.
+     */
+    | { readonly kind: "indexed"; readonly lookup: number; readonly list: number; readonly first: number }
+    /** A list's `at`, which takes a row's position. */
+    | { readonly kind: "listAt"; readonly lookup: number; readonly list: number }
+    /** A row a lookup through an index gave, in local `row`, and a component of it, `read` an index into the lookup's read, at `path`. */
+    | { readonly kind: "indexRow"; readonly lookup: number; readonly row: number }
+    | { readonly kind: "rowRead"; readonly lookup: number; readonly row: number; readonly read: number; readonly path: Path }
+    /** A resource the kernel reduces into, by its index in `Signature.reduced`. */
+    | { readonly kind: "reducer"; readonly reduced: number }
+    /**
+     * A helper, compiled in its own module. `identity` is unique per definition; `name` is for messages. `intrinsic` is
+     * the WGSL builtin it matches, if its module declares one.
+     */
+    | { readonly kind: "function"; readonly name: string; readonly identity: string; readonly params: readonly Pattern[]; readonly body: BlockStatement | SourceExpression; readonly module: Module; readonly intrinsic?: Program.Intrinsic }
+    /** A module namespace, such as `Vec3`, at its file. */
+    | { readonly kind: "namespace"; readonly file: string }
+    | { readonly kind: "method"; readonly owner: "math" | "commands"; readonly name: string }
+    | { readonly kind: "row" }
+    | { readonly kind: "context" }
+    /** The context's `resources`, `lookup` and `reduce`. */
+    | { readonly kind: "resources" }
+    | { readonly kind: "lookups" }
+    | { readonly kind: "reducers" }
+    | { readonly kind: "commands" }
+    | { readonly kind: "math" };
+
+export const scalarValue = (expression: Expression): Value => ({ kind: "scalar", expression });
+
+const describe: { readonly [K in Value["kind"]]: string } = {
+    scalar: "a number", dynamic: "a value", tuple: "a tuple", struct: "a struct", component: "a component value",
+    snapshot: "a component value", found: "a lookup result", lookup: "a lookup", indexed: "a lookup's list", listAt: "a list's at", indexRow: "a lookup's row", rowRead: "a value of a lookup's row", reducer: "a reduction", function: "a helper",
+    method: "a method", row: "row", context: "the context", resources: "the resources", lookups: "the lookups", reducers: "the reductions", commands: "commands", math: "Math", namespace: "a namespace",
+};
+
+/** A short description of a value's kind, for error messages. */
+export const describeValue = (value: Value): string => describe[value.kind];

package/src/implementation/index.ts

@@ -0,0 +1,2 @@
+export { create, createWorld, join, type CreatedWorld, type WorldOptions } from './world/create.js';
+export { backToBack } from './world/loop.js';

package/src/implementation/world/activate.ts

@@ -0,0 +1,127 @@
+import type { Finalizer } from '../../interface/finalizer/created.js';
+import type { Rule } from '../../interface/rule/created.js';
+import type { RuleFacts } from '../../interface/registry/strata.js';
+import { createFinalizerRunner, placeFinalizer, type FinalizerRunner } from './finalizers.js';
+import { finalizerKeysOf, type TaskChannel } from './remote-systems.js';
+import { programFinalizers, programRules, programVersion } from '../../interface/registry/program.js';
+import { triggersOf } from './program.js';
+import { ensureResources, findResource } from './resources.js';
+import { idOf, metIdOf, type Key, type State } from './state.js';
+import { restratify } from './structure.js';
+import { idOfItem, idOfKey, labelOf, labelOfItem, threadOf } from '../../interface/registry/index.js';
+
+/**
+ * Why a joined thread that imported the items of ids `imported` can't claim `threads`: a program finalizer on one that
+ * it never imported, or that has no id or names a key without one, so it can't name it; null when none.
+ */
+export const finalizerCrossing = (threads: readonly string[], imported: ReadonlySet<string>): string | null => {
+    for (const finalizer of programFinalizers()) {
+        if (finalizer.kind !== "finalizer") continue;
+        const thread = threadOf(finalizer.declaration, "Finalizer", finalizer.name);
+        if (thread === null || !threads.includes(thread)) continue;
+        const label = labelOfItem(finalizer);
+        const id = idOfItem(finalizer);
+        if (id === undefined) return `Finalizer "${label}" runs on thread "${thread}" and has no id, so a joined thread can't run it; the build gives top-level finalizers one.`;
+        if (!imported.has(id)) return `Finalizer "${label}" runs on thread "${thread}", which the joined thread claiming it never imported.`;
+        const unnamed = finalizerKeysOf(finalizer).find(key => idOfKey(key) === undefined);
+        if (unnamed !== undefined) return `Finalizer "${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.`;
+    }
+    return null;
+};
+
+/** The channel of the joined thread a finalizer runs on, or null for the world's thread. */
+const channelOf = (state: State, finalizer: Finalizer): TaskChannel | null => {
+    if (!state.claimed || finalizer.kind !== "finalizer") return null;
+    const thread = threadOf(finalizer.declaration, "Finalizer", finalizer.name);
+    const channel = thread === null ? undefined : state.threadTasks.get(thread);
+    return channel === undefined || channel.gone() ? null : channel;
+};
+
+/**
+ * Places a runner on its joined thread, or here: false when that thread can't name it, which the next sync point
+ * reports once.
+ */
+const placed = (state: State, runner: FinalizerRunner): boolean => {
+    try {
+        placeFinalizer(state, runner, channelOf(state, runner.finalizer));
+        return true;
+    }
+    catch (error) {
+        if (!state.unplacedSeen.has(runner.finalizer)) {
+            state.unplacedSeen.add(runner.finalizer);
+            state.unplaced.push({ finalizer: runner.finalizer, error });
+        }
+        return false;
+    }
+};
+
+/**
+ * Between runs, once claims were made or released: each active finalizer runs on the joined thread filling its thread,
+ * or here. One its thread can't name stops being active, and activates again once its thread is released.
+ */
+export const placeFinalizers = (state: State): void => {
+    const kept = state.finalizers.filter(runner => (channelOf(state, runner.finalizer) ?? null) === (runner.remote?.channel ?? null) || placed(state, runner));
+    if (kept.length === state.finalizers.length) return;
+    for (const runner of state.finalizers) if (!kept.includes(runner)) state.activated.delete(runner.finalizer);
+    state.finalizers.splice(0, state.finalizers.length, ...kept);
+};
+
+const resourcesOf = (finalizer: Finalizer): readonly Key[] => [...finalizer.declaration.resources?.read ?? [], ...finalizer.declaration.resources?.write ?? []];
+
+/** Between runs: adds the resources of every finalizer in the program, so one can activate at any sync point. */
+export const ensureProgramResources = (state: State, ensured: { version: number }): void => {
+    const version = programVersion();
+    if (ensured.version === version) return;
+    ensured.version = version;
+    ensureResources(state, new Set(programFinalizers().flatMap(resourcesOf)));
+    // Finalizers waiting for these can activate at the next sync point.
+    state.activation.met = true;
+};
+
+const ready = (state: State, item: Rule | Finalizer): boolean => {
+    const { keys, any } = triggersOf(item);
+    return keys.length === 0 || (any ? keys.some(key => metIdOf(state, key) !== undefined) : keys.every(key => metIdOf(state, key) !== undefined));
+};
+
+/**
+ * At the start of a sync point: activates the program's rules and finalizers that can match here now, so they apply
+ * from this sync point on. Until the world has met each component one needs, nothing can match it. Activating
+ * resolves its components' ids, which may make more ready.
+ */
+export const activate = (state: State): void => {
+    const { activation, activated, structure } = state;
+    if (!activation.met && activation.version === programVersion()) return;
+    const facts: RuleFacts[] = [];
+    const runners = new Map<Finalizer, FinalizerRunner>();
+    while (activation.met || activation.version !== programVersion()) {
+        activation.met = false;
+        activation.version = programVersion();
+        for (const rule of programRules()) {
+            if (activated.has(rule) || !ready(state, rule)) continue;
+            activated.add(rule);
+            const { components, derive } = rule.declaration;
+            const ids = (keys: readonly Key[]): number[] => keys.map(key => idOf(state, key));
+            facts.push({ has: ids(components.has ?? []), not: ids(components.not ?? []), derives: ids(derive) });
+        }
+        for (const finalizer of programFinalizers()) {
+            // A finalizer added during a run waits for its resources, which are added between runs.
+            if (activated.has(finalizer) || !ready(state, finalizer) || resourcesOf(finalizer).some(key => findResource(state, key) === undefined)) continue;
+            // One a joined thread runs is placed there; one it can't name doesn't activate, which the sync point reports once.
+            if (state.unplacedSeen.has(finalizer)) continue;
+            const runner = createFinalizerRunner(state, finalizer);
+            if (!placed(state, runner)) continue;
+            activated.add(finalizer);
+            runners.set(finalizer, runner);
+        }
+    }
+    if (facts.length > 0) {
+        restratify(structure, [...structure.rules, ...facts], structure.hosts, id => labelOf(state.keys[id]));
+        // Entities may already match a rule added to the program after the world met its components.
+        structure.rederive = true;
+    }
+    if (runners.size > 0) {
+        const existing = new Map(state.finalizers.map(runner => [runner.finalizer, runner]));
+        const ordered = programFinalizers().flatMap(finalizer => runners.get(finalizer) ?? existing.get(finalizer) ?? []);
+        state.finalizers.splice(0, state.finalizers.length, ...ordered);
+    }
+};