@adobe/ecs 0.2.3 → 0.2.4

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 left out. */
+    readonly resolve: (systems: readonly object[] | 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
@@ -86,7 +99,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. */
@@ -165,6 +178,74 @@ const conflictOf = (a: Access, b: Access): Key | undefined => {
     return undefined;
 };
 
+/** Every key two accesses conflict on. */
+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)),
+])];
+
+/** 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 };
+};
+
+/**
+ * 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 } = 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 object[] | 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"
+                : [...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 +260,125 @@ 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("");
+                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 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;
+    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/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);
 };
 
 /**

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 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,
+     * 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,15 @@ 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.
+     * - `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>;
+    }): 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

@@ -14,7 +14,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: undefined };
     checkLeaf(system);
     claimSystem(system, undefined);
     return system;

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

@@ -171,6 +171,14 @@ describe("System.create of a composite", () => {
         const looped = System.create({ before: [first], after: [second] }, () => {});
         expect(() => System.create({ systems: [first, second, looped] })).toThrow("Ordering cycle");
     });
+    it("takes a row declared whole as written, every member but references, and says so in a conflict", () => {
+        const pass = (row: object): void => { void row; };
+        const whole = System.create({ components: { with: [position, parent], whole: true } }, row => { pass(row); });
+        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.');
+    });
     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; });
         const watch = System.create({ readonly: true, components: { with: [position] } }, row => { void row[position]; });

package/src/interface/system/create.ts

@@ -16,8 +16,9 @@ import type { Listed, Property } from './property.js';
 import type { System } from './system.js';
 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, compact, componentLists, lookupsLists, resourceUses, upReads, whereReadsOf } from './resolve.js';
+import { accessOf, commandLists, compact, componentLists, lookupsLists, resourceUses, upReads, whereReadsOf } from './resolve.js';
 
 type Lookups<D> = Property<D, "lookup">;
 
@@ -68,9 +69,10 @@ type Targeted = {
     readonly order?: never;
 };
 
+
 /** `where` names only shared components, and keeps rows unordered across archetypes, so it's without `up`, `order` and a target. */
 type Where<D> = D extends { readonly components: { readonly where: infer W } }
-    ? { readonly components?: { readonly where?: { readonly [K in Exclude<keyof W, Shared>]: { readonly "error: where names only shared components, which each archetype holds one value of": K } } } }
+    ? { readonly components?: { readonly where?: SharedOnly<W> } }
         & (D extends { readonly up: object } | { readonly order: object } | { readonly target: string }
             ? { readonly components?: { readonly where?: { readonly "error: where can't be used with up, order or a target, which run rows across archetypes": true } } } : {})
     : {};
@@ -99,6 +101,7 @@ type Validate<D extends Declaration> =
         ? { readonly kernel?: boolean | { readonly "error: a GPU kernel can't have optional components yet": true } } : {})
     & (D extends { readonly readonly: true } ? Readonly : {})
     // Tables are copies a readonly system without components reads.
