@adobe/ecs 0.2.3 → 0.3.0

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}`]);
@@ -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, 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; });
         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, commandListsOf, 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: commandListsOf(`System "${name}"`, 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/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

@@ -0,0 +1,98 @@
+// © 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("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",
+            "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"));
+    });
+});

package/src/interface/system/describe.ts

@@ -0,0 +1,122 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { indexDefinitionOf } from '../registry/indexes.js';
+import { labelOf } from '../registry/names.js';
+import { requireDefinition } from '../registry/program.js';
+import { isLeaf, placementsOf, scheduleOf, type Placement } from '../registry/schedule.js';
+import type { Leaf } from './leaf.js';
+import type { System } from './system.js';
+
+type Key = symbol;
+
+const none: readonly never[] = [];
+
+/** A leaf as the system value it is. */
+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.commands();
+    return {
+        /** The system, the value its constructor returned. */
+        system: asSystem(leaf),
+        name: leaf.name,
+        components: {
+            read: [...components?.read ?? none, ...up === undefined ? none : [up.through]],
+            write: components?.write ?? none,
+            /** What it requires without reading: `with` members it doesn't use, `added` and `changed` filters' among them. */
+            has: components?.has ?? none,
+            optional: components?.optional ?? none,
+            not: components?.not ?? none,
+            added: components?.added ?? none,
+            changed: components?.changed ?? none,
+            /** What it reads of each row's parent, through `up`. */
+            parent: up?.read ?? none,
+        },
+        resources: {
+            read: resources?.read ?? none,
+            write: resources?.write ?? none,
+            reduce: resources?.reduce ?? none,
+            changed: resources?.changed ?? none,
+            is: resources?.is ?? none,
+            not: resources?.not ?? none,
+        },
+        lookups: Object.entries(lookup ?? {}).map(([name, used]) => ({
+            name,
+            /** The label of the index it looks up through, or null for a lookup by entity. */
+            index: "index" in used && used.index !== undefined ? indexDefinitionOf(used.index)?.name ?? null : null,
+            read: used.read ?? none,
+        })),
+        /** The label of the sorted index ordering its rows, or null. */
+        order: indexDefinitionOf(order)?.name ?? null,
+        /** What its commands name by kind, and whether it despawns; null where the build couldn't follow them. */
+        commands: commands === null ? null : {
+            spawn: commands?.spawn ?? none,
+            add: commands?.add ?? none,
+            remove: commands?.remove ?? none,
+            despawn: commands?.despawn === true,
+        },
+        /** Whether it takes its row whole (`components: { whole: true }`), every member written. */
+        whole: components?.whole === true,
+        /** The systems it follows directly, with what ordered it after each and the keys that need that order. */
+        after: placements.map(placement => ({ system: asSystem(placement.leaf), name: placement.leaf.name, because: placement.because, conflicts: placement.conflicts })),
+    };
+};
+
+type Described = ReturnType<typeof describeLeaf>;
+
+const keys = (list: readonly Key[]): string => list.map(labelOf).join(" ");
+
+/** A system's lines of text, after its name in a column of `width`. */
+const linesOf = (system: Described, width: number): readonly string[] => {
+    const lines: string[] = [];
+    const add = (label: string, text: string): void => { if (text !== "") lines.push(`${label.padEnd(10)}${text}`); };
+    const { components, resources, commands } = system;
+    add("reads", keys(components.read));
+    add("writes", `${keys(components.write)}${system.whole ? " (its whole row)" : ""}`);
+    add("requires", [keys(components.has), components.not.length === 0 ? "" : `not ${keys(components.not)}`, components.optional.length === 0 ? "" : `optional ${keys(components.optional)}`].filter(text => text !== "").join(", "));
+    add("filters", [...components.added.map(key => `added ${labelOf(key)}`), ...components.changed.map(key => `changed ${labelOf(key)}`), ...resources.changed.map(key => `changed ${labelOf(key)}`)].join(", "));
+    add("parent", keys(components.parent));
+    add("resources", [resources.read.length === 0 ? "" : `reads ${keys(resources.read)}`, resources.write.length === 0 ? "" : `writes ${keys(resources.write)}`,
+        resources.reduce.length === 0 ? "" : `reduces ${keys(resources.reduce)}`, resources.is.length === 0 ? "" : `while ${keys(resources.is)}`,
+        resources.not.length === 0 ? "" : `unless ${keys(resources.not)}`].filter(text => text !== "").join(", "));
+    for (const lookup of system.lookups) add("looks up", `${lookup.name}${lookup.index === null ? "" : ` through ${lookup.index}`}${lookup.read.length === 0 ? "" : `: ${keys(lookup.read)}`}`);
+    if (system.order !== null) add("ordered", `by ${system.order}`);
+    if (commands === null) add("commands", "unknown: the build couldn't follow them");
+    else add("commands", [commands.spawn.length === 0 ? "" : `spawn ${keys(commands.spawn)}`, commands.add.length === 0 ? "" : `add ${keys(commands.add)}`,
+        commands.remove.length === 0 ? "" : `remove ${keys(commands.remove)}`, commands.despawn ? "despawn" : ""].filter(text => text !== "").join(", "));
+    add("after", system.after.map(placement => `${placement.name} (${placement.because}${placement.conflicts.length === 0 ? "" : `: ${keys(placement.conflicts)}`})`).join(", "));
+    const indent = " ".repeat(width);
+    return lines.length === 0 ? [system.name] : lines.map((line, i) => `${i === 0 ? system.name.padEnd(width) : indent}${line}`);
+};
+
+/**
+ * Describes how a system or composite runs: its tiers in run order, systems in one tier having no ordering path between
+ * them, each with the sync point after it, if any, and its readonly systems apart, which run after its last sync
+ * point. For each system, what the build inferred it reads, writes, looks up and commands, whether it takes its row
+ * whole, and the systems it follows directly, with what ordered it after each. `text` gives it all to read; the rest
+ * is data to assert on.
+ */
+export const describe = <I, R>(system: System<I, R>) => {
+    const definition = requireDefinition(system);
+    const schedule = scheduleOf(definition);
+    const placements = placementsOf(definition);
+    const tiers = schedule.tiers.map((tier, t) => ({
+        systems: tier.map(leaf => describeLeaf(leaf, placements.get(leaf) ?? none)),
+        /**
+         * Why a sync point follows the tier, applying the commands so far: each system whose commands may change what a
+         * later one that follows it uses, through `keys`, none listed where it despawns or a cascade could; null for none.
+         */
+        sync: schedule.syncs[t]?.map(reason => ({ from: asSystem(reason.from), to: asSystem(reason.to), keys: reason.keys })) ?? null,
+    }));
+    const readonly = schedule.observer.flatMap(member => isLeaf(member) ? [describeLeaf(member, none)] : []);
+    const width = Math.max(0, ...[...tiers.flatMap(tier => tier.systems), ...readonly].map(described => described.name.length)) + 2;
+    const text = [
+        ...tiers.flatMap((tier, t) => [
+            ...tier.systems.flatMap((described, i) => linesOf(described, width).map((line, l) => `${(i === 0 && l === 0 ? `tier ${t}` : "").padEnd(8)}${line}`)),
+            ...(tier.sync ?? none).map((reason, r) => `${(r === 0 ? "sync" : "").padEnd(8)}${reason.from.name}'s commands${reason.keys.length === 0 ? "" : ` of ${keys(reason.keys)}`}, for ${reason.to.name}`),
+        ]),
+        ...readonly.length === 0 ? none : ["readonly", ...readonly.flatMap(described => linesOf(described, width).map(line => `${"".padEnd(8)}${line}`))],
+    ].map(line => line.trimEnd()).join("\n");
+    return { tiers, readonly, text };
+};

