@adobe/ecs 0.2.1 → 0.2.4

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/describe.test-helper.ts

@@ -51,7 +51,7 @@ export const spawn = System.create(({ commands }) => {
     commands.spawn([position, velocity])({ [position]: [0, 0, 0], [velocity]: [1, 0, 0] });
 });
 
-export const observe = System.create({ observer: true, components: { with: [position] } }, row => {
+export const observe = System.create({ readonly: true, components: { with: [position] } }, row => {
     console.log(row[position]);
 });
 

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

@@ -109,7 +109,7 @@ describe("a module's systems described", () => {
     it("says why systems that run as written have no code: per-run systems, observers, render systems, kernel: false and one declared in a function", () => {
         expect(described("spawn")).toMatchObject({ kind: "per-run", runs: `Its body as written, on the "world" thread` });
         for (const backend of ["js", "wasm", "wgsl"] as const) expect(reasonOf(described("spawn")[backend])).toBe("per-run systems run as written; only row systems compile");
-        expect(described("observe")).toMatchObject({ kind: "observer", js: { kind: "none", reason: expect.stringMatching(/^an observer runs as written/) } });
+        expect(described("observe")).toMatchObject({ kind: "readonly", js: { kind: "none", reason: expect.stringMatching(/^a readonly system runs as written/) } });
         expect(described("draw")).toMatchObject({ kind: "render", runs: expect.stringContaining("while the world has a GPU device"), wgsl: { kind: "none", reason: expect.stringMatching(/^a render system runs as written/) } });
         const unflagged = described("unflagged");
         expect(unflagged).toMatchObject({ kernel: false, js: { kind: "none", reason: "as written, because `kernel: false`" }, wasm: { kind: "none", reason: "as written, because `kernel: false`" }, wgsl: { kind: "eligible" } });

package/src/implementation/compiler/describe.ts

@@ -30,7 +30,7 @@ export type Backend =
  * What runs a system: over every matched row, once per run, as an observer, on one entity its input names (`target`),
  * or as a render system.
  */
-export type SystemKind = "row" | "per-run" | "observer" | "target" | "render";
+export type SystemKind = "row" | "per-run" | "readonly" | "target" | "render";
 
 /**
  * A system of a module as the build compiles it: its call's offsets in the code transformed, the binding it's
@@ -427,7 +427,7 @@ export const describeSystems = async (sites: TransformedSites, format: (code: st
         const kernel: boolean | "gpu" | null = literal === true || literal === false ? literal : literal === "gpu" ? "gpu" : null;
         const kind: SystemKind = created === "render" ? "render"
             : declaration === undefined ? "per-run"
-            : propertyOf(declaration, "observer") !== null ? "observer"
+            : propertyOf(declaration, "readonly") !== null ? "readonly"
             : propertyOf(declaration, "target") !== null ? "target"
             : propertyOf(declaration, "components") !== null ? "row" : "per-run";
         const base = { start: node.start, end: node.end, binding: bindings.get(node) ?? null, kind, kernel };
@@ -442,7 +442,7 @@ export const describeSystems = async (sites: TransformedSites, format: (code: st
             ? threadOf(declaration, body, kind === "render" ? positionsOf("render", declaration) : positionsOf("system", declaration)) : "world";
         if (kind === "render") return asWritten("a render system runs as written, recording GPU work with shaders of your own; `Gpu.wgsl` gives them their accessors", "world");
         if (kind === "per-run") return asWritten("per-run systems run as written; only row systems compile", written());
-        if (kind === "observer") return asWritten("an observer runs as written, reading the settled state after the run's last sync point; only row systems that aren't observers compile", written());
+        if (kind === "readonly") return asWritten("a readonly system runs as written, reading the settled state after the run's last sync point; only row systems that aren't readonly compile", written());
         if (kind === "target") return asWritten("a system with `target` runs as written, once, on the entity its input names; only systems over every matched row compile", written());
         if (declaration === undefined || body === undefined || body.type === "SpreadElement" || !isFunction(body)) {
             return asWritten(declaration === undefined ? "its declaration isn't written in its call, so the build can't read whether it's a kernel" : "its body isn't a function written in place or bound at module scope, so the build can't read it", "world");

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/hygiene.test.ts

@@ -34,7 +34,7 @@ const spawn = System.create(({ commands }) => {
 });
 
 const read: number[][] = [];
-const readAll = System.create({ observer: true, components: { with: [p, c, l, s, e, v0, v1] } }, row => {
+const readAll = System.create({ readonly: true, components: { with: [p, c, l, s, e, v0, v1] } }, row => {
     read.push([row[p], row[c], row[l], row[s], row[e], row[v0], row[v1]]);
 });
 

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/plugin.test.ts

@@ -645,7 +645,7 @@ export { World as OtherWorld };
 export const runOther = async (key) => {
     const spawn = System.create(({ commands }) => { commands.spawn([key].slice())({ [key]: 10 }); });
     let total = 0;
-    const count = System.create({ observer: true, components: { with: [key] } }, (row) => { total += row[key]; });
+    const count = System.create({ readonly: true, components: { with: [key] } }, (row) => { total += row[key]; });
     const world = World.create();
     await world.run(spawn);
     await world.run(spawn);
@@ -662,7 +662,7 @@ declare$(score, "component", { type: { type: "number" } });
 ${recorder}
 const spawn = System.create(({ commands }) => { commands.spawn([score].slice())({ [score]: 1 }); });
 let counted = 0;
-const count = System.create({ observer: true, components: { with: [score] } }, (row) => { counted += row[score]; });
+const count = System.create({ readonly: true, components: { with: [score] } }, (row) => { counted += row[score]; });
 export const copies = World === OtherWorld ? 1 : 2;
 export const run = async () => {
     const world = World.create();

package/src/implementation/compiler/signature.ts

@@ -120,7 +120,7 @@ export const kernelOf = (declaration: ObjectExpression): KernelRequest | null =>
         }
     }
     if (declaration.properties.some(property => property.type === "SpreadElement")) return null;
-    if (!declares(declaration, "components") || declares(declaration, "observer") || declares(declaration, "target")) return null;
+    if (!declares(declaration, "components") || declares(declaration, "readonly") || declares(declaration, "target")) return null;
     return { target: "cpu", required: false };
 };
 

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

@@ -335,7 +335,7 @@ describe("kernels by default", () => {
     test("runs as written, without failing, a body that leaves the subset or a declaration a kernel can't have", async () => {
         expect(await attached(`const log = []; const kernel = System.create({ components: { with: [mass] } }, row => { log.push(row[mass]); });`)).toBe(false);
         expect(await attached(`const kernel = System.create({ components: { with: [mass] } }, (row, { resources }) => { resources[delta] = row[mass]; });`)).toBe(false);
-        expect(await attached(`const kernel = System.create({ observer: true, components: { with: [mass] } }, row => { void row[mass]; });`)).toBe(false);
+        expect(await attached(`const kernel = System.create({ readonly: true, components: { with: [mass] } }, row => { void row[mass]; });`)).toBe(false);
         expect(await attached(`const kernel = System.create({ target: "entity", components: { with: [score] } }, row => { row[score] = 1; });`)).toBe(false);
         expect(await attached(`const make = () => System.create({ components: { with: [score] } }, row => { row[score] = 1; });`)).toBe(false);
     });
@@ -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 () => {
-        const result = await transform(system("observer: true, components: { with: [position] }", "(row) => { helper(row); }"));
+    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 observer: 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

@@ -141,7 +141,7 @@ export const functionOf = (binding: ModuleBinding | undefined): Node | undefined
 const empty: ObjectExpression = { type: "ObjectExpression", properties: [], start: 0, end: 0 };
 
 /** Whether a declaration has property `name`, written out. */
-/** Whether a declaration gives `name` the literal `true`, as the world takes `observer`. */
+/** Whether a declaration gives `name` the literal `true`, as the world takes `readonly`. */
 const declaresTrue = (declaration: ObjectExpression, name: string): boolean => declaration.properties.some(property =>
     property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === name
     && property.value.type === "Literal" && property.value.value === true);
@@ -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);
-            // An observer'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, "observer")) 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;
 };

package/src/implementation/world/batches.test.ts

@@ -29,7 +29,7 @@ declare module "@adobe/ecs" {
 }
 
 describe("staged spawns", () => {
-    it("are seen once by `added` observers in earlier, the same and later tiers, and not before the sync point", async () => {
+    it("are seen once by `added` observers in earlier, the same and later tiers, from the sync point after them", async () => {
         const seen = { early: 0, same: 0, late: 0 };
         const spawned: Entity[] = [];
         const early = System.create({ components: { added: [score] } }, () => { seen.early++; });
@@ -42,8 +42,8 @@ describe("staged spawns", () => {
         const frame = System.create({ systems: [early, spawn, same, late] });
         const world = createWorld({ [workers]: 0 });
         await world.run(frame);
-        // Nothing saw the spawns during their own run.
-        expect(seen).toEqual({ early: 0, same: 0, late: 0 });
+        // Only what follows the spawn saw them in their own run, after the sync point it needs.
+        expect(seen).toEqual({ early: 0, same: 0, late: 100 });
         await world.run(frame);
         await world.run(frame);
         expect(seen).toEqual({ early: 100, same: 100, late: 100 });

package/src/implementation/world/buffer.ts

@@ -7,6 +7,13 @@ export const spawnCommand = 0;
 export const despawnCommand = 1;
 export const addCommand = 2;
 export const removeCommand = 3;
+/**
+ * Names the ids of its query's `with`, then of its `not`, and with a `where`, last, `despawnWhereHolds`, whose value is
+ * whether an archetype holds the `where`'s values; its entity is how many are of `with`.
+ */
+export const despawnWhereCommand = 4;
+/** The id a `despawnWhere` names its `where` by, which no component has. */
+export const despawnWhereHolds = -1;
 
 /** Rows `start` to `end` of a kernel's spawn batch, committed in its buffer's place in merge order. */
 export type Staged = { batch: SpawnBatch; start: number; end: number };