@adobe/ecs 0.2.3 → 0.3.0

package/src/interface/registry/schedule.ts

@@ -4,8 +4,8 @@ import type { Definition } from '../system/definition.js';
 import type { Leaf } from '../system/leaf.js';
 import { firstItemOf } from './items.js';
 import { requireDefinition } from './program.js';
-import { firstKeyOf, labelOf, sameDeclaration } from './names.js';
-import { lookupKeysOf, orderKeysOf } from './indexes.js';
+import { declarationOf, firstKeyOf, labelOf, sameDeclaration } from './names.js';
+import { indexDefinitionOf, lookupKeysOf, orderKeysOf } from './indexes.js';
 
 type Key = symbol;
 
@@ -29,9 +29,15 @@ const checkInputs = (leaves: readonly Leaf[]): void => {
 /**
  * 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 readonly leaves, in no
- * tier: they run after its sync point, ordered with nothing.
+ * tier: they run after its sync point, ordered with nothing. `syncs` holds, after each tier, the reasons for a sync
+ * point there, which applies the commands so far before the next tier, or null for none.
  */
-export type Schedule = { readonly tiers: readonly (readonly Leaf[])[]; readonly reductions: ReadonlyMap<Key, number>; readonly observer: readonly Leaf[] };
+export type Schedule = {
+    readonly tiers: readonly (readonly Leaf[])[];
+    readonly reductions: ReadonlyMap<Key, number>;
+    readonly observer: readonly Leaf[];
+    readonly syncs: readonly (readonly SyncReason[] | null)[];
+};
 
 export const isLeaf = (system: Definition): system is Leaf => system.kind !== "composite";
 
@@ -42,7 +48,14 @@ export const isObserver = (system: Definition): system is Leaf & { readonly decl
 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>[] };
+type Graph = {
+    readonly units: readonly Definition[];
+    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 and resources left out. */
+    readonly resolve: (systems: readonly unknown[] | undefined) => readonly number[];
+};
 
 /**
  * A leaf runs from its start to its end, and a composite spans its members. `after` and `before` order one system's end
@@ -66,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];
         });
@@ -86,7 +100,7 @@ const graphOf = (root: Definition): Graph => {
             successors[end(unit)].add(end(other));
         }
     });
-    return { units, successors };
+    return { units, successors, members, resolve };
 };
 
 /** Kahn's algorithm over nodes. Throws on a cycle. */
@@ -136,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[] => {
@@ -155,16 +169,155 @@ 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 };
+};
+
+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));
 };
 
-/** Contributors to one resource don't conflict with each other: their fold doesn't depend on which runs first. */
+/** 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, 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) => {
+    const graph = graphOf(system);
+    const leaves = graph.units.flatMap((unit, index) => isLeaf(unit) && !isObserver(unit) ? [{ leaf: unit, unit: index }] : []);
+    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));
+            });
+        }
+    });
+    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;
+};
+
+/**
+ * What put a leaf after another: a constraint of either, or of a composite holding it, naming the other or a composite
+ * holding it (`after`, `before`), its reading a fold the other contributes to (`reduction`), or being placed during a
+ * span (`during`). `conflicts` are the keys both access, one writing, which need the order.
+ */
+export type Placement = { readonly leaf: Leaf; readonly because: "after" | "before" | "during" | "reduction"; readonly conflicts: readonly Key[] };
+
+/**
+ * For each leaf in a system's tiers, the leaves it follows directly: those with an ordering path to it through no other
+ * leaf of its tiers.
+ */
+export const placementsOf = (system: Definition): ReadonlyMap<Leaf, readonly Placement[]> => {
+    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) => {
+        const visit = (member: number): void => {
+            ancestors[member].push(unit);
+            for (const inner of graph.members[member]) visit(inner);
+        };
+        for (const member of members) visit(member);
+    });
+    /** Whether `systems` names `unit` or a composite holding it. */
+    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));
+    };
+    const constrains = (unit: number, list: "after" | "before", other: number): boolean =>
+        [unit, ...ancestors[unit]].some(holder => holder !== 0 && names(graph.units[holder].declaration[list], other));
+    const placements = new Map<Leaf, readonly Placement[]>();
+    leaves.forEach(({ leaf, unit }, b) => {
+        const before = leaves.flatMap((other, a) => a !== b && reaches(reach, end(other.unit), start(unit)) ? [a] : []);
+        const direct = before.filter(a => !before.some(other => other !== a && reaches(reach, end(leaves[a].unit), start(leaves[other].unit))));
+        placements.set(leaf, direct.map(a => {
+            const other = leaves[a];
+            const because = constrains(unit, "after", other.unit) ? "after"
+                : constrains(other.unit, "before", unit) ? "before"
+                : 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]) };
+        }));
+    });
+    return placements;
+};
+
 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. */