package/src/interface/system/index.ts

@@ -1,4 +1,5 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 export type { Commands } from './commands.js';
 export * from './create.js';
+export { describe } from './describe.js';
 export { render, type RenderContext, type RenderTable } from './render.js';

package/src/interface/system/leaf.ts

@@ -1,5 +1,6 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Schema } from '../schema/schema.js';
+import type { CommandLists } from './access.js';
 import type { Resolved } from './declaration.js';
 import type { Name } from './name.js';
 
@@ -17,4 +18,10 @@ export type Leaf = {
     readonly declaration: Resolved;
     readonly input: InputSchema | undefined;
     readonly body: (...parameters: never[]) => void;
+    /**
+     * 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 | undefined;
 };

package/src/interface/system/render.ts

@@ -11,7 +11,7 @@ import type { Body } from './body.js';
 import type { ReturnsNoPromise } from './input.js';
 import { accessorsOf } from '../gpu/accessors.js';
 import { checkLeaf } from './check.js';
-import { accessOf, compact, resourceUses } from './resolve.js';
+import { accessOf, compact, noCommands, resourceUses } from './resolve.js';
 import type { Leaf } from './leaf.js';
 import type { StructComponent } from './struct.js';
 import type { Shared } from '../component/value.js';
@@ -96,6 +96,7 @@ export const render = <const D extends RenderDeclaration, B extends Body<D>>(
         },
         input: undefined,
         body,
+        commands: noCommands,
     };
     if (uses.write.length > 0 || uses.reduce.length > 0) throw new Error(`${what} writes or reduces into resources; a render system only reads.`);
     checkLeaf(system);

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

@@ -1,7 +1,7 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import { describe, expect, it } from "vitest";
 import "../registry/declarations.js";
-import { componentLists, lookupsLists, resourceUses, type Access } from "./resolve.js";
+import { commandListsOf, componentLists, lookupsLists, resourceUses, type Access } from "./resolve.js";
 
 const mass = Symbol("resolveTest/mass");
 const pool = Symbol("resolveTest/pool");
@@ -47,3 +47,19 @@ describe("resourceUses", () => {
         expect(() => resourceUses("System \"s\"", changing(pool), undefined)).not.toThrow();
     });
 });
+
+describe("commandListsOf", () => {
+    const commanding = (commands: () => unknown): Access => ({ components: null, resources: null, lookup: null, up: null, commands, at: "a test" });
+    it("reads what the commands name at the first call, once", () => {
+        let reads = 0;
+        const lists = commandListsOf("System \"s\"", commanding(() => { reads++; return { spawn: [[mass, position]], add: [mass], remove: [], despawn: false }; }));
+        expect(reads).toBe(0);
+        expect([lists(), lists(), reads]).toEqual([{ spawn: [mass, position], add: [mass] }, { spawn: [mass, position], add: [mass] }, 1]);
+    });
+    it("names the system and the declaration its commands name before it's initialized", () => {
+        for (const message of ["Cannot access 'standard' before initialization", "can't access lexical declaration 'standard' before initialization"]) {
+            const lists = commandListsOf("System \"s\"", commanding(() => { throw new ReferenceError(message); }));
+            expect(lists).toThrow(`System "s" names "standard" in its commands before it's initialized: declare it above the system.`);
+        }
+    });
+});

package/src/interface/system/resolve.ts

@@ -3,7 +3,7 @@ import { takeAccessOf } from '../registry/ids.js';
 import { indexDefinitionOf } from '../registry/indexes.js';
 import { declarationOf, labelOf } from '../registry/names.js';
 import { isString, isStruct } from '../registry/schemas.js';
-import type { ComponentAccess, ComponentLists, Lookup, SystemLookup, SystemLookupLists } from './access.js';
+import type { CommandLists, ComponentAccess, ComponentLists, Lookup, SystemLookup, SystemLookupLists } from './access.js';
 
 type Key = symbol;
 
@@ -23,11 +23,26 @@ export type Access = {
     readonly up: readonly Key[] | null;
     /** The resources the predicates of its declaration's `where` read; absent without predicates. */
     readonly where?: readonly Key[] | null;
+    /**
+     * What its commands name, keys or lists of them, by kind, and whether it despawns, or a function giving that; absent
+     * where no build said.
+     */
+    readonly commands?: unknown;
     readonly at: string;
 };
 
