@adobe/ecs 0.0.0-stage → 0.1.0

package/src/interface/registry/names.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, it } from "vitest";
+import type { AnyDeclaration } from "./declarations.js";
+import { identify } from "./ids.test-helper.js";
+import { claimKey, declarationOf, kindOf, labelOf } from "./names.js";
+
+/** Declarations as registration records them; claiming a key doesn't check them. */
+const number: AnyDeclaration = { type: { type: "number" } };
+const boolean: AnyDeclaration = { type: { type: "boolean" } };
+
+describe("claimKey", () => {
+    it("accepts a plain symbol, with or without a description", () => {
+        const described = Symbol("claimKey/described");
+        const anonymous = Symbol();
+        claimKey(described, "component", { type: { type: "number" } });
+        claimKey(anonymous, "resource", number);
+        expect([kindOf(described), kindOf(anonymous)]).toEqual(["component", "resource"]);
+        expect(declarationOf(anonymous)).toBe(number);
+    });
+    it("keys by identity: symbols with one description are different keys", () => {
+        const first = Symbol("claimKey/twin");
+        const second = Symbol("claimKey/twin");
+        claimKey(first, "component", { type: { type: "number" } });
+        expect(() => claimKey(second, "resource", boolean)).not.toThrow();
+        expect([kindOf(first), kindOf(second)]).toEqual(["component", "resource"]);
+        expect(kindOf("claimKey/twin")).toBe(undefined);
+    });
+    it("rejects strings, Symbol.for symbols and well-known symbols, recording nothing", () => {
+        const shared = Symbol.for("claimKey/shared");
+        expect(() => claimKey("claimKey/text", "component", { type: { type: "number" } })).toThrow(`Cannot register component "claimKey/text": a key is a plain Symbol(...), not a string.`);
+        expect(() => claimKey(1, "component", { type: { type: "number" } })).toThrow("a key is a plain Symbol(...), not a number.");
+        expect(() => claimKey(shared, "resource", number)).toThrow("a Symbol.for key is shared across the program, so another could claim it; use Symbol(...).");
+        expect(() => claimKey(Symbol.iterator, "trait")).toThrow("Symbol.iterator is a well-known symbol.");
+        expect([kindOf(shared), kindOf(Symbol.iterator)]).toEqual([undefined, undefined]);
+    });
+    it("rejects a key claimed as another kind", () => {
+        const key = Symbol("claimKey/crossKind");
+        claimKey(key, "trait");
+        expect(() => claimKey(key, "component", { type: { type: "number" } })).toThrow(`Cannot register component "claimKey/crossKind": already registered as a trait.`);
+        expect(kindOf(key)).toBe("trait");
+    });
+});
+
+describe("labelOf", () => {
+    it("labels a key by its description while no other registered key has it, else by its id", () => {
+        const first = Symbol("labelOf/shared");
+        const second = Symbol("labelOf/shared");
+        const lone = Symbol("labelOf/lone");
+        identify(first, "a.ts#first");
+        identify(second, "b.ts#second");
+        identify(lone, "c.ts#lone");
+        expect([labelOf(first), labelOf(lone)]).toEqual(["labelOf/shared", "labelOf/lone"]);
+        claimKey(first, "component", number);
+        claimKey(lone, "component", number);
+        expect([labelOf(first), labelOf(second), labelOf(lone)]).toEqual(["labelOf/shared", "b.ts#second", "labelOf/lone"]);
+        claimKey(second, "resource", number);
+        expect([labelOf(first), labelOf(second), labelOf(lone)]).toEqual(["a.ts#first", "b.ts#second", "labelOf/lone"]);
+    });
+    it("labels a key without an id by its description, numbered by registration when another key has it", () => {
+        const first = Symbol("labelOf/twin");
+        const second = Symbol("labelOf/twin");
+        const third = Symbol("labelOf/twin");
+        expect(labelOf(first)).toBe("labelOf/twin");
+        claimKey(second, "component", { type: { type: "number" } });
+        claimKey(first, "component", { type: { type: "number" } });
+        claimKey(third, "trait");
+        expect([labelOf(first), labelOf(second), labelOf(third)]).toEqual(["labelOf/twin#2", "labelOf/twin", "labelOf/twin#3"]);
+    });
+    it("gives a key without a description a numbered label, and names other values as text", () => {
+        const anonymous = Symbol();
+        expect(labelOf(anonymous)).toBe("Symbol()");
+        claimKey(anonymous, "trait");
+        expect(labelOf(anonymous)).toMatch(/^Symbol\(\)(#\d+)?$/);
+        expect([labelOf("text"), labelOf(1)]).toEqual(["text", "1"]);
+    });
+});

package/src/interface/registry/names.ts

@@ -0,0 +1,154 @@
+import type { AnyDeclaration } from './declarations.js';
+import { idOfKey } from './ids.js';
+import { sameItem } from './items.js';
+
+/** What a key names. */
+export type Kind = "component" | "resource" | "trait";
+
+/**
+ * A registered key: its kind, its declaration (none for a trait), its description, its id if the plugin gave one, and
+ * the label it has without one, numbered when another key had its description; shared by every symbol registered under
+ * its id. `first` is the symbol registered first, `newest` the one registered last.
+ */
+type Entry = {
+    readonly kind: Kind;
+    readonly declaration: AnyDeclaration | undefined;
+    readonly description: string;
+    readonly id: string | undefined;
+    readonly numbered: string;
+    readonly first: symbol;
+    newest: symbol;
+};
+
+/** Every component, resource and user trait, by symbol identity: symbols of one id share an entry. */
+const entries = new Map<symbol, Entry>();
+
+/** Entries by the ids the plugin gave their keys. */
+const identified = new Map<string, Entry>();
+
+/** Numbered labels given, so each key's is unique. */
+const labels = new Set<string>();
+
+/** How many registered keys have each description. */
+const described = new Map<string, number>();
+
+/** A symbol's description, `Symbol()` without one. */
+const descriptionOf = (key: symbol): string => key.description === undefined || key.description === "" ? "Symbol()" : key.description;
+
+/** `Symbol.iterator` and the rest, which the platform shares, so they can't be keys. */
+const wellKnown: ReadonlyMap<symbol, string> = new Map(Reflect.ownKeys(Symbol).flatMap((name): [symbol, string][] => {
+    const value: unknown = Reflect.get(Symbol, name);
+    return typeof value === "symbol" ? [[value, `Symbol.${String(name)}`]] : [];
+}));
+
+/** Whether a key is a component, a resource or a trait. */
+export const kindOf = (key: unknown): Kind | undefined => typeof key === "symbol" ? entries.get(key)?.kind : undefined;
+
+/** The declaration of a registered component or resource. */
+export const declarationOf = (key: unknown): AnyDeclaration | undefined => typeof key === "symbol" ? entries.get(key)?.declaration : undefined;
+
+/** Whether two values are one key: the same value, or symbols registered under one id. */
+export const sameKey = (a: unknown, b: unknown): boolean => {
+    if (a === b) return true;
+    if (typeof a !== "symbol" || typeof b !== "symbol") return false;
+    const entry = entries.get(a);
+    return entry !== undefined && entry === entries.get(b);
+};
+
+/** The symbol first registered as this key, which stands for it wherever keys are compared; any other value as it is. */
+export const firstKeyOf = <K>(key: K): K | symbol => typeof key === "symbol" ? entries.get(key)?.first ?? key : key;
+
+/** The symbol last registered as this key, by which a world gives values; any other value as it is. */
+export const newestKeyOf = <K>(key: K): K | symbol => typeof key === "symbol" ? entries.get(key)?.newest ?? key : key;
+
+/**
+ * How errors and reports name a key: its description, `Symbol()` without one, while no other registered key has it;
+ * else its id when the plugin gave it one, and without one, for a registered key, its description numbered by
+ * registration order. Any other value is named as text.
+ */
+export const labelOf = (key: unknown): string => {
+    if (typeof key !== "symbol") return String(key);
+    const known = wellKnown.get(key);
+    if (known !== undefined) return known;
+    const entry = entries.get(key);
+    const description = entry?.description ?? descriptionOf(key);
+    if ((described.get(description) ?? 0) <= (entry === undefined ? 0 : 1)) return description;
+    return entry === undefined ? idOfKey(key) ?? description : entry.id ?? entry.numbered;
+};
+
+/** A label for a key registered now without an id, its description numbered when another key's has it. */
+const numberedFor = (description: string): string => {
+    let label = description;
+    for (let n = 2; labels.has(label); n++) label = `${description}#${n}`;
+    labels.add(label);
+    return label;
+};
+
+/** Throws, naming the key, for a key registration can't take. */
+export const failRegistration = (kind: Kind, key: unknown, message: string): never => {
+    throw new Error(`Cannot register ${kind} "${labelOf(key)}": ${message}`);
+};
+
+/** The key, or a throw for one that isn't a plain `Symbol(...)`: a `Symbol.for` or well-known symbol is shared. */
+export const requireKey = (kind: Kind, key: unknown): symbol => {
+    if (typeof key !== "symbol") return failRegistration(kind, key, `a key is a plain Symbol(...), not a ${typeof key}.`);
+    if (Symbol.keyFor(key) !== undefined) return failRegistration(kind, key, "a Symbol.for key is shared across the program, so another could claim it; use Symbol(...).");
+    const known = wellKnown.get(key);
+    if (known !== undefined) return failRegistration(kind, key, `${known} is a well-known symbol.`);
+    return key;
+};
+
+/**
+ * Whether two declarations are the same, as a module evaluated again declares them, such as on a hot reload. Keys
+ * compare as `sameKey` does, and systems and finalizers they list as `sameItem` does, since evaluating their modules
+ * again makes new values of them.
+ */
+export const sameDeclaration = (a: unknown, b: unknown): boolean => {
+    if (a === b) return true;
+    if (typeof a === "symbol" || typeof b === "symbol") return sameKey(a, b);
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null || Array.isArray(a) !== Array.isArray(b)) return false;
+    if ("declaration" in a && "declaration" in b) return sameItem(a, b);
+    // A set or map, such as a default, compares by its entries in order, as a module evaluated again makes them.
+    if (a instanceof Set) return b instanceof Set && sameDeclaration(Array.from(a), Array.from(b));
+    if (a instanceof Map) return b instanceof Map && sameDeclaration(Array.from(a), Array.from(b));
+    if (b instanceof Set || b instanceof Map) return false;
+    const keys = Reflect.ownKeys(a);
+    const others = Reflect.ownKeys(b);
+    return keys.length === others.length && keys.every(key => {
+        const other = typeof key === "symbol" ? others.find(candidate => sameKey(key, candidate)) : key;
+        return other !== undefined && Reflect.has(b, other) && sameDeclaration(Reflect.get(a, key), Reflect.get(b, other));
+    });
+};
+
+/**
+ * Records a key as a component, resource or trait, with its declaration. A symbol whose id is already a registered
+ * key's, of its kind with the same declaration, as a module evaluated again makes it, is that key. Throws for a key
+ * that isn't a plain `Symbol(...)`, one already registered, or one whose id is another kind's or has another
+ * declaration.
+ */
+export const claimKey = (key: unknown, kind: Kind, declaration?: AnyDeclaration): void => {
+    const symbol = requireKey(kind, key);
+    const existing = entries.get(symbol);
+    if (existing !== undefined) {
+        failRegistration(kind, symbol, existing.kind === kind ? `already registered as a ${kind}, with another declaration.` : `already registered as a ${existing.kind}.`);
+    }
+    const id = idOfKey(symbol);
+    const named = id === undefined ? undefined : identified.get(id);
+    if (named !== undefined) {
+        if (named.kind !== kind) failRegistration(kind, symbol, `its id is a ${named.kind}'s.`);
+        if (!sameDeclaration(named.declaration, declaration)) {
+            failRegistration(kind, symbol, "its id is another key's, with another declaration; if a module was evaluated again with a changed declaration, reload the page.");
+        }
+        named.newest = symbol;
+        entries.set(symbol, named);
+        return;
+    }
+    const description = descriptionOf(symbol);
+    const entry: Entry = { kind, declaration, description, id, numbered: numberedFor(description), first: symbol, newest: symbol };
+    described.set(description, (described.get(description) ?? 0) + 1);
+    if (id !== undefined) identified.set(id, entry);
+    entries.set(symbol, entry);
+};
+
+/** The symbol last registered under an id, by which a world gives values, or undefined where none was. */
+export const keyOfId = (id: string): symbol | undefined => identified.get(id)?.newest;

package/src/interface/registry/program.ts

@@ -0,0 +1,111 @@
+import type { Finalizer } from '../finalizer/created.js';
+import type { Rule } from '../rule/created.js';
+import type { Definition } from '../system/definition.js';
+import { recordItem, registeredAs } from './items.js';
+import { declarationOf, firstKeyOf, labelOf, sameDeclaration } from './names.js';
+import { orderFinalizers } from './finalizer-order.js';
+import { strataOf, type RuleFacts } from './strata.js';
+
+/** What a system, rule or finalizer constructor recorded. */
+export type Item = Definition | Rule | Finalizer;
+
+type Key = symbol;
+
+const rules: Rule[] = [];
+/** In the order every world runs them. */
+let finalizers: readonly Finalizer[] = [];
+let created = 0;
+
+/**
+ * Records a system under the id the plugin gave its declaration. Declared again under that id the same, as a module
+ * evaluated again declares it, it's a new value of the same system. Throws for that id with another kind or declaration.
+ */
+export const claimSystem = (system: Definition, id: string | undefined): void => {
+    recordItem(system, id, registeredAs(system, id, sameDeclaration));
+};
+
+/** Every rule's facts with the `within` hosts of their components, numbered for this check only. Throws for a cycle. */
+const checkStrata = (all: readonly Rule[]): void => {
+    const ids = new Map<Key, number>();
+    const keys: Key[] = [];
+    const hosts: number[] = [];
+    const idOf = (symbol: Key): number => {
+        const key = firstKeyOf(symbol);
+        const existing = ids.get(key);
+        if (existing !== undefined) return existing;
+        const id = keys.length;
+        ids.set(key, id);
+        keys.push(key);
+        hosts.push(-1);
+        const within = declarationOf(key)?.within;
+        if (typeof within === "symbol") hosts[id] = idOf(within);
+        return id;
+    };
+    const facts = all.map((rule): RuleFacts => {
+        const { components, derive } = rule.declaration;
+        return { has: (components.has ?? []).map(idOf), not: (components.not ?? []).map(idOf), derives: derive.map(idOf) };
+    });
+    strataOf(facts, hosts, id => labelOf(keys[id]));
+};
+
+/**
+ * Records a rule under the id the plugin gave its declaration, which applies in every world, and returns it; declared
+ * again under that id the same, it's the rule already recorded. Throws for a cycle through a negation, and for that id
+ * with another kind or declaration.
+ */
+export const addRule = (rule: Rule, id: string | undefined): Rule => {
+    const existing = registeredAs(rule, id, sameDeclaration);
+    const found = existing === undefined ? undefined : rules.find(other => other === existing);
+    if (found !== undefined) return found;
+    checkStrata([...rules, rule]);
+    recordItem(rule, id, undefined);
+    rules.push(rule);
+    created++;
+    return rule;
+};
+
+/**
+ * Records a finalizer under the id the plugin gave its declaration, which applies in every world, and returns it;
+ * declared again under that id the same, it's the finalizer already recorded, which keeps its place with the new body.
+ * Throws for an order that cycles or leaves a resource conflict, and for that id with another kind or declaration.
+ */
+export const addFinalizer = (finalizer: Finalizer, id: string | undefined): Finalizer => {
+    const registered = registeredAs(finalizer, id, sameDeclaration);
+    const existing = registered === undefined ? undefined : finalizers.find(other => other === registered);
+    if (existing?.kind === "finalizer" && finalizer.kind === "finalizer") {
+        existing.body = finalizer.body;
+        return existing;
+    }
+    if (existing?.kind === "changes" && finalizer.kind === "changes") {
+        existing.body = finalizer.body;
+        return existing;
+    }
+    const ordered = orderFinalizers([...finalizers, finalizer]);
+    recordItem(finalizer, id, undefined);
+    finalizers = ordered;
+    created++;
+    return finalizer;
+};
+
+/** Only constructors make values with a system's kind and a declaration. */
+const isDefinition = (system: object): system is Definition =>
+    "declaration" in system && "kind" in system && (system.kind === "system" || system.kind === "render" || system.kind === "composite");
+
+/** A system's definition: the value a System constructor returned, or undefined for any other value. */
+export const definitionOf = (system: { readonly name: string }): Definition | undefined => isDefinition(system) ? system : undefined;
+
+/** A system's definition. Throws for a value no constructor returned. */
+export const requireDefinition = (system: { readonly name: string }): Definition => {
+    const definition = definitionOf(system);
+    if (definition === undefined) throw new Error(`"${String(system.name)}" isn't a system a System constructor returned.`);
+    return definition;
+};
+
+/** Counts rules and finalizers recorded, so a world can tell when one was added since it last looked. */
+export const programVersion = (): number => created;
+
+/** The program's rules, in creation order. */
+export const programRules = (): readonly Rule[] => rules;
+
+/** The program's finalizers, in the order every world runs them. */
+export const programFinalizers = (): readonly Finalizer[] => finalizers;

package/src/interface/registry/reduction.ts

@@ -0,0 +1,7 @@
+import type { Reduction } from '../resource/reduction.js';
+
+/** Every reduction operator. */
+export const reductionOperators: readonly Reduction[] = ["+", "*", "min", "max", "&", "|", "^"];
+
+/** Whether a value is a reduction operator. */
+export const isReduction = (value: unknown): value is Reduction => reductionOperators.some(operator => operator === value);

package/src/interface/registry/schedule.ts

@@ -0,0 +1,215 @@
+import type { Schema } from '../schema/schema.js';
+import type { Definition } from '../system/definition.js';
+import type { Leaf } from '../system/leaf.js';
+import { firstItemOf, labelOfItem } from './items.js';
+import { requireDefinition } from './program.js';
+import { firstKeyOf, labelOf, sameDeclaration } from './names.js';
+import { lookupKeysOf, orderKeysOf } from './indexes.js';
+
+type Key = symbol;
+
+/** Throws unless each leaf's input is an object schema of named fields, and a field several declare has one schema. */
+const checkInputs = (leaves: readonly Leaf[]): void => {
+    const fields = new Map<string, { readonly schema: Schema; readonly system: string }>();
+    for (const leaf of leaves) {
+        const { input } = leaf.declaration;
+        const name = labelOfItem(leaf);
+        if (input === undefined) continue;
+        const schema: Schema = input;
+        if (!("type" in schema) || schema.type !== "object" || typeof schema.properties !== "object" || schema.properties === null) {
+            throw new Error(`System "${name}": input is an object schema of named fields.`);
+        }
+        for (const [field, property] of Object.entries(schema.properties)) {
+            const seen = fields.get(field);
+            if (seen === undefined) fields.set(field, { schema: property, system: name });
+            else if (!sameDeclaration(seen.schema, property)) {
+                throw new Error(`Systems "${seen.system}" and "${name}" declare input field "${field}" with different schemas.`);
+            }
+        }
+    }
+};
+
+/**
+ * Leaves in run order, grouped into tiers. Leaves in one tier have no ordering path between them. `reductions` are the
+ * resources its leaves reduce into, each with how many of them contribute. `observer` are its observer leaves, in no
+ * tier: they run after its sync point, ordered with nothing.
+ */
+export type Schedule = { readonly tiers: readonly (readonly Leaf[])[]; readonly reductions: ReadonlyMap<Key, number>; readonly observer: readonly Leaf[] };
+
+export const isLeaf = (system: Definition): system is Leaf => system.kind !== "composite";
+
+/** Whether a system is an observer leaf, which runs after a sync point rather than in a tier. */
+export const isObserver = (system: Definition): system is Leaf => system.kind !== "composite" && system.declaration.observer === true;
+
+/** Each system is an interval, from its start node to its end node. */
+const start = (unit: number): number => 2 * unit;
+const end = (unit: number): number => 2 * unit + 1;
+
+type Graph = { readonly units: readonly Definition[]; readonly successors: readonly Set<number>[] };
+
+/**
+ * A leaf runs from its start to its end, and a composite spans its members. `after` and `before` order one system's end
+ * before another's start, and `during` places a system inside another's span. The root's own constraints are ignored,
+ * as are constraints naming systems outside it. Values of one system, as a module evaluated again makes them, are one
+ * unit, the first reached.
+ */
+const graphOf = (root: Definition): Graph => {
+    const units: Definition[] = [];
+    const members: (readonly number[])[] = [];
+    const indexOf = new Map<object, number>();
+    const visit = (system: Definition): number => {
+        const first = firstItemOf(system);
+        const known = indexOf.get(first);
+        if (known !== undefined) return known;
+        const unit = units.push(system) - 1;
+        indexOf.set(first, unit);
+        members[unit] = isLeaf(system) ? [] : system.declaration.systems.map(member => visit(requireDefinition(member)));
+        return unit;
+    };
+    visit(root);
+    const successors = units.flatMap(() => [new Set<number>(), new Set<number>()]);
+    // An observer system is ordered with nothing, so constraints naming one are ignored.
+    const resolve = (systems: readonly object[] | undefined): readonly number[] =>
+        (systems ?? []).flatMap(system => {
+            const unit = indexOf.get(firstItemOf(system));
+            return unit === undefined || isObserver(units[unit]) ? [] : [unit];
+        });
+    units.forEach((system, unit) => {
+        successors[start(unit)].add(end(unit));
+        for (const member of members[unit]) {
+            successors[start(unit)].add(start(member));
+            successors[end(member)].add(end(unit));
+        }
+        if (system === root) return;
+        const { before, after, during } = system.declaration;
+        for (const other of resolve(after)) successors[end(other)].add(start(unit));
+        for (const other of resolve(before)) successors[end(unit)].add(start(other));
+        for (const other of resolve(during)) {
+            successors[start(other)].add(start(unit));
+            successors[end(unit)].add(end(other));
+        }
+    });
+    return { units, successors };
+};
+
+/** Kahn's algorithm over nodes. Throws on a cycle. */
+const topologicalOrder = ({ units, successors }: Graph): number[] => {
+    const incoming = successors.map(() => 0);
+    for (const next of successors) for (const node of next) incoming[node]++;
+    const order: number[] = [];
+    const ready = successors.map((_, node) => node).filter(node => incoming[node] === 0);
+    while (ready.length > 0) {
+        const node = ready.pop() ?? 0;
+        order.push(node);
+        for (const next of successors[node]) if (--incoming[next] === 0) ready.push(next);
+    }
+    if (order.length < successors.length) {
+        const cyclic = units.filter((_, unit) => incoming[start(unit)] > 0 || incoming[end(unit)] > 0).map(system => `"${labelOfItem(system)}"`);
+        throw new Error(`Ordering cycle between ${cyclic.join(", ")}.`);
+    }
+    return order;
+};
+
+/** `reach[a]` has bit `b` set when there's a path from node `a` to node `b`. */
+const reachability = (order: readonly number[], successors: readonly Set<number>[]): Uint32Array[] => {
+    const words = Math.ceil(order.length / 32);
+    const reach = order.map(() => new Uint32Array(words));
+    for (let i = order.length - 1; i >= 0; i--) {
+        const node = order[i];
+        for (const next of successors[node]) {
+            reach[node][next >>> 5] |= 1 << (next & 31);
+            for (let w = 0; w < words; w++) reach[node][w] |= reach[next][w];
+        }
+    }
+    return reach;
+};
+
+const reaches = (reach: readonly Uint32Array[], from: number, to: number): boolean => (reach[from][to >>> 5] & (1 << (to & 31))) !== 0;
+
+/** Whether one of two systems ends before the other starts. */
+const ordered = (reach: readonly Uint32Array[], a: number, b: number): boolean => reaches(reach, end(a), start(b)) || reaches(reach, end(b), start(a));
+
+/** Each node's tier: the most leaves on any path to it, so a leaf's tier is where it starts. */
+const depthsOf = ({ units, successors }: Graph, order: readonly number[]): number[] => {
+    const depth = successors.map(() => 0);
+    for (const node of order) {
+        const step = node % 2 === 0 && isLeaf(units[node >>> 1]) && !isObserver(units[node >>> 1]) ? 1 : 0;
+        for (const next of successors[node]) depth[next] = Math.max(depth[next], depth[node] + (next === node + 1 ? step : 0));
+    }
+    return depth;
+};
+
+type Access = { readonly reads: ReadonlySet<Key>; readonly writes: ReadonlySet<Key>; readonly reduces: ReadonlySet<Key> };
+
+/** The resources a leaf reduces into. */
+export const reducedBy = (leaf: Leaf): readonly Key[] => {
+    const { reduce } = leaf.declaration;
+    return reduce === undefined ? [] : Object.getOwnPropertySymbols(reduce).filter(key => Reflect.get(reduce, key) !== undefined);
+};
+
+/**
+ * Reads include change filters, since they observe writers' ticks, and the key parts of indexes looked up through or
+ * ordered by, which the index is found and kept by. Presence-only lists don't conflict. Keys are each one's first
+ * symbol.
+ */
+export const accessOf = (leaf: Leaf): Access => {
+    const { components, lookup, resources, up } = leaf.declaration;
+    const reads = new Set<Key>([...components?.read ?? [], ...components?.added ?? [], ...components?.changed ?? [], ...resources?.read ?? [], ...resources?.changed ?? []].map(firstKeyOf));
+    for (const name in lookup) for (const key of [...lookup[name].read ?? [], ...lookupKeysOf(lookup[name])]) reads.add(firstKeyOf(key));
+    for (const key of orderKeysOf(leaf.declaration)) reads.add(firstKeyOf(key));
+    if (up !== undefined) for (const key of [up.through, ...up.read ?? []]) reads.add(firstKeyOf(key));
+    const writes = new Set<Key>([...components?.write ?? [], ...resources?.write ?? []].map(firstKeyOf));
+    return { reads, writes, reduces: new Set(reducedBy(leaf).map(firstKeyOf)) };
+};
+
+/** Contributors to one resource don't conflict with each other: their fold doesn't depend on which runs first. */
+const conflictOf = (a: Access, b: Access): Key | undefined => {
+    for (const key of a.writes) if (b.writes.has(key) || b.reads.has(key) || b.reduces.has(key)) return key;
+    for (const key of b.writes) if (a.reads.has(key) || a.reduces.has(key)) return key;
+    return undefined;
+};
+
+const schedules = new WeakMap<Definition, Schedule>();
+
+/** A system's schedule, created once per system. Throws on a cycle, or on two conflicting leaves with no ordering path between them. */
+export const scheduleOf = (system: Definition): Schedule => {
+    let schedule = schedules.get(system);
+    if (schedule === undefined) schedules.set(system, schedule = createSchedule(system));
+    return schedule;
+};
+
+/**
+ * Orders a system's leaves into tiers. Throws on a cycle, on two conflicting leaves with no ordering path between them,
+ * or on inputs that don't merge.
+ */
+const createSchedule = (system: Definition): Schedule => {
+    const graph = graphOf(system);
+    const observer = graph.units.filter(isObserver);
+    const leaves = graph.units.flatMap((unit, index) => isLeaf(unit) && !isObserver(unit) ? [{ leaf: unit, unit: index }] : []);
+    checkInputs(leaves.map(({ leaf }) => leaf));
+    const accesses = leaves.map(({ leaf }) => accessOf(leaf));
+    // Leaves that read a resource run after every leaf that reduces into it, so they read the finished fold.
+    const reductions = new Map<Key, number>();
+    accesses.forEach((access, contributor) => {
+        for (const key of access.reduces) {
+            reductions.set(key, (reductions.get(key) ?? 0) + 1);
+            accesses.forEach((other, reader) => {
+                if (reader !== contributor && other.reads.has(key)) graph.successors[end(leaves[contributor].unit)].add(start(leaves[reader].unit));
+            });
+        }
+    });
+    const order = topologicalOrder(graph);
+    const reach = reachability(order, graph.successors);
+    for (let a = 0; a < leaves.length; a++) {
+        for (let b = a + 1; b < leaves.length; b++) {
+            const key = conflictOf(accesses[a], accesses[b]);
+            if (key !== undefined && !ordered(reach, leaves[a].unit, leaves[b].unit)) {
+                throw new Error(`Systems "${labelOfItem(leaves[a].leaf)}" and "${labelOfItem(leaves[b].leaf)}" both access "${labelOf(key)}" and one writes it; order them with before or after.`);
+            }
+        }
+    }
+    const depth = depthsOf(graph, order);
+    const tiers: Leaf[][] = [];
+    for (const { leaf, unit } of leaves) (tiers[depth[start(unit)]] ??= []).push(leaf);
+    return { tiers: tiers.filter(tier => tier !== undefined), reductions, observer };
+};

package/src/interface/registry/schemas.ts

@@ -0,0 +1,61 @@
+import type { Schema } from '../schema/schema.js';
+
+/** Whether a constant is a struct's value: numbers and booleans, in fixed arrays and objects. */
+const isStructValue = (value: unknown): boolean =>
+    typeof value === "number" || typeof value === "boolean"
+    || (Array.isArray(value) ? value.every(isStructValue) : typeof value === "object" && value !== null && Object.values(value).every(isStructValue));
+
+/** Whether a schema describes a struct: numbers, booleans, entities, fixed-length tuples and structs of those. */
+export const isStruct = (schema: Schema): boolean => {
+    if ("const" in schema) return isStructValue(schema.const);
+    if (!("type" in schema)) return false;
+    switch (schema.type) {
+        case "number":
+        case "integer":
+        case "boolean":
+            return true;
+        case "array":
+            return schema.minItems !== undefined && schema.minItems === schema.maxItems && isStruct(schema.items);
+        case "object": {
+            const { required, properties } = schema;
+            const names = Object.keys(properties);
+            return (required === undefined || names.every(name => required.includes(name))) && names.every(name => isStruct(properties[name]));
+        }
+        default:
+            return false;
+    }
+};
+
+const isNull = (schema: Schema): boolean => ("type" in schema && schema.type === "null") || ("const" in schema && schema.const === null);
+
+/** Whether a schema describes a string: any string, a string `const`, or a union of those, with `null` or without. */
+export const isString = (schema: Schema): boolean => {
+    if ("const" in schema) return typeof schema.const === "string";
+    if ("anyOf" in schema) return schema.anyOf.some(isString) && schema.anyOf.every(member => isString(member) || isNull(member));
+    return "type" in schema && schema.type === "string";
+};
+
+const hasBooleanValue = (value: unknown): boolean =>
+    typeof value === "boolean" || (typeof value === "object" && value !== null && Object.values(value).some(hasBooleanValue));
+
+/** Whether a struct schema has a boolean leaf. */
+export const hasBoolean = (schema: Schema): boolean => {
+    if ("const" in schema) return hasBooleanValue(schema.const);
+    if (!("type" in schema)) return false;
+    if (schema.type === "boolean") return true;
+    if (schema.type === "array") return hasBoolean(schema.items);
+    if (schema.type === "object") return Object.values(schema.properties).some(hasBoolean);
+    return false;
+};
+
+/** Whether a schema accepts `null`, so a value of it may start there. */
+export const allowsNull = (schema: Schema): boolean =>
+    ("type" in schema && schema.type === "null") || ("const" in schema && schema.const === null) || ("anyOf" in schema && schema.anyOf.some(allowsNull));
+
+/** Whether a schema is an entity's. */
+export const isEntity = (schema: Schema): boolean => "format" in schema && schema.format === "entity";
+
+/** Whether a schema accepts `null` or `false`, so a system can run on the condition of a value of it. */
+export const conditional = (schema: Schema): boolean =>
+    allowsNull(schema) || ("type" in schema && schema.type === "boolean") || ("const" in schema && schema.const === false)
+    || ("anyOf" in schema && schema.anyOf.some(conditional));