@adobe/ecs 0.2.3 → 0.3.0

package/src/implementation/compiler/augmentations.ts

@@ -819,6 +819,9 @@ export const augmentationInsertions = async (module: Module, host: AugmentationH
                     if (error.notData.node && !thread) fail(module, member, `${key.name} is a DOM Node, which lives on "main": declare \`thread: "main"\``);
                 }
                 await checkBuiltIns(key.name, kind, typeNode, schema, builtIns);
+                const freshType = schema !== undefined ? null : await converter.freshOf(typeNode, module);
+                const emptied = schema !== undefined && "type" in schema && (schema.type === "map" || schema.type === "set") ? (schema.type === "map" ? "Map" : "Set") : freshType;
+                if (defaultNode !== undefined && emptied !== null) fail(module, defaultNode, `${key.name} is a Readonly${emptied}, which starts empty in each world: leave its default out`);
                 const given = defaultNode === undefined ? undefined : await literalDefault(defaultNode, key.name);
                 if (schema !== undefined && given !== undefined && !matchesSchema(schema, given)) fail(module, defaultNode ?? member, `${key.name}'s default isn't of its declared type`);
                 let start = given === undefined ? undefined : codeOf(given);
@@ -838,7 +841,8 @@ export const augmentationInsertions = async (module: Module, host: AugmentationH
                         const namespaced = await namespacedDefault(typeNode, key.name, undefined, oneObject);
                         if (namespaced !== null) read({ text: namespaced.text, locals: namespaced.local === undefined ? [] : [namespaced.local], given: true });
                         else if (needed && !await allowsNullType(typeNode, module, new Set())) {
-                            fail(module, member, `${kind} ${key.name} holds a value that isn't data, so nothing gives it a start: let its type allow null, or give its type a namespace with a deeply readonly \`default\`; a ReadonlyMap or ReadonlySet starts fresh in each world, a Map or Set doesn't`);
+                            if (freshType !== null) fresh = freshType;
+                            else fail(module, member, `${kind} ${key.name} holds a value that isn't data, so nothing gives it a start: let its type allow null, give its type a namespace with a deeply readonly \`default\`, or declare it a ReadonlyMap or ReadonlySet, which starts empty in each world`);
                         }
                     }
                     else {

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,10 @@ 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,
+    // and in a function, read at first need, so a list declared below the system is read once its module has loaded.
+    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/compiler/type-schemas.ts

@@ -424,11 +424,15 @@ export const createConverter = (host: TypeHost, root: string) => {
             case "TSBooleanKeyword": return { type: "boolean" };
             case "TSNullKeyword": return { type: "null" };
             case "TSUnknownKeyword": return notData(use, false);
+            // A symbol can't be cloned to another thread or saved.
+            case "TSSymbolKeyword": return use === "declaration" ? notData(use, false) : fail(module, type, `${a} is ${supported}`);
             case "TSFunctionType": case "TSConstructorType":
                 return use === "declaration" ? notData(use, false) : fail(module, type, `${a} is ${supported}`);
             case "TSParenthesizedType": return await convert(type.typeAnnotation, module, active, use);
             case "TSTypeOperator":
-                return type.operator === "readonly" ? await convert(type.typeAnnotation, module, active, use) : fail(module, type, `\`${type.operator}\` isn't ${a}: ${a} is ${supported}`);
+                if (type.operator === "readonly") return await convert(type.typeAnnotation, module, active, use);
+                // Keys, as `Resource.Key` and `unique symbol` are, may be symbols.
+                return use === "declaration" ? notData(use, false) : fail(module, type, `\`${type.operator}\` isn't ${a}: ${a} is ${supported}`);
             case "TSLiteralType": {
                 const { literal } = type;
                 if (literal.type === "Literal" && (typeof literal.value === "string" || typeof literal.value === "number" || typeof literal.value === "boolean")) return { const: literal.value };
@@ -677,7 +681,29 @@ export const createConverter = (host: TypeHost, root: string) => {
         return { anyOf: values.map(value => ({ const: value })) };
     };
 
-    return { convert, read, site, fail, typeNamed, constantNamed, returnTypeNamed, valueOfType };
+    /**
+     * `"Map"` or `"Set"` for a declared type that is a `ReadonlyMap` or `ReadonlySet`, read through aliases, which starts
+     * empty in each world whatever it holds; null for any other.
+     */
+    const freshOf = async (type: TypeNode, module: Module, seen: Set<Declared> = new Set()): Promise<"Map" | "Set" | null> => {
+        if (type.type === "TSParenthesizedType") return await freshOf(type.typeAnnotation, module, seen);
+        if (type.type === "TSTypeOperator" && type.operator === "readonly") return await freshOf(type.typeAnnotation, module, seen);
+        if (type.type !== "TSTypeReference") return null;
+        const path = nameParts(type.typeName);
+        const [only] = path;
+        const count = type.typeArguments?.params.length ?? 0;
+        if (path.length === 1 && only !== undefined && !module.types.has(only) && !module.imports.has(only)) {
+            if (only === "ReadonlyMap" && count === 2) return "Map";
+            if (only === "ReadonlySet" && count === 1) return "Set";
+        }
+        if (count !== 0) return null;
+        const found = await typeNamed(path, module);
+        if (found === null || typeof found === "string" || found.declaration.type !== "TSTypeAliasDeclaration" || seen.has(found.declaration)) return null;
+        seen.add(found.declaration);
+        return await freshOf(found.declaration.typeAnnotation, found.module, seen);
+    };
+
+    return { convert, freshOf, read, site, fail, typeNamed, constantNamed, returnTypeNamed, valueOfType };
 };
 
 /** A name and the properties read from it, `Entity.none` as `["Entity", "none"]`; null for any other expression. */

package/src/implementation/world/activate.ts

@@ -2,14 +2,15 @@
 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 { createFinalizerRunner, followResources, placeFinalizer, watchedResourcesOf, 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, keysVersion, 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,14 +68,34 @@ 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" ? watchedResourcesOf(finalizer.declaration.watch) : [],
+];
+
+/**
+ * What a world ensured of the program's resources: the program's version then, and the keys' while a changes finalizer
+ * watches resources by a trait, which a resource registering later may declare.
+ */
+export type Ensured = { version: number; keys: number; traits: boolean };
+
+/** Whether the program's finalizers may use a resource the world hasn't ensured. */
+export const programResourcesChanged = (ensured: Ensured): boolean => ensured.version !== programVersion() || (ensured.traits && ensured.keys !== keysVersion());
 
 /** 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 => {
-    const version = programVersion();
-    if (ensured.version === version) return;
-    ensured.version = version;
+export const ensureProgramResources = (state: State, ensured: Ensured): void => {
+    if (!programResourcesChanged(ensured)) return;
+    ensured.version = programVersion();
+    ensured.keys = keysVersion();
+    ensured.traits = programFinalizers().some(finalizer => finalizer.kind === "changes" && finalizer.declaration.watch.resourceTraits.length > 0);
     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 watchedResourcesOf(finalizer.declaration.watch)) watchResource(state, idOf(state, key));
+    }
+    // Active finalizers watching resources by a trait follow those registered since.
+    for (const runner of state.finalizers) if (runner.finalizer.kind === "changes") followResources(state, runner.finalizer.declaration.watch, runner.resourceWatches);
     // Finalizers waiting for these can activate at the next sync point.
     state.activation.met = true;
 };
@@ -90,11 +111,12 @@ const ready = (state: State, item: Rule | Finalizer): boolean => {
  * resolves its components' ids, which may make more ready.
  */
 export const activate = (state: State): void => {
-    const { activation } = state;
-    if (!activation.met && activation.version === programVersion()) return;
-    activateNow(state);
+    if (activationPending(state)) activateNow(state);
 };
 
+/** Whether a rule or finalizer of the program may be ready to activate: a component met, or the program changed. */
+export const activationPending = (state: State): boolean => state.activation.met || state.activation.version !== programVersion();
+
 /** `activate` once something may be ready: apart, so a sync point with nothing to activate allocates no closure context. */
 const activateNow = (state: State): void => {
     const { activation, activated, structure } = state;

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 };