+type Named = readonly (Key | readonly Key[])[];
+type Commanded = { readonly spawn: Named; readonly add: Named; readonly remove: Named; readonly despawn: boolean };
+
 const isKeys = (value: unknown): value is readonly Key[] => Array.isArray(value) && value.every(key => typeof key === "symbol");
 
+const isNamed = (value: unknown): value is Named => Array.isArray(value) && value.every(item => typeof item === "symbol" || isKeys(item));
+
+/** A binding a command named that holds neither a key nor a list of them isn't followed. */
+const isCommanded = (value: unknown): value is Commanded => typeof value === "object" && value !== null
+    && isNamed(Reflect.get(value, "spawn")) && isNamed(Reflect.get(value, "add")) && isNamed(Reflect.get(value, "remove"))
+    && typeof Reflect.get(value, "despawn") === "boolean";
+
 const isUsed = (value: unknown): value is Used => typeof value === "object" && value !== null
     && isKeys(Reflect.get(value, "read")) && isKeys(Reflect.get(value, "write"))
     && (Reflect.get(value, "mutate") === undefined || isKeys(Reflect.get(value, "mutate")));
@@ -106,7 +121,7 @@ export const componentLists = (components: ComponentAccess, used: Used | null, r
         : used.write;
     const read = used === null ? without(held, write) : without(used.read, write);
     const has = [...without(members, read, write), ...without(filtered, read, write)];
-    return compact({ read, write, has, optional, not: components.not, added: components.added, changed: components.changed, where, whereReads });
+    return compact({ read, write, has, optional, not: components.not, added: components.added, changed: components.changed, where, whereReads, whole: components.whole });
 };
 
 /**
@@ -161,5 +176,48 @@ export const whereReadsOf = (what: string, components: ComponentAccess | undefin
     return reads;
 };
 
+/**
+ * What a body's commands name, as the world takes it, read at the first call and kept: null where the build couldn't
+ * follow them, nothing for none. The build gives them as a function, so a list declared below the system is read once
+ * its module has loaded; one still uninitialized then, as an import cycle leaves it, throws naming it.
+ */
+export const commandListsOf = (what: string, access: Access): (() => CommandLists | null | undefined) => {
+    let read = false;
+    let lists: CommandLists | null | undefined;
+    return () => {
+        if (!read) {
+            lists = listsOf(what, access.commands);
+            read = true;
+        }
+        return lists;
+    };
+};
+
+/** The command lists of a system whose body issues none. */
+export const noCommands = (): undefined => undefined;
+
+const listsOf = (what: string, given: unknown): CommandLists | null | undefined => {
+    const commands = typeof given === "function" ? evaluated(what, () => Reflect.apply(given, undefined, [])) : given;
+    if (commands === undefined) return undefined;
+    if (!isCommanded(commands)) return null;
+    if (!commands.despawn && commands.spawn.length + commands.add.length + commands.remove.length === 0) return undefined;
+    const flat = (named: Named): Key[] => [...new Set(named.flat())];
+    const lists = compact({ spawn: flat(commands.spawn), add: flat(commands.add), remove: flat(commands.remove), despawn: commands.despawn ? true as const : undefined });
+    return Object.keys(lists).length === 0 ? undefined : lists;
+};
+
+/** What the build's function of a body's commands gives. */
+const evaluated = (what: string, commands: () => unknown): unknown => {
+    try {
+        return commands();
+    } catch (error) {
+        if (!(error instanceof ReferenceError)) throw error;
+        // Engines quote the binding in the message: "Cannot access 'standard' before initialization", or "can't access
+        // lexical declaration 'standard' before initialization".
+        const binding = /'([A-Za-z_$][\w$]*)'/.exec(error.message)?.[1];
+        throw new Error(`${what} names ${binding === undefined ? "a declaration" : `"${binding}"`} in its commands before it's initialized: declare it above the system.`, { cause: error });
+    }
+};
+
 /** What a body reads of its parent's values. */
 export const upReads = (what: string, access: Access): readonly Key[] => followed(what, access.up, "its parent's values", access);