@@ -179,33 +332,126 @@ export const scheduleOf = (system: Definition): Schedule => {
  * or on inputs that don't merge.
  */
 const createSchedule = (system: Definition): Schedule => {
-    const graph = graphOf(system);
+    const { graph, leaves, accesses, reductions } = orderedOf(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 "${leaves[a].leaf.name}" and "${leaves[b].leaf.name}" both access "${labelOf(key)}" and one writes it; order them with before or after.`);
+                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("");
+                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}`);
             }
         }
     }
     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 };
+    const byDepth: Leaf[][] = [];
+    for (const { leaf, unit } of leaves) (byDepth[depth[start(unit)]] ??= []).push(leaf);
+    const tiers = byDepth.filter(tier => tier !== undefined);
+    // A sync point comes between tiers, so a schedule of one tier has none.
+    if (tiers.length < 2) return { tiers, reductions, observer, syncs: tiers.map(() => null) };
+    const tierOf = new Map<Leaf, number>();
+    tiers.forEach((tier, t) => { for (const leaf of tier) tierOf.set(leaf, t); });
+    const edges: { readonly lo: number; readonly hi: number; readonly reason: SyncReason }[] = [];
+    leaves.forEach((from, a) => {
+        const changed = structuralOf(from.leaf);
+        if (changed === null) return;
+        leaves.forEach((to, b) => {
+            if (a === b || !reaches(reach, end(from.unit), start(to.unit))) return;
+            const keys = affected(changed, touchesOf(to.leaf));
+            if (keys !== null) edges.push({ lo: tierOf.get(from.leaf) ?? 0, hi: (tierOf.get(to.leaf) ?? 0) - 1, reason: { from: from.leaf, to: to.leaf, keys } });
+        });
+    });
+    return { tiers, reductions, observer, syncs: syncsOf(tiers.length, edges) };
+};
+
+/**
+ * Why a sync point follows a tier: a system in it or before it whose commands may change, structurally, what a system
+ * after the sync point that follows it reads, matches, looks up or indexes. `keys` are the components its commands name
+ * that the later one uses, none where it despawns, or where its commands or a cascade could change anything.
+ */
+export type SyncReason = { readonly from: Leaf; readonly to: Leaf; readonly keys: readonly Key[] };
+
+/** 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.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));
+    // A reference written may despawn its holder, or remove itself, at the sync point.
+    for (const key of keys) if (declarationOf(key)?.reference !== undefined) return "any";
+    return keys.size === 0 ? null : keys;
+};
+
+/**
+ * The components a leaf's rows, lookups, indexes and order name, which commands could change its view of; `any` when
+ * one of them matches every entity, `cascaded` when it names a component a rule derives or `within` removes.
+ */
+const touchesOf = (leaf: Leaf): { readonly keys: ReadonlySet<Key>; readonly any: boolean; readonly cascaded: boolean } => {
+    const { components, lookup, up, order } = leaf.declaration;
+    const keys = new Set<Key>();
+    let any = false;
+    const add = (list: readonly Key[] | undefined): void => { for (const key of list ?? []) keys.add(firstKeyOf(key)); };
+    /** Names what a query requires; one requiring nothing matches every entity. */
+    const requires = (required: readonly (readonly Key[] | undefined)[], others: readonly (readonly Key[] | undefined)[]): void => {
+        if (required.every(list => list === undefined || list.length === 0)) any = true;
+        for (const list of [...required, ...others]) add(list);
+    };
+    const indexed = (index: unknown): void => {
+        const declaration = indexDefinitionOf(index)?.declaration;
+        if (declaration !== undefined) requires([declaration.key, declaration.components?.has], [declaration.components?.not]);
+    };
+    if (components !== undefined) {
+        requires([components.read, components.write, components.has, components.added, components.changed], [components.optional, components.not]);
+        add(Object.getOwnPropertySymbols(components.where ?? {}));
+    }
+    for (const name in lookup) {
+        const used = lookup[name];
+        if ("index" in used && used.index !== undefined) {
+            indexed(used.index);
+            add(used.read);
+        }
+        else if (!("index" in used)) requires([used.read, used.has], [used.optional, used.not, Array.isArray(used.changed) ? used.changed : undefined]);
+    }
+    if (order !== undefined) indexed(order);
+    if (up !== undefined) add([up.through, ...up.read ?? []]);
+    const cascaded = [...keys].some(key => { const declared = declarationOf(key); return declared?.derived === true || declared?.within !== undefined; });
+    return { keys, any, cascaded };
+};
+
+/** The keys through which `changed` may change what `touches` names; null where it can't. */
+const affected = (changed: ReadonlySet<Key> | "any", touches: ReturnType<typeof touchesOf>): readonly Key[] | null => {
+    if (touches.keys.size === 0 && !touches.any) return null;
+    if (changed === "any") return [];
+    if (touches.any || touches.cascaded) return [...changed];
+    const keys = [...changed].filter(key => touches.keys.has(key));
+    return keys.length === 0 ? null : keys;
+};
+
+/**
+ * The fewest sync points that put one between the tiers of each edge, after a tier from `lo` to `hi`: each placed as
+ * late as the first edge it must cover allows, so it covers every edge open then. An edge's reason goes to the first
+ * sync point within its tiers.
+ */
+const syncsOf = (count: number, edges: readonly { readonly lo: number; readonly hi: number; readonly reason: SyncReason }[]): readonly (readonly SyncReason[] | null)[] => {
+    const syncs: (SyncReason[] | null)[] = new Array<SyncReason[] | null>(count).fill(null);
+    let last = -1;
+    for (const { lo, hi } of [...edges].sort((a, b) => a.hi - b.hi)) {
+        if (last >= lo) continue;
+        last = hi;
+        syncs[hi] = [];
+    }
+    for (const { lo, hi, reason } of edges) {
+        for (let t = lo; t <= hi; t++) {
+            const reasons = syncs[t];
+            if (reasons === null) continue;
+            reasons.push(reason);
+            break;
+        }
+    }
+    return syncs;
 };

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/access.ts

