@adobe/ecs 0.2.4 → 0.3.0

package/src/interface/finalizer/create.ts

@@ -6,13 +6,13 @@ 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 { Listed, Property } from '../system/property.js';
+import type { Property } from '../system/property.js';
 import type { ThreadOfComponent } from '../component/value.js';
 import type { ThreadOfResource } from '../resource/value.js';
 import type { Resource } from '../resource/resource.js';
 import type { Component } from '../component/component.js';
 import type { Elsewhere, OneThread, ThreadedBy, ThreadsOf } from '../system/threads.js';
-import type { ChangeSet, Context, Row, Watched, WatchedResources } from './body.js';
+import type { ChangeSet, Context, Row, Watched, WatchedResources, WatchListed } from './body.js';
 import type { Changes, Leaf } from './created.js';
 import type { ChangesDeclaration, Declaration, Resolved, ResolvedChanges } from './declaration.js';
 import { accessOf, compact, lookupsLists, resourceUses, type Access } from '../system/resolve.js';
@@ -28,7 +28,7 @@ type Remote<D> = true extends Elsewhere<ThreadsOf<D>>
     : {};
 
 /** 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> | ThreadOfResource<Listed<D, "watch"> & Resource.Key>>
+type OnWorld<D extends ChangesDeclaration> = true extends Elsewhere<ThreadsOf<D> | ThreadOfComponent<Extract<WatchListed<D, "components">, Component.Key>> | ThreadOfResource<Extract<WatchListed<D, "resources">, Resource.Key>>>
     ? { readonly "error: a changes finalizer watches and reads only the world's thread's objects": true }
     : {};
 
@@ -127,6 +127,39 @@ export const create = <const D extends Declaration>(
     return addFinalizer(finalizer, id);
 };
 
+const isList = (watch: NonNullable<ChangesDeclaration["watch"]>): watch is Extract<ChangesDeclaration["watch"], readonly unknown[]> => Array.isArray(watch);
+
+/** What a changes finalizer watches, sorted by kind. Throws for a key that's neither of the kinds it's listed as, or derived. */
+const watchOf = (name: string, watch: ChangesDeclaration["watch"]): ResolvedChanges["watch"] => {
+    const components: symbol[] = [];
+    const componentTraits: symbol[] = [];
+    const resources: symbol[] = [];
+    const resourceTraits: symbol[] = [];
+    const sort = (key: unknown, kinds: readonly ("component" | "resource")[]): void => {
+        const kind = kindOf(key);
+        if (typeof key !== "symbol" || kind === undefined || (kind !== "trait" && !kinds.includes(kind))) {
+            const among = kinds.length === 2 ? "" : ` among its ${kinds[0]}s`;
+            throw new Error(`Finalizer "${name}" watches "${labelOf(key)}"${among}, which isn't a registered ${kinds.length === 2 ? "component, resource" : kinds[0]} or trait: ${whyUnregistered(key)}.`);
+        }
+        if (kind === "trait") {
+            if (kinds.includes("component")) componentTraits.push(key);
+            if (kinds.includes("resource")) resourceTraits.push(key);
+            return;
+        }
+        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.`);
+        (kind === "component" ? components : resources).push(key);
+    };
+    if (watch === undefined) return { components: true, componentTraits, resources, resourceTraits };
+    if (isList(watch)) {
+        for (const key of watch) sort(key, ["component", "resource"]);
+        return { components, componentTraits, resources, resourceTraits };
+    }
+    const every = watch.components === true;
+    if (!every) for (const key of watch.components) sort(key, ["component"]);
+    for (const key of watch.resources) sort(key, ["resource"]);
+    return { components: every ? true : components, componentTraits: every ? [] : componentTraits, resources, resourceTraits };
+};
+
 /**
  * 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, a
@@ -139,7 +172,7 @@ export const changes = <const D extends ChangesDeclaration>(
     const id = takeIdOfDeclaration(declared);
     const name = nameOf(declared, id, "finalizer");
     const what = `Finalizer "${name}"`;
-    const declaration: ResolvedChanges = { ...resolveShared(what, declared, accessOf(what, declared)), ...declared.watch === undefined ? {} : { watch: declared.watch } };
+    const declaration: ResolvedChanges = { ...resolveShared(what, declared, accessOf(what, declared)), watch: watchOf(name, declared.watch) };
     const finalizer: Changes = { kind: "changes", name, declaration, body };
     checkResources(name, declaration.resources);
     requireRegistered("Finalizer", name, "resource", declaration.resources?.read);
@@ -149,14 +182,9 @@ export const changes = <const D extends ChangesDeclaration>(
         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 ?? []) {
-        const kind = kindOf(key);
-        if (kind !== "component" && kind !== "resource") throw new Error(`Finalizer "${name}" watches "${labelOf(key)}", which isn't a registered component or resource: ${whyUnregistered(key)}.`);
-        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 watched = (kind: "component" | "resource"): readonly symbol[] => (declaration.watch ?? []).filter(key => kindOf(key) === kind);
-    const read = [...declaration.resources?.read ?? [], ...watched("resource")];
-    const thread = threadOf({ components: { read: watched("component") }, resources: { ...declaration.resources, read }, lookup: declaration.lookup }, "Finalizer", name);
+    const { watch } = declaration;
+    const read = [...declaration.resources?.read ?? [], ...watch.resources];
+    const thread = threadOf({ components: { read: watch.components === true ? [] : watch.components }, resources: { ...declaration.resources, read }, 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/declaration.ts

@@ -5,6 +5,8 @@ import type { Lookup } from '../system/access.js';
 import type { Finalizer } from './finalizer.js';
 import type { Essential } from '../component/value.js';
 import type { Resource } from '../resource/resource.js';
+import type { Traits } from '../trait/types.js';
+import type { BuiltIn } from '../trait/key.js';
 
 /**
  * What every finalizer declares. What its body reads of its row and lookups, and reads and writes of resources, the
@@ -25,12 +27,23 @@ export type Declaration = Shared & {
     readonly components: { readonly with?: readonly Component.Key[]; readonly optional?: readonly Component.Key[]; readonly not?: readonly Component.Key[] };
 };
 
+/** A trait of your own, which watches every component and resource declaring it. */
+export type OwnTrait = Exclude<keyof Traits<never>, BuiltIn>;
+
 /**
- * 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; and the resources it watches, none by default, written since the
- * last sync point's finalizers ran.
+ * A finalizer that sees each sync point's structural changes to the components it watches, and the resources it
+ * watches written since the last sync point's finalizers ran. By default it watches every component that isn't derived
+ * or an object a joined thread fills, and no resource. `watch` lists components, resources and traits of your own, or,
+ * as an object, every component (`components: true`) or those listed, beside the resources listed. A trait watches each
+ * component and resource declaring it, as each registers, but those the default leaves out and resources on another
+ * thread.
  */
-export type ChangesDeclaration = Shared & { readonly watch?: readonly (Essential | Resource.Key)[] };
+export type ChangesDeclaration = Shared & {
+    readonly watch?: readonly (Essential | Resource.Key | OwnTrait)[] | {
+        readonly components: true | readonly (Essential | OwnTrait)[];
+        readonly resources: readonly (Resource.Key | OwnTrait)[];
+    };
+};
 
 type Key = symbol;
 
@@ -47,4 +60,16 @@ export type Resolved = ResolvedShared & {
     readonly components: { readonly read?: readonly Key[]; readonly has?: readonly Key[]; readonly optional?: readonly Key[]; readonly not?: readonly Key[] };
 };
 
-export type ResolvedChanges = ResolvedShared & { readonly watch?: readonly Key[] };
+/**
+ * A changes finalizer's declaration as the world takes it. It watches the components listed, or every one (`true`),
+ * and those declaring a trait of `componentTraits`; the resources listed, and those declaring a trait of
+ * `resourceTraits`.
+ */
+export type ResolvedChanges = ResolvedShared & {
+    readonly watch: {
+        readonly components: true | readonly Key[];
+        readonly componentTraits: readonly Key[];
+        readonly resources: readonly Key[];
+        readonly resourceTraits: readonly Key[];
+    };
+};

package/src/interface/registry/index.ts

@@ -3,7 +3,7 @@
 export type { AnyDeclaration } from './declarations.js';
 export { schemaOf, threadOfDeclaration } from './declarations.js';
 export type { Kind } from './names.js';
-export { declarationOf, firstKeyOf, keyOfId, kindOf, labelOf, newestKeyOf, whyUnregistered } from './names.js';
+export { declarationOf, declaresTrait, declaredOf, firstKeyOf, keyOfId, keysVersion, kindOf, labelOf, newestKeyOf, whyUnregistered } from './names.js';
 export type { Item } from './program.js';
 export { definitionOf, programFinalizers, programRules, programVersion, requireDefinition } from './program.js';
 export type { Schedule } from './schedule.js';

package/src/interface/registry/names.ts

@@ -22,6 +22,9 @@ type Entry = {
 /** Every component, resource and user trait, by symbol identity: symbols of one id share an entry. */
 const entries = new Map<symbol, Entry>();
 
+/** How many keys were registered, counting a symbol registered under another's id. */
+let registered = 0;
+
 /** Entries by the ids the plugin gave their keys. */
 const identified = new Map<string, Entry>();
 
@@ -155,12 +158,28 @@ export const claimKey = (key: unknown, kind: Kind, declaration?: AnyDeclaration)
         }
         named.newest = symbol;
         entries.set(symbol, named);
+        registered++;
         return;
     }
     const description = descriptionOf(symbol);
     const entry: Entry = { kind, declaration, description, id, first: symbol, newest: symbol };
     if (id !== undefined) identified.set(id, entry);
     entries.set(symbol, entry);
+    registered++;
+};
+
+/** How many keys are registered so far, so a world can tell when one registered since it last looked. */
+export const keysVersion = (): number => {
+    catchUp();
+    return registered;
+};
+
+/** Whether a component's or resource's declaration declares one of `traits`, keys of traits of your own. */
+export const declaresTrait = (key: unknown, traits: readonly symbol[]): boolean => {
+    const declaration = declarationOf(key);
+    if (declaration === undefined) return false;
+    for (const declared of Object.getOwnPropertySymbols(declaration)) for (const trait of traits) if (sameKey(declared, trait)) return true;
+    return false;
 };
 
 /** The symbol last registered under an id, by which a world gives values, or undefined where none was. */

package/src/interface/registry/schedule.ts

@@ -53,8 +53,8 @@ type Graph = {
     readonly successors: readonly Set<number>[];
     /** Each unit's members, by unit: none for a leaf. */
     readonly members: readonly (readonly number[])[];
-    /** The units a list of systems names, readonly systems left out. */
-    readonly resolve: (systems: readonly object[] | undefined) => readonly number[];
+    /** The units a list of systems names, readonly systems and resources left out. */
+    readonly resolve: (systems: readonly unknown[] | undefined) => readonly number[];
 };
 
 /**
@@ -79,8 +79,9 @@ const graphOf = (root: Definition): Graph => {
     visit(root);
     const successors = units.flatMap(() => [new Set<number>(), new Set<number>()]);
     // A readonly system is ordered with nothing, so constraints naming one are ignored.
-    const resolve = (systems: readonly object[] | undefined): readonly number[] =>
+    const resolve = (systems: readonly unknown[] | undefined): readonly number[] =>
         (systems ?? []).flatMap(system => {
+            if (typeof system !== "object" || system === null) return [];
             const unit = indexOf.get(firstItemOf(system));
             return unit === undefined || isObserver(units[unit]) ? [] : [unit];
         });
@@ -149,7 +150,7 @@ const depthsOf = ({ units, successors }: Graph, order: readonly number[]): numbe
     return depth;
 };
 
-type Access = { readonly reads: ReadonlySet<Key>; readonly writes: ReadonlySet<Key>; readonly reduces: ReadonlySet<Key> };
+type Access = { readonly reads: ReadonlySet<Key>; readonly writes: ReadonlySet<Key>; readonly reduces: ReadonlySet<Key>; readonly leaf: Leaf };
 
 /** The resources a leaf reduces into. */
 export const reducedBy = (leaf: Leaf): readonly Key[] => {
@@ -168,21 +169,53 @@ export const accessOf = (leaf: Leaf): Access => {
     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)) };
+    return { reads, writes, reduces: new Set(reducedBy(leaf).map(firstKeyOf)), leaf };
 };
 