package/src/interface/system/shared-only.ts

@@ -0,0 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Shared } from '../component/value.js';
+
+/** A `where`'s keys that aren't shared components, each an error: `where` names only shared components. */
+export type SharedOnly<W> = { readonly [K in Exclude<keyof W, Shared>]: { readonly "error: where names only shared components, which each archetype holds one value of": K } };

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

@@ -154,6 +154,12 @@ System.create({
     // @ts-expect-error ordering takes systems
     after: ["test/unregistered"],
 }, () => {});
+// Ordering by a resource: before or after every other system of the composite that uses it.
+System.create({ before: [time], after: [integrate, score] }, ({ resources }) => { resources[time] = resources[score]; });
+System.create({
+    // @ts-expect-error ordering takes systems and resources, not components
+    after: [position],
+}, () => {});
 
 // @ts-expect-error a system with input can't use change filters
 System.create({ components: { changed: [position] } }, (_row, _context, input: { readonly distance: number }) => { void input; });

package/src/interface/system/tables.ts

@@ -1,16 +1,22 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Component } from '../component/component.js';
+import type { Shared } from '../component/value.js';
 import type { Resource } from '../resource/resource.js';
 import type { Table } from '../world/table/table.js';
 
 /**
- * What a readonly system's `tables` reads: of every archetype matching `with` and `not` that holds any of
+ * What a readonly system's `tables` reads: of every archetype matching `with`, `not` and `where` that holds any of
  * `components`, a table of those it holds; and, with `resources`, each resource's value.
  */
 export type TablesDeclaration = {
     readonly components: readonly Component.Key[];
     readonly with?: readonly Component.Key[];
     readonly not?: readonly Component.Key[];
+    /**
+     * Keeps the tables to the archetypes holding these values of shared components, each one required as `with`
+     * requires it, as a system's `where` of values keeps its system to them.
+     */
+    readonly where?: { readonly [K in Shared]?: Component<K> };
     readonly resources?: readonly Resource.Key[];
 };
 