@@ -27,6 +27,12 @@ export type ComponentAccess = {
      * change filters, an archetype it skipped keeps its rows unseen until it passes again.
      */
     readonly where?: { readonly [K in Shared]?: Component<K> | ((value: Component<K>, context: { readonly resources: ReadResources }) => boolean) };
+    /**
+     * Takes its row whole, as a body passing it on does, where the build can't follow how it's used: every member counts
+     * as written, for order, conflicts and placement, but references and shared components, which change only through
+     * commands, as read. Without it, a body whose row the build can't follow fails the build.
+     */
+    readonly whole?: true;
 };
 
 /**
@@ -85,6 +91,8 @@ export type ComponentLists = {
     readonly where?: { readonly [key: symbol]: unknown };
     /** The resources its `where`'s predicates read, which the build infers: when one changed, they're evaluated again. */
     readonly whereReads?: readonly Key[];
+    /** Whether it takes its row whole, as its declaration said. */
+    readonly whole?: true;
 };
 
 /** A lookup as the world takes it, with what its body reads of its rows in `read`. */
@@ -105,3 +113,11 @@ export type ResourceLists = {
     readonly is?: readonly Key[];
     readonly not?: readonly Key[];
 };
+
+/** The components a system's commands name, by kind, and whether it despawns, as the build inferred them. */
+export type CommandLists = {
+    readonly spawn?: readonly Key[];
+    readonly add?: readonly Key[];
+    readonly remove?: readonly Key[];
+    readonly despawn?: true;
+};

