@adobe/ecs 0.0.0-stage → 0.1.0

package/src/interface/component/register.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import { Entity } from "../entity/entity.js";
+import { declarationOf, kindOf, threadOfDeclaration } from "../registry/index.js";
+import { Trait } from "../trait/trait.js";
+import { Component } from "./component.js";
+
+const parent = Symbol("typesComponentTest/parent");
+const count = Symbol("typesComponentTest/count");
+const label = Symbol("typesComponentTest/label");
+const placed = Symbol("typesComponentTest/placed");
+const position = Symbol("typesComponentTest/position");
+const bitmap = Symbol("typesComponentTest/bitmap");
+const marked = Symbol("typesComponentTest/marked");
+const mark = Symbol("typesComponentTest/mark");
+const late = Symbol("typesComponentTest/late");
+const slot = Symbol("typesComponentTest/slot");
+
+declare module "@adobe/ecs" {
+    export interface Threads {
+        typesComponentTest: true;
+    }
+    export interface Components {
+        [parent]: { type: Entity; reference: "owner" };
+        [count]: { type: number };
+        [label]: { type: string };
+        [placed]: { type: readonly string[]; thread: "typesComponentTest" };
+        [position]: { type: readonly [number, number] };
+        [bitmap]: { type: ImageBitmap; transfer: true };
+        [marked]: { type: true; [mark]: true };
+        [slot]: { type: number; derived: true };
+    }
+    export interface Traits<N> {
+        readonly [mark]: true;
+        readonly [late]: true;
+    }
+}
+
+Trait.register(mark);
+Component.register(parent, { type: Entity.schema, reference: "owner" });
+Component.register(count, { type: { type: "number" } });
+Component.register(label, { type: { type: "string" } });
+Component.register(placed, { type: { type: "array", items: { type: "string" } }, thread: "typesComponentTest" });
+Component.register(position, { type: { type: "array", items: { type: "number" }, minItems: 2, maxItems: 2 } });
+Component.register(bitmap, { transfer: true });
+Component.register(marked, { type: { const: true }, [mark]: true });
+Component.register(slot, { type: { type: "number", default: 0 }, derived: true });
+
+const untyped: (...parameters: never[]) => unknown = Component.register;
+
+/** Registers as an untyped caller would, bypassing the types' checks. */
+const register = (key: unknown, declaration: object): void => {
+    Reflect.apply(untyped, undefined, [key, declaration]);
+};
+
+describe("Component.register", () => {
+    it("records the declaration, and its thread: none for a struct or a string, else its own or \"world\"", () => {
+        expect(declarationOf(parent)).toEqual({ type: Entity.schema, reference: "owner" });
+        expect(kindOf(parent)).toBe("component");
+        expect(threadOfDeclaration({ type: Entity.schema })).toBe(null);
+        expect(threadOfDeclaration({ type: { const: true } })).toBe(null);
+        expect(threadOfDeclaration({ type: { type: "object", properties: { at: { type: "number" } } } })).toBe(null);
+        expect(threadOfDeclaration({ type: { type: "array", items: { type: "number" } } })).toBe("world");
+        expect(threadOfDeclaration({ type: { type: "object", properties: { at: { type: "number" } }, required: [] } })).toBe("world");
+        expect([parent, label, placed, position].map(name => threadOfDeclaration(declarationOf(name) ?? {}))).toEqual([null, null, "typesComponentTest", null]);
+        expect(threadOfDeclaration({ type: { anyOf: [{ const: "edit" }, { const: "view" }] } })).toBe(null);
+        expect(threadOfDeclaration({ type: { anyOf: [{ type: "string" }, { type: "null" }] } })).toBe(null);
+        expect(threadOfDeclaration({ type: { anyOf: [{ type: "string" }, { type: "number" }] } })).toBe("world");
+    });
+    it("accepts the same declaration again, as a module evaluated again makes it, and rejects a different one or a key of another kind", () => {
+        expect(() => Component.register(count, { type: { type: "number" } })).not.toThrow();
+        expect(() => register(count, { type: { type: "integer" } })).toThrow(`Cannot register component "typesComponentTest/count": already registered as a component, with another declaration.`);
+        expect(declarationOf(count)).toEqual({ type: { type: "number" } });
+        const claimed = Symbol("typesComponentTest/claimed");
+        register(claimed, { type: { const: true } });
+        expect(() => Reflect.apply(Trait.register, undefined, [claimed])).toThrow(`Cannot register trait "typesComponentTest/claimed": already registered as a component.`);
+        expect(kindOf(count)).toBe("component");
+    });
+    it("takes only plain symbols as keys, so built-in traits' string names are no component's", () => {
+        // @ts-expect-error a key is a symbol, and derived is a built-in trait's name
+        expect(() => Component.register("derived", { type: { const: true } })).toThrow(`Cannot register component "derived": a key is a plain Symbol(...), not a string.`);
+        expect(() => register(Symbol.for("typesComponentTest/shared"), { type: { const: true } })).toThrow("a Symbol.for key is shared across the program");
+        expect(() => register(Symbol.asyncIterator, { type: { const: true } })).toThrow("Symbol.asyncIterator is a well-known symbol.");
+        expect(kindOf("derived")).toBe(undefined);
+    });
+    it("rejects what types reject, for untyped callers, recording nothing", () => {
+        expect(() => register(Symbol("typesComponentTest/strayTrait"), { type: { type: "number" }, unknown: true })).toThrow("unknown isn't a registered trait");
+        expect(() => register(Symbol("typesComponentTest/badReference"), { type: { type: "number" }, reference: "weak" })).toThrow("a reference's type is Entity.schema");
+        expect(() => register(Symbol("typesComponentTest/badSlot"), { type: { type: "number" }, derived: true })).toThrow("a derived component's type has a default");
+        expect(() => register(Symbol("typesComponentTest/reduced"), { type: { type: "number" }, reduce: "+" })).toThrow("only a resource is reduced");
+        const badReference = Symbol("typesComponentTest/badReference");
+        expect(() => register(badReference, { type: { type: "number" }, reference: "weak" })).toThrow("a reference's type is Entity.schema");
+        expect(declarationOf(badReference)).toBe(undefined);
+        expect(kindOf(badReference)).toBe(undefined);
+    });
+    it("rejects a schema whose GPU layout can't hold it", () => {
+        expect(() => register(Symbol("typesComponentTest/storageText"), { type: { type: "array", items: { type: "string" }, layout: "storage" } })).toThrow("layout needs numbers");
+    });
+    it("checks thread and transfer as far as values tell", () => {
+        expect(() => register(Symbol("typesComponentTest/placedStruct"), { type: { type: "number" }, thread: "main" })).toThrow("a struct lives in shared memory, so it has no thread");
+        expect(() => register(Symbol("typesComponentTest/placedTag"), { type: { const: true }, thread: "main" })).toThrow("a struct lives in shared memory");
+        expect(() => register(Symbol("typesComponentTest/placedText"), { type: { type: "string" }, thread: "main" })).toThrow("a string lives in shared memory, so it has no thread");
+        expect(() => register(Symbol("typesComponentTest/placedMode"), { type: { anyOf: [{ const: "edit" }, { const: "view" }] }, thread: "main" })).toThrow("a string lives in shared memory");
+        expect(() => register(Symbol("typesComponentTest/emptyThread"), { thread: "" })).toThrow("thread is a thread's name");
+        expect(() => register(Symbol("typesComponentTest/dataTransfer"), { type: { type: "string" }, transfer: true })).toThrow("a value with a schema is data, which isn't Transferable");
+        expect(() => register(Symbol("typesComponentTest/falseTransfer"), { transfer: false })).toThrow("transfer is true");
+    });
+    it("records no type for a value that isn't data", () => {
+        expect(declarationOf(bitmap)).toEqual({ transfer: true });
+        expect(Reflect.has(declarationOf(bitmap) ?? {}, "type")).toBe(false);
+        expect(() => Component.register(bitmap, { transfer: true })).not.toThrow();
+    });
+    it("rejects a default beside a component's schema, which holds it", () => {
+        expect(() => register(Symbol("typesComponentTest/defaulted"), { type: { type: "number" }, default: 0 })).toThrow("its schema holds its default");
+    });
+    it("takes traits other packages register, in the namespace components share", () => {
+        const early = Symbol("typesComponentTest/early");
+        expect(() => register(early, { type: { const: true }, [late]: true })).toThrow(`typesComponentTest/late isn't a registered trait`);
+        Trait.register(late);
+        expect(() => register(early, { type: { const: true }, [late]: true })).not.toThrow();
+        expect(declarationOf(marked)).toEqual({ type: { const: true }, [mark]: true });
+        expect(() => Trait.register(mark)).not.toThrow();
+        expect(declarationOf(slot)).toEqual({ type: { type: "number", default: 0 }, derived: true });
+    });
+});