package/src/interface/world/run.type-test.ts

@@ -62,7 +62,17 @@ void ecs.Report;
 // @ts-expect-error no run numbers
 const numbered: Promise<number> = world.run(main);
 
-void [counted, notText, nextValue, scaledValue, drawn, rows, composite, input, nothing, numbered, time];
+// Asked for its changes, after its input, a run resolves to them, in the shape changes finalizers take.
+const changes = world.run(move, { distance: 1 }, { changes: true });
+const alone = world.run(main, { changes: true });
+check<Equal<typeof changes, typeof alone>>();
+check<Equal<Awaited<typeof alone>["resources"][number]["key"], Ecs.Resource.Key>>();
+// @ts-expect-error its input comes first
+void world.run(move, { changes: true }, { distance: 1 });
+// @ts-expect-error a run asks only for its changes
+void world.run(main, { changes: false });
+
+void [counted, notText, nextValue, scaledValue, drawn, rows, composite, input, nothing, numbered, time, changes];
 
 // A body returns no promise: it starts the work, and a later run finishes it.
 // @ts-expect-error a body returns no promise

package/src/interface/world/table/index.ts

@@ -13,7 +13,8 @@ export type Column =
     | { readonly kind: "value"; readonly value: unknown };
 
 /**
- * What `commands.spawnTables` spawned: each table's new entities in its row order, `Entity.none` for a row it didn't
- * spawn, and how many rows it didn't, those owned by an entity outside the tables.
+ * What `commands.spawnTables` spawned: each table's entities in its row order, the one spawned for each row, the one
+ * existing for a row its `existing` maps, and `Entity.none` for a row it didn't spawn; and how many rows it didn't,
+ * those owned by an entity outside the tables.
  */
 export type Spawned = { readonly entities: readonly Float64Array[]; readonly dropped: number };

package/src/interface/world/world.ts

@@ -1,6 +1,9 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Input } from '../system/input.js';
 import type { System } from '../system/system.js';
+import type { ChangeSet } from '../finalizer/body.js';
+import type { Essential } from '../component/value.js';
+import type { Resource } from '../resource/resource.js';
 
 /**
  * A world. Systems read and change it; readonly systems read it after each run's and tick's sync point. Every member's
@@ -23,6 +26,16 @@ export type World = {
      * added or GPU work, is reported out of band, as ticks' failures are (see `add`).
      */
     run<I, R>(system: System<I, R>, ...input: Input<NoInfer<I>>): Promise<R>;
+    /**
+     * Runs as `run` does, and resolves to this run's own changes, in the shape `Finalizer.changes` gives, rather than its
+     * value: the structural changes its commands made, rules and cascades included, to every component that isn't
+     * derived or an object a joined thread fills, the values its adds gave components entities had before and after, and
+     * each resource its systems write or reduce into whose value changed, compared as `Finalizer.changes` compares them;
+     * `previous` and `next` give values before and after the run. Commands the finalizers of an earlier sync point
+     * queued apply first, at a sync point of their own. Values written to rows aren't structural changes, so they're in
+     * none. The run pays for this only when asked. Only on the world's thread: a joined thread's rejects.
+     */
+    run<I, R>(system: System<I, R>, ...input: [...Input<NoInfer<I>>, options: { readonly changes: true }]): Promise<ChangeSet<Essential, Resource.Key>>;
     /**
      * Adds a system to every tick, from the next one on, ordered with those already added by its constraints, as a
      * composite's members are. A tick runs on a beat of the `cadence` resource where `always` is set, `wake` is due or