@adobe/ecs 0.2.4 → 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/inferred.ts

@@ -85,8 +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)}`;
-    // 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} }`;
+    // 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)} }`;
 };
 

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

@@ -1436,13 +1436,13 @@ describe("inferred access", () => {
 
     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";
+            /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 }");
+            .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 }");
+            .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 }");
+        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); }"]) {

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,7 +2,7 @@
 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';
@@ -10,7 +10,7 @@ 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, kindOf, 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
@@ -71,19 +71,31 @@ export const placeFinalizers = (state: State): void => {
 /** 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") : [],
+    ...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 finalizer.declaration.watch ?? []) if (kindOf(key) === "resource") watchResource(state, idOf(state, key));
+        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;
 };
@@ -99,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/commands.ts

@@ -151,9 +151,10 @@ export const createCommands = (state: State, target: { readonly buffer: CommandB
     },
     spawnTables: (tables, options) => {
         const resources = options?.resources;
-        if (resources === undefined) return spawnTables(state, tables, options?.existing);
+        const updates = options?.update === true ? target.buffer : null;
+        if (resources === undefined) return spawnTables(state, tables, options?.existing, updates);
         checkResources(resources);
-        const spawned = spawnTables(state, tables, options?.existing);
+        const spawned = spawnTables(state, tables, options?.existing, updates);
         queueResources(state, resources);
         return spawned;
     },

package/src/implementation/world/create.ts

@@ -33,8 +33,8 @@ import { refreshDirectories } from './directories.js';
 import { createRegistrar, type Registration } from './register.js';
 import type { Schedule } from '../../interface/registry/schedule.js';
 import { ensureResources, findResource, initialOf, setResource } from './resources.js';
-import { ensureProgramResources, activate, finalizerCrossing, placeFinalizers } from './activate.js';
-import { isObserver, isWorldWritten, kindOf, programVersion, scheduleOf, type Composite } from '../../interface/registry/index.js';
+import { ensureProgramResources, activate, finalizerCrossing, placeFinalizers, programResourcesChanged, type Ensured } from './activate.js';
+import { isObserver, isWorldWritten, kindOf, scheduleOf, type Composite } from '../../interface/registry/index.js';
 import { always } from '../../interface/resources/always.js';
 import { cadence, type Cadence } from '../../interface/resources/cadence.js';
 import { clock } from '../../interface/resources/clock.js';
@@ -284,7 +284,7 @@ export const createWorld = (resources: InitialResources = {}, options: WorldOpti
         if (state.observer.posts.length !== 0) await settlePosts(state, true);
     };
     let disposed = false;
-    const ensured = { version: -1 };
+    const ensured: Ensured = { version: -1, keys: -1, traits: false };
 
     const minimumChunk = options.minimumChunk ?? defaultMinimumChunk;
 
@@ -545,7 +545,7 @@ export const createWorld = (resources: InitialResources = {}, options: WorldOpti
     /** Follows what changed since the last run: program resources, change watches, workers and the device; null when nothing did. */
     const prepareRun = (): Promise<void> | null => {
         // Resources added between runs move the resource entity, whose structs a tail may still read.
-        if (ensured.version !== programVersion() && (state.channels.length > 0 || state.observer.posts.length > 0)) return drainThenPrepare();
+        if (programResourcesChanged(ensured) && (state.channels.length > 0 || state.observer.posts.length > 0)) return drainThenPrepare();
         ensureProgramResources(state, ensured);
         if (startWatches(state)) return followChanges(true, false);
         if (workersChanged()) return followChanges(false, true);

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

@@ -4,7 +4,7 @@ import { Rule } from "../../interface/rule/rule.js";
 import { System } from "../../interface/system/system.js";
 import { createWorld } from "../index.js";
 import { readResource } from "./reads.test-helper.js";
-import { Entity, F32, I32, Mat4x4, Quat, U32, Vec2, Vec3, Vec4 } from "../../index.js";
+import { Entity, F32, I32, Mat4x4, Quat, U32, Vec2, Vec3, Vec4, type Resource } from "../../index.js";
 
 const pool = Symbol();
 const names = Symbol();
@@ -14,6 +14,8 @@ const index = Symbol();
 const turn = Symbol();
 const least = Symbol();
 const all = Symbol();
+const written = Symbol();
+const keys = Symbol();
 
 /** A pool declared through an alias of ReadonlyMap. */
 type Pool = ReadonlyMap<string, number>;
@@ -30,6 +32,8 @@ declare module "@adobe/ecs" {
         [turn]: { type: Quat };
         [least]: { type: F32; reduce: "min" };
         [all]: { type: boolean; reduce: "&" };
+        [written]: { type: ReadonlyMap<Resource.Key, unknown> };
+        [keys]: { type: ReadonlySet<symbol> };
     }
 }
 
@@ -49,6 +53,25 @@ describe("a resource declared without a default", () => {
     });
 });
 
