@adobe/ecs 0.2.3 → 0.2.4

package/src/implementation/world/resource-changes.ts

@@ -0,0 +1,67 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { readCell } from './cells.js';
+import { indexOf } from './entities.js';
+import type { Storage } from './archetype.js';
+import type { State } from './state.js';
+
+/** A watched resource written to a value that isn't equal to the one its finalizers last saw. */
+export type ResourceChange = { readonly id: number; readonly previous: unknown; readonly next: unknown };
+
+const noChanges: readonly ResourceChange[] = [];
+
+/** Where resource `id` lives now, or null before the world has it. */
+const cellOf = (state: State, id: number): { readonly storage: Storage; readonly row: number } | null => {
+    if (state.resourceEntity < 0) return null;
+    const index = indexOf(state.resourceEntity);
+    const storage = state.archetypes[state.entities.archetype[index]]?.storageById[id];
+    return storage === undefined ? null : { storage, row: state.entities.row[index] };
+};
+
+/** Starts following resource `id` for a changes finalizer watching it, from its value now. */
+export const watchResource = (state: State, id: number): void => {
+    if (state.resourcesSeen.has(id)) return;
+    const cell = cellOf(state, id);
+    state.resourcesSeen.set(id, cell === null ? { value: state.starts[id], tick: 0 } : { value: readCell(cell.storage, cell.row), tick: cell.storage.changed[cell.row] });
+};
+
+/** Whether a watched resource was written since its finalizers last ran, so a sync point is due for them to see it. */
+export const resourcesWritten = (state: State): boolean => {
+    for (const [id, seen] of state.resourcesSeen) {
+        const cell = cellOf(state, id);
+        if (cell !== null && cell.storage.changed[cell.row] > seen.tick) return true;
+    }
+    return false;
+};
+
+/**
+ * Each watched resource written since its finalizers last ran, to a value that isn't equal to the one they saw then,
+ * with that value and its value now, which they see from now on.
+ */
+export const takeResourceChanges = (state: State): readonly ResourceChange[] => {
+    let changes: ResourceChange[] | null = null;
+    for (const [id, seen] of state.resourcesSeen) {
+        const cell = cellOf(state, id);
+        if (cell === null) continue;
+        const tick = cell.storage.changed[cell.row];
+        if (tick <= seen.tick) continue;
+        const next = readCell(cell.storage, cell.row);
+        if (!sameValue(seen.value, next)) (changes ??= []).push({ id, previous: seen.value, next });
+        state.resourcesSeen.set(id, { value: next, tick });
+    }
+    return changes ?? noChanges;
+};
+
+const isPlain = (value: object): boolean => {
+    const prototype: unknown = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+
+/** Whether two values are equal: data leaf by leaf, as `Object.is` compares leaves, and any other object by identity. */
+export const sameValue = (a: unknown, b: unknown): boolean => {
+    if (Object.is(a, b)) return true;
+    if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+    if (Array.isArray(a)) return Array.isArray(b) && a.length === b.length && a.every((item, i) => sameValue(item, b[i]));
+    if (Array.isArray(b) || !isPlain(a) || !isPlain(b)) return false;
+    const keys = Object.keys(a);
+    return keys.length === Object.keys(b).length && keys.every(key => Object.hasOwn(b, key) && sameValue(Reflect.get(a, key), Reflect.get(b, key)));
+};

package/src/implementation/world/rows.ts

@@ -12,7 +12,7 @@ import { ownTag } from './move-log.js';
 import { resourceCell } from './resources.js';
 import { labelOf } from '../../interface/registry/names.js';
 import { idOf, type Key, type State } from './state.js';
-import { readTables } from './tables-read.js';
+import { tablesReader } from './tables-read.js';
 import { combine, contributed, identityOf, type ReductionTarget } from './reductions.js';
 import { createIndexLookup, type Since } from './index-lookups.js';
 import type { WorldIndex } from './indexes.js';
@@ -131,13 +131,26 @@ const viewOf = (storage: RowStorage): TypedArray => {
     return layout.kind === "linear" && storage.write !== writeGeneral ? storage.views[layout.leaves[0].view] : storage.views.f32;
 };
 
-const slotOf = (archetype: RowArchetype, id: number): Slot => {
+const storageOf = (archetype: RowArchetype, id: number): RowStorage => {
     const storage = archetype.storageById[id];
     // A system matches only archetypes with every component it reads or writes.
     if (storage === undefined) throw new Error(`Archetype ${archetype.id} lacks component ${id}.`);
+    return storage;
+};
+
+const slotOf = (archetype: RowArchetype, id: number): Slot => {
+    const storage = storageOf(archetype, id);
     return { storage, view: viewOf(storage), value: constantOf(storage) };
 };
 
+/** Points `slot` at `archetype`'s storage of component `id`, allocating nothing, since rows bind once per archetype a run. */
+const bindSlot = (slot: Slot, archetype: RowArchetype, id: number): void => {
+    const storage = storageOf(archetype, id);
+    slot.storage = storage;
+    slot.view = viewOf(storage);
+    slot.value = constantOf(storage);
+};
+
 /** An optional component's getter where the archetype lacks it, and its setter, which fails its system. */
 const absentGetter = (): undefined => undefined;
 const absentSetterOf = (key: Key): (value: unknown) => void => () => {
@@ -168,11 +181,7 @@ export const createRow = (host: RowHost, archetype: RowArchetype, keys: readonly
             row.entities = next.entities;
             for (let i = 0; i < ids.length; i++) {
                 const slot = slots[i];
-                if (slot === undefined) continue;
-                const { storage, view, value } = slotOf(next, ids[i]);
-                slot.storage = storage;
-                slot.view = view;
-                slot.value = value;
+                if (slot !== undefined) bindSlot(slot, next, ids[i]);
             }
         },
     };
@@ -271,12 +280,7 @@ export const sharedRows = (host: RowHost, keys: readonly Key[], ids: readonly nu
             slots: ids.map(id => slotOf(archetype, id)),
             bind: next => {
                 row.entities = next.entities;
-                for (let i = 0; i < ids.length; i++) {
-                    const { storage, view, value } = slotOf(next, ids[i]);
-                    row.slots[i].storage = storage;
-                    row.slots[i].view = view;
-                    row.slots[i].value = value;
-                }
+                for (let i = 0; i < ids.length; i++) bindSlot(row.slots[i], next, ids[i]);
             },
         };
         Object.defineProperty(value, rowOfValue, { value: row });
@@ -511,7 +515,10 @@ export const createContext = (state: State, declaration: Pick<Resolved, "lookup"
     const value: { up?: unknown } = own();
     const { tables } = declaration;
     // Each read copies the tables as they are then.
-    if (tables !== undefined) Object.defineProperty(value, "tables", { get: () => readTables(state, tables), enumerable: true });
+    if (tables !== undefined) {
+        const read = tablesReader(state, tables);
+        Object.defineProperty(value, "tables", { get: read, enumerable: true });
+    }
     const { lookup, resources } = declaration;
     const names = Object.keys(lookup ?? {});
     if (names.length > 0) {

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

@@ -226,6 +226,43 @@ describe("references", () => {
         await world.dispose();
     });
 
+    it("cascade through entities spawned together, whichever archetype each is spawned into first", async () => {
+        const world = createWorld({ [workers]: 0 });
+        const step = at(world);
+        let gone = Entity.none, owner = Entity.none, child = Entity.none, watcher = Entity.none;
+        await step(commands => { gone = commands.spawn([mark])({ [mark]: 0 }); });
+        await step(commands => commands.despawn(gone));
+        await step(commands => {
+            // The archetypes of the child and the watcher take their first spawns before the owner's does.
+            commands.spawn([mark, owned])({ [mark]: 1, [owned]: Entity.none });
+            commands.spawn([mark, follows])({ [mark]: 2, [follows]: Entity.none });
+            owner = commands.spawn([mark, owned, sprite])({ [mark]: 3, [owned]: gone });
+            child = commands.spawn([mark, owned])({ [mark]: 4, [owned]: owner });
+            watcher = commands.spawn([mark, follows])({ [mark]: 5, [follows]: owner });
+        });
+        expect(await read(world, owner, mark)).toBeNull();
+        expect(await read(world, child, mark)).toBeNull();
+        expect(await components(world, watcher)).toEqual([mark]);
+        await world.dispose();
+    });
+
+    it("cascade to entities spawned in the sync point their owner despawns in", async () => {
+        const world = createWorld({ [workers]: 0 });
+        const step = at(world);
+        let owner = Entity.none, child = Entity.none, grandchild = Entity.none;
+        await step(commands => { owner = commands.spawn([mark])({ [mark]: 0 }); });
+        await step(commands => {
+            // The grandchild's archetype takes its first spawn before the child's does.
+            commands.spawn([mark, owned, sprite])({ [mark]: 1, [owned]: Entity.none });
+            child = commands.spawn([mark, owned])({ [mark]: 2, [owned]: owner });
+            grandchild = commands.spawn([mark, owned, sprite])({ [mark]: 3, [owned]: child });
+            commands.despawn(owner);
+        });
+        expect(await read(world, child, mark)).toBeNull();
+        expect(await read(world, grandchild, mark)).toBeNull();
+        await world.dispose();
+    });
+
     it("move a holder whose weak reference is dropped to an archetype no entity had, closed by the rules", async () => {
         const world = createWorld({ [workers]: 0 });
         const step = at(world);

package/src/implementation/world/run-changes.test.ts

@@ -0,0 +1,88 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { expect, it } from "vitest";
+import { Entity, Finalizer, System } from "../../index.js";
+import { createWorld } from "../index.js";
+import type { Tables } from "../../interface/system/tables.js";
+import type { Table } from "../../interface/world/table/table.js";
+
+const name = Symbol("runChanges/name");
+const score = Symbol("runChanges/score");
+const spent = Symbol("runChanges/spent");
+const echo = Symbol("runChanges/echo");
+const budget = Symbol("runChanges/budget");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [name]: { type: string };
+        [score]: { type: number };
+        [spent]: { type: true };
+        [echo]: { type: string };
+    }
+    interface Resources {
+        [budget]: { type: number; default: 10 };
+    }
+}
+
+// An entity spent leaves an echo, which its finalizer spawns at the next sync point.
+Finalizer.create({ components: { with: [name, spent] } }, (row, { commands }) => { commands.spawn([echo])({ [echo]: row[name] }); });
+
+const spawn = System.create({}, ({ commands }, input: { readonly who: string }) => { commands.spawn([name])({ [name]: input.who }); });
+const score10 = System.create({ components: { with: [name], not: [score] }, after: [spawn] }, (row, { commands }) => { commands.add(row.entity, score, 10); });
+const enter = System.create([spawn, score10]);
+const rescore = System.create({ components: { with: [score] } }, (row, { commands }) => { commands.add(row.entity, score, row[score] + 1); });
+const spend = System.create({ components: { with: [name] } }, (row, { commands, resources }) => {
+    commands.add(row.entity, spent);
+    commands.despawn(row.entity);
+    resources[budget] -= 1;
+});
+const raise = System.create({}, ({ resources }) => { resources[budget] = resources[budget]; });
+const readNamed = System.create({ readonly: true, tables: { components: [name] } }, ({ tables }): Tables => tables);
+const copied: { tables: readonly Table[] } = { tables: [] };
+const copy = System.create(({ commands }) => { commands.spawnTables(copied.tables); });
+const clear = System.create(({ commands }) => { commands.despawnWhere({ with: [name] }); });
+
+const describe = (changes: Awaited<ReturnType<typeof run>>) => changes.groups.map(group => ({
+    from: group.from?.map(key => key.description) ?? null, to: group.to?.map(key => key.description) ?? null,
+    replaced: group.replaced.map(key => key.description),
+    values: group.entities.map(entity => [changes.previous(entity, score), changes.next(entity, score), changes.previous(entity, name) ?? changes.next(entity, name)]),
+}));
+const run = (world: ReturnType<typeof createWorld>) => world.run(rescore, { changes: true });
+
+it("resolves to the run's own changes, merged across its sync points, with values before and after it", async () => {
+    await using world = createWorld();
+    const entered = await world.run(enter, { who: "ada" }, { changes: true });
+    expect(describe(entered)).toEqual([{ from: null, to: ["runChanges/name", "runChanges/score"], replaced: [], values: [[null, 10, "ada"]] }]);
+    expect(entered.resources).toEqual([]);
+    expect(describe(await run(world))).toEqual([{ from: ["runChanges/name", "runChanges/score"], to: ["runChanges/name", "runChanges/score"], replaced: ["runChanges/score"], values: [[10, 11, "ada"]] }]);
+});
+
+it("leaves out what finalizers of an earlier sync point queued, and gives what its systems wrote of resources", async () => {
+    await using world = createWorld();
+    await world.run(enter, { who: "bo" });
+    // Its finalizer queues an echo for the next sync point, which applies before the next run's own changes.
+    const spent = await world.run(spend, { changes: true });
+    expect(describe(spent)).toEqual([{ from: ["runChanges/name", "runChanges/score"], to: null, replaced: [], values: [[10, null, "bo"]] }]);
+    expect(spent.resources).toEqual([{ key: budget, previous: 10, next: 9 }]);
+    const raised = await world.run(raise, { changes: true });
+    expect([raised.groups, raised.resources]).toEqual([[], []]);
+    expect(raised.previous(Entity.none, name)).toBe(null);
+});
+
+it("runs as usual without the option, and with input that only looks like it", async () => {
+    await using world = createWorld();
+    const echoing = System.create({}, (_context, input: { readonly changes: boolean }) => input.changes);
+    expect(await world.run(echoing, { changes: true })).toBe(true);
+    expect(await world.run(raise)).toBe(undefined);
+});
+
+it("gives the rows spawnTables spawns and the entities despawnWhere despawns as a run's changes", async () => {
+    await using world = createWorld();
+    await world.run(enter, { who: "cy" });
+    copied.tables = (await world.run(readNamed)).archetypes;
+    // The tables copy names alone.
+    expect(describe(await world.run(copy, { changes: true }))).toEqual([{ from: null, to: ["runChanges/name"], replaced: [], values: [[null, null, "cy"]] }]);
+    expect(describe(await world.run(clear, { changes: true }))).toEqual([
+        { from: ["runChanges/name"], to: null, replaced: [], values: [[null, null, "cy"]] },
+        { from: ["runChanges/name", "runChanges/score"], to: null, replaced: [], values: [[10, null, "cy"]] },
+    ]);
+});

package/src/implementation/world/run-changes.ts

@@ -0,0 +1,160 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Entity } from '../../interface/entity/entity.js';
+import type { Essential, ReadonlyType } from '../../interface/component/value.js';
+import type { ChangeSet } from '../../interface/finalizer/body.js';
+import type { Resource } from '../../interface/resource/resource.js';
+import { isLeaf, newestKeyOf, scheduleOf, type Definition, type Leaf } from '../../interface/registry/index.js';
+import type { Archetype } from './archetype.js';
+import { readCell } from './cells.js';
+import { asEntity, indexOf, locate } from './entities.js';
+import { sameValue } from './resource-changes.js';
+import { findResource, initialOf } from './resources.js';
+import { metIdOf, type Key, type State } from './state.js';
+import type { Queued } from './synchronize.js';
+
+/**
+ * What a run asked for its changes holds while it runs: by entity its sync points planned, the watched components it
+ * had before the run, none for one born in it, with their values then, and those its adds gave a value; and the
+ * resources its systems write or reduce into, with their values before it.
+ */
+export type Recording = {
+    readonly before: Map<number, { readonly ids: readonly number[] | null; readonly values: ReadonlyMap<number, unknown> }>;
+    readonly given: Map<number, Set<number>>;
+    readonly resources: ReadonlyMap<Key, unknown>;
+};
+
+/** Every component but derived ones and the objects a joined thread fills, as a changes finalizer watches by default. */
+const watched = (state: State, id: number): boolean => !state.derived[id] && !state.resources.has(id) && state.remote[id] === undefined;
+
+const noValues: ReadonlyMap<number, unknown> = new Map();
+
+/** The values of components `ids` of an archetype's row. */
+const valuesAt = (archetype: Archetype, ids: readonly number[], row: number): ReadonlyMap<number, unknown> => {
+    const values = new Map<number, unknown>();
+    for (const id of ids) {
+        const storage = archetype.storageById[id];
+        if (storage !== undefined) values.set(id, readCell(storage, row));
+    }
+    return values;
+};
+
+/** Starts recording a run whose systems write or reduce into `resources`, from their values now. */
+export const startRecording = (state: State, resources: Iterable<Key>): Recording => {
+    const values = new Map<Key, unknown>();
+    for (const key of resources) {
+        const cell = findResource(state, key);
+        values.set(key, cell === undefined ? initialOf(state, key) : readCell(cell.storage, cell.row));
+    }
+    return { before: new Map(), given: new Map(), resources: values };
+};
+
+/**
+ * At a sync point of the run, before it applies: each entity its plan names that no earlier one did, with what it has
+ * now, and the components its adds give a value. `born` holds the rows committed from batches here, by archetype.
+ */
+export const recordPlan = (state: State, recording: Recording, queued: readonly Queued[], born: ReadonlyMap<number, number>): void => {
+    const { plan, archetypes, entities } = state;
+    const note = (entity: number, from: Archetype | null): void => {
+        if (recording.before.has(entity) || from?.resource === true) return;
+        if (from === null) {
+            recording.before.set(entity, { ids: null, values: noValues });
+            return;
+        }
+        const row = entities.row[indexOf(entity)];
+        const ids = from.components.filter(id => watched(state, id));
+        recording.before.set(entity, { ids, values: valuesAt(from, ids, row) });
+    };
+    const give = (entity: number, buffer: number, start: number, end: number): void => {
+        const { ids } = queued[buffer].buffer;
+        for (let k = start; k < end; k++) {
+            if (!watched(state, ids[k])) continue;
+            let given = recording.given.get(entity);
+            if (given === undefined) recording.given.set(entity, given = new Set());
+            given.add(ids[k]);
+        }
+    };
+    for (let entry = 0; entry < plan.count; entry++) {
+        const entity = plan.entity[entry];
+        const fromId = plan.from[entry];
+        const first = fromId < 0 ? undefined : born.get(fromId);
+        note(entity, fromId < 0 || (first !== undefined && entities.row[indexOf(entity)] >= first) ? null : archetypes[fromId]);
+        if (plan.start[entry] < 0) continue;
+        give(entity, plan.buffer[entry], plan.start[entry], plan.end[entry]);
+        const more = plan.more.size === 0 ? undefined : plan.more.get(entry);
+        if (more !== undefined) for (let r = 0; r < more.length; r += 3) give(entity, more[r], more[r + 1], more[r + 2]);
+    }
+    // Rows committed from batches no command touched have no entry.
+    for (const [id, first] of born) {
+        const archetype = archetypes[id];
+        for (let row = first; row < archetype.count; row++) note(archetype.entities[row], null);
+    }
+};
+
+/** A watched component's newest key: watched components are registered and not derived, so they're essential. */
+const keyOf = (state: State, id: number): Essential => newestKeyOf(state.keys[id]) as Essential;
+
+/** A group of a change set, as it's built. */
+type Grouped = { from: Essential[] | null; to: Essential[] | null; added: Essential[]; removed: Essential[]; replaced: Essential[]; entities: Entity[] };
+
+/**
+ * The run's change set once its last sync point applied: each entity grouped by the watched components it had before
+ * the run and has after, those it gained and lost, and those adds gave a value it had before and after, with their
+ * values then and now; and each resource its systems write or reduce into whose value changed.
+ */
+export const changesOf = (state: State, recording: Recording): ChangeSet<Essential, Resource.Key> => {
+    const { archetypes, entities } = state;
+    const groups = new Map<string, Grouped>();
+    const after = new Map<number, ReadonlyMap<number, unknown>>();
+    for (const [entity, { ids: before }] of recording.before) {
+        const index = locate(entities, entity);
+        const to = index < 0 ? null : archetypes[entities.archetype[index]];
+        const ids = to === null ? null : to.components.filter(id => watched(state, id));
+        if (before === null && ids === null) continue;
+        const added = (ids ?? []).filter(id => !(before ?? []).includes(id));
+        const removed = (before ?? []).filter(id => !(ids ?? []).includes(id));
+        const replaced = [...recording.given.get(entity) ?? []].filter(id => before?.includes(id) === true && ids?.includes(id) === true).sort((a, b) => a - b);
+        if (added.length === 0 && removed.length === 0 && replaced.length === 0) continue;
+        if (to !== null && ids !== null) {
+            after.set(entity, valuesAt(to, ids, entities.row[index]));
+        }
+        const name = `${before?.join(",") ?? "-"}|${ids?.join(",") ?? "-"}|${replaced.join(",")}`;
+        let group = groups.get(name);
+        const keys = (list: readonly number[] | null): Essential[] | null => list === null ? null : list.map(id => keyOf(state, id));
+        if (group === undefined) {
+            groups.set(name, group = { from: keys(before), to: keys(ids), added: added.map(id => keyOf(state, id)), removed: removed.map(id => keyOf(state, id)), replaced: replaced.map(id => keyOf(state, id)), entities: [] });
+        }
+        group.entities.push(asEntity(entity));
+    }
+    const resources: { key: Resource.Key; previous: unknown; next: unknown }[] = [];
+    for (const [key, previous] of recording.resources) {
+        const cell = findResource(state, key);
+        const next = cell === undefined ? previous : readCell(cell.storage, cell.row);
+        // A key the run's systems name is a resource's.
+        if (!sameValue(previous, next)) resources.push({ key: newestKeyOf(key) as Resource.Key, previous, next });
+    }
+    const valueOf = (values: ReadonlyMap<number, unknown> | undefined, key: Essential): unknown => {
+        const id = metIdOf(state, key);
+        return id !== undefined && values?.has(id) === true ? values.get(id) : null;
+    };
+    return {
+        groups: [...groups.values()],
+        // Values read from storage match each key's registered schema, so they have its type.
+        resources: resources as ChangeSet<Essential, Resource.Key>["resources"],
+        previous: <K extends Essential>(entity: Entity, key: K) => valueOf(recording.before.get(entity)?.values, key) as ReadonlyType<K> | null,
+        next: <K extends Essential>(entity: Entity, key: K) => valueOf(after.get(entity), key) as ReadonlyType<K> | null,
+    };
+};
+
+/** A system's leaves that run in tiers, or the system itself. */
+const leavesOf = (definition: Definition): readonly Leaf[] => isLeaf(definition) ? [definition] : scheduleOf(definition).tiers.flat();
+
+/** The resources a system's leaves write or reduce into. */
+export const resourcesWrittenBy = (definition: Definition): ReadonlySet<Key> =>
+    new Set(leavesOf(definition).flatMap(leaf => [...leaf.declaration.resources?.write ?? [], ...leaf.declaration.resources?.reduce ?? []]));
+
+/** Whether a system or composite takes input, so a run's options follow it. */
+export const takesInput = (definition: Definition): boolean =>
+    isLeaf(definition) ? definition.input !== undefined : [...scheduleOf(definition).tiers.flat(), ...scheduleOf(definition).observer].some(leaf => leaf.input !== undefined);
+
+/** Whether a run's options ask for its changes. */
+export const asksForChanges = (options: unknown): boolean => typeof options === "object" && options !== null && Reflect.get(options, "changes") === true;

package/src/implementation/world/runner.ts

@@ -63,7 +63,7 @@ const noIndexParameters: readonly number[] = [];
 const noAddresses: readonly number[] = [];
 
 /** An archetype's change filters for a runner, and the WASM addresses of its columns and filters (`filterCache`). */
-type Filtered = { readonly version: number; readonly filters: readonly Filter[]; addresses: readonly number[]; addressed: WasmKernel | null };
+type Filtered = { readonly archetype: Archetype; readonly version: number; readonly filters: readonly Filter[]; addresses: readonly number[]; addressed: WasmKernel | null };
 
 /**
  * Runs one leaf system. Each run takes a new tick, which becomes the system's `lastRun`. `start` does main-thread work
@@ -470,7 +470,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
 
     /** Drops match `m`, its last taking its place; with `where`, one evaluated stays among those evaluated. */
     const removeMatch = (m: number): void => {
-        filterCache.delete(matches[m]);
+        filterCache[matches[m].id] = undefined;
         matchOf[matches[m].id] = -1;
         let hole = m;
         if (where !== null && m < where.evaluated) {
@@ -487,7 +487,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
     /** Matches `m` anew, reused for other values: its point is its last run's, and `where` evaluates it again. */
     const renewMatch = (m: number): void => {
         const archetype = matches[m];
-        filterCache.delete(archetype);
+        filterCache[archetype.id] = undefined;
         points[m] = lastRun;
         generations[m] = archetype.generation;
         if (where !== null && m < where.evaluated) {
@@ -563,12 +563,12 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
      * and the WASM addresses of its columns and filters, for the WASM kernel `addressed` they were taken for, since a
      * kernel loaded again may stamp a tick column the last one muted.
      */
-    const filterCache = new Map<Archetype, Filtered>();
+    const filterCache: (Filtered | undefined)[] = [];
     const noFilters: readonly Filter[] = [];
 
     const filteredOf = (archetype: Archetype) => {
-        const cached = filterCache.get(archetype);
-        if (cached !== undefined && cached.version === archetype.version) return cached;
+        const cached = filterCache[archetype.id];
+        if (cached !== undefined && cached.archetype === archetype && cached.version === archetype.version) return cached;
         const filters = addedIds.length + changedIds.length === 0 ? noFilters : [
             ...addedIds.flatMap(id => {
                 const storage = archetype.storageById[id];
@@ -579,8 +579,8 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
                 return storage === undefined ? [] : [{ ticks: storage.changed, chunks: storage.chunkChanged, blocks: storage.blockChanged }];
             }),
         ];
-        const entry: Filtered = { version: archetype.version, filters, addresses: noAddresses, addressed: null };
-        filterCache.set(archetype, entry);
+        const entry: Filtered = { archetype, version: archetype.version, filters, addresses: noAddresses, addressed: null };
+        filterCache[archetype.id] = entry;
         return entry;
     };
 
@@ -614,13 +614,14 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         const { value } = row;
         const values = context.value;
         const input = runInput;
+        const { body } = system;
         const filters = filtersOf(archetype);
         // Every row passes, so nothing is filtered.
         // A body may remove its own system, after which no row of it runs.
         if (since < 0 || filters.length === 0) {
             for (let index = 0, count = archetype.count; index < count && !holdings.removed; index++) {
                 row.index = index;
-                const returned = system.body(value, values, input);
+                const returned = body(value, values, input);
                 if (returned !== undefined) noPromise(returned);
             }
             return;
@@ -628,7 +629,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         forEachPassingRange(filters, since, 0, archetype.count, (start, end) => {
             for (let index = start; index < end && !holdings.removed; index++) {
                 row.index = index;
-                const returned = system.body(value, values, input);
+                const returned = body(value, values, input);
                 if (returned !== undefined) noPromise(returned);
             }
         });
@@ -714,10 +715,11 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         const upContext = context.value;
         const input = runInput;
         upContext.up = parentRow === null ? null : parentRow.value;
+        const { body } = system;
         for (let n = start; n < end && !holdings.removed; n++) {
             row.index = rows[n];
             if (parentRow !== null) parentRow.index = parents[n];
-            const returned = system.body(row.value, upContext, input);
+            const returned = body(row.value, upContext, input);
             if (returned !== undefined) noPromise(returned);
         }
     };
@@ -748,9 +750,10 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
             }
             const row = bindRow(archetype);
             const { value } = row;
+            const { body } = system;
             for (let n = run.start; n < run.end && !holdings.removed; n++) {
                 row.index = run.rows[n];
-                const returned = system.body(value, contextValue, input);
+                const returned = body(value, contextValue, input);
                 if (returned !== undefined) noPromise(returned);
             }
         }
@@ -762,6 +765,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         const { entries, stride, words, lengths, blocks } = sorted;
         const contextValue = context.value;
         const input = runInput;
+        const { body } = system;
         let current = -1;
         let row: ReturnType<typeof bindRow> | null = null;
         let value: object | null = null;
@@ -782,7 +786,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
                     current = owner;
                 }
                 row.index = entries[at + 2];
-                const returned = system.body(value, contextValue, input);
+                const returned = body(value, contextValue, input);
                 if (returned !== undefined) noPromise(returned);
             }
         }

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

@@ -195,10 +195,10 @@ describe("a shared component", () => {
         }));
         expect(looked.sort()).toEqual(["1 sees red", "2 sees red"]);
         const assign: (row: object) => void = row => { Reflect.set(row, team, "blue"); };
-        const assigning = System.create({ kernel: false, components: { with: [team, health] } }, row => {
+        // Taken whole, the row is written: every member but shared ones and references.
+        const assigning = System.create({ kernel: false, components: { with: [team, health], whole: true } }, row => {
             if (row[health] === 1) assign(row);
         });
-        // The build takes the row as written whole, since it can't follow it: every member but shared ones and references.
         expect((await runReported(world, assigning)).failures.map(failure => failure.message)).toEqual([
             expect.stringContaining(`"sharedTest/team" is shared: its value is its archetype's, so give it another with commands.add rather than assigning it`),
         ]);

package/src/implementation/world/state.ts

@@ -1,4 +1,5 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Recording } from './run-changes.js';
 import { createHolds, type Holds } from './stop-lists.js';
 import type { Entity } from '../../interface/entity/entity.js';
 import type { Leaf } from '../../interface/system/leaf.js';
@@ -126,6 +127,13 @@ export type State = {
     reshapes: number;
     /** Sync points applied, which reclaiming counts. */
     syncs: number;
+    /**
+     * By id, each resource a changes finalizer watches: its value and change tick when its finalizers last ran, which a
+     * later write's report gives as its previous value. Empty while none watches one.
+     */
+    readonly resourcesSeen: Map<number, { value: unknown; tick: number }>;
+    /** What the run in progress records of its changes, when it was asked for them; null otherwise. */
+    recording: Recording | null;
     /** The records strings' columns name, in shared memory; null without it, where strings are held as objects. */
     readonly strings: StringStore | null;
     /** Whether each component is derived, so only rules add and remove it. */
@@ -317,6 +325,8 @@ export const createState = (shared?: boolean, wasm = true, simd = true, gpu = fa
         membership: { log: [], base: 0 },
         reshapes: 0,
         syncs: 0,
+        resourcesSeen: new Map(),
+        recording: null,
         strings: memory.shared ? createStrings(memory) : null,
         derived: [],
         transfers: [],
@@ -504,6 +514,15 @@ export const commandIdOf = (state: State, key: unknown): number => {
     return id;
 };
 
+/** The id of a component a query names, derived ones included. Throws for a key that isn't a registered component. */
+export const queryIdOf = (state: State, key: unknown): number => {
+    const known = typeof key === "symbol" ? state.ids.get(key) : undefined;
+    if (known !== undefined && !state.resources.has(known)) return known;
+    if (typeof key !== "symbol") throw new Error(`"${labelOf(key)}" isn't a component: a component's key is a symbol.`);
+    if (kindOf(key) === "resource") throw new Error(`"${labelOf(key)}" is a resource, not a component.`);
+    return idOf(state, key);
+};
+
 /**
  * An archetype's key: its sorted component ids, each shared one with the number of its value, so archetypes of one
  * component set but other values are others.