package/src/interface/component/register.ts

@@ -0,0 +1,28 @@
+import { createRegistry, type AnyDeclaration } from "../registry/declarations.js";
+import type { Resource } from "../resource/resource.js";
+import type { Schema } from "../schema/schema.js";
+import type { Key as TraitKey } from "../trait/key.js";
+import type { Declaration } from "./declaration.js";
+import type { Key } from "./key.js";
+
+const registry = createRegistry("component");
+
+/**
+ * Registers the component `key`, a plain `Symbol(...)` whose traits `Components` declares, with exactly those traits:
+ * `type` as a schema that describes the declared type, left out only for a type that isn't data, which is stored as
+ * it is.
+ * ```ts
+ * declare module "@adobe/ecs" { interface Components { [position]: { type: Vec3 } } }
+ * Component.register(position, { type: Vec3.schema });
+ * ```
+ * The declaration is fixed from then on. The same declaration again is accepted, and so is a new symbol with the id
+ * of a component, as a module evaluated again makes it, which is then that key. A key also declared as a resource or
+ * a trait can't be registered: names are unique across the three. Throws for a key that isn't a plain symbol (a
+ * `Symbol.for` or well-known symbol isn't), one registered, or whose id is registered, as another kind or with another
+ * declaration, a trait that isn't registered, a trait's value that can't hold for the declaration, or a schema asking
+ * for a GPU layout it can't meet.
+ */
+export function register<K extends Exclude<Key, Resource.Key | TraitKey> & symbol, const S extends Schema & { readonly default?: unknown } = never>(key: K, declaration: Declaration<K, S>): void;
+export function register(key: unknown, declaration: AnyDeclaration): void {
+    registry(key, declaration);
+}