package/src/interface/system/check.ts

@@ -138,11 +138,23 @@ const checkWhere = (leaf: Leaf): void => {
     const where = declaration.components?.where;
     if (where === undefined) return;
     if (declaration.up !== undefined || declaration.order !== undefined || declaration.target !== undefined) throw new Error(`System "${name}" uses where with up, order or a target, which run rows across archetypes.`);
+    checkWhereValues(`System "${name}"`, "where", "a system", where, true);
+};
+
+/**
+ * Throws for a `where`, the one `named` says of `subject`, which keeps what `keeps` says to archetypes, naming what
+ * isn't a shared component or giving one a value not of its type, or a predicate unless `predicates`.
+ */
+export const checkWhereValues = (subject: string, named: string, keeps: string, where: { readonly [key: symbol]: unknown }, predicates: boolean): void => {
     for (const key of Object.getOwnPropertySymbols(where)) {
         const found = declarationOf(key);
-        if (kindOf(key) !== "component" || found?.shared !== true) throw new Error(`System "${name}": where names "${labelOf(key)}", which isn't a shared component: where keeps a system to archetypes by their shared values.`);
+        if (kindOf(key) !== "component" || found?.shared !== true) throw new Error(`${subject}: ${named} names "${labelOf(key)}", which isn't a shared component: where keeps ${keeps} to archetypes by their shared values.`);
         const value: unknown = Reflect.get(where, key);
-        if (typeof value !== "function" && found.type !== undefined && !matchesSchema(found.type, value)) throw new Error(`System "${name}": where gives "${labelOf(key)}" ${labelOf(value)}, which isn't one of its type's values.`);
+        if (typeof value === "function") {
+            if (!predicates) throw new Error(`${subject}: ${named} gives "${labelOf(key)}" a predicate, and takes only values.`);
+            continue;
+        }
+        if (found.type !== undefined && !matchesSchema(found.type, value)) throw new Error(`${subject}: ${named} gives "${labelOf(key)}" ${labelOf(value)}, which isn't one of its type's values.`);
     }
 };
 
@@ -176,6 +188,7 @@ const checkTables = (leaf: Leaf): void => {
     requireRegistered("System", name, "component", tables.with);
     requireRegistered("System", name, "component", tables.not);
     requireRegistered("System", name, "resource", tables.resources);
+    if (tables.where !== undefined) checkWhereValues(`System "${name}"`, "tables' where", "tables", tables.where, false);
 };
 
 /**
@@ -207,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

@@ -3,6 +3,7 @@ import type { Component } from '../component/component.js';
 import type { Entity } from '../entity/entity.js';
 import type { Essential, Shared } from '../component/value.js';
 import type { Table } from '../world/table/table.js';
+import type { SharedOnly } from './shared-only.js';
 import type { ValuesOf } from './values-of.js';
 
 /** The value an `add` of one component takes: none for a tag. */
@@ -63,6 +64,18 @@ export type Commands = {
         ...constant: RequiresPreset<C> extends true ? [constant?: P & SharedPreset<C> & Named<C, P>] : [constant?: P & Named<C, P>]
     ): (...values: SpawnValues<C, P>) => Entity;
     despawn(entity: Entity): void;
