@adobe/ecs 0.2.1 → 0.2.4

package/src/implementation/world/rows.ts

@@ -12,6 +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 { 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';
@@ -130,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 => () => {
@@ -167,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]);
             }
         },
     };
@@ -270,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 });
@@ -506,8 +511,14 @@ const never: Since = { value: -1 };
 const own = (): object => Object.create({});
 
 /** Resource cells are resolved once per run: they move only at sync points. An unresolved resource throws on access. */
-export const createContext = (state: State, declaration: Pick<Resolved, "lookup" | "resources">, { targets = [], commands, indexes, since = never }: Extras = {}): Context => {
+export const createContext = (state: State, declaration: Pick<Resolved, "lookup" | "resources" | "tables">, { targets = [], commands, indexes, since = never }: Extras = {}): Context => {
     const value: { up?: unknown } = own();
+    const { tables } = declaration;
+    // Each read copies the tables as they are then.
+    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/run-results.test.ts

@@ -30,11 +30,11 @@ const spawn = System.create(({ commands }) => {
 const raise = System.create(({ resources }) => {
     resources[level] += 1;
 });
-const count = System.create({ observer: true, components: { with: [amount] } }, () => {
+const count = System.create({ readonly: true, components: { with: [amount] } }, () => {
     counted++;
 });
 let counted = 0;
-const readLevel = System.create({ observer: true }, ({ resources }) => resources[level]);
+const readLevel = System.create({ readonly: true }, ({ resources }) => resources[level]);
 const broken = System.create(() => {
     throw new Error("broken");
 });
@@ -57,7 +57,7 @@ describe("a run", () => {
         expect(await world.run(System.create({ components: { with: [amount] } }, row => row[amount]))).toBeUndefined();
         expect(await world.run(System.create([readLevel, raise]))).toBeUndefined();
         expect(await world.run(raise)).toBeUndefined();
-        const whenChanged = System.create({ observer: true, resources: { changed: [level] } }, ({ resources }) => resources[level]);
+        const whenChanged = System.create({ readonly: true, resources: { changed: [level] } }, ({ resources }) => resources[level]);
         expect(await world.run(whenChanged)).toBe(2);
         // Unchanged since it last ran: skipped.
         expect(await world.run(whenChanged)).toBeUndefined();
@@ -94,7 +94,7 @@ describe("a run", () => {
     it("rejects when its own observer system fails, and reports one added out of band", async () => {
         using reported = catchOutOfBand();
         await using world = inline();
-        const failingObserver = System.create({ observer: true }, () => {
+        const failingObserver = System.create({ readonly: true }, () => {
             throw new Error("observer failed");
         });
         await expect(world.run(failingObserver)).rejects.toThrow(/observer failed/);
@@ -144,7 +144,7 @@ const spawnTwins = System.create(({ commands }) => {
     commands.spawn([serial])({ [serial]: 1 });
     commands.spawn([serial])({ [serial]: 1 });
 });
-const findTwin = System.create({ observer: true, lookup: { twins: { index: bySerial } } }, ({ lookup }) => lookup.twins(1)?.entity ?? null);
+const findTwin = System.create({ readonly: true, lookup: { twins: { index: bySerial } } }, ({ lookup }) => lookup.twins(1)?.entity ?? null);
 const setGate = System.create({}, ({ resources }, input: { readonly open: boolean }) => {
     resources[gate] = input.open;
 });
@@ -207,10 +207,10 @@ describe("a run's observer pass", () => {
     it("fails the run for its own observer system, and reports one added out of band, in one run", async () => {
         using reported = catchOutOfBand();
         await using world = inline();
-        const ownFails = System.create({ observer: true }, () => {
+        const ownFails = System.create({ readonly: true }, () => {
             throw new Error("own failed");
         });
-        const addedFails = System.create({ observer: true }, () => {
+        const addedFails = System.create({ readonly: true }, () => {
             throw new Error("added failed");
         });
         world.add(addedFails);
@@ -255,7 +255,7 @@ describe("out-of-band reports", () => {
     it("aren't made again for a system skipped between its failures", async () => {
         using reported = catchOutOfBand();
         await using world = inline();
-        const failsWhenChanged = System.create({ observer: true, resources: { changed: [level] } }, () => {
+        const failsWhenChanged = System.create({ readonly: true, resources: { changed: [level] } }, () => {
             throw new Error("changed failed");
         });
         world.add(failsWhenChanged);
@@ -294,7 +294,7 @@ describe("out-of-band reports", () => {
         using reported = catchOutOfBand();
         const world = inline();
         let failing = false;
-        const failsAdded = System.create({ observer: true }, () => {
+        const failsAdded = System.create({ readonly: true }, () => {
             if (failing) throw new Error("added failed");
         });
         world.add(failsAdded);
@@ -331,7 +331,7 @@ describe("out-of-band reports", () => {
     it("aren't made again for a row system whose change filter passed no row between its failures", async () => {
         using reported = catchOutOfBand();
         await using world = inline();
-        const failsOnChange = System.create({ observer: true, components: { with: [amount], changed: [amount] } }, () => {
+        const failsOnChange = System.create({ readonly: true, components: { with: [amount], changed: [amount] } }, () => {
             throw new Error("row failed");
         });
         const bump = System.create({ components: { with: [amount] } }, row => {

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
@@ -260,7 +260,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         : createOrderedRender(indexLookups.ordered, ordered, accessors.map(accessor => idOf(state, accessor.component)), declaration.shader?.group ?? 0, `${leafNumber}:`);
     const touches = [...new Set([...query?.read ?? [], ...query?.write ?? []])].map(key => idOf(state, key));
     const writes = (query?.write ?? []).map(key => idOf(state, key));
-    const looks = [...new Set([...Object.values(declaration.lookup ?? {}).flatMap(lookup => lookup.read ?? []), ...declaration.up?.read ?? []])].map(key => idOf(state, key));
+    const looks = [...new Set([...Object.values(declaration.lookup ?? {}).flatMap(lookup => lookup.read ?? []), ...declaration.up?.read ?? [], ...declaration.tables?.components ?? []])].map(key => idOf(state, key));
     /** Record keys by archetype. */
     const keys = new Map<Archetype, string>();
     const keyOf = (archetype: Archetype): string => {
@@ -339,7 +339,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
     let runInput: unknown;
     const context = createContext(state, declaration, {
         targets: kernel === null ? targets : [],
-        commands: leaf.kind === "render" || declaration.kernel === "gpu" || declaration.observer === true ? undefined : commands,
+        commands: leaf.kind === "render" || declaration.kernel === "gpu" || declaration.readonly === true ? undefined : commands,
         indexes: indexLookups.byName,
         since: lookupSince,
     });
@@ -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);
             }
         }
@@ -1343,7 +1347,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
             return taken;
         },
         didRun: () => ran && (query === undefined || bodyRanOnRow()),
-        restart: declaration.observer !== true || !holdsNothing(holdings) ? null : since => {
+        restart: declaration.readonly !== true || !holdsNothing(holdings) ? null : since => {
             lastRun = since;
             holdings.removed = false;
             holdings.released = false;

package/src/implementation/world/shared-gpu.browser.test.ts

@@ -59,7 +59,7 @@ const fractions = System.create({ kernel: "gpu", components: { with: [scale, val
 });
 const fractionsOf = async (world: ReturnType<typeof createWorld>): Promise<readonly (readonly number[])[]> => {
     const read: [number, number[]][] = [];
-    await world.run(System.create({ observer: true, components: { with: [value, copied, product, sum, compound] } }, row => { read.push([row[value], [row[copied], row[product], row[sum], row[compound], row[value]]]); }));
+    await world.run(System.create({ readonly: true, components: { with: [value, copied, product, sum, compound] } }, row => { read.push([row[value], [row[copied], row[product], row[sum], row[compound], row[value]]]); }));
     return read.sort((a, b) => a[0] - b[0]).map(([, values]) => values);
 };
 
@@ -71,7 +71,7 @@ const device = async (): Promise<GPUDevice> => {
 
 const results = async (world: ReturnType<typeof createWorld>): Promise<readonly string[]> => {
     const read: [number, string][] = [];
-    await world.run(System.create({ observer: true, components: { with: [value, out, steps] } }, row => { read.push([row[value], `${row[out]} ${row[steps]}`]); }));
+    await world.run(System.create({ readonly: true, components: { with: [value, out, steps] } }, row => { read.push([row[value], `${row[out]} ${row[steps]}`]); }));
     return read.sort((a, b) => a[0] - b[0]).map(([, text]) => text);
 };
 

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

@@ -62,7 +62,7 @@ const wideOnGpu = System.create({ kernel: "gpu", components: { with: [wide, out]
 /** Every row's results, by its value. */
 const results = async (world: ReturnType<typeof createWorld>): Promise<readonly string[]> => {
     const read: [number, string][] = [];
-    await world.run(System.create({ observer: true, components: { with: [value, out, steps] } }, row => { read.push([row[value], `${row[out]} ${row[steps]}`]); }));
+    await world.run(System.create({ readonly: true, components: { with: [value, out, steps] } }, row => { read.push([row[value], `${row[out]} ${row[steps]}`]); }));
     return read.sort((a, b) => a[0] - b[0]).map(([, text]) => text);
 };
 
@@ -98,7 +98,7 @@ describe("a kernel reading a shared component", () => {
         await world.run(spawn);
         expect((await runReported(world, moving)).failures).toEqual([]);
         const scales: number[] = [];
-        await world.run(System.create({ observer: true, components: { with: [scale] } }, row => { scales.push(row[scale]); }));
+        await world.run(System.create({ readonly: true, components: { with: [scale] } }, row => { scales.push(row[scale]); }));
         expect(new Set(scales)).toEqual(new Set([2]));
         // A kernel built without knowing a component is shared, naming it in a command, fails where it registers.
         const description = kernelOf(compute);