package/src/interface/component/types.ts

@@ -0,0 +1,6 @@
+/**
+ * Each component's traits, `type` included, by augmentation: `[position]: { type: Vec3 }`,
+ * `[slot]: { type: Slot; derived: true }`. Registration must give exactly these.
+ */
+export interface Components {
+}

package/src/interface/component/value.ts

@@ -0,0 +1,34 @@
+import type { ThreadOf } from '../thread/of.js';
+import type { Key as TraitKey } from "../trait/key.js";
+import type { Key } from "./key.js";
+import type { Components } from "./types.js";
+
+/** Every component's value type, computed once so `Value` is a lookup. */
+type ValueTypes = { readonly [K in Key]: Components[K] extends { readonly type: infer T } ? T : never };
+
+/** The value type of component `K`. */
+export type Value<K extends Key> = ValueTypes[K];
+
+type Primitive = string | number | boolean | bigint | symbol | null | undefined;
+
+/** Component `K`'s value as reads return it: read-only, with branded primitives such as `Entity` as they are. */
+export type ReadonlyValue<K extends Key> = Value<K> extends Primitive ? Value<K> : Readonly<Value<K>>;
+
+/** Components that declare trait `T`, with a value assignable to `V`. */
+export type With<T extends TraitKey, V = unknown> = { [K in Key]: Components[K] extends { readonly [P in T]: V } ? K : never }[Key];
+
+
+/** Components only rules add and remove. */
+export type Derived = With<"derived">;
+
+/** Components user code adds and removes: the only ones commands take. */
+export type Essential = Exclude<Key, Derived>;
+
+/** Components systems may write: every one but references, which change only through commands. */
+export type Writable = Exclude<Key, With<"reference">>;
+
+/** Every component's thread, computed once so `ThreadOf` is a lookup. */
+type Threads = { readonly [K in Key]: ThreadOf<Components[K], Value<K>> };
+
+/** The thread component `K` lives on, or `never` for a struct, which lives in shared memory. */
+export type ThreadOfComponent<K extends Key> = Threads[K];

package/src/interface/component/values.ts

@@ -0,0 +1,5 @@
+import type { Key } from "./key.js";
+import type { Value } from './value.js';
+
+/** Values for any subset of components, keyed by component. */
+export type Values = { readonly [K in Key]?: Value<K> };

package/src/interface/entity/entity.ts

@@ -0,0 +1,9 @@
+declare const entityBrand: unique symbol;
+
+/**
+ * An entity id, live or not: a branded number; 0 is none. The brand makes entity-valued components and fields visible
+ * to types and schemas, and costs nothing at runtime.
+ */
+export type Entity = number & { readonly [entityBrand]: true };
+
+export * as Entity from './index.js';

package/src/interface/entity/index.ts

@@ -0,0 +1,8 @@
+import type { Schema } from '../schema/schema.js';
+import type { Entity } from './entity.js';
+
+/** The schema of every entity-typed value. */
+export const schema = { type: "integer", format: "entity" } as const satisfies Schema;
+
+/** No entity: index 0 is never one, so zeroed memory and an entity-valued default mean none, and a lookup of it returns null. */
+export const none = 0 as Entity;

package/src/interface/finalizer/body.ts

@@ -0,0 +1,51 @@
+import type { Component } from '../component/component.js';
+import type { Entity } from '../entity/entity.js';
+import type { Resource } from '../resource/resource.js';
+import type { Commands } from '../system/commands.js';
+import type { Listed, Property } from '../system/property.js';
+import type { LookupFunction, ResourceValues, Values } from '../system/values.js';
+import type { ChangesDeclaration, Declaration } from './declaration.js';
+import type { Essential, ReadonlyValue } from '../component/value.js';
+import type { Elsewhere, ThreadsOf } from '../system/threads.js';
+
+/** The entity that stopped matching, with its `read` values as they are before the sync point applies. */
+export type Row<D extends Declaration> =
+    { readonly entity: Entity } & { readonly [K in Listed<Property<D, "components">, "read"> & Component.Key]: Component.Value<K> };
+
+type Resources<D> = Listed<Property<D, "resources">, "read"> | Listed<Property<D, "resources">, "write">;
+
+/**
+ * Resources and lookups, each present only when declared, and the commands it issues for the next sync point: none on
+ * another thread than the world's, which runs after the sync point.
+ */
+export type Context<D extends Declaration | ChangesDeclaration> =
+    ([Resources<D>] extends [never] ? {} : {
+        readonly resources: Values<Listed<Property<D, "resources">, "read">, Listed<Property<D, "resources">, "write">, Resource.Key, ResourceValues>;
+    })
+    & ([keyof Property<D, "lookup">] extends [never] ? {} : {
+        readonly lookup: { readonly [K in keyof Property<D, "lookup">]: LookupFunction<Property<D, "lookup">[K]> };
+    })
+    & (true extends Elsewhere<ThreadsOf<D>> ? {} : { readonly commands: Commands });
+
+/** The components a changes finalizer sees. */
+export type Watched<D extends ChangesDeclaration> = Property<D, "watch"> extends readonly Essential[] ? Listed<D, "watch"> & Essential : Essential;
+
+/** Entities whose components changed the same way: `from` and `to` are null for those spawned and despawned. */
+export type Group<C extends Component.Key> = {
+    readonly from: readonly C[] | null;
+    readonly to: readonly C[] | null;
+    readonly added: readonly C[];
+    readonly removed: readonly C[];
+    /** Given a value by an add while the entity has it before and after, removed and added again meanwhile or not. */
+    readonly replaced: readonly C[];
+    readonly entities: readonly Entity[];
+};
+
+/** A sync point's structural changes to the watched components, and the values adds replace, before they apply. */
+export type ChangeSet<C extends Component.Key> = {
+    readonly groups: readonly Group<C>[];
+    /** The value before the sync point, or null if the entity didn't have it. */
+    previous<K extends C>(entity: Entity, component: K): ReadonlyValue<K> | null;
+    /** The value after it, or null if the entity won't have it. */
+    next<K extends C>(entity: Entity, component: K): ReadonlyValue<K> | null;
+};

