@adobe/ecs 0.2.3 → 0.2.4

package/src/guide/18-identity.out

@@ -1 +1 @@
-Error: System "explode" (@adobe/ecs@0.2.3/src/guide/18-identity.ts#explode) failed: boom
+Error: System "explode" (@adobe/ecs@0.2.4/src/guide/18-identity.ts#explode) failed: boom

package/src/guide/guide.test.ts

@@ -1,70 +1,5 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
-import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { formatWithOptions } from "node:util";
-import ts from "typescript";
-import { afterAll, expect, it, vi } from "vitest";
-
-/**
- * Each chapter here is its prose, `NN-name.md`, and a program, which its `main` runs. Run, it prints what the `.out`
- * file beside it says: a line per console call, as node writes its values, on one line each. Ids name the package's
- * version, which is left out of the comparison, so a new version changes no example. The folder is read as the test
- * runs, not through `import.meta.glob`, which vitest's cache of transformed modules would keep as of the test's first
- * run, missing a chapter added since.
- */
-const folder = new URL(".", import.meta.url);
-const files = readdirSync(folder);
-const read = (file: string): string => readFileSync(new URL(file, folder), "utf8");
-const names = files.filter(file => /^\d+-[\w-]+\.ts$/.test(file) && !file.endsWith(".type-test.ts")).map(file => file.slice(0, -".ts".length)).sort();
-const proseFiles = files.filter(file => /^\d+-[\w-]+\.md$/.test(file)).sort();
-/** Where the mutation tests write each program changed: `.mutants` in the package. */
-const mutants = new URL("../../.mutants/", import.meta.url);
-afterAll(() => rmSync(mutants, { recursive: true, force: true }));
-
-const levels = ["log", "info", "warn", "error", "debug"] as const;
-const unversioned = (text: string): string => text.replace(/@adobe\/ecs@[^/\s]+\//g, "@adobe/ecs/");
-const chapterOf = (file: string): number => Number(/^(\d+)-/.exec(file)?.[1]);
-
-/** What `main` prints, a line per console call, and how it failed, if it did. */
-const printed = async (main: () => Promise<void>): Promise<string> => {
-    const lines: string[] = [];
-    const spies = levels.map(level => vi.spyOn(console, level).mockImplementation((...values: unknown[]) => {
-        lines.push(formatWithOptions({ breakLength: Infinity, compact: true }, ...values));
-    }));
-    try {
-        await main();
-    } catch (error) {
-        lines.push(`main failed: ${String(error)}`);
-    } finally {
-        for (const spy of spies) spy.mockRestore();
-    }
-    return lines.map(line => `${line}\n`).join("");
-};
-
-/** What a program prints, run from its file, or how it failed, as a declaration the world rejects fails its import. */
-const run = (file: URL): Promise<string> => printed(async () => {
-    const program: unknown = await import(/* @vite-ignore */ file.href);
-    const main: unknown = Reflect.get(Object(program), "main");
-    if (typeof main !== "function") throw new Error(`${file.pathname} exports no main`);
-    await Reflect.apply(main, undefined, []);
-});
-
-/** Code without its comments, as TypeScript prints it. */
-const withoutComments = (source: string): string =>
-    ts.createPrinter({ removeComments: true }).printFile(ts.createSourceFile("program.ts", source, ts.ScriptTarget.ESNext, false));
-
-/** Each chapter's code: its files', without comments. */
-const codeOf = (chapter: number): string =>
-    files.filter(file => file.endsWith(".ts") && !file.endsWith(".test.ts") && chapterOf(file) === chapter).map(file => withoutComments(read(file))).join("\n");
-
-/** What prose shows as code: its inline code and its blocks. */
-const shownIn = (prose: string): readonly string[] => [...prose.matchAll(/```\w*\n([\s\S]*?)```|`([^`\n]+)`/g)].map(([, block, inline]) => block ?? inline ?? "");
-
-/** Each link of the prose to lines of a program, which the interactive guide shows in its editor: `NN-name.ts#L4-L9`. */
-const editorLinks = proseFiles.flatMap(prose => [...read(prose).matchAll(/\]\(([^)#\s]*)#L(\d+)(?:-L(\d+))?\)/g)].map(([, file = "", from = "", to]) =>
-    ({ prose, file, from: Number(from), to: Number(to ?? from) })));
-
-/** The chapters the guide's index lists, in order: each its number, title and prose. */
-const listed = [...read("README.md").matchAll(/^(?:- |(\d+)\. )\[([^\]]+)\]\(([^)]+)\)$/gm)].map(([, number = "0", title = "", file = ""]) => ({ number: Number(number), title, file }));
+import { checkChapters } from "ecs-guide-checks";
 
 /** What each chapter teaches, which its prose names as code and its program does; 0 is the unnumbered keys chapter's. */
 const teaches: { readonly [chapter: number]: readonly string[] } = {
@@ -111,7 +46,7 @@ const mutations: { readonly [chapter: number]: readonly (readonly [string, strin
     ],
     4: [["world.remove(advance);", ""]],
     5: [["after: [hit] ", ""], ["during: [update] ", ""]],
-    6: [["commands.add(hero, health, 5);", ""], ["commands.despawn(commands.spawn([health])({ [health]: 1 }));", "commands.spawn([health])({ [health]: 1 });"], ["watched.add(watch);", ""], ["const watch = System.create({ readonly: true, ", "const watch = System.create({ "]],
+    6: [["commands.add(hero, health, 5);", ""], ["after: [spawn] ", ""], ["commands.despawn(commands.spawn([health])({ [health]: 1 }));", "commands.spawn([health])({ [health]: 1 });"], ["watched.add(watch);", ""], ["const watch = System.create({ readonly: true, ", "const watch = System.create({ "]],
     7: [["resources: { changed: [level] } ", ""], [", changed: [score]", ""], [", not: [paused]", ""], ["is: [map], ", ""]],
     8: [["target: \"entity\",", ""]],
     9: [["with: [mesh], not: [hidden]", "with: [mesh]"], ["Rule.create({ components: { with: [sprite], not: [hidden] }, derive: [drawn] });", ""], ["Rule.create({ components: { with: [drawn] }, derive: [layer] });", ""]],
@@ -132,86 +67,4 @@ const mutations: { readonly [chapter: number]: readonly (readonly [string, strin
     22: [["context.fill();", ""]],
 };
 
-it("has prose and an expected output beside each program, and none without one, and Setup's prose", () => {
-    expect(files.filter(file => file.endsWith(".out")).map(file => file.slice(0, -".out".length)).sort()).toEqual(names);
-    expect(proseFiles).toEqual(["00-setup.md", ...names.map(name => `${name}.md`)].sort());
-});
-
-it("lists every chapter in its index, the unnumbered first, numbered as its files are and by the title its prose gives", () => {
-    expect(listed.map(chapter => chapter.file).sort()).toEqual(proseFiles);
-    expect(listed.map(chapter => chapter.number)).toEqual(listed.map(chapter => chapter.number).sort((a, b) => a - b));
-    for (const { number, title, file } of listed) {
-        expect(number).toBe(chapterOf(file));
-        const [heading, ...rest] = read(file).split("\n");
-        expect(heading).toBe(`# ${title}`);
-        expect(rest.join("\n").trim()).not.toBe("");
-    }
-});
-
-it.each(names)("%s prints what its .out says", async name => {
-    const expected = read(`${name}.out`);
-    expect(expected.trim()).not.toBe("");
-    expect(unversioned(await run(new URL(`${name}.ts`, folder)))).toBe(unversioned(expected));
-});
-
-it.each(Object.entries(teaches))("chapter %s's prose names what it teaches, as code, and its program does it", (chapter, taught) => {
-    const prose = `${names.find(name => chapterOf(name) === Number(chapter)) ?? ""}.md`;
-    const shown = shownIn(read(prose)).join("\n");
-    const code = codeOf(Number(chapter));
-    expect(taught.filter(name => !shown.includes(name))).toEqual([]);
-    expect(taught.filter(name => !code.includes(name))).toEqual([]);
-});
-
-it("teaches something in every chapter", () => {
-    expect(Object.keys(teaches).map(Number)).toEqual(names.map(chapterOf));
-});
-
-it("keeps code in the prose to a line or two, the program in the editor showing the rest", () => {
-    const long = proseFiles.flatMap(file => [...read(file).matchAll(/```\w*\n([\s\S]*?)```/g)].filter(([, block = ""]) => block.split("\n").length > 3).map(() => file));
-    expect(long).toEqual([]);
-});
-
-it("links chapters only to chapters there are", () => {
-    const chapterLinks = proseFiles.flatMap(file => [...read(file).matchAll(/\]\(([^)#\s]+\.md)\)/g)].map(([, target = ""]) => target));
-    expect(chapterLinks.length).toBeGreaterThan(0);
-    expect(chapterLinks.filter(target => !proseFiles.includes(target))).toEqual([]);
-});
-
-/** The messages of TypeScript's syntax errors in code. */
-const syntaxErrors = (code: string): readonly string[] => {
-    const { diagnostics = [] } = ts.transpileModule(code, { reportDiagnostics: true, compilerOptions: { target: ts.ScriptTarget.ESNext, module: ts.ModuleKind.ESNext } });
-    return diagnostics.map(diagnostic => ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n"));
-};
-
-it.each(editorLinks.map(link => [`${link.prose} to ${link.file}#L${link.from}-L${link.to}`, link] as const))("links %s, lines of its own program that are whole code", (_place, { prose, file, from, to }) => {
-    expect(file.startsWith(prose.replace(/\.md$/, "."))).toBe(true);
-    const lines = read(file).split("\n");
-    expect(from).toBeGreaterThanOrEqual(1);
-    expect(to).toBeGreaterThanOrEqual(from);
-    expect(to).toBeLessThanOrEqual(lines.length);
-    const code = lines.slice(from - 1, to).join("\n");
-    expect(withoutComments(code).trim()).not.toBe("");
-    expect(lines[from - 1]?.trim()).not.toBe("");
-    expect(lines[to - 1]?.trim()).not.toBe("");
-    // Lines cut short leave a brace or a call open, which parses neither as statements nor as a declaration's members.
-    expect(syntaxErrors(code).length === 0 || syntaxErrors(`interface Members {\n${code}\n}`).length === 0 ? [] : syntaxErrors(code)).toEqual([]);
-});
-
-it.each(Object.entries(mutations).flatMap(([chapter, changes]) => changes.map(([from, to, failure], index) => [Number(chapter), from, to, failure, index] as const)))(
-    "catches chapter %s's point taken away, %j, in its output", async (chapter, from, to, failure, index) => {
-        const name = names.find(item => chapterOf(item) === chapter) ?? "";
-        const source = read(`${name}.ts`);
-        expect(source.split(from).length).toBe(2);
-        // A file of the package's own, compiled as the program is, outside its sources, which other tests read.
-        const mutant = `${name}-${index}.ts`;
-        mkdirSync(mutants, { recursive: true });
-        const file = new URL(mutant, mutants);
-        writeFileSync(file, source.replace(from, to).replace(` from "../index.js";`, ` from "../src/index.js";`));
-        try {
-            const output = (await run(file)).replaceAll(`.mutants/${mutant}`, `src/guide/${name}.ts`);
-            expect(unversioned(output)).not.toBe(unversioned(read(`${name}.out`)));
-            if (failure !== undefined) expect(output).toContain(failure);
-        } finally {
-            rmSync(file, { force: true });
-        }
-    });
+checkChapters({ folder: new URL(".", import.meta.url), teaches, mutations });

package/src/implementation/compiler/body-access.ts

@@ -9,14 +9,23 @@ type Access = { readonly read: ReadonlySet<string>; readonly write: ReadonlySet<
 /** The keys a body reads, writes and contributes to, by module-scope binding name; null where the body doesn't show every use. */
 export type Used = {
     readonly query: Access | null;
+    /** Where and why the build lost track of the row, unless the declaration takes it whole on purpose. */
+    readonly rowLost?: { readonly at: Node; readonly why: string };
     readonly resources: (Access & { readonly reduce: ReadonlySet<string> }) | null;
     /** The components read from each lookup's results, by lookup name: null for one whose results aren't followed. */
     readonly lookups: ReadonlyMap<string, ReadonlySet<string> | null> | null;
     /** The components read from `up`. */
     readonly up: ReadonlySet<string> | null;
+    /**
+     * What its commands name, by kind: keys and lists of keys, as their module-scope bindings; whether it despawns.
+     * Null where the body passes its commands on, aliases them, or names what they take otherwise.
+     */
+    readonly commands: Commanded | null;
 };
 
-const unknown: Used = { query: null, resources: null, lookups: null, up: null };
+type Commanded = { readonly spawn: ReadonlySet<string>; readonly add: ReadonlySet<string>; readonly remove: ReadonlySet<string>; readonly despawn: boolean };
+
+const unknownAt = (at: Node, why: string): Used => ({ query: null, rowLost: { at, why }, resources: null, lookups: null, up: null, commands: null });
 
 /** Whether `node`, a child of `parent`, names a property or label, or declares a binding, rather than referring to one. */
 const isName = (node: Node, parent: Node | undefined): boolean => {
@@ -115,6 +124,13 @@ const indexLookupNames = (declaration: ObjectExpression): ReadonlySet<string> =>
 
 type Group = "resources" | "lookup" | "reduce" | "up";
 
+/** Whether a declaration's `components` says `whole: true`: its body uses its row whole, on purpose. */
+const takesRowWhole = (declaration: ObjectExpression): boolean => declaration.properties.some(property =>
+    property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === "components"
+    && property.value.type === "ObjectExpression" && property.value.properties.some(member =>
+        member.type === "Property" && !member.computed && member.key.type === "Identifier" && member.key.name === "whole"
+        && member.value.type === "Literal" && member.value.value === true));
+
 const isGroup = (name: string): name is Group => name === "resources" || name === "lookup" || name === "reduce" || name === "up";
 
 /**
@@ -123,15 +139,27 @@ const isGroup = (name: string): name is Group => name === "resources" || name ==
  * context's `resources`, `lookup` and `reduce` are indexed only by module-scope keys the body doesn't shadow, or
  * destructured by them, and never passed on, aliased or spread. A lookup's results are followed where each is indexed
  * by such keys or tested, directly or through a `const` declared once; a lookup through an index's lists where they're
- * read for `length` and `changed`, and their rows from `at` as a lookup's results are.
+ * read for `length` and `changed`, and their rows from `at` as a lookup's results are. A row whose declaration takes it
+ * `whole` isn't followed.
  */
 export const usedBy = (declaration: ObjectExpression, body: Node, module: ModuleScope, positions: { readonly row: number; readonly context: number }): Used => {
-    if (!isFunctionBody(body)) return unknown;
-    if (body.type === "FunctionExpression" && mentions(body.body, "arguments")) return unknown;
+    const used = followedBy(declaration, body, module, positions);
+    if (takesRowWhole(declaration)) return { query: null, resources: used.resources, lookups: used.lookups, up: used.up, commands: used.commands };
+    // A body without a row loses none.
+    return positions.row < 0 && used.rowLost !== undefined ? { query: used.query, resources: used.resources, lookups: used.lookups, up: used.up, commands: used.commands } : used;
+};
+
+const followedBy = (declaration: ObjectExpression, body: Node, module: ModuleScope, positions: { readonly row: number; readonly context: number }): Used => {
+    if (!isFunctionBody(body)) return unknownAt(body, "its body isn't a function written in place");
+    if (body.type === "FunctionExpression" && mentions(body.body, "arguments")) return unknownAt(body, "it reads `arguments`");
     // Code `eval` runs can use anything.
-    if (mentions(body, "eval")) return unknown;
+    if (mentions(body, "eval")) return unknownAt(body, "it calls `eval`");
     const counts = new Map<string, number>();
-    declaredIn(body.body, name => counts.set(name, (counts.get(name) ?? 0) + 1));
+    const declaredAt = new Map<string, Node>();
+    declaredIn(body.body, (name, at) => {
+        counts.set(name, (counts.get(name) ?? 0) + 1);
+        if (!declaredAt.has(name)) declaredAt.set(name, at);
+    });
     const parameters = new Set(body.params.flatMap(parameter => patternNames(parameter)));
     const isKey = (name: string): boolean => module.has(name) && !counts.has(name) && !parameters.has(name);
     /** The key `node` names: a module-scope binding, or a namespace's member (`Shapes.circle`), as its source; null for any other. */
@@ -150,9 +178,15 @@ export const usedBy = (declaration: ObjectExpression, body: Node, module: Module
     const up = new Set<string>();
     let upKnown = true;
     const lookupReads = new Map<string, Set<string> | null>((lookups ?? []).map(name => [name, new Set<string>()]));
-    let queryKnown = true;
+    let rowLost: { readonly at: Node; readonly why: string } | undefined;
+    /** Stops following the row, at the first use it can't. */
+    const loseRow = (at: Node, why: string): void => { rowLost ??= { at, why }; };
     let resourcesKnown = true;
     let lookupsKnown = lookups !== null;
+    const commands = { spawn: new Set<string>(), add: new Set<string>(), remove: new Set<string>(), despawn: false };
+    let commandsKnown = true;
+    /** Names bound to the context's commands. */
+    const commandNames = new Set<string>();
     const unknownLookup = (lookup: string): void => { lookupReads.set(lookup, null); };
     const unknownGroup = (group: Group): void => {
         if (group === "lookup") lookupsKnown = false;
@@ -206,6 +240,11 @@ export const usedBy = (declaration: ObjectExpression, body: Node, module: Module
     };
     /** Binds the context's groups from a destructuring of it; `declaredOnce` says whether a bound name is safe to follow. */
     const contextNamed = (declaredOnce: (name: string) => boolean) => (property: string, value: Pattern): boolean => {
+        if (property === "commands") {
+            if (value.type === "Identifier" && declaredOnce(value.name)) commandNames.add(value.name);
+            else commandsKnown = false;
+            return true;
+        }
         if (!isGroup(property)) return true;
         if (value.type === "Identifier" && declaredOnce(value.name)) groups.set(value.name, property);
         else if (value.type === "ObjectPattern") destructureGroup(property, value);
@@ -216,13 +255,15 @@ export const usedBy = (declaration: ObjectExpression, body: Node, module: Module
         resourcesKnown = false;
         lookupsKnown = false;
         upKnown = false;
+        commandsKnown = false;
     };
 
     const row = positions.row < 0 ? undefined : body.params[positions.row];
     const context = positions.context < 0 ? undefined : body.params[positions.context];
     const rowName = row?.type === "Identifier" && !counts.has(row.name) ? row.name : null;
     const contextName = context?.type === "Identifier" && !counts.has(context.name) ? context.name : null;
-    if (row !== undefined && rowName === null && !destructure(row, rowNamed, key => query.read.add(key))) queryKnown = false;
+    if (row?.type === "Identifier" && rowName === null) loseRow(declaredAt.get(row.name) ?? row, `it declares another \`${row.name}\` here, which hides its row: rename one`);
+    else if (row !== undefined && rowName === null && !destructure(row, rowNamed, key => query.read.add(key))) loseRow(row, "it destructures its row by something other than its keys and `entity`");
     if (context !== undefined && contextName === null && !destructure(context, contextNamed(name => !counts.has(name)), () => unknownContext())) unknownContext();
 
     /** A lookup's row `value`, a child of `ancestors[at]`: indexed by a key, read for `entity`, bound to a `const`, or tested. */
@@ -284,6 +325,44 @@ export const usedBy = (declaration: ObjectExpression, body: Node, module: Module
         const lookup = list.type === "Identifier" ? results.get(list.name) : calledLookup(list);
         return lookup !== undefined && indexed.has(lookup) ? lookup : undefined;
     };
+    /** Whether `node` is `context.commands`. */
+    const isContextCommands = (node: Node): boolean => node.type === "MemberExpression" && !node.computed && node.object.type === "Identifier"
+        && node.object.name === contextName && node.property.type === "Identifier" && node.property.name === "commands";
+    /** The keys and lists of keys a command's argument names: a key or list by binding, or an array literal of them. */
+    const listOf = (node: Node | undefined): readonly string[] | null => {
+        if (node === undefined) return null;
+        const key = keyOf(node);
+        if (key !== null) return [key];
+        if (node.type !== "ArrayExpression") return null;
+        const names: string[] = [];
+        for (const element of node.elements) {
+            const named = element === null ? null : keyOf(element.type === "SpreadElement" ? element.argument : element);
+            if (named === null) return null;
+            names.push(named);
+        }
+        return names;
+    };
+    /** A use of the commands at `node`, a child of `ancestors[at]`: a call of one of them, whose keys are listed. */
+    const useCommands = (node: Node, ancestors: readonly Node[], at: number): void => {
+        const parent = ancestors[at];
+        const call = ancestors[at - 1];
+        if (parent?.type !== "MemberExpression" || parent.object !== node || parent.computed || parent.property.type !== "Identifier"
+            || call?.type !== "CallExpression" || call.callee !== parent) {
+            commandsKnown = false;
+            return;
+        }
+        const command = parent.property.name;
+        if (command === "despawn" || command === "despawnWhere") {
+            commands.despawn = true;
+            return;
+        }
+        const listed = command === "spawn" ? listOf(call.arguments[0]) : command === "add" || command === "remove" ? listOf(call.arguments[1]) : null;
+        if (listed === null || (command !== "spawn" && command !== "add" && command !== "remove")) {
+            commandsKnown = false;
+            return;
+        }
+        for (const name of listed) commands[command].add(name);
+    };
     /** Finds groups and lookups bound by `const` declarations declared once, and `const`s holding a lookup's result, before any reference is classified. */
     const collect = (node: Node, kind: string | undefined): void => {
         if (node.type === "VariableDeclarator" && kind === "const" && node.init) {
@@ -298,6 +377,10 @@ export const usedBy = (declaration: ObjectExpression, body: Node, module: Module
                     groups.set(node.id.name, group);
                     followed.add(node.init);
                 }
+                if (isContextCommands(node.init)) {
+                    commandNames.add(node.id.name);
+                    followed.add(node.init);
+                }
             }
             else if (node.init.type === "Identifier" && node.init.name === contextName) {
                 if (destructure(node.id, contextNamed(once), () => unknownContext())) followed.add(node.init);
@@ -354,31 +437,36 @@ export const usedBy = (declaration: ObjectExpression, body: Node, module: Module
             if (parent?.type === "MemberExpression" && parent.object === node) {
                 const { property } = parent;
                 if (!parent.computed) {
-                    if (property.type !== "Identifier" || !rowNamed(property.name)) queryKnown = false;
+                    if (property.type !== "Identifier" || !rowNamed(property.name)) loseRow(parent, "it reads a member of its row by name, and a row names only `entity`");
                     return;
                 }
                 const key = keyOf(property);
                 // A part of a value written, `row[key][0] = …`, writes it, which the compiler rejects as it must.
                 const use = key === null ? null : deepUseOf(parent, ancestors, ancestors.length - 2);
-                if (use === null || key === null) queryKnown = false;
+                if (key === null) loseRow(parent, "it indexes its row by something other than a module-scope key");
+                else if (use === null) loseRow(parent, "it deletes a member of its row");
                 else {
                     if (use.read) query.read.add(key);
                     if (use.write) query.write.add(key);
                     if (use.mutate) query.mutate.add(key);
                 }
             }
-            else if (!(parent?.type === "VariableDeclarator" && parent.init === node && destructure(parent.id, rowNamed, key => query.read.add(key)))) queryKnown = false;
+            else if (!(parent?.type === "VariableDeclarator" && parent.init === node && destructure(parent.id, rowNamed, key => query.read.add(key)))) {
+                loseRow(parent ?? node, "it passes its row on, aliases or spreads it");
+            }
         }
         else if (name === contextName) {
             if (parent?.type === "MemberExpression" && parent.object === node && !parent.computed && parent.property.type === "Identifier") {
                 const property = parent.property.name;
                 if (isGroup(property)) useGroup(property, parent, ancestors, ancestors.length - 2);
+                else if (property === "commands" && !followed.has(parent)) useCommands(parent, ancestors, ancestors.length - 2);
                 return;
             }
             if (!followed.has(node)) unknownContext();
         }
         else {
             const at = ancestors.length - 1;
+            if (commandNames.has(name)) return useCommands(node, ancestors, at);
             const group = groups.get(name);
             if (group !== undefined) return useGroup(group, node, ancestors, at);
             const caller = callers.get(name);
@@ -426,9 +514,11 @@ export const usedBy = (declaration: ObjectExpression, body: Node, module: Module
     for (const parameter of body.params) visitPattern(parameter);
     visit(body.body);
     return {
-        query: queryKnown ? query : null,
+        query: rowLost === undefined ? query : null,
+        ...rowLost === undefined ? {} : { rowLost },
         resources: resourcesKnown ? resources : null,
         lookups: lookupsKnown ? lookupReads : null,
         up: upKnown ? up : null,
+        commands: commandsKnown ? commands : null,
     };
 };

package/src/implementation/compiler/estree.ts

@@ -47,18 +47,21 @@ export const patternNames = (pattern: Pattern): readonly string[] => {
     }
 };
 
-/** Calls `declare` for each name declared anywhere inside `node`, once per declaration: variables, parameters, functions, classes and catch parameters. */
-export const declaredIn = (node: Node, declare: (name: string) => void): void => {
+/**
+ * Calls `declare` for each name declared anywhere inside `node`, once per declaration, with the pattern or name that
+ * declares it: variables, parameters, functions, classes and catch parameters.
+ */
+export const declaredIn = (node: Node, declare: (name: string, at: Node) => void): void => {
     switch (node.type) {
-        case "VariableDeclarator": for (const name of patternNames(node.id)) declare(name); break;
+        case "VariableDeclarator": for (const name of patternNames(node.id)) declare(name, node.id); break;
         case "FunctionDeclaration": case "FunctionExpression": case "ClassDeclaration": case "ClassExpression":
-            if (node.id) declare(node.id.name);
+            if (node.id) declare(node.id.name, node.id);
             break;
-        case "CatchClause": if (node.param) for (const name of patternNames(node.param)) declare(name); break;
+        case "CatchClause": if (node.param) for (const name of patternNames(node.param)) declare(name, node.param); break;
         default: break;
     }
     if (node.type === "ArrowFunctionExpression" || node.type === "FunctionExpression" || node.type === "FunctionDeclaration") {
-        for (const param of node.params) for (const name of patternNames(param)) declare(name);
+        for (const param of node.params) for (const name of patternNames(param)) declare(name, param);
     }
     for (const child of children(node)) declaredIn(child, declare);
 };

package/src/implementation/compiler/inferred.test.ts

@@ -26,7 +26,7 @@ const readOf = (declaration: ObjectExpression, name: string): readonly string[]
 describe("resolvedDeclaration", () => {
     test("takes a lookup by entity whose rows the build didn't follow as reading all it requires", () => {
         const declaration = declarationOf("{ lookup: { targets: { with: [mass, position] } } }");
-        const resolved = resolvedDeclaration(declaration, { query: null, resources: null, lookups: new Map([["targets", null]]), up: null });
+        const resolved = resolvedDeclaration(declaration, { query: null, resources: null, lookups: new Map([["targets", null]]), up: null, commands: null });
         expect(readOf(resolved, "targets")).toEqual(["mass", "position"]);
     });
 });

package/src/implementation/compiler/inferred.ts

@@ -77,7 +77,7 @@ const list = (names: Iterable<string>): string => `[${[...names].join(", ")}]`;
  * module-scope bindings the body indexes by, null for a group it couldn't follow, and `at` where the body is.
  */
 export const accessText = (used: Used, at: string, where?: ReadonlySet<string> | null): string => {
-    const { query, resources, lookups, up } = used;
+    const { query, resources, lookups, up, commands } = used;
     // Keys changed inside their values are listed only when there are some, for registration to judge by kind.
     const mutate = (keys: ReadonlySet<string>): string => keys.size === 0 ? "" : `, mutate: ${list(keys)}`;
     const components = query === null ? "null" : `{ read: ${list([...query.read].filter(key => !query.write.has(key)))}, write: ${list(query.write)}${mutate(query.mutate)} }`;
@@ -85,7 +85,9 @@ export const accessText = (used: Used, at: string, where?: ReadonlySet<string> |
     const lookupText = lookups === null ? "null" : `{ ${[...lookups].map(([name, read]) => `${JSON.stringify(name)}: ${read === null ? "null" : list(read)}`).join(", ")} }`;
     // The resources `where`'s predicates read, only with predicates.
     const whereText = where === undefined ? "" : `, where: ${where === null ? "null" : list(where)}`;
-    return `{ components: ${components}, resources: ${resourceText}, lookup: ${lookupText}, up: ${up === null ? "null" : list(up)}${whereText}, at: ${JSON.stringify(at)} }`;
+    // Lists of keys stay as their bindings name them, so a list imported from another module is read where it's made.
+    const commandText = commands === null ? "null" : `{ spawn: ${list(commands.spawn)}, add: ${list(commands.add)}, remove: ${list(commands.remove)}, despawn: ${commands.despawn} }`;
+    return `{ components: ${components}, resources: ${resourceText}, lookup: ${lookupText}, up: ${up === null ? "null" : list(up)}${whereText}, commands: ${commandText}, at: ${JSON.stringify(at)} }`;
 };
 
 /** A declaration's parts the build makes, located at `at`, so a failure in them points at the declaration. */

package/src/implementation/compiler/transform.test.ts

@@ -924,10 +924,10 @@ describe("terminal bodies", () => {
         return code.includes("terminal$((") && code.includes("function terminal$(body)");
     };
     test.each([
-        ["no context", "(row)", "console.log(row);", `{ components: { with: [mass] } }`],
+        ["no context", "(row)", "console.log(row);", `{ components: { with: [mass], whole: true } }`],
         ["a context destructured without commands", "({ resources })", "console.log(resources);", `{}`],
         ["a context used only through its other properties", "(context)", "console.log(context.resources);", `{ resources: {} }`],
-        ["a context reaching resources and lookups", "(row, context)", "console.log(context.resources, context.lookup, row);", `{ components: { with: [mass] } }`],
+        ["a context reaching resources and lookups", "(row, context)", "console.log(context.resources, context.lookup, row);", `{ components: { with: [mass], whole: true } }`],
         ["nested destructuring", "({ resources: { [delta]: d } })", "console.log(d);", `{ resources: {} }`],
     ])("mark a body with %s", async (_, parameters, body, declaration) => {
         expect(await marked(parameters, body, declaration)).toBe(true);
@@ -1412,34 +1412,54 @@ describe("inferred access", () => {
             .toContain("components: { read: [position], write: [] }");
     });
 
-    test("a row it can't follow as unknown, which the world takes as every member written, with a warning", async () => {
-        const result = await transform(system("components: { with: [position] }", "(row) => { helper(row); }"));
-        expect(result !== null && "code" in result ? [result.code.includes("components: null"), result.warnings.length] : null).toEqual([true, 1]);
+    test("fails at the use of a system's row it can't follow, saying why, unless its declaration takes the row whole", async () => {
+        const failure = async (source: string) => {
+            const result = await transform(source);
+            return result !== null && "failure" in result ? result.failure : null;
+        };
+        const passed = await failure(system("components: { with: [position] }", "(row) => { helper(row); }"));
+        expect(passed?.message).toMatch(/^the build can't follow how this body uses its row, since it passes its row on, aliases or spreads it, so it would take every component in with, added and changed as written: .*components: \{ whole: true \}/);
+        expect(passed?.position).toBe(header.length + "const system = System.create({ components: { with: [position] } }, (row) => { ".length);
+        const shadowed = await failure(system("components: { with: [position] }", "(row, { commands }) => { for (const row of list) commands.despawn(row); }"));
+        expect(shadowed?.message).toContain("it declares another `row` here, which hides its row: rename one");
+        expect(shadowed?.position).toBe(header.length + "const system = System.create({ components: { with: [position] } }, (row, { commands }) => { for (const ".length);
+        expect((await failure(system("components: { with: [position] }", "(row) => { console.log(row.size); }")))?.message).toContain("it reads a member of its row by name");
+        expect((await failure(system("components: { with: [position] }", "(row) => { delete row[position]; }")))?.message).toContain("it deletes a member of its row");
+        for (const readonly of ["readonly: false, ", "readonly: watching, "]) {
+            expect(await failure(`const watching = true;\n${system(`${readonly}components: { with: [position] }`, "(row) => { helper(row); }")}`)).not.toBe(null);
+        }
+        const whole = await transform(system("components: { with: [position], whole: true }", "(row) => { helper(row); }"));
+        expect(whole !== null && "code" in whole ? [whole.code.includes("components: null"), whole.warnings] : null).toEqual([true, []]);
+        // Taken whole on purpose, a row the build could follow is still taken whole.
+        expect(await inferred(system("components: { with: [position], whole: true }", "(row) => { console.log(row[position]); }"))).toContain("components: null");
+    });
+
+    test("commands by kind, keys and lists as their bindings name them, however the context reaches them", async () => {
+        const commanded = async (body: string, declaration = "components: { with: [position] }"): Promise<string> =>
+            /commands: (null|\{[^}]*\})/.exec(await inferred(`const Shapes = [mass];\nconst Listed = [velocity];\n${system(declaration, body)}`))?.[1] ?? "none";
+        expect(await commanded("(row, { commands }) => { commands.spawn([mass, ...Shapes])({}); commands.add(row.entity, velocity, 1); commands.remove(row.entity, [mass]); }"))
+            .toBe("{ spawn: [mass, Shapes], add: [velocity], remove: [mass], despawn: false }");
+        expect(await commanded("(row, context) => { const c = context.commands; c.despawn(row.entity); context.commands.add(row.entity, Listed, {}); }"))
+            .toBe("{ spawn: [], add: [Listed], remove: [], despawn: true }");
+        expect(await commanded("(row, context) => { const { commands } = context; commands.despawnWhere({ with: [mass] }); }")).toContain("despawn: true");
+        expect(await commanded("(row) => { row[position] = 1; }")).toBe("{ spawn: [], add: [], remove: [], despawn: false }");
+        for (const body of ["(row, { commands }) => { helper(commands); }", "(row, { commands }) => { commands.add(row.entity, keyOf(1), 1); }",
+            "(row, { commands: { spawn } }) => { spawn([mass]); }", "(row, context) => { helper(context); }",
+            "(row, { commands }) => { commands.spawnTables(tables); }"]) {
+            expect(await commanded(body)).toBe("null");
+        }
     });
 
-    test("an observer's row it can't follow as unknown without a warning, since the world takes an observer's as read", async () => {
+    test("a readonly system's row it can't follow as unknown without a failure, since the world takes a readonly system's as read", async () => {
         const result = await transform(system("readonly: true, components: { with: [position] }", "(row) => { helper(row); }"));
         expect(result !== null && "code" in result ? [result.code.includes("components: null"), result.warnings] : null).toEqual([true, []]);
     });
 
-    test("a row it can't follow with a warning unless the declaration says readonly: true, as the world reads it", async () => {
-        for (const observer of ["observer: false, ", "observer: watching, "]) {
-            const result = await transform(`const watching = true;\n${system(`${observer}components: { with: [position] }`, "(row) => { helper(row); }")}`);
-            expect(result !== null && "code" in result ? result.warnings.length : null).toBe(1);
-        }
-    });
-
-    test("a lookup's rows it can't follow without a warning, since what they hold is what the declaration says", async () => {
+    test("a lookup's rows it can't follow without a failure, since what they hold is what the declaration says", async () => {
         const result = await transform(system("components: { with: [target] }, lookup: { targets: { with: [mass] } }", "(row, { lookup }) => { helper(lookup.targets(row[target])); }"));
         expect(result !== null && "code" in result ? [result.code.includes(`"targets": null`), result.warnings] : null).toEqual([true, []]);
     });
 
-    test("warnings name the module by the label given, with line and column", async () => {
-        const result = await transformKernels(`${header}${system("components: { with: [position] }", "(row) => { helper(row); }")}`, "/repo/app/src/features/a/model.ts", parse,
-            async specifier => specifier === "ecs" ? ownCopy : null, () => "", createLinker(host({}, reductions), parse), true, "src/features/a/model.ts");
-        expect(result !== null && "code" in result ? result.warnings.map(warning => /^[^ ]*:/.exec(warning)?.[0]) : null).toEqual([`src/features/a/model.ts:${header.split("\n").length}:${"const system = System.create({ components: { with: [position] } }, ".length + 1}:`]);
-    });
-
     test("resources read, written and reduced, however its context reaches them", async () => {
         expect(await inferred(system("", "(context) => { context.resources[score] = context.resources[delta]; }")))
             .toContain("resources: { read: [delta], write: [score], reduce: [] }");
@@ -1519,7 +1539,7 @@ describe("inferred access", () => {
     });
 
     test("a body mentioning eval as one it can't follow", async () => {
-        expect(await inferred(system("components: { with: [position] }", "(row) => { eval(\"row[position] = 1\"); }"))).toContain("components: null");
+        expect(await inferred(system("components: { with: [position] }", "(row) => { eval(\"row[position] = 1\"); }"))).toContain("since it calls `eval`");
     });
 
     test("fail the build for an async or generator body", async () => {

package/src/implementation/compiler/transform.ts

@@ -313,9 +313,11 @@ export const transformKernels = async (
             const used = kernel?.used ?? inOrder(usedBy(declared, body, module.bindings, positions), declared);
             requireRequired(used, declared, body);
             const where = at(body);
-            // A readonly system's row, and a lookup's rows, it can't follow are taken as read whole, which is what their
-            // declarations already say; only a row taken as written whole costs what the author should know of.
-            if (used.query === null && !declaresTrue(declared, "readonly")) warnings.push(`${where}: the build can't follow how this body uses its row, so it takes every component in with, added and changed as written: index the row by key directly, or destructure it by key, to let it tell what the body reads and writes.`);
+            // A readonly system's row, a finalizer's, and a lookup's rows it can't follow are taken as read whole, which is
+            // what their declarations already say; a system's row taken as written whole would change its schedule unseen.
+            if (created === "system" && used.rowLost !== undefined && !declaresTrue(declared, "readonly")) {
+                fail(used.rowLost.at, `the build can't follow how this body uses its row, since ${used.rowLost.why}, so it would take every component in with, added and changed as written: index the row by key directly, or destructure it by key; or declare \`components: { whole: true }\` for a body that uses its row whole`);
+            }
             accessing = true;
             const access = accessText(used, where, whereReads.has(node) ? whereReads.get(node) ?? null : undefined);
             if (kernel !== undefined) {

package/src/implementation/world/activate.ts

@@ -3,13 +3,14 @@ import type { Finalizer } from '../../interface/finalizer/created.js';
 import type { Rule } from '../../interface/rule/created.js';
 import type { RuleFacts } from '../../interface/registry/strata.js';
 import { createFinalizerRunner, placeFinalizer, type FinalizerRunner } from './finalizers.js';
+import { watchResource } from './resource-changes.js';
 import { finalizerKeysOf, type TaskChannel } from './remote-systems.js';
 import { programFinalizers, programRules, programVersion } from '../../interface/registry/program.js';
 import { triggersOf } from './program.js';
 import { ensureResources, findResource } from './resources.js';
 import { idOf, metIdOf, type Key, type State } from './state.js';
 import { restratify } from './structure.js';
-import { idOfItem, idOfKey, labelOf, threadOf } from '../../interface/registry/index.js';
+import { idOfItem, idOfKey, kindOf, labelOf, threadOf } from '../../interface/registry/index.js';
 
 /**
  * Why a joined thread that imported the items of ids `imported` can't claim `threads`: a program finalizer on one that
@@ -67,7 +68,11 @@ export const placeFinalizers = (state: State): void => {
     state.finalizers.splice(0, state.finalizers.length, ...kept);
 };
 
-const resourcesOf = (finalizer: Finalizer): readonly Key[] => [...finalizer.declaration.resources?.read ?? [], ...finalizer.declaration.resources?.write ?? []];
+/** The resources a finalizer reads, writes or, for a changes finalizer, watches. */
+const resourcesOf = (finalizer: Finalizer): readonly Key[] => [
+    ...finalizer.declaration.resources?.read ?? [], ...finalizer.declaration.resources?.write ?? [],
+    ...finalizer.kind === "changes" ? (finalizer.declaration.watch ?? []).filter(key => kindOf(key) === "resource") : [],
+];
 
 /** Between runs: adds the resources of every finalizer in the program, so one can activate at any sync point. */
 export const ensureProgramResources = (state: State, ensured: { version: number }): void => {
@@ -75,6 +80,10 @@ export const ensureProgramResources = (state: State, ensured: { version: number
     if (ensured.version === version) return;
     ensured.version = version;
     ensureResources(state, new Set(programFinalizers().flatMap(resourcesOf)));
+    // A watched resource is followed from now, before its finalizer activates, so writes before then are seen.
+    for (const finalizer of programFinalizers()) {
+        if (finalizer.kind === "changes") for (const key of finalizer.declaration.watch ?? []) if (kindOf(key) === "resource") watchResource(state, idOf(state, key));
+    }
     // Finalizers waiting for these can activate at the next sync point.
     state.activation.met = true;
 };