+    /**
+     * 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.
+     */
+    despawnWhere<const W extends object = {}>(query: {
+        readonly with: readonly [Component.Key, ...Component.Key[]];
+        readonly not?: readonly Component.Key[];
+        readonly where?: W & SharedOnly<NoInfer<W>> & { readonly [K in Shared]?: Component<K> };
+    }): void;
     /** Adds or replaces one component's value, marking it changed. */
     add<K extends Essential>(entity: Entity, component: K, ...value: ValueArgument<K>): void;
     /** Adds or replaces the values of `components`, marking them changed. */
@@ -77,9 +90,20 @@ export type Commands = {
      * outside them isn't spawned, nor anything it owns, through owner references, as despawning its owner would; a
      * weak reference to one is left out of its row, which is spawned without it; any other value naming one is
      * `Entity.none`. Returns, at once, each table's new entities, alive at the sync point. A column's stride must be its
-     * component's in this world, and its length its table's count. `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. On the world's thread only.
+     * component's in this world, and its length its table's count. On the world's thread only.
+     * - `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[], resources?: { readonly [key: symbol]: unknown }): Table.Spawned;
+    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/commands.type-test.ts

@@ -13,6 +13,7 @@ const label = Symbol("commandsTypeTest/label");
 const player = Symbol("commandsTypeTest/player");
 const slot = Symbol("commandsTypeTest/slot");
 const time = Symbol("commandsTypeTest/time");
+const chunk = Symbol("commandsTypeTest/chunk");
 declare module '@adobe/ecs' {
     export interface Components {
         [position]: { type: number };
@@ -20,6 +21,7 @@ declare module '@adobe/ecs' {
         [label]: { type: string | null };
         [player]: { type: true };
         [slot]: { type: number; derived: true };
+        [chunk]: { type: number; shared: true };
     }
     export interface Resources {
         [time]: { type: number };
@@ -84,4 +86,33 @@ export const issue = (commands: Commands, entity: Entity): void => {
     // @ts-expect-error commands never remove a derived component
     commands.remove(entity, slot);
     commands.despawn(entity);
+
+    // `despawnWhere` takes a query of at least one component, derived ones included.
+    commands.despawnWhere({ with: [player] });
+    commands.despawnWhere({ with: [position, slot], not: [player] });
+    commands.despawnWhere({ with: particle });
+    // @ts-expect-error `with` names at least one component
+    commands.despawnWhere({ with: [] });
+    // @ts-expect-error a query names components, not resources
+    commands.despawnWhere({ with: [time] });
+    // @ts-expect-error in `not` too
+    commands.despawnWhere({ with: [player], not: [time] });
+    // @ts-expect-error it takes a query, not an entity
+    commands.despawnWhere(entity);
+    // Its `where` gives values of shared components, as a system's `where` of values does.
+    commands.despawnWhere({ with: [position], where: { [chunk]: 3 } });
+    const unloaded = { [chunk]: 4 } as const;
+    commands.despawnWhere({ with: [position], where: unloaded });
+    // @ts-expect-error a value of the component's type
+    commands.despawnWhere({ with: [position], where: { [chunk]: "3" } });
+    // @ts-expect-error where names only shared components
+    commands.despawnWhere({ with: [position], where: { [position]: 3 } });
+    // @ts-expect-error where takes values, not predicates
+    commands.despawnWhere({ with: [position], where: { [chunk]: (value: number) => value > 3 } });
+    const placed = { [position]: 3 } as const;
+    // @ts-expect-error where names only shared components, in a constant too
+    commands.despawnWhere({ with: [position], where: placed });
+    const mixed = { [chunk]: 3, [position]: 3 } as const;
+    // @ts-expect-error and in a constant naming a shared one beside it
+    commands.despawnWhere({ with: [position], where: mixed });
 };

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 };
+    const system: Leaf & System<unknown> = { kind: "system", name, declaration, input: schema, body, commands: noCommands };
     checkLeaf(system);
     claimSystem(system, undefined);
     return system;