-/** Contributors to one resource don't conflict with each other: their fold doesn't depend on which runs first. */
+const names = (list: readonly Key[] | undefined, key: Key): boolean => list !== undefined && list.some(item => firstKeyOf(item) === key);
+
+/** Whether a leaf reaches a key only through its rows: neither looked up, read through `up`, indexed nor ordered by. */
+const onlyThroughRows = (leaf: Leaf, key: Key): boolean => {
+    const { components, lookup, up } = leaf.declaration;
+    if (!names(components?.read, key) && !names(components?.write, key) && !names(components?.added, key) && !names(components?.changed, key)) return false;
+    for (const name in lookup) if (names(lookup[name].read, key) || names(lookupKeysOf(lookup[name]), key)) return false;
+    if (names(orderKeysOf(leaf.declaration), key)) return false;
+    return up === undefined || (firstKeyOf(up.through) !== key && !names(up.read, key));
+};
+
+/** Whether no entity can match both leaves' rows: one requires a component the other's `not` lists. */
+const exclusive = (a: Leaf, b: Leaf): boolean => {
+    const requiresExcluded = (one: Leaf, other: Leaf): boolean => {
+        const { components } = one.declaration;
+        const not = other.declaration.components?.not;
+        if (components === undefined || not === undefined || not.length === 0) return false;
+        for (const list of [components.read, components.write, components.has, components.added, components.changed]) {
+            for (const key of list ?? []) if (!names(components.optional, firstKeyOf(key)) && names(not, firstKeyOf(key))) return true;
+        }
+        return false;
+    };
+    return requiresExcluded(a, b) || requiresExcluded(b, a);
+};
+
+/** Whether a conflict on `key` is waived: both reach it only through rows that never match one entity. */
+const waived = (a: Access, b: Access, key: Key): boolean => onlyThroughRows(a.leaf, key) && onlyThroughRows(b.leaf, key) && exclusive(a.leaf, b.leaf);
+
+/**
+ * The first key two accesses conflict on, one writing it, or undefined. Contributors to one resource don't conflict
+ * with each other: their fold doesn't depend on which runs first. Nor do two whose rows never match one entity on a key
+ * both reach only through their rows.
+ */
 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;