+describe("a ReadonlyMap or ReadonlySet of what isn't data", () => {
+    it("starts at an empty one of each world's own, which a system replaces whole, keys and values kept as they are", async () => {
+        await using first = createWorld();
+        await using second = createWorld();
+        const [firstWritten, secondWritten] = [await readResource(first, written), await readResource(second, written)];
+        expect([firstWritten, secondWritten, await readResource(first, keys)]).toEqual([new Map(), new Map(), new Set()]);
+        expect(firstWritten).not.toBe(secondWritten);
+        const value = { at: 1 };
+        await first.run(System.create(({ resources }) => {
+            resources[written] = new Map([[count, value]]);
+            resources[keys] = new Set([count]);
+        }));
+        const read = await readResource(first, written);
+        expect([read.get(count), await readResource(first, keys)]).toEqual([value, new Set([count])]);
+        expect(read.get(count)).toBe(value);
+        expect(await readResource(second, written)).toBe(secondWritten);
+    });
+});
+
 describe("a derived component declared without a default", () => {
     it("starts every row of a world at one empty Map of its own, since values are replaced whole", async () => {
         const spawn = System.create(({ commands }) => {

package/src/implementation/world/despawn-where.test.ts

@@ -119,16 +119,36 @@ describe("despawnWhere", () => {
         await world.dispose();
     });
 
-    it("despawns matching entities spawned at the same sync point, whenever spawned, since spawns commit first", async () => {
+    it("keeps what the same sync point spawns, whenever spawned and whatever earlier commands give it", async () => {
         const { world, run } = withCommands();
+        let alive = Entity.none;
+        await run(commands => { alive = commands.spawn([mark, value])({ [value]: 0 }); });
         const spawned: Entity[] = [];
         await run(commands => {
             spawned.push(commands.spawn([mark, value])({ [value]: 1 }));
+            const tagged = commands.spawn([value])({ [value]: 2 });
+            commands.add(tagged, mark);
+            spawned.push(tagged);
             commands.despawnWhere({ with: [mark] });
-            spawned.push(commands.spawn([mark, value])({ [value]: 2 }));
-            spawned.push(commands.spawn([value])({ [value]: 3 }));
+            spawned.push(commands.spawn([mark, value])({ [value]: 3 }));
         });
-        expect(await aliveEach(world, spawned)).toEqual([false, false, true]);
+        expect([await aliveEach(world, [alive]), await aliveEach(world, spawned)]).toEqual([[false], [true, true, true]]);
+        await world.dispose();
+    });
+
+    it("clears the events a frame made before, keeping those it makes, in one system", async () => {
+        const { world, run } = withCommands();
+        let first = Entity.none, second = Entity.none;
+        await run(commands => {
+            commands.despawnWhere({ with: [mark] });
+            first = commands.spawn([mark, value])({ [value]: 1 });
+        });
+        expect(await aliveEach(world, [first])).toEqual([true]);
+        await run(commands => {
+            commands.despawnWhere({ with: [mark] });
+            second = commands.spawn([mark, value])({ [value]: 2 });
+        });
+        expect(await aliveEach(world, [first, second])).toEqual([false, true]);
         await world.dispose();
     });
 
@@ -256,18 +276,21 @@ describe("despawnWhere", () => {
         await world.dispose();
     });
 
-    it("despawns by where the entities spawned at the same sync point, and none for a value no archetype holds", async () => {
+    it("despawns by where what was alive before the sync point, keeping what it spawns, and none for a value no archetype holds", async () => {
         const { world, run } = withCommands();
         const spawned: Entity[] = [];
         await run(commands => {
             spawned.push(commands.spawn([mark, chunk], { [chunk]: 1 })());
-            commands.despawnWhere({ with: [mark], where: { [chunk]: 1 } });
             spawned.push(commands.spawn([mark, chunk], { [chunk]: 2 })());
+        });
+        await run(commands => {
+            spawned.push(commands.spawn([mark, chunk], { [chunk]: 1 })());
+            commands.despawnWhere({ with: [mark], where: { [chunk]: 1 } });
             commands.despawnWhere({ with: [mark], where: { [chunk]: 3 } });
         });
-        expect(await aliveEach(world, spawned)).toEqual([false, true]);
+        expect(await aliveEach(world, spawned)).toEqual([false, true, true]);
         await run(commands => commands.despawnWhere({ with: [mark], where: {} }));
-        expect(await aliveEach(world, spawned)).toEqual([false, false]);
+        expect(await aliveEach(world, spawned)).toEqual([false, false, false]);
         await world.dispose();
     });
 

package/src/implementation/world/execute.ts

@@ -3,14 +3,15 @@ import type { Leaf } from '../../interface/system/leaf.js';
 import type { Chunk, ChunkResult, Runner, Workers } from './runner.js';
 import type { Schedule } from '../../interface/registry/schedule.js';
 import type { Archetype, Storage } from './archetype.js';
-import { countRan, idOf, startRan, type State } from './state.js';
+import { countRan, countRanHere, idOf, startRan, type State } from './state.js';
 import type { GpuEngine } from './gpu.js';
 import { applySync, prepareSync, syncPending } from './synchronize.js';
-import { activate } from './activate.js';
+import { resourcesWritten } from './resource-changes.js';
+import { activate, activationPending } from './activate.js';
 import { markRun } from './move-log.js';
 import { postTails, settleAll, settleKeys, settleRunners, tailsOf, type TailOutcome } from './tails.js';
 import { settlePosts, settleObserverKeys, settleObserverRunners } from './joined-observer.js';
-import { locate } from './entities.js';
+import { locate, reserved } from './entities.js';
 import { clearBuffer, createBuffer } from './buffer.js';
 import { drainSegment, type Segment } from './command-ring.js';
 import { combine, identityOf, writeReduction, type ReductionTarget } from './reductions.js';
@@ -101,6 +102,18 @@ type Prepared = {
     readonly remotes: number[];
     /** The indexes each tier's runners look up through, refreshed before it. */
     readonly uses: (readonly IndexUse[])[];
+    /**
+     * By tier, the last tier of the pass starting there: tiers whose systems all run on the world's thread as written,
+     * which look up through no index from the second on, run in one pass while their sync points apply nothing. Its own
+     * tier for any other.
+     */
+    readonly passes: number[];
+    /**
+     * By tier within a pass of several, how many runners it and the pass's later tiers hold, and whether any runs on the
+     * GPU: what a pass entered there counts once it ran to its end.
+     */
+    readonly passSystems: number[];
+    readonly passGpu: boolean[];
     /** The world's `runnersVersion` its runners were read at. */
     version: number;
     readonly started: (readonly Chunk[])[][];
@@ -168,7 +181,8 @@ const preparedFor = (context: ExecuteContext, schedule: Schedule): Prepared => {
     let prepared = bySchedule.get(schedule);
     if (prepared === undefined) {
         prepared = {
-            runners: schedule.tiers.map(tier => tier.map(context.runnerOf)), remotes: schedule.tiers.map(() => 0), uses: schedule.tiers.map(() => []), version: -1,
+            runners: schedule.tiers.map(tier => tier.map(context.runnerOf)), remotes: schedule.tiers.map(() => 0), uses: schedule.tiers.map(() => []),
+            passes: schedule.tiers.map((_, t) => t), passSystems: schedule.tiers.map(() => 0), passGpu: schedule.tiers.map(() => false), version: -1,
             started: schedule.tiers.map(tier => new Array<readonly Chunk[]>(tier.length)),
             systems: [], tiers: [], tasks: new Map(), warnings: [], warningCount: 0, warned: null, outcome: { failures: null, skipped: null },
             placement: -1, tailing: null, settling: 0, chunk: 0, error: undefined, tierFailed: false, dropped: 0,
@@ -189,9 +203,38 @@ const refresh = (context: ExecuteContext, schedule: Schedule, prepared: Prepared
         prepared.remotes[t] = remote;
         prepared.uses[t] = mergeUses(runners);
     }
+    passesOf(schedule, prepared);
     prepared.version = context.state.runnersVersion;
 };
 
+/** Whether every runner of a tier runs on the world's thread as written: none a kernel or on a joined thread. */
+const asWritten = (runners: readonly Runner[]): boolean => {
+    for (let i = 0; i < runners.length; i++) if (runners[i].kernel !== null || runners[i].remote !== null) return false;
+    return true;
+};
+
+/** Finds a schedule's passes (`Prepared["passes"]`) from its runners as read now. */
+const passesOf = (schedule: Schedule, prepared: Prepared): void => {
+    const { runners, uses, passes, passSystems, passGpu } = prepared;
+    let last = -1;
+    for (let t = 0; t < schedule.tiers.length; t++) {
+        if (!asWritten(runners[t])) last = t;
+        else if (last < t) {
+            last = t;
+            while (last + 1 < schedule.tiers.length && uses[last + 1].length === 0 && asWritten(runners[last + 1])) last++;
+        }
+        passes[t] = last;
+    }
+    for (let t = schedule.tiers.length - 1; t >= 0; t--) {
+        const tier = runners[t];
+        const continues = passes[t] > t;
+        let gpu = continues && passGpu[t + 1];
+        for (let i = 0; i < tier.length; i++) if (tier[i].placement !== "cpu") gpu = true;
+        passSystems[t] = tier.length + (continues ? passSystems[t + 1] : 0);
+        passGpu[t] = gpu;
+    }
+};
+
 /**
  * Drains a worker's segment into a buffer of its own, queued in its place: commands, spawn blocks staged to commit in
  * its place, and the reservations it left unused. Fails if it doesn't start with its task's merge tag.
@@ -477,11 +520,20 @@ const executeTiers = (context: ExecuteContext, whole: Schedule, args: unknown):
                 if (building !== null) return handed = executeFrom(context, schedule, prepared, folds, args, null, t, building, null);
                 if (state.indexFailures.length !== 0) (outcome.failures ??= []).push(...state.indexFailures.splice(0));
             }
-            startTier(context, prepared, t, args);
-            const waiting = settleTier(state, folds, prepared, schedule.tiers[t], t, nothing);
-            if (waiting !== null) return handed = executeFrom(context, schedule, prepared, folds, args, null, t, null, waiting);
-            if (endTier(state, null, prepared, schedule, t)) break;
-            if (schedule.syncs[t] !== null) syncNow(context, prepared, false);
+            const last = prepared.passes[t];
+            if (last > t) {
+                const reached = runPass(context, prepared, schedule, folds, args, t, last);
+                if (typeof reached !== "number") return handed = reached;
+                if (reached < 0) break;
+                t = reached;
+            }
+            else {
+                startTier(context, prepared, t, args);
+                const waiting = settleTier(state, folds, prepared, schedule.tiers[t], t, nothing);
+                if (waiting !== null) return handed = executeFrom(context, schedule, prepared, folds, args, null, t, null, waiting);
+                if (endTier(state, null, prepared, schedule, t)) break;
+            }
+            if (schedule.syncs[t] !== null && !idleSync(state)) syncNow(context, prepared, false);
         }
     }
     finally {
@@ -490,6 +542,43 @@ const executeTiers = (context: ExecuteContext, whole: Schedule, args: unknown):
     return reportOf(state, prepared);
 };
 
+/**
+ * Runs tiers `first` to `last`, a pass, one after another with none of the checks between tiers that only a tier on
+ * another thread, using an index or after a sync point that applies something needs. Returns the last tier it ran,
+ * after which the caller applies its sync point: `last`, or one before it whose sync point applies something or whose
+ * bodies replaced runners; -1 when one failed, the tiers after it skipped; or what `executeFrom` returns once one waits
+ * for something.
+ */
+const runPass = (context: ExecuteContext, prepared: Prepared, schedule: Schedule, folds: Map<unknown, Fold> | null, args: unknown, first: number, last: number): number | Promise<RunReport> => {
+    const { state } = context;
+    for (let v = first; v <= last; v++) {
+        startTier(context, prepared, v, args);
+        const waiting = settleTier(state, folds, prepared, schedule.tiers[v], v, nothing);
+        if (waiting !== null) {
+            for (let ran = first; ran < v; ran++) countRan(state, prepared.runners[ran]);
+            return executeFrom(context, schedule, prepared, folds, args, null, v, null, waiting);
+        }
+        if (prepared.tierFailed || (v < last && (prepared.version !== state.runnersVersion || (schedule.syncs[v] !== null && !idleSync(state))))) {
+            for (let ran = first; ran <= v; ran++) countRan(state, prepared.runners[ran]);
+            if (!prepared.tierFailed) return v;
+            const { outcome } = prepared;
+            for (let later = v + 1; later < schedule.tiers.length; later++) for (const leaf of schedule.tiers[later]) (outcome.skipped ??= []).push(leaf);
+            return -1;
+        }
+    }
+    countRanHere(state, prepared.passSystems[first], prepared.passGpu[first]);
+    return last;
+};
+
+/**
+ * Whether a sync point within a run, with no joined thread, would apply nothing and leave nothing to do after:
+ * nothing queued, drained, unreserved or pending (`syncPending`), no rule or finalizer to activate, and no layout for
+ * workers to see.
+ */
+const idleSync = (state: State): boolean => state.queued.length === 0 && state.drained === 0 && state.unused.length === 0
+    && state.channels.length === 0 && state.logs.length === 0 && state.bumped.length === 0 && state.counted.length === 0 && state.carried === null && !state.structure.rederive && state.unplaced.length === 0
+    && (state.resourcesSeen.size === 0 || !resourcesWritten(state)) && !activationPending(state) && !reserved(state.entities);
+
 /**
  * A sync point with nothing to wait for: no GPU, tails or observer posts, which `executeTiers` checked before each
  * tier and bodies can't add. The run's `last` lets go of strings no reader holds.

package/src/implementation/world/finalizers.ts

@@ -14,7 +14,8 @@ import { idOf, type Key, type State } from './state.js';
 import type { Queued } from './synchronize.js';
 import type { Essential, ReadonlyType } from '../../interface/component/value.js';
 import type { Leaf } from '../../interface/finalizer/created.js';
-import { newestKeyOf, threadOf } from '../../interface/registry/index.js';
+import { declaredOf, declaresTrait, newestKeyOf, threadOf, threadOfDeclaration } from '../../interface/registry/index.js';
+import type { ResolvedChanges } from '../../interface/finalizer/declaration.js';
 import type { Layout } from '../../interface/registry/layout.js';
 import type { TaskChannel } from './remote-systems.js';
 import { resourceOffsetsOf, writeStops, type StopsOf } from './stop-lists.js';
@@ -30,8 +31,8 @@ export type FinalizerRunner = {
     readonly excluded: readonly number[];
     /** For a changes finalizer: whether it watches a component, by id. */
     readonly watches: (id: number) => boolean;
-    /** For a changes finalizer: the resources it watches, by id. */
-    readonly resourceWatches: readonly number[];
+    /** For a changes finalizer: the resources it watches, by id, which grow as resources declaring a trait it watches register. */
+    readonly resourceWatches: number[];
     /** By archetype id: 1 if it matches, 2 if not, 0 until known. */
     readonly matches: number[];
     readonly context: Context;
@@ -63,19 +64,23 @@ export const createFinalizerRunner = (state: State, finalizer: Finalizer): Final
     const reads = query?.read ?? [];
     // By default every component that isn't derived, including ones a world first meets later; never resources, nor
     // the objects a joined thread fills, whose storage here holds only tags.
-    let watches = (id: number): boolean => !state.derived[id] && !state.resources.has(id) && state.remote[id] === undefined;
-    const watch = finalizer.kind === "changes" ? finalizer.declaration.watch : undefined;
+    const everyComponent = (id: number): boolean => !state.derived[id] && !state.resources.has(id) && state.remote[id] === undefined;
+    let watches = everyComponent;
     const resourceWatches: number[] = [];
-    if (watch !== undefined) {
-        // `Finalizer.changes` rejected derived components.
-        const watched = new Set(watch.map(key => idOf(state, key)));
-        for (const id of watched) {
-            if (!state.resources.has(id)) continue;
-            watched.delete(id);
-            resourceWatches.push(id);
-            watchResource(state, id);
+    if (finalizer.kind === "changes") {
+        const { watch } = finalizer.declaration;
+        followResources(state, watch, resourceWatches);
+        if (watch.components !== true) {
+            // `Finalizer.changes` rejected derived components.
+            const listed = new Set(watch.components.map(key => idOf(state, key)));
+            const traits = watch.componentTraits;
+            if (traits.length === 0) watches = id => listed.has(id);
+            else {
+                /** By id: 1 where its key declares one of the traits, 2 where it doesn't. */
+                const declaring: number[] = [];
+                watches = id => listed.has(id) || (everyComponent(id) && (declaring[id] ??= declaresTrait(state.keys[id], traits) ? 1 : 2) === 1);
+            }
         }
-        watches = id => watched.has(id);
     }
     const target = { buffer: createBuffer() };
     const commands = createCommands(state, target);
@@ -102,6 +107,30 @@ export const createFinalizerRunner = (state: State, finalizer: Finalizer): Final
     };
 };
 
+/**
+ * The resources a changes finalizer watches: those it lists, and those registered so far that declare a trait it
+ * watches, but those on another thread than the world's.
+ */
+export const watchedResourcesOf = (watch: ResolvedChanges["watch"]): readonly Key[] => {
+    if (watch.resourceTraits.length === 0) return watch.resources;
+    const found: Key[] = [...watch.resources];
+    for (const [key, declared] of declaredOf("resource")) {
+        const thread = threadOfDeclaration(declared);
+        if ((thread === null || thread === "world") && declaresTrait(key, watch.resourceTraits)) found.push(key);
+    }
+    return found;
+};
+
+/** Adds to `ids` each resource a changes finalizer watches that it doesn't hold, following its changes from now. */
+export const followResources = (state: State, watch: ResolvedChanges["watch"], ids: number[]): void => {
+    for (const key of watchedResourcesOf(watch)) {
+        const id = idOf(state, key);
+        if (ids.includes(id)) continue;
+        ids.push(id);
+        watchResource(state, id);
+    }
+};
+
 /**
  * Places a finalizer on a joined thread's channel, posting it there, or back on the world's thread with null. Its reads
  * are listed as the thread reads them: objects by their tags, linear structs by their bytes, strings by handles of

package/src/implementation/world/lifetime.test-helper.ts

@@ -73,7 +73,7 @@ export const freshKernel = (system: System): System => {
     const description = kernelOf(system);
     if (leaf === undefined || leaf.kind === "composite" || description === undefined) throw new Error("Not a kernel system.");
     // What `System.create` makes of the same declaration and body, without the id a top-level binding takes.
-    const copy: Leaf & System = { kind: leaf.kind, name: leaf.name, declaration: leaf.declaration, input: leaf.input, body: leaf.body };
+    const copy: Leaf & System = { kind: leaf.kind, name: leaf.name, declaration: leaf.declaration, input: leaf.input, body: leaf.body, commands: leaf.commands };
     claimSystem(copy, undefined);
     return attachKernel(copy, description);
 };