package/src/interface/finalizer/create.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, it } from "vitest";
+import { Component } from "../component/component.js";
+import { identify } from "../registry/ids.test-helper.js";
+import { labelOfItem, programFinalizers, programRules } from "../registry/index.js";
+import { Resource } from "../resource/resource.js";
+import { Rule } from "../rule/rule.js";
+import { clock } from "../resources/index.js";
+import { Finalizer } from "./finalizer.js";
+
+const node = Symbol("typesFinalizerTest/node");
+const label = Symbol("typesFinalizerTest/label");
+const slot = Symbol("typesFinalizerTest/slot");
+const total = Symbol("typesFinalizerTest/total");
+const time = Symbol("typesFinalizerTest/time");
+const mark = Symbol("typesFinalizerTest/mark");
+const other = Symbol("typesFinalizerTest/other");
+const page = Symbol("typesFinalizerTest/page");
+const tags = Symbol("typesFinalizerTest/tags");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [node]: { type: HTMLElement; thread: "main" };
+        [label]: { type: string };
+        [slot]: { type: number; derived: true };
+        [mark]: { type: true; derived: true };
+        [other]: { type: true; derived: true };
+        [tags]: { type: readonly string[] };
+    }
+    export interface Resources {
+        [total]: { type: number; reduce: "+" };
+        [time]: { type: number };
+        [page]: { type: Document | null; thread: "main" };
+    }
+}
+
+Component.register(node, { thread: "main" });
+Component.register(label, { type: { type: "string" } });
+Component.register(tags, { type: { type: "array", items: { type: "string" } } });
+Component.register(slot, { type: { type: "number", default: 0 }, derived: true });
+Resource.register(total, { type: { type: "number", default: 0 }, reduce: "+" });
+Resource.register(time, { type: { type: "number", default: 0 } });
+Resource.register(page, { thread: "main" });
+Component.register(mark, { type: { const: true }, derived: true });
+Component.register(other, { type: { const: true }, derived: true });
+
+/** Declares as an untyped caller would, bypassing the types' checks. */
+const untyped = (constructor: (...parameters: never[]) => unknown, declaration: object): unknown => Reflect.apply(constructor, undefined, [declaration, () => {}]);
+
+describe("Finalizer.create and Finalizer.changes", () => {
+    it("record finalizers in creation order, keep the place of one declared again under its id with its new body, and reject its id with another declaration", () => {
+        const release = Finalizer.create(identify({ name: "typesFinalizerTest/release", components: { read: [node] } }, "f.ts#release"), () => {});
+        const save = Finalizer.changes({ name: "typesFinalizerTest/save", watch: [label] }, () => {});
+        expect(programFinalizers().map(finalizer => finalizer.name)).toEqual([release.name, save.name]);
+        const body = (): void => {};
+        expect(Finalizer.create(identify({ name: "typesFinalizerTest/release", components: { read: [node] } }, "f.ts#release"), body)).toBe(release);
+        expect(programFinalizers()[0]?.kind === "finalizer" ? programFinalizers()[0]?.body : null).toBe(body);
+        expect(() => Finalizer.create(identify({ name: "typesFinalizerTest/release", components: { read: [label] } }, "f.ts#release"), () => {})).toThrow("reload the page");
+        expect(() => Finalizer.changes(identify({ name: "typesFinalizerTest/release" }, "f.ts#release"), () => {})).toThrow("its id is a finalizer's");
+        expect(programFinalizers()).toHaveLength(2);
+    });
+    it("keep finalizers of one name apart, labeled apart", () => {
+        const first = Finalizer.changes({ name: "typesFinalizerTest/twin", watch: [label] }, () => {});
+        const second = Finalizer.changes({ name: "typesFinalizerTest/twin", watch: [label] }, () => {});
+        expect(second).not.toBe(first);
+        expect([first, second].map(labelOfItem)).toEqual(["typesFinalizerTest/twin", "typesFinalizerTest/twin#2"]);
+        const third = Finalizer.changes({ name: "typesFinalizerTest/ordered", watch: [label], after: [second], before: [first] }, () => {});
+        expect(programFinalizers().slice(-3)).toEqual([second, third, first]);
+    });
+    it("order finalizers by before and after, and reject a cycle or a resource conflict with no order", () => {
+        const late = Finalizer.create({ name: "typesFinalizerTest/late", components: { read: [label] }, resources: { read: [time] } }, () => {});
+        const early = Finalizer.create({ name: "typesFinalizerTest/early", components: { read: [label] }, resources: { write: [time] }, before: [late] }, () => {});
+        expect(programFinalizers().map(finalizer => finalizer.name).filter(name => name === early.name || name === late.name)).toEqual([early.name, late.name]);
+        expect(() => Finalizer.create({ name: "typesFinalizerTest/conflict", components: { read: [label] }, resources: { read: [time] } }, () => {})).toThrow('both access "typesFinalizerTest/time", one writing it');
+        expect(() => Finalizer.create({ name: "typesFinalizerTest/cycle", components: { read: [label] }, before: [early], after: [late] }, () => {})).toThrow("ordered in a cycle");
+        expect(() => untyped(Finalizer.create, { name: "typesFinalizerTest/clock", components: {}, resources: { write: [clock] } })).toThrow(`writes "clock", which only the world writes`);
+        expect(programFinalizers()).toHaveLength(7);
+    });
+    it("reject what types reject, for untyped callers", () => {
+        expect(() => untyped(Finalizer.create, { name: "typesFinalizerTest/both", components: {}, resources: { read: [time], write: [time] } })).toThrow("in both resources read and write");
+        expect(() => untyped(Finalizer.create, { name: "typesFinalizerTest/reduced", components: {}, resources: { write: [total] } })).toThrow("which is reduced");
+        expect(() => untyped(Finalizer.create, { name: "typesFinalizerTest/span", components: { read: [node, tags] } })).toThrow('uses "typesFinalizerTest/node" on "main" and "typesFinalizerTest/tags" on "world"');
+        expect(() => untyped(Finalizer.changes, { name: "typesFinalizerTest/derived", watch: [slot] })).toThrow("which is derived");
+        expect(() => untyped(Finalizer.changes, { name: "typesFinalizerTest/resource", watch: [time] })).toThrow("which isn't a registered component");
+        expect(() => untyped(Finalizer.create, { name: "typesFinalizerTest/hasResource", components: { has: [time] } })).toThrow(`Finalizer "typesFinalizerTest/hasResource" uses component "typesFinalizerTest/time", which isn't a registered component`);
+        expect(() => untyped(Finalizer.create, { name: "typesFinalizerTest/lookupNot", components: { read: [label] }, lookup: { others: { not: [Symbol("typesFinalizerTest/unregistered")] } } })).toThrow("which isn't a registered component");
+        expect(programFinalizers()).toHaveLength(7);
+    });
+    it("reject resource writes and lookups in a finalizer on another thread than the world's, and a changes finalizer watching or reading another thread's values", () => {
+        expect(() => untyped(Finalizer.create, { name: "typesFinalizerTest/detachWriting", components: { read: [node] }, resources: { write: [time] } }))
+            .toThrow(`Finalizer "typesFinalizerTest/detachWriting" runs on thread "main" and writes resources; one on another thread than the world's runs after the sync point, so it writes none.`);
+        expect(() => untyped(Finalizer.create, { name: "typesFinalizerTest/pageWriting", components: { read: [tags] }, resources: { write: [page] } }))
+            .toThrow('uses "typesFinalizerTest/tags" on "world" and "typesFinalizerTest/page" on "main"');
+        expect(() => untyped(Finalizer.create, { name: "typesFinalizerTest/detachLooking", components: { read: [node] }, lookup: { labels: { read: [mark] } } }))
+            .toThrow(`Finalizer "typesFinalizerTest/detachLooking" runs on thread "main" and looks up other entities; one on another thread than the world's runs after the sync point, so it looks up none.`);
+        expect(() => untyped(Finalizer.changes, { name: "typesFinalizerTest/saveNodes", watch: [node] }))
+            .toThrow(`Finalizer "typesFinalizerTest/saveNodes" watches or reads values on thread "main"; a changes finalizer runs on the world's thread, in the sync point.`);
+        expect(() => untyped(Finalizer.changes, { name: "typesFinalizerTest/savePage", watch: [tags], resources: { read: [page] } }))
+            .toThrow('uses "typesFinalizerTest/tags" on "world" and "typesFinalizerTest/page" on "main"');
+        expect(() => untyped(Finalizer.changes, { name: "typesFinalizerTest/savePageOnly", resources: { read: [page] } }))
+            .toThrow(`Finalizer "typesFinalizerTest/savePageOnly" watches or reads values on thread "main"; a changes finalizer runs on the world's thread, in the sync point.`);
+        // Reading another thread's values, without writing or looking up, it's created.
+        const detach = Finalizer.create({ name: "typesFinalizerTest/detach", components: { read: [node] }, resources: { read: [page] } }, () => {});
+        expect(programFinalizers()).toHaveLength(8);
+        // Finalizers on different threads run at different times, so neither is ordered before the other.
+        const late = programFinalizers().find(finalizer => finalizer.name === "typesFinalizerTest/late");
+        expect(() => untyped(Finalizer.create, { name: "typesFinalizerTest/afterDetach", components: { read: [label] }, after: [detach] }))
+            .toThrow(`Finalizer "typesFinalizerTest/afterDetach" runs on thread "world" and is ordered with "typesFinalizerTest/detach", which runs on thread "main"; finalizers on different threads run at different times, so neither is ordered before the other.`);
+        expect(() => untyped(Finalizer.create, { name: "typesFinalizerTest/beforeLate", components: { read: [node] }, before: [late] }))
+            .toThrow(`Finalizer "typesFinalizerTest/beforeLate" runs on thread "main" and is ordered with "typesFinalizerTest/late", which runs on thread "world"`);
+        expect(() => untyped(Finalizer.changes, { name: "typesFinalizerTest/saveAfterDetach", watch: [label], after: [detach] }))
+            .toThrow(`Finalizer "typesFinalizerTest/saveAfterDetach" runs on thread "world" and is ordered with "typesFinalizerTest/detach"`);
+        Finalizer.create({ name: "typesFinalizerTest/detachAgain", components: { read: [node] }, after: [detach] }, () => {});
+        expect(programFinalizers()).toHaveLength(9);
+    });
+});
+
+describe("Rule.create", () => {
+    it("records a rule and returns it, the one already recorded when declared again under its id, and rejects its id with another declaration", () => {
+        const slots = Rule.create(identify({ name: "typesFinalizerTest/slots", components: { has: [label] }, derive: [slot] }, "r.ts#slots"));
+        expect(programRules()).toEqual([slots]);
+        expect(Rule.create(identify({ name: "typesFinalizerTest/slots", components: { has: [label] }, derive: [slot] }, "r.ts#slots"))).toBe(slots);
+        expect(() => Rule.create(identify({ name: "typesFinalizerTest/slots", components: { has: [node] }, derive: [slot] }, "r.ts#slots"))).toThrow("reload the page");
+        const twin = Rule.create({ name: "typesFinalizerTest/slots", components: { has: [node] }, derive: [slot] });
+        expect(programRules()).toEqual([slots, twin]);
+        expect([slots, twin].map(labelOfItem)).toEqual(["typesFinalizerTest/slots (r.ts#slots)", "typesFinalizerTest/slots#2"]);
+    });
+    it("rejects rules that derive in a cycle through a negation", () => {
+        Rule.create({ name: "typesFinalizerTest/marks", components: { not: [mark] }, derive: [other] });
+        expect(() => Rule.create({ name: "typesFinalizerTest/others", components: { has: [other] }, derive: [mark] })).toThrow("cycle through a negation");
+        expect(programRules()).toHaveLength(3);
+    });
+    it("rejects a rule deriving a component that isn't derived, or matching on a resource", () => {
+        const create = (declaration: object): unknown => Reflect.apply(Rule.create, undefined, [declaration]);
+        expect(() => create({ name: "typesFinalizerTest/essential", components: {}, derive: [label] })).toThrow("which isn't declared derived");
+        expect(() => create({ name: "typesFinalizerTest/onResource", components: { has: [time] }, derive: [slot] })).toThrow("which isn't a registered component");
+        expect(programRules()).toHaveLength(3);
+    });
+});
+
+describe("rules and finalizers without a name", () => {
+    it("are named by their binding and id, or else by their kind numbered", () => {
+        const rule = Rule.create(identify({ components: { has: [node] }, derive: [slot] }, "rules.ts#slotted"));
+        const release = Finalizer.create(identify({ components: { read: [node] } }, "finalizers.ts#release"), () => {});
+        expect([rule, release].map(labelOfItem)).toEqual(["slotted (rules.ts#slotted)", "release (finalizers.ts#release)"]);
+        const labels = [Rule.create({ components: { has: [label] }, derive: [slot] }), Finalizer.changes({ watch: [label] }, () => {})].map(labelOfItem);
+        expect(labels.map(found => found.replace(/#\d+$/, "#n"))).toEqual(["rule #n", "finalizer #n"]);
+    });
+});

package/src/interface/finalizer/create.ts

@@ -0,0 +1,128 @@
+import { declarationOf, kindOf, labelOf } from '../registry/names.js';
+import { takeIdOfDeclaration } from '../registry/ids.js';
+import { firstItemOf, labelOfItem, nameOf } from '../registry/items.js';
+import { addFinalizer, programFinalizers } from '../registry/program.js';
+import { requireRegistered, threadOf } from '../registry/threads.js';
+import { checkWorldWritten } from '../registry/written.js';
+import { checkLookup } from '../registry/indexes.js';
+import type { Resource } from '../resource/resource.js';
+import type { Listed, Property } from '../system/property.js';
+import type { ThreadOfComponent } from '../component/value.js';
+import type { Component } from '../component/component.js';
+import type { Elsewhere, OneThread, ThreadedBy, ThreadsOf } from '../system/threads.js';
+import type { ChangeSet, Context, Row, Watched } from './body.js';
+import type { Changes, Leaf } from './created.js';
+import type { ChangesDeclaration, Declaration } from './declaration.js';
+import type { Finalizer } from './finalizer.js';
+import type { Finalizer as Registered } from './created.js';
+
+/** A resource in `write` is readable too, so it isn't also in `read`. */
+type Validate<D extends Declaration | ChangesDeclaration> =
+    { readonly resources?: { readonly read?: readonly Exclude<Resource.Key, Listed<Property<D, "resources">, "write">>[] } };
+
+/**
+ * A finalizer on another thread than the world's runs there after the sync point, which doesn't wait for it: it writes
+ * no resources and looks up nothing.
+ */
+type Remote<D> = true extends Elsewhere<ThreadsOf<D>>
+    ? ([Listed<Property<D, "resources">, "write">] extends [never] ? {} : { readonly "error: a finalizer on another thread than the world's writes no resources": true })
+    & ([keyof Property<D, "lookup">] extends [never] ? {} : { readonly "error: a finalizer on another thread than the world's looks up nothing": true })
+    : {};
+
+/** A changes finalizer runs on the world's thread, in the sync point: it watches and reads no other thread's objects. */
+type OnWorld<D> = true extends Elsewhere<ThreadsOf<D> | ThreadOfComponent<Listed<D, "watch"> & Component.Key>>
+    ? { readonly "error: a changes finalizer watches and reads only the world's thread's objects": true }
+    : {};
+
+type Key = symbol;
+
+/** Throws if a resource is in both `read` and `write`, or a reduced one is written. */
+const checkResources = (name: string, resources: { readonly read?: readonly Key[]; readonly write?: readonly Key[] } | undefined): void => {
+    const writes = new Set(resources?.write);
+    const both = (resources?.read ?? []).find(key => writes.has(key));
+    if (both !== undefined) throw new Error(`Finalizer "${name}" lists "${labelOf(both)}" in both resources read and write; write already makes it readable.`);
+    checkWorldWritten(`Finalizer "${name}"`, resources?.write);
+    for (const key of writes) {
+        if (declarationOf(key)?.reduce !== undefined) throw new Error(`Finalizer "${name}" writes "${labelOf(key)}", which is reduced; only its contributors' fold sets it.`);
+    }
+};
+
+/** The thread a registered finalizer runs on: a changes finalizer, and one using no objects, on the world's. */
+const runsOn = (finalizer: Registered): string => finalizer.kind === "finalizer" ? threadOf(finalizer.declaration, "Finalizer", finalizer.name) ?? "world" : "world";
+
+/** Throws for a finalizer ordered with one on another thread: they run at different times. */
+const checkOrder = (name: string, thread: string, declaration: { readonly before?: readonly Finalizer[]; readonly after?: readonly Finalizer[] }): void => {
+    for (const other of [...declaration.before ?? [], ...declaration.after ?? []]) {
+        const first = firstItemOf(other);
+        const found = programFinalizers().find(finalizer => firstItemOf(finalizer) === first);
+        if (found === undefined) continue;
+        const theirs = runsOn(found);
+        if (theirs !== thread) {
+            throw new Error(`Finalizer "${name}" runs on thread "${thread}" and is ordered with "${labelOfItem(found)}", which runs on thread "${theirs}"; finalizers on different threads run at different times, so neither is ordered before the other.`);
+        }
+    }
+};
+
+/**
+ * Declares a finalizer for each entity that stops matching its components, which applies in every world, and returns
+ * it. It runs on the thread its object components and resources live on: on another than the world's, after the sync
+ * point, issuing no commands. Throws if it names a component or resource that isn't registered as one, lists a
+ * resource in both `read` and `write`, writes a reduced one, uses object values of different threads, writes resources
+ * or looks up entities on another thread than the world's, or is ordered with a finalizer on another thread, in a cycle
+ * or with a resource conflict.
+ */
+export const create = <const D extends Declaration>(
+    declaration: D & Validate<D> & OneThread<ThreadsOf<D>, ThreadedBy<D>> & Remote<D>,
+    body: (row: Row<D>, context: Context<D>) => void,
+): Finalizer => {
+    const id = takeIdOfDeclaration(declaration);
+    const name = nameOf(declaration.name, id, "finalizer");
+    const finalizer: Leaf<D> = { kind: "finalizer", name, declaration, body };
+    checkResources(name, declaration.resources);
+    const thread = threadOf(declaration, "Finalizer", name);
+    if (thread !== null && thread !== "world") {
+        const elsewhere = `one on another thread than the world's runs after the sync point, so it`;
+        if ((declaration.resources?.write?.length ?? 0) > 0) throw new Error(`Finalizer "${name}" runs on thread "${thread}" and writes resources; ${elsewhere} writes none.`);
+        if (Object.keys(declaration.lookup ?? {}).length > 0) throw new Error(`Finalizer "${name}" runs on thread "${thread}" and looks up other entities; ${elsewhere} looks up none.`);
+    }
+    checkOrder(name, thread ?? "world", declaration);
+    requireRegistered("Finalizer", name, "component", declaration.components.has);
+    requireRegistered("Finalizer", name, "component", declaration.components.not);
+    for (const lookupName in declaration.lookup) {
+        checkLookup("Finalizer", name, lookupName, declaration.lookup[lookupName]);
+        const lookup = declaration.lookup[lookupName];
+        requireRegistered("Finalizer", name, "component", "has" in lookup ? lookup.has : undefined);
+        requireRegistered("Finalizer", name, "component", "not" in lookup ? lookup.not : undefined);
+    }
+    return addFinalizer(finalizer, id);
+};
+
+/**
+ * Declares a finalizer of each sync point's structural changes, which applies in every world, and returns it. It runs
+ * on the world's thread. Throws as `create` does, for a watched component that isn't registered or is derived, and for
+ * one watching or reading another thread's values.
+ */
+export const changes = <const D extends ChangesDeclaration>(
+    declaration: D & Validate<D> & OnWorld<D>,
+    body: (changes: ChangeSet<Watched<D>>, context: Context<D>) => void,
+): Finalizer => {
+    const id = takeIdOfDeclaration(declaration);
+    const name = nameOf(declaration.name, id, "finalizer");
+    const finalizer: Changes<D> = { kind: "changes", name, declaration, body };
+    checkResources(name, declaration.resources);
+    requireRegistered("Finalizer", name, "resource", declaration.resources?.read);
+    requireRegistered("Finalizer", name, "resource", declaration.resources?.write);
+    for (const lookupName in declaration.lookup) {
+        const lookup = declaration.lookup[lookupName];
+        checkLookup("Finalizer", name, lookupName, lookup);
+        for (const keys of [lookup.read, "has" in lookup ? lookup.has : undefined, "not" in lookup ? lookup.not : undefined]) requireRegistered("Finalizer", name, "component", keys);
+    }
+    for (const key of declaration.watch ?? []) {
+        if (kindOf(key) !== "component") throw new Error(`Finalizer "${name}" watches "${labelOf(key)}", which isn't a registered component.`);
+        if (declarationOf(key)?.derived === true) throw new Error(`Finalizer "${name}" watches "${labelOf(key)}", which is derived; it sees only components user code adds and removes.`);
+    }
+    const thread = threadOf({ components: { read: declaration.watch }, resources: declaration.resources, lookup: declaration.lookup }, "Finalizer", name);
+    if (thread !== null && thread !== "world") throw new Error(`Finalizer "${name}" watches or reads values on thread "${thread}"; a changes finalizer runs on the world's thread, in the sync point.`);
+    checkOrder(name, "world", declaration);
+    return addFinalizer(finalizer, id);
+};

package/src/interface/finalizer/created.ts

@@ -0,0 +1,21 @@
+import type { ChangesDeclaration, Declaration } from './declaration.js';
+
+// Bodies' parameters are checked where they're created, so a finalizer holds any body.
+
+/** Runs, inside a sync point, for each entity that stops matching its components. */
+export type Leaf<D extends Declaration = Declaration> = {
+    readonly kind: "finalizer";
+    readonly name: string;
+    readonly declaration: D;
+    body: (...parameters: never[]) => void;
+};
+
+/** Runs, inside a sync point, with all its structural changes to the components it watches. */
+export type Changes<D extends ChangesDeclaration = ChangesDeclaration> = {
+    readonly kind: "changes";
+    readonly name: string;
+    readonly declaration: D;
+    body: (...parameters: never[]) => void;
+};
+
+export type Finalizer = Leaf | Changes;

package/src/interface/finalizer/declaration.ts

@@ -0,0 +1,29 @@
+import type { Component } from '../component/component.js';
+import type { Resource } from '../resource/resource.js';
+import type { Lookup } from '../system/access.js';
+import type { Finalizer } from './finalizer.js';
+import type { Name } from './name.js';
+import type { Essential } from '../component/value.js';
+import type { Reduced } from '../resource/reduction.js';
+import type { WorldWritten } from '../resource/written.js';
+
+type Shared = {
+    readonly name?: Name;
+    /** Read-only access to other entities, as they are before the sync point applies. */
+    readonly lookup?: { readonly [name: string]: Lookup };
+    /** Writes take the sync point's tick, so each system sees them once. A resource in `write` is also readable. */
+    readonly resources?: { readonly read?: readonly Resource.Key[]; readonly write?: readonly Exclude<Resource.Key, Reduced | WorldWritten>[] };
+    readonly before?: readonly Finalizer[];
+    readonly after?: readonly Finalizer[];
+};
+
+/** A finalizer that runs for each entity that stops matching its components. */
+export type Declaration = Shared & {
+    readonly components: { readonly read?: readonly Component.Key[]; readonly has?: readonly Component.Key[]; readonly not?: readonly Component.Key[] };
+};
+
+/**
+ * A finalizer that sees each sync point's structural changes to the components it watches: by default, every one that
+ * isn't derived or an object a joined thread fills.
+ */
+export type ChangesDeclaration = Shared & { readonly watch?: readonly Essential[] };

package/src/interface/finalizer/finalizer.ts

@@ -0,0 +1,7 @@
+/**
+ * A finalizer, the value `Finalizer.create` or `Finalizer.changes` returned: identified by that value, labeled by its
+ * name, and listed in other finalizers' `before` and `after`.
+ */
+export type Finalizer = { readonly name: string };
+
+export * as Finalizer from './index.js';

package/src/interface/finalizer/index.ts

@@ -0,0 +1 @@
+export * from './create.js';