+    for (const key of a.writes) if ((b.writes.has(key) || b.reads.has(key) || b.reduces.has(key)) && !waived(a, b, key)) return key;
+    for (const key of b.writes) if ((a.reads.has(key) || a.reduces.has(key)) && !waived(a, b, key)) return key;
     return undefined;
 };
 
-/** Every key two accesses conflict on. */
+/** Every key two accesses conflict on, as `conflictOf` finds the first. */
 const conflictsOf = (a: Access, b: Access): readonly Key[] => [...new Set([
     ...[...a.writes].filter(key => b.writes.has(key) || b.reads.has(key) || b.reduces.has(key)),
     ...[...b.writes].filter(key => a.reads.has(key) || a.reduces.has(key)),
-])];
+])].filter(key => !waived(a, b, key));
 
 /** A system's leaves in its tiers, with their units and accesses, and its graph with readers of folds after their contributors. */
 const orderedOf = (system: Definition) => {
@@ -199,7 +232,46 @@ const orderedOf = (system: Definition) => {
             });
         }
     });
-    return { graph, leaves, accesses, reductions };
+    return { graph, leaves, accesses, reductions, keyed: orderByResources(graph, leaves, accesses) };
+};
+
+const noneKeyed: ReadonlyMap<string, "before" | "after"> = new Map();
+
+const listsResource = (list: readonly unknown[] | undefined): boolean => list !== undefined && list.some(item => typeof item === "symbol");
+
+/** The resources a list of `before` or `after` names, each by its first symbol. */
+const resourcesIn = (list: readonly unknown[] | undefined): readonly Key[] =>
+    (list ?? []).flatMap(item => typeof item === "symbol" ? [firstKeyOf(item)] : []);
+
+/**
+ * Orders each leaf naming a resource in `before` or `after` before or after every other leaf using it, adding the edges
+ * to `graph`: but one its constraints already order the other way, and one naming the resource in the same list. By
+ * unit, as `"<earlier> <later>"`, the list that ordered each pair.
+ */
+const orderByResources = (graph: Graph, leaves: readonly { readonly leaf: Leaf; readonly unit: number }[], accesses: readonly Access[]): ReadonlyMap<string, "before" | "after"> => {
+    if (!leaves.some(({ leaf }) => listsResource(leaf.declaration.before) || listsResource(leaf.declaration.after))) return noneKeyed;
+    const keyed = new Map<string, "before" | "after">();
+    const lists = leaves.map(({ leaf }) => ({ before: resourcesIn(leaf.declaration.before), after: resourcesIn(leaf.declaration.after) }));
+    const uses = leaves.map(({ leaf }, index) => new Set([...accesses[index].reads, ...accesses[index].writes, ...accesses[index].reduces,
+        ...[...leaf.declaration.resources?.is ?? [], ...leaf.declaration.resources?.not ?? []].map(firstKeyOf)]));
+    const reach = reachability(topologicalOrder(graph), graph.successors);
+    const edges: (readonly [number, number, "before" | "after"])[] = [];
+    leaves.forEach(({ unit }, index) => {
+        for (const list of ["before", "after"] as const) {
+            for (const key of lists[index][list]) {
+                leaves.forEach((other, o) => {
+                    if (o === index || !uses[o].has(key) || lists[o][list].includes(key)) return;
+                    const [earlier, later] = list === "before" ? [unit, other.unit] : [other.unit, unit];
+                    if (!reaches(reach, end(later), start(earlier))) edges.push([earlier, later, list]);
+                });
+            }
+        }
+    });
+    for (const [earlier, later, list] of edges) {
+        graph.successors[end(earlier)].add(start(later));
+        keyed.set(`${earlier} ${later}`, list);
+    }
+    return keyed;
 };
 
 /**
@@ -214,7 +286,7 @@ export type Placement = { readonly leaf: Leaf; readonly because: "after" | "befo
  * leaf of its tiers.
  */
 export const placementsOf = (system: Definition): ReadonlyMap<Leaf, readonly Placement[]> => {
-    const { graph, leaves, accesses } = orderedOf(system);
+    const { graph, leaves, accesses, keyed } = orderedOf(system);
     const reach = reachability(topologicalOrder(graph), graph.successors);
     const ancestors = graph.units.map(() => [] as number[]);
     graph.members.forEach((members, unit) => {
@@ -225,7 +297,7 @@ export const placementsOf = (system: Definition): ReadonlyMap<Leaf, readonly Pla
         for (const member of members) visit(member);
     });
     /** Whether `systems` names `unit` or a composite holding it. */
-    const names = (systems: readonly object[] | undefined, unit: number): boolean => {
+    const names = (systems: readonly unknown[] | undefined, unit: number): boolean => {
         const named = graph.resolve(systems);
         return named.includes(unit) || ancestors[unit].some(holder => named.includes(holder));
     };
@@ -239,7 +311,7 @@ export const placementsOf = (system: Definition): ReadonlyMap<Leaf, readonly Pla
             const other = leaves[a];
             const because = constrains(unit, "after", other.unit) ? "after"
                 : constrains(other.unit, "before", unit) ? "before"
-                : [...accesses[a].reduces].some(key => accesses[b].reads.has(key)) ? "reduction" : "during";
+                : keyed.get(`${other.unit} ${unit}`) ?? ([...accesses[a].reduces].some(key => accesses[b].reads.has(key)) ? "reduction" : "during");
             return { leaf: other.leaf, because, conflicts: conflictsOf(accesses[a], accesses[b]) };
         }));
     });