+    & (D extends { readonly tables: { readonly where: infer W } } ? { readonly tables?: { readonly where?: SharedOnly<W> } } : {})
     & (D extends { readonly tables: object }
         ? (D extends { readonly readonly: true } ? {} : { readonly tables?: { readonly "error: tables are read by a readonly system": true } })
         & (Property<D, "components"> extends undefined ? {} : { readonly tables?: { readonly "error: a system reading tables has no components": true } })
@@ -175,9 +178,10 @@ export function create(first: Declaration | Leaf["body"] | readonly System<unkno
     const body = typeof first === "function" ? first : second;
     if (body === undefined) throw new Error("A system needs a body, and a composite its systems.");
     const name = nameOf(first, id, "system");
-    const declaration = resolve(`System "${name}"`, declared, accessOf(`System "${name}"`, first));
+    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 };
+    const system: Leaf & System<unknown> = { kind: "system", name, declaration, input: schema, body, commands: commandLists(access) };
     checkLeaf(system);
     claimSystem(system, id);
     return system;
@@ -194,7 +198,7 @@ const resolve = (what: string, declared: Declaration, access: ReturnType<typeof
     for (const key of [...whereReads, ...declared.tables?.resources ?? []]) if (!uses.read.includes(key) && !uses.write.includes(key) && !conditions.includes(key)) uses.read.push(key);
     const resolved: Resolved = {
         ...rest,
-        ...components === undefined ? {} : { components: componentLists(components, access.components, reading, whereReads) },
+        ...components === undefined ? {} : { components: componentLists(components, components.whole === true ? null : access.components, reading, whereReads) },
         ...lookup === undefined ? {} : { lookup: lookupsLists(lookup, access) },
         ...up === undefined ? {} : { up: { through: up.through, read: upReads(what, access) } },
     };

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

@@ -0,0 +1,79 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Index } from "../indexes/index-type.js";
+import { System } from "./system.js";
+
+const position = Symbol("describeTest/position");
+const cell = Symbol("describeTest/cell");
+const speed = Symbol("describeTest/speed");
+const hover = Symbol("describeTest/hover");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [position]: { type: number };
+        [cell]: { type: number };
+    }
+    export interface Resources {
+        [speed]: { type: number };
+        [hover]: { type: number };
+    }
+}
+
+const byCell = Index.create({ key: [cell] });
+
+const spawnCells = System.create(({ commands }) => { commands.spawn([position])({ [position]: 1 }); });
+const move = System.create({ components: { with: [position] }, after: [spawnCells] }, (row, { resources }) => { row[position] += resources[speed]; });
+const deriveCells = System.create({ components: { with: [position], not: [cell] }, after: [move] }, (row, { commands }) => { commands.add(row.entity, cell, row[position]); });
+const pick = System.create({ lookup: { cells: { index: byCell } }, after: [deriveCells] }, ({ lookup, resources }) => { resources[hover] = lookup.cells(1).length; });
+const nudge = System.create({ components: { with: [position], whole: true } }, row => { Reflect.set(row, position, 0); });
+const watch = System.create({ readonly: true, components: { with: [position] } }, row => { void row[position]; });
+const frame = System.create([spawnCells, move, deriveCells, pick, watch]);
+
+describe("System.describe", () => {
+    it("gives tiers in run order, readonly systems apart, and what each system uses, as data", () => {
+        const described = System.describe(frame);
+        expect(described.tiers.map(tier => tier.systems.map(system => system.name))).toEqual([["spawnCells"], ["move"], ["deriveCells"], ["pick"]]);
+        expect(described.readonly.map(system => system.system)).toEqual([watch]);
+        const [[spawning], [moving], [deriving], [picking]] = described.tiers.map(tier => tier.systems);
+        expect(spawning?.commands).toEqual({ spawn: [position], add: [], remove: [], despawn: false });
+        expect([moving?.components.write, moving?.resources.read, moving?.commands?.add]).toEqual([[position], [speed], []]);
+        expect([deriving?.components.read, deriving?.components.not, deriving?.commands?.add]).toEqual([[position], [cell], [cell]]);
+        expect([picking?.lookups, picking?.resources.write]).toEqual([[{ name: "cells", index: "byCell", read: [] }], [hover]]);
+        expect(moving?.after).toEqual([{ system: spawnCells, name: "spawnCells", because: "after", conflicts: [] }]);
+        expect(deriving?.after).toEqual([{ system: move, name: "move", because: "after", conflicts: [position] }]);
+        expect(System.describe(nudge).tiers[0]?.systems[0]?.whole).toBe(true);
+    });
+    it("gives the fewest sync points between tiers whose commands a later system depends on, and why", () => {
+        expect(System.describe(frame).tiers.map(tier => tier.sync)).toEqual([
+            [{ from: spawnCells, to: move, keys: [position] }, { from: spawnCells, to: deriveCells, keys: [position] }],
+            null,
+            [{ from: deriveCells, to: pick, keys: [cell] }],
+            null,
+        ]);
+        // Despawning may change anything a later system matches; writing values needs no sync point.
+        const clear = System.create({ components: { with: [cell] } }, (row, { commands }) => { commands.despawn(row.entity); });
+        const count = System.create({ components: { with: [position] }, after: [clear] }, row => { void row[position]; });
+        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("gives a text form to read", () => {
+        expect(System.describe(frame).text).toBe([
+            "tier 0  spawnCells   commands  spawn describeTest/position",
+            "sync    spawnCells's commands of describeTest/position, for move",
+            "        spawnCells's commands of describeTest/position, for deriveCells",
+            "tier 1  move         writes    describeTest/position",
+            "                     resources reads describeTest/speed",
+            "                     after     spawnCells (after)",
+            "tier 2  deriveCells  reads     describeTest/position",
+            "                     requires  not describeTest/cell",
+            "                     commands  add describeTest/cell",
+            "                     after     move (after: describeTest/position)",
+            "sync    deriveCells's commands of describeTest/cell, for pick",
+            "tier 3  pick         resources writes describeTest/hover",
+            "                     looks up  cells through byCell",
+            "                     after     deriveCells (after)",
+            "readonly",
+            "        watch        reads     describeTest/position",
+        ].join("\n"));
+    });
+});