@@ -271,7 +343,8 @@ const createSchedule = (system: Definition): Schedule => {
             if (key !== undefined && !ordered(reach, leaves[a].unit, leaves[b].unit)) {
                 const whole = [leaves[a].leaf, leaves[b].leaf].filter(leaf => leaf.declaration.components?.whole === true)
                     .map(leaf => ` "${leaf.name}" takes its row whole (components.whole), so it writes every member.`).join("");
-                throw new Error(`Systems "${leaves[a].leaf.name}" and "${leaves[b].leaf.name}" both access "${labelOf(key)}" and one writes it; order them with before or after.${whole}`);
+                const rows = onlyThroughRows(leaves[a].leaf, key) && onlyThroughRows(leaves[b].leaf, key) ? ", or, if they never match one entity, add a component of one to the other's not" : "";
+                throw new Error(`Systems "${leaves[a].leaf.name}" and "${leaves[b].leaf.name}" both access "${labelOf(key)}" and one writes it; order them with before or after${rows}.${whole}`);
             }
         }
     }
@@ -305,7 +378,7 @@ export type SyncReason = { readonly from: Leaf; readonly to: Leaf; readonly keys
 
 /** The components a leaf's commands may add or remove, by spawn, add or remove; `"any"` once it despawns or isn't followed. */
 const structuralOf = (leaf: Leaf): ReadonlySet<Key> | "any" | null => {
-    const { commands } = leaf;
+    const commands = leaf.commands();
     if (commands === undefined) return null;
     if (commands === null || commands.despawn === true) return "any";
     const keys = new Set([...commands.spawn ?? [], ...commands.add ?? [], ...commands.remove ?? []].map(firstKeyOf));

package/src/interface/rule/rule.type-test.ts

@@ -7,7 +7,7 @@ import { System } from '../system/system.js';
 import type { Create } from '../world/create.js';
 import type { World } from '../world/world.js';
 import { Rule } from './rule.js';
-import type { Writable } from '../component/value.js';
+import type { Essential, Writable } from '../component/value.js';
 import type { ChangeSet } from '../finalizer/body.js';
 
 type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
@@ -18,6 +18,9 @@ const hidden = Symbol("ruleTypeTest/hidden");
 const slot = Symbol("ruleTypeTest/slot");
 const parent = Symbol("ruleTypeTest/parent");
 const time = Symbol("ruleTypeTest/time");
+const inDocument = Symbol("ruleTypeTest/inDocument");
+const kept = Symbol("ruleTypeTest/kept");
+const saved = Symbol("ruleTypeTest/saved");
 
 declare module '@adobe/ecs' {
     export interface Components {
@@ -25,9 +28,14 @@ declare module '@adobe/ecs' {
         [hidden]: { type: true };
         [slot]: { type: number; derived: true };
         [parent]: { type: Entity; reference: "owner" };
+        [kept]: { type: number; [inDocument]: true };
     }
     export interface Resources {
         [time]: { type: number };
+        [saved]: { type: number; [inDocument]: true };
+    }
+    export interface Traits<N> {
+        readonly [inDocument]: N extends unknown ? true : never;
     }
 }
 
@@ -81,6 +89,20 @@ Finalizer.changes({ watch: [source, parent] }, (changes, { commands }) => {
 // @ts-expect-error changes finalizers don't watch derived components
 Finalizer.changes({ watch: [slot] }, () => {});
 
+// A trait of your own watches every component and resource declaring it.
+Finalizer.changes({ watch: [inDocument, source] }, changes => {
+    check<Equal<typeof changes, ChangeSet<typeof kept | typeof source, typeof saved>>>();
+});
+// Every component, and the resources chosen, by key or trait.
+Finalizer.changes({ watch: { components: true, resources: [time, inDocument] } }, changes => {
+    check<Equal<typeof changes, ChangeSet<Essential, typeof time | typeof saved>>>();
+});
+Finalizer.changes({ watch: { components: [inDocument], resources: [] } }, changes => {
+    check<Equal<typeof changes, ChangeSet<typeof kept>>>();
+});
+// @ts-expect-error components lists components and traits, resources resources and traits
+Finalizer.changes({ watch: { components: [time], resources: [source] } }, () => {});
+
 // References change only through commands, so systems can't write them.
 System.create({ components: { with: [parent, source] } }, row => { row[source] = row[parent]; });
 System.create({ components: { with: [parent] } }, row => {

package/src/interface/system/check.ts

@@ -220,6 +220,8 @@ export const checkLeaf = (leaf: Leaf): void => {
     threadOf(declaration, "System", name);
     requireRegistered("System", name, "component", components?.has);
     requireRegistered("System", name, "component", components?.not);
+    if (declaration.before !== undefined) requireRegistered("System", name, "resource", declaration.before.filter(item => typeof item === "symbol"));
+    if (declaration.after !== undefined) requireRegistered("System", name, "resource", declaration.after.filter(item => typeof item === "symbol"));
     for (const lookupName in lookup) {
         const found = lookup[lookupName];
         requireRegistered("System", name, "component", "has" in found ? found.has : undefined);

package/src/interface/system/commands.ts

@@ -65,9 +65,9 @@ export type Commands = {
     ): (...values: SpawnValues<C, P>) => Entity;
     despawn(entity: Entity): void;
     /**
-     * Despawns, as a `despawn` of each would, every entity that has each component of `with` and none of `not` once the
-     * commands issued before it apply, and every entity spawned at the same sync point that does, whenever spawned.
-     * Derived components may be named. `where` keeps it to the archetypes holding these values of shared components,
+     * Despawns, as a `despawn` of each would, every entity alive before its sync point that has each component of
+     * `with` and none of `not` once the commands issued before it apply, as a row system over the same query despawning
+     * each of its rows would; never one the sync point spawns, whenever spawned. Derived components may be named. `where` keeps it to the archetypes holding these values of shared components,
      * each one required as `with` requires it, as a system's `where` of values does. Never the resource entity. Only on
      * the world's thread: a joined thread's throws.
      */
@@ -94,11 +94,16 @@ export type Commands = {
      * - `existing` maps entities to ones already alive in this world, which stand for them: a row whose entity it maps
      *   isn't spawned, its entry in the result is the entity it maps to, and every value naming one it maps names that
      *   entity, whether or not it's in the tables. Fails for one that isn't alive.
+     * - `update` writes each row `existing` maps onto the entity standing for it, as `commands.add` of its table's
+     *   components would: adding those the entity lacks, replacing and marking changed those it has, and leaving its
+     *   other components as they are. Its entity values are rewritten as a spawned row's are, but a reference naming an
+     *   entity that isn't there, weak or owner, is left out, so the entity's own stands.
      * - `resources` sets each resource it names, by key, at the sync point, as commands apply, each value checked
      *   against its resource's schema; not one only the world writes, nor one living on another thread.
      */
     spawnTables(tables: readonly Table[], options?: {
         readonly resources?: { readonly [key: symbol]: unknown };
         readonly existing?: ReadonlyMap<Entity, Entity>;
+        readonly update?: boolean;
     }): Table.Spawned;
 };

package/src/interface/system/create-resolved.ts

@@ -3,6 +3,7 @@ import { nameOf } from '../registry/items.js';
 import { claimSystem } from '../registry/program.js';
 import { checkLeaf, inputSchemaOf } from './check.js';
 import type { Resolved } from './declaration.js';
+import { noCommands } from './resolve.js';
 import type { Leaf } from './leaf.js';
 import type { System } from './system.js';
 
@@ -14,7 +15,7 @@ import type { System } from './system.js';
 export const createResolved = (declaration: Resolved, body: Leaf["body"], input?: unknown): System<unknown> => {
     const name = nameOf(declaration, undefined, "system");
     const schema = inputSchemaOf(name, body, declaration.components === undefined ? 1 : 2, input);
-    const system: Leaf & System<unknown> = { kind: "system", name, declaration, input: schema, body, commands: undefined };
+    const system: Leaf & System<unknown> = { kind: "system", name, declaration, input: schema, body, commands: noCommands };
     checkLeaf(system);
     claimSystem(system, undefined);
     return system;

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

@@ -49,7 +49,7 @@ describe("System.create", () => {
         const body = (): void => {};
         // A body the build doesn't see is given what it uses.
         const move = System.create(giveAccess({ components: { with: [position] } }, { write: [position], resources: { read: [time] } }), body);
-        expect(definitionOf(move)).toEqual({ kind: "system", name: "move", declaration: { components: { write: [position] }, resources: { read: [time] } }, body });
+        expect(definitionOf(move)).toEqual({ kind: "system", name: "move", declaration: { components: { write: [position] }, resources: { read: [time] } }, body, commands: expect.any(Function) });
         expect(move.name).toBe("move");
         expect(definitionOf({ name: "move" })).toBe(undefined);
     });
@@ -71,7 +71,7 @@ describe("System.create", () => {
     it("labels a system made with neither an id nor a binding by its kind numbered", () => {
         const body = ({ commands }: { readonly commands: System.Commands }): void => { commands.spawn([position])({ [position]: 0 }); };
         const [alone] = [System.create(giveAccess(identify(body, "setup.ts#spawnOnce")))];
-        expect(definitionOf(alone)).toEqual({ kind: "system", name: "spawnOnce", declaration: {}, body });
+        expect(definitionOf(alone)).toEqual({ kind: "system", name: "spawnOnce", declaration: {}, body, commands: expect.any(Function) });
         const [first, second] = [System.create(() => {}), System.create({ systems: [alone] })].map(system => system.name);
         const number = Number(first?.slice("system #".length));
         expect([first, second]).toEqual([`system #${number}`, `system #${number + 1}`]);
@@ -177,7 +177,7 @@ describe("System.create of a composite", () => {
         const reader = System.create({ components: { with: [position] } }, row => { void row[position]; });
         const definition = definitionOf(whole);
         expect(definition?.kind === "system" ? definition.declaration.components : null).toEqual({ read: [parent], write: [position], whole: true });
-        expect(() => System.create([whole, reader])).toThrow('both access "typesSystemTest/position" and one writes it; order them with before or after. "whole" takes its row whole (components.whole), so it writes every member.');
+        expect(() => System.create([whole, reader])).toThrow(`both access "typesSystemTest/position" and one writes it; order them with before or after, or, if they never match one entity, add a component of one to the other's not. "whole" takes its row whole (components.whole), so it writes every member.`);
     });
     it("runs readonly members after its sync point, in no tier, never conflicting and ignoring constraints naming them", () => {
         const write = System.create({ components: { with: [position] } }, row => { row[position] += 1; });

package/src/interface/system/create.ts

@@ -18,7 +18,7 @@ import type { OneThread, ThreadedBy, ThreadsOf } from './threads.js';
 import type { HeldBy } from './values.js';
 import type { SharedOnly } from './shared-only.js';
 import type { Shared } from '../component/value.js';
-import { accessOf, commandLists, compact, componentLists, lookupsLists, resourceUses, upReads, whereReadsOf } from './resolve.js';
+import { accessOf, commandListsOf, compact, componentLists, lookupsLists, resourceUses, upReads, whereReadsOf } from './resolve.js';
 
 type Lookups<D> = Property<D, "lookup">;
 
@@ -181,7 +181,7 @@ export function create(first: Declaration | Leaf["body"] | readonly System<unkno
     const access = accessOf(`System "${name}"`, first);
     const declaration = resolve(`System "${name}"`, declared, access);
     const schema = inputSchemaOf(name, body, declaration.components === undefined ? 1 : 2, input);
-    const system: Leaf & System<unknown> = { kind: "system", name, declaration, input: schema, body, commands: commandLists(access) };
+    const system: Leaf & System<unknown> = { kind: "system", name, declaration, input: schema, body, commands: commandListsOf(`System "${name}"`, access) };
     checkLeaf(system);
     claimSystem(system, id);
     return system;

package/src/interface/system/declaration.ts

@@ -52,10 +52,16 @@ export type Declaration = {
     readonly target?: string;
     /** Makes this a render system (see `render`): its body records GPU work over the GPU copy of the components it names. */
     readonly shader?: Shader;
-    /** Hard constraint. */
-    readonly before?: readonly System<unknown>[];
-    /** Hard constraint. */
-    readonly after?: readonly System<unknown>[];
+    /**
+     * Hard constraint: runs before each system listed, and, for a resource listed, before every other system of the
+     * composite that uses it, but those its constraints already order before it and those listing it in `before` too.
+     */
+    readonly before?: readonly (System<unknown> | Resource.Key)[];
+    /**
+     * Hard constraint: runs after each system listed, and, for a resource listed, after every other system of the
+     * composite that uses it, but those its constraints already order after it and those listing it in `after` too.
+     */
+    readonly after?: readonly (System<unknown> | Resource.Key)[];
     /** Runs inside the span of the systems listed: after what they follow and before what follows them. */
     readonly during?: readonly System<unknown>[];
     /**

package/src/interface/system/describe.test.ts

@@ -56,6 +56,25 @@ describe("System.describe", () => {
         const tally = System.create({ after: [count] }, ({ resources }) => { resources[hover] = resources[speed]; });
         expect(System.describe(System.create([clear, count, tally])).tiers.map(tier => tier.sync)).toEqual([[{ from: clear, to: count, keys: [] }], null, null]);
     });
+    it("lists no conflict on a key two systems reach through rows that never match one entity", () => {
+        const placeCells = System.create({ components: { with: [position, cell] } }, row => { row[cell] = row[position]; });
+        const clearCells = System.create({ components: { with: [cell], not: [position] }, after: [placeCells] }, row => { row[cell] = 0; });
+        expect(System.describe(System.create([placeCells, clearCells])).tiers[1]?.systems[0]?.after).toEqual([{ system: placeCells, name: "placeCells", because: "after", conflicts: [] }]);
+    });
+    it("says a system follows another by a resource one lists in before or after", () => {
+        const setSpeed = System.create({ before: [speed] }, ({ resources }) => { resources[speed] = 2; });
+        const readSpeed = System.create({ components: { with: [position] } }, (row, { resources }) => { row[position] = resources[speed]; });
+        const readHover = System.create({ after: [hover] }, ({ resources }) => resources[hover] + resources[speed]);
+        const setHover = System.create({ after: [setSpeed] }, ({ resources }) => { resources[hover] = 1; });
+        const described = System.describe(System.create([readHover, readSpeed, setHover, setSpeed]));
+        expect(described.tiers.map(tier => tier.systems.map(system => [system.name, system.after.map(placement => [placement.name, placement.because])]))).toEqual([
+            [["setSpeed", []]],
+            [["readSpeed", [["setSpeed", "before"]]], ["setHover", [["setSpeed", "after"]]]],
+            [["readHover", [["setHover", "after"]]]],
+        ]);
+        // @ts-expect-error ordering takes resources, not components
+        expect(() => System.create({ after: [position] }, () => {})).toThrow(`uses resource "describeTest/position", which isn't a registered resource`);
+    });
     it("gives a text form to read", () => {
         expect(System.describe(frame).text).toBe([
             "tier 0  spawnCells   commands  spawn describeTest/position",

package/src/interface/system/describe.ts

@@ -16,7 +16,7 @@ const asSystem = (leaf: Leaf): System<unknown, unknown> => leaf;
 /** What the build inferred one system uses, and what placed it, as plain data. */
 const describeLeaf = (leaf: Leaf, placements: readonly Placement[]) => {
     const { components, resources, lookup, up, order } = leaf.declaration;
-    const { commands } = leaf;
+    const commands = leaf.commands();
     return {
         /** The system, the value its constructor returned. */
         system: asSystem(leaf),

package/src/interface/system/leaf.ts

@@ -19,8 +19,9 @@ export type Leaf = {
     readonly input: InputSchema | undefined;
     readonly body: (...parameters: never[]) => void;
     /**
-     * What its body's commands name, as the build inferred them: null where it couldn't follow them, undefined for
-     * none. Apart from its declaration, so a module evaluated again with other commands declares the same system.
+     * What its body's commands name, as the build inferred them, read at first need: null where it couldn't follow
+     * them, undefined for none. Apart from its declaration, so a module evaluated again with other commands declares the
+     * same system.
      */
-    readonly commands?: CommandLists | null;
+    readonly commands: () => CommandLists | null | undefined;
 };