@adobe/ecs 0.2.1 → 0.2.4

package/src/implementation/world/joined-observer.test.ts

@@ -22,7 +22,7 @@ declare module "@adobe/ecs" {
 
 /** What the observer system read, were it run: this test stands for the thread, so it never runs. */
 const seen: number[] = [];
-const watch = System.create({ observer: true, components: { with: [amount] } }, row => { seen.push(row[amount]); });
+const watch = System.create({ readonly: true, components: { with: [amount] } }, row => { seen.push(row[amount]); });
 
 describe("an observer system on a joined thread", () => {
     it("is waited for, not cancelled, by a sync point after a writer copied the rest of a post the thread claimed partway", async () => {

package/src/implementation/world/joining-worker.fixture.ts

@@ -42,7 +42,7 @@ const channel = scopeChannel<FromJoiningWorker, ToJoiningWorker>();
 let hosted: ReturnType<typeof createWorld> | null = null;
 /** What the observer system `listen` adds heard. */
 const heard: number[] = [];
-const hear = System.create({ observer: true }, ({ resources }) => { heard.push(resources[total]); });
+const hear = System.create({ readonly: true }, ({ resources }) => { heard.push(resources[total]); });
 const messageOf = (error: unknown): string => error instanceof Error ? error.message : String(error);
 /** Ends this thread at once: node's worker exits, and a browser worker closes, dropping the tasks it queued. */
 const exit = (): void => {

package/src/implementation/world/joining.fixture.ts

@@ -16,7 +16,7 @@ import { add, drive, idle, names, shelf, total, until } from "./joining.test-hel
 /** A system only this thread imports, which a world on a worker never did. */
 const unimportedByWorker = System.create({}, () => {});
 /** An observer system only this thread imports, reading an object of `main`, so it's placed on a thread claiming it. */
-const shelvedHere = System.create({ observer: true }, ({ resources }) => resources[shelf].length);
+const shelvedHere = System.create({ readonly: true }, ({ resources }) => resources[shelf].length);
 
 type Worker = {
     readonly ask: (message: ToJoiningWorker, transfer?: readonly unknown[]) => Promise<FromJoiningWorker>;

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

@@ -36,7 +36,7 @@ export const append = System.create({}, ({ resources }, input: { readonly name:
     return resources[names].length;
 });
 /** Reads `total` from an observer system, which a joined thread runs itself. */
-export const readTotal = System.create({ observer: true }, ({ resources }) => resources[total]);
+export const readTotal = System.create({ readonly: true }, ({ resources }) => resources[total]);
 export const spawn = System.create({}, ({ commands }, input: { readonly x: number }) => {
     commands.spawn([point, label, marked])({ [point]: [input.x, -input.x], [label]: `p${input.x}` });
 });

package/src/implementation/world/kernel-spawns.test.ts

@@ -63,7 +63,7 @@ const countAdded = System.create({ components: { added: [value], with: [made] }
 
 /** Each made entity's value, in storage order. */
 const madeValues: number[] = [];
-const readMade = System.create({ observer: true, components: { with: [value, made] } }, row => { madeValues.push(row[value]); });
+const readMade = System.create({ readonly: true, components: { with: [value, made] } }, row => { madeValues.push(row[value]); });
 const valuesOf = async (world: ReturnType<typeof createWorld>): Promise<number[]> => {
     madeValues.length = 0;
     await world.run(readMade);

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

@@ -43,8 +43,7 @@ const failOnce = System.create(() => { throw new Error("unnamed"); });
 
 describe("systems, rules and finalizers of one label", () => {
     it("are distinct in schedules, both run, and are told apart in reports by their ids", async () => {
-        // Its body is written in place, calling what it's given with the row, which the build takes as writing every member.
-        const linked = (after: readonly System[], body: (row: { [value]: number }) => void): System => System.create({ components: { with: [value] }, after }, row => body(row));
+        const linked = (after: readonly System[], body: (row: { [value]: number }) => void): System => System.create({ components: { with: [value], whole: true }, after }, row => body(row));
         const a = linked([], row => { ran.push("a"); row[value] += 1; });
         const b = linked([a], row => { ran.push("b"); row[value] += 1; throw new Error("b failed"); });
         const c = linked([b], row => { ran.push(`c${row[value]}`); });

package/src/implementation/world/observe-factories.test.ts

@@ -37,7 +37,7 @@ const nothing = System.create({}, () => {});
 
 /** Counts passes: the observer passes after each run's sync point. */
 const passes = { count: 0 };
-const counter = System.create({ observer: true }, () => { passes.count++; });
+const counter = System.create({ readonly: true }, () => { passes.count++; });
 
 /**
  * A world of `count` entities, each amount its index and one more, at level 1: the runs below registered, so runners
@@ -184,7 +184,7 @@ describe("observer factories", () => {
     it("rethrow only their own systems' failures from their runs, not those of observer systems the world added", async () => {
         using reported = catchOutOfBand();
         await using world = await seeded(3);
-        const failing = System.create({ observer: true }, () => { throw new Error("added failed"); });
+        const failing = System.create({ readonly: true }, () => { throw new Error("added failed"); });
         world.add(failing);
         const caught: unknown[] = [];
         const original = globalThis.queueMicrotask;

package/src/implementation/world/observe-ticks-cases.test.ts

@@ -29,7 +29,7 @@ const count = System.create({}, ({ resources }) => { resources[frames] += 1; });
 const watch = System.create({}, ({ resources }) => { resources[seen] = resources[clock].tick; });
 const fail = System.create({}, () => { throw new Error("tick failed"); });
 const nothing = System.create({}, () => {});
-const idle = System.create({ observer: true }, () => {});
+const idle = System.create({ readonly: true }, () => {});
 const fast = System.create({}, ({ resources }) => {
     resources[cadence] = { kind: "fixed", step: 1 };
     resources[always] = true;

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

@@ -2,7 +2,7 @@
 import { System } from "../../interface/system/system.js";
 import type { World } from "../../interface/world/world.js";
 
-const settled = System.create({ observer: true }, () => {});
+const settled = System.create({ readonly: true }, () => {});
 
 /**
  * Resolves once every observer factory subscribed before it had its first value: after the factories' flush, which the

package/src/implementation/world/observer-contained-worker.fixture.ts

@@ -24,7 +24,7 @@ export type FromContainedWorker =
 
 const channel = scopeChannel<FromContainedWorker, ToContainedWorker>();
 let remote: World | null = null;
-const placed = System.create({ observer: true }, () => {});
+const placed = System.create({ readonly: true }, () => {});
 
 channel.onMessage(async message => {
     if ("protocol" in message) return;

package/src/implementation/world/observer-contained.test-helper.ts

@@ -32,7 +32,7 @@ export const setHolding = System.create({}, ({ resources }, input: { readonly ho
 });
 
 /** After each sync point that changed the tally: notes it, and, while `holding` says so, waits there to be released. */
-export const watchTally = System.create({ observer: true, resources: { changed: [tally] } }, ({ resources }) => {
+export const watchTally = System.create({ readonly: true, resources: { changed: [tally] } }, ({ resources }) => {
     const value = resources[tally];
     tallies.push(value);
     const { words } = gate;

package/src/implementation/world/observer-contained.test.ts

@@ -29,10 +29,10 @@ const pause = System.create({}, ({ resources }, input: { readonly paused: boolea
 });
 
 const seen: { wide: number[][]; steps: number[] } = { wide: [], steps: [] };
-const watchWide = System.create({ observer: true, resources: { changed: [wide] } }, ({ resources }) => {
+const watchWide = System.create({ readonly: true, resources: { changed: [wide] } }, ({ resources }) => {
     seen.wide.push([...resources[wide]]);
 });
-const watchSteps = System.create({ observer: true, resources: { not: [paused], changed: [steps] } }, ({ resources }) => {
+const watchSteps = System.create({ readonly: true, resources: { not: [paused], changed: [steps] } }, ({ resources }) => {
     seen.steps.push(resources[steps]);
 });
 

package/src/implementation/world/observer-joined.test-helper.ts

@@ -103,7 +103,7 @@ export type Seen = { counter: number; rows: number; wrong: number };
 export const seen: Seen[] = [];
 
 /** Reads every row, which must all be of one tick, pausing at the end of its first chunk while `stall` says so. */
-export const watchRows = System.create({ observer: true, components: { with: [stamp, spot, word] } }, (row, { resources }) => {
+export const watchRows = System.create({ readonly: true, components: { with: [stamp, spot, word] } }, (row, { resources }) => {
     const value = resources[counter];
     let last = seen.at(-1);
     if (last === undefined || last.counter !== value || last.rows === 1000) seen.push(last = { counter: value, rows: 0, wrong: 0 });
@@ -117,7 +117,7 @@ export const watchRows = System.create({ observer: true, components: { with: [st
 export const looked: Entity[] = [];
 
 /** Looks up every row by entity, which must all be of one tick, spinning halfway while `stall` says so. */
-export const lookRows = System.create({ observer: true, lookup: { found: { with: [stamp, spot] } } }, ({ resources, lookup }) => {
+export const lookRows = System.create({ readonly: true, lookup: { found: { with: [stamp, spot] } } }, ({ resources, lookup }) => {
     const value = resources[counter];
     const run: Seen = { counter: value, rows: 0, wrong: 0 };
     seen.push(run);
@@ -146,7 +146,7 @@ export const nextPhase = System.create({}, ({ resources }) => {
 export const hot: number[] = [];
 export const byHeat = Index.create({ key: [heat], sorted: true });
 /** Counts the rows at least 150 hot, through the sorted index on what the GPU kernel writes. */
-export const countHot = System.create({ observer: true, lookup: { hot: { index: byHeat } } }, ({ lookup }) => {
+export const countHot = System.create({ readonly: true, lookup: { hot: { index: byHeat } } }, ({ lookup }) => {
     hot.push(lookup.hot({ ">=": 150 }).length);
 });
 
@@ -164,7 +164,7 @@ export const mottos: { readonly round: number; readonly motto: string }[] = [];
  * Reads only resources, a string among them: waits on the gate first, while `stall` says so, its round plus one, then
  * reads the motto, which must be its round's.
  */
-export const watchMotto = System.create({ observer: true }, ({ resources }) => {
+export const watchMotto = System.create({ readonly: true }, ({ resources }) => {
     const round = resources[mottoRound];
     pauseAt(resources[stall], round + 1);
     mottos.push({ round, motto: resources[motto] });

package/src/implementation/world/observer-joined.test.ts

@@ -59,43 +59,43 @@ const reset = (): void => {
 /** The entities the tests look up, by the joined thread's systems. */
 const watched: Entity[] = [];
 
-const watchLevel = System.create({ observer: true, resources: { changed: [level] } }, ({ resources }) => {
+const watchLevel = System.create({ readonly: true, resources: { changed: [level] } }, ({ resources }) => {
     seen.calls++;
     seen.levels.push(resources[level]);
 });
-const watchAmounts = System.create({ observer: true, components: { with: [amount], changed: [amount] } }, row => {
+const watchAmounts = System.create({ readonly: true, components: { with: [amount], changed: [amount] } }, row => {
     (seen.amounts[seen.amounts.length - 1] ??= []).push(row[amount]);
 });
-const startAmounts = System.create({ observer: true }, () => { seen.amounts.push([]); });
+const startAmounts = System.create({ readonly: true }, () => { seen.amounts.push([]); });
 const amountsPass = System.create([startAmounts, watchAmounts]);
-const lookChanged = System.create({ observer: true, lookup: { found: { with: [amount], changed: [amount] } } }, ({ lookup }) => {
+const lookChanged = System.create({ readonly: true, lookup: { found: { with: [amount], changed: [amount] } } }, ({ lookup }) => {
     seen.looked.push(watched.flatMap(entity => {
         const row = lookup.found(entity);
         return row === null ? [] : [row[amount], row.changed];
     }));
 });
-const countTagged = System.create({ observer: true, lookup: { all: { index: allTagged } } }, ({ lookup }) => {
+const countTagged = System.create({ readonly: true, lookup: { all: { index: allTagged } } }, ({ lookup }) => {
     seen.tagged.push(lookup.all().length);
 });
-const inCell = System.create({ observer: true, lookup: { found: { index: byCell } } }, ({ lookup }) => {
+const inCell = System.create({ readonly: true, lookup: { found: { index: byCell } } }, ({ lookup }) => {
     const found = lookup.found(11);
     seen.tagged.push(found.length === 0 ? 0 : found.length * 100 + (found.at(0)?.[amount] ?? -1));
 });
-const failing = System.create({ observer: true }, ({ resources }) => {
+const failing = System.create({ readonly: true }, ({ resources }) => {
     if (resources[level] > 1) throw new Error("observer joined failure");
 });
-const readLabels = System.create({ observer: true, components: { with: [label, amount] } }, row => {
+const readLabels = System.create({ readonly: true, components: { with: [label, amount] } }, row => {
     seen.labels.push(`${row[label].text}${row[amount]}`);
 });
 
 /** On the joined thread, as it reads labels: each watched entity's label and amount, which the world's run resolves to. */
-const labelsThere = System.create({ observer: true, lookup: { labelled: { with: [label, amount] } } }, ({ lookup }) =>
+const labelsThere = System.create({ readonly: true, lookup: { labelled: { with: [label, amount] } } }, ({ lookup }) =>
     watched.map(entity => {
         const row = lookup.labelled(entity);
         return row === null ? "none" : `${row[label].text}${row[amount]}`;
     }));
 /** On the joined thread, as it reads labels: throws there. */
-const failsThere = System.create({ observer: true, lookup: { labelled: { with: [label] } } }, ({ lookup }) => {
+const failsThere = System.create({ readonly: true, lookup: { labelled: { with: [label] } } }, ({ lookup }) => {
     if (lookup.labelled(Entity.none) === null) throw new Error("observerJoinedTest failure there");
     return 0;
 });
@@ -218,7 +218,7 @@ describe("observer systems on a joined thread", () => {
             Index.create({ key: [cell], sorted: true, components: { with: [amount] } }),
         ];
         const [madeTagged, madeByCell] = made();
-        const sizes = System.create({ observer: true, lookup: { all: { index: madeTagged, changed: [cell] }, cells: { index: madeByCell } } }, ({ lookup }) => {
+        const sizes = System.create({ readonly: true, lookup: { all: { index: madeTagged, changed: [cell] }, cells: { index: madeByCell } } }, ({ lookup }) => {
             const all = lookup.all();
             seen.looked.push([all.changed]);
             const high = lookup.cells({ ">=": 5 });
@@ -284,10 +284,18 @@ describe("observer systems on a joined thread", () => {
         await close();
     });
 
-    it("refuse only systems that aren't observer", async () => {
+    it("refuse only systems that aren't readonly, saying to declare them so", async () => {
         const { remote, close } = await joined();
-        expect(() => remote.add(raise)).toThrow("A joined thread adds only observer systems");
-        expect(() => remote.remove(raise)).toThrow("A joined thread removes only observer systems");
+        expect(() => remote.add(raise)).toThrow(`System "raise" isn't readonly, and a joined thread adds only readonly systems: declare it readonly: true to read the world from this thread, or add it on the world's thread.`);
+        expect(() => remote.remove(raise)).toThrow(`System "raise" isn't readonly, and a joined thread removes only readonly systems: others are removed on the world's thread.`);
+        await close();
+    });
+
+    it("refuse a readonly system reading tables, which only the world's thread gives", async () => {
+        const { remote, close } = await joined();
+        const readTables = System.create({ readonly: true, tables: { components: [label] } }, ({ tables }) => tables.archetypes.length);
+        expect(() => remote.add(readTables)).toThrow(`System "readTables" reads tables, which only the world's thread gives: run or add it there.`);
+        await expect(remote.run(readTables)).rejects.toThrow(`System "readTables" reads tables, which only the world's thread gives: run or add it there.`);
         await close();
     });
 
@@ -309,7 +317,7 @@ describe("observer systems on a joined thread", () => {
         const { world, close } = await joined(["observerJoinedTest"]);
         await world.run(spawnLabelled);
         // Made in a function, so the build gives it no id.
-        const made = () => System.create({ observer: true, components: { with: [label, amount] } }, row => {
+        const made = () => System.create({ readonly: true, components: { with: [label, amount] } }, row => {
             seen.labels.push(`${row[label].text}${row[amount]}`);
         });
         const madeLabels = made();

package/src/implementation/world/observer.browser.test.ts

@@ -27,11 +27,11 @@ const warm = System.create({ kernel: "gpu", components: { with: [rate, heat] } }
 });
 
 let total = 0;
-const sum = System.create({ observer: true, components: { with: [heat] } }, row => { total += row[heat]; });
+const sum = System.create({ readonly: true, components: { with: [heat] } }, row => { total += row[heat]; });
 
 const byHeat = Index.create({ key: [heat], sorted: true });
 let hot = 0;
-const countHot = System.create({ observer: true, lookup: { hot: { index: byHeat } } }, ({ lookup }) => {
+const countHot = System.create({ readonly: true, lookup: { hot: { index: byHeat } } }, ({ lookup }) => {
     hot = lookup.hot({ ">=": 150 }).length;
 });
 

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

@@ -37,33 +37,33 @@ const grow = System.create({ components: { with: [amount] } }, row => { row[amou
 const nothing = System.create({}, () => {});
 
 // It keeps its context, which the build can't follow, so it's given what it reads.
-const watchLevel = System.create(giveAccess({ observer: true }, { resources: { read: [level] } }), context => {
+const watchLevel = System.create(giveAccess({ readonly: true }, { resources: { read: [level] } }), context => {
     seen.levels.push(context.resources[level]);
     seen.contexts.push(context);
 });
-const watchAmounts = System.create({ observer: true, components: { with: [amount], changed: [amount] } }, row => { seen.amounts.push(row[amount]); });
-const count = System.create({ observer: true, components: { with: [amount] } }, () => { seen.counted.push(1); });
-const inCell = System.create({ observer: true, lookup: { found: { index: byCell } } }, ({ lookup }) => {
+const watchAmounts = System.create({ readonly: true, components: { with: [amount], changed: [amount] } }, row => { seen.amounts.push(row[amount]); });
+const count = System.create({ readonly: true, components: { with: [amount] } }, () => { seen.counted.push(1); });
+const inCell = System.create({ readonly: true, lookup: { found: { index: byCell } } }, ({ lookup }) => {
     seen.cells.push(lookup.found(7).length);
 });
-const failing = System.create({ observer: true }, ({ resources }) => {
+const failing = System.create({ readonly: true }, ({ resources }) => {
     if (resources[level] > 0) throw new Error("observer failed");
 });
 const raiseThenWatch = System.create([raise, watchLevel]);
-const watchLevelChanges = System.create({ observer: true, resources: { changed: [level] } }, ({ resources }) => {
+const watchLevelChanges = System.create({ readonly: true, resources: { changed: [level] } }, ({ resources }) => {
     seen.levels.push(resources[level]);
 });
 
 /** The world a removing body acts on. */
 let current: World | null = null;
-const removeLevel = System.create({ observer: true }, () => {
+const removeLevel = System.create({ readonly: true }, () => {
     seen.removals.push(1);
     current?.remove(watchLevel);
 });
 
 /** Adds `watchLevel` to the world the test runs, during a run. */
 const addWatch = System.create({}, () => { current?.add(watchLevel); });
-const addLevel = System.create({ observer: true }, () => {
+const addLevel = System.create({ readonly: true }, () => {
     current?.add(watchLevel);
 });
 

package/src/implementation/world/optional-workers.fixture.ts

@@ -30,7 +30,7 @@ const assign = System.create({ kernel: true, components: { with: [position], opt
     row[velocity] = row[position];
 });
 const totals = { moved: 0, still: 0 };
-const sum = System.create({ observer: true, components: { with: [position], optional: [velocity] } }, row => {
+const sum = System.create({ readonly: true, components: { with: [position], optional: [velocity] } }, row => {
     if (row[velocity] === undefined) totals.still += row[position];
     else totals.moved += row[position];
 });

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

@@ -73,7 +73,7 @@ const copySpeedKernel = System.create({
     if (found !== null) row[order] = found[velocity] === undefined ? -found[position] : found[velocity];
 });
 const speeds: number[] = [];
-const readSpeeds = System.create({ observer: true, components: { with: [other, order] } }, row => { speeds.push(row[order]); });
+const readSpeeds = System.create({ readonly: true, components: { with: [other, order] } }, row => { speeds.push(row[order]); });
 
 /** What finalizers read of rows that stopped, on the world's thread and on the markers'. */
 const stopped: string[] = [];
@@ -87,7 +87,7 @@ export const finalizeThere = Finalizer.create({ components: { with: [position, m
 const despawnAll = System.create({ components: { with: [position] } }, (row, { commands }) => { commands.despawn(row.entity); });
 
 let seen: (readonly [number, number | undefined, string | undefined])[] = [];
-const read = System.create({ observer: true, components: { with: [position], optional: [velocity, label] } }, row => {
+const read = System.create({ readonly: true, components: { with: [position], optional: [velocity, label] } }, row => {
     seen.push([row[position], row[velocity], row[label]]);
 });
 const sorted = () => [...seen].sort((a, b) => a[0] - b[0]);
@@ -109,7 +109,7 @@ const lookedThere = System.create({ components: { with: [position, marker] }, lo
 });
 // An observer system there reads copies of rows across archetypes, which tell which have the optional component.
 let watched: (readonly [number, number | undefined])[] = [];
-const watchThere = System.create({ observer: true, components: { with: [position], optional: [velocity] } }, row => {
+const watchThere = System.create({ readonly: true, components: { with: [position], optional: [velocity] } }, row => {
     watched.push([row[position], row[velocity]]);
 });
 // A tail there: it writes only its thread's objects, so it runs after the sync point, reading copies of rows.
@@ -165,7 +165,7 @@ const markEither = System.create({ kernel: true, components: { with: [mark], opt
     if (row[far] !== undefined) row[mark] = 2;
 });
 const marked: number[] = [];
-const watchStamped = System.create({ observer: true, components: { with: [mark], changed: [mark] } }, row => { marked.push(row[mark]); });
+const watchStamped = System.create({ readonly: true, components: { with: [mark], changed: [mark] } }, row => { marked.push(row[mark]); });
 const clearNear = System.create({ kernel: false, components: { with: [mark], optional: [near] } }, row => {
     if (row[near] !== undefined) row[near] = undefined;
 });
@@ -195,7 +195,7 @@ describe("optional components", () => {
 
     it("pass change filters on other components, and are stamped changed when written", async () => {
         const changed: number[] = [];
-        const watch = System.create({ observer: true, components: { with: [velocity], changed: [velocity] } }, row => { changed.push(row[velocity]); });
+        const watch = System.create({ readonly: true, components: { with: [velocity], changed: [velocity] } }, row => { changed.push(row[velocity]); });
         const speedUp = System.create({ components: { with: [position], optional: [velocity] } }, row => {
             const speed = row[velocity];
             if (speed !== undefined && row[position] > 50) row[velocity] = speed + 1;
@@ -212,7 +212,7 @@ describe("optional components", () => {
     it("run in an index's order across archetypes that have them and don't", async () => {
         const byOrder = Index.create({ key: [order], sorted: true });
         const ordered: (number | undefined)[] = [];
-        const list = System.create({ observer: true, components: { with: [position], optional: [velocity] }, order: byOrder }, row => {
+        const list = System.create({ readonly: true, components: { with: [position], optional: [velocity] }, order: byOrder }, row => {
             ordered.push(row[velocity]);
         });
         await using world = inline();
@@ -297,7 +297,7 @@ describe("optional components", () => {
         await world.run(spawnMarked);
         stoppedThere.length = 0;
         await world.run(despawnAll);
-        await remote.run(System.create({ observer: true }, () => {}));
+        await remote.run(System.create({ readonly: true }, () => {}));
         expect(stoppedThere.sort()).toEqual(["10:5:null", "1:none:null"]);
         await remote.dispose();
         await world.dispose();

package/src/implementation/world/perf.md

@@ -220,7 +220,7 @@ Shared components and `where`, against `12e366d`, node: the whole suite three ti
 - **A shared value read in a row costs what a column's does:** `shared read 100K` 4.04–4.10 ns a row against 4.24–4.27 for `column read 100K`, the value bound with the row once per archetype. In a kernel it's a parameter of each call: `shared read 100K kernel` 0.40–0.41 against 0.50 for `column read 100K kernel`, one column fewer to stream.
 - **Spawning with a shared constant:** `spawn bulk shared`, one spawner reused, 17.3–18.1 ns a spawn against 33.3–34.3 for `spawn bulk plain`, whose cell is a column; `spawn singles shared`, its spawner found by its constants each call, 313–323 ns against 229 for `spawn singles plain`: about 90 ns a call to find the spawner, a tuple's leaves walked through a tree of its stored leaves (`shared.ts`) and each constant in turn through the shape's tree of spawners, with no text built.
 - **`where` over 1K cells,** 3 × 3 of them in view: `where 1K cells still` 0.49 ns a cell, 0.5 µs a run with nothing evaluated; `where 1K cells moving`, every predicate evaluated again as the camera moves each run, 18.7–19.0 ns a cell, each predicate's resources read once per evaluation.
-- **Many small archetypes:** `small archetypes 1K`, 10K rows over 1K archetypes of one cell each, 7.26–7.43 ns a row against 3.46–3.49 for `one archetype 10K`: about 39 ns an archetype, binding its row and walking its filters, which a shared component's values multiply.
+- **Many small archetypes:** `small archetypes 1K`, 10K rows over 1K archetypes of one cell each, 6.8–7.0 ns a row against 3.04 for `one archetype 10K`: about 38 ns an archetype, binding its row, which a shared component's values multiply.
 
 Review fixes to shared components and `where`, node, alternating against the commit before each, medians of four to six rounds:
 - **Arrivals precise** (`arrivals.ts`): a system with `where` and change filters reads a ring of the moves since its last run, each archetype moved into owing the point of the one its rows came from, where every arrival made the archetype count from the oldest point of all matches, found by a scan of them. New `where changed 1K cells drifting in view`, every cell in view, 1% of 10K rows moving to the next cell before each run: 123.6 → 69.2 ns a cell; `where changed 1K cells drifting`, 3 × 3 cells in view, 2.0 → 2.8 ns a cell, the ring's 102 entries a run read, about 7 ns each, and cells moved into from culled ones scanned since that one's point; `changed 1K cells drifting`, without `where`, 52.3 → 52.0. `where 1K cells still` and `moving` within noise.
@@ -241,6 +241,8 @@ Step figures marked (vitest) are from the node vitest lane: read them as relativ
   kernel, the second call stayed a call and boxed each entity, a double past 2^32. `despawn bulk kernel` 4.60 → 4.12 ms;
   `despawn bulk` compiled 4.55 ms against 4.32 as written before, 4.10 after.
 - Inline value writes instead of closures, an 8-shape spawn cache, edges indexed by component id, archetypes grown once per sync point: create 38 → 27.6 ms.
+- Holders of references spawned in a sync point are linked a block at a time before the cascade, from their columns, rather than listed as triples for the cascade and for the holder index each; and `commands.spawnTables` lists owners between its rows only when one is dropped, and reserves a table's entities at once when every row spawns: `spawn tables 1M owner` 160 → 53 ms, `spawn owned 1M` 133 → 64 ms, against 10 ms for `spawn tables 1M`. Each holder is journaled once, so an `up` tree builds again past 4096 journal entries and an eighth of its rows, as indexes do: `up load` 183 → 120 ms.
+- A row loop reads the body into a local once, which V8 otherwise loads again each row, since the call could change it; rows bind without allocating, and filters are found by archetype id: `with 100K` 4.24 → 3.97 ns a row, `one archetype 10K` 3.47 → 3.04, `small archetypes 1K` 7.74 → 6.90, `shared read 100K` 4.07 → 3.78.
 
 **Change filters.**
 - Chunk ticks, the newest tick per 1024 rows, so filters skip unchanged chunks: clustered sparse to ~0.09 ms.

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

@@ -42,7 +42,7 @@ const caught: number[] = [];
 export const catchUp = System.create({ kernel: false, components: { with: [position], changed: [position], where: { [cell]: (at, { resources }) => at[0] === resources[camera] } } }, row => { caught.push(row[position]); });
 // On a joined thread.
 const heard: number[] = [];
-export const hear = System.create({ observer: true, components: { with: [cell, position], where: { [cell]: at => at[0] === 50 } } }, row => { heard.push(row[cell][0] * 1000 + row[position]); });
+export const hear = System.create({ readonly: true, components: { with: [cell, position], where: { [cell]: at => at[0] === 50 } } }, row => { heard.push(row[cell][0] * 1000 + row[position]); });
 
 /** Moves an entity to cell `[x, 0]`. */
 const step = System.create({}, ({ commands }, input: { readonly entity: Entity; readonly x: number }) => { commands.add(input.entity, cell, [input.x, 0]); });
@@ -59,7 +59,7 @@ const spawnAt = (world: ReturnType<typeof inline>, x: number, components: readon
 /** Every row's cell and position, by position. */
 const cellsOf = async (world: ReturnType<typeof inline>): Promise<readonly string[]> => {
     const found: [number, string][] = [];
-    await world.run(System.create({ observer: true, components: { with: [cell, position] } }, row => { found.push([row[position], `${row[cell][0]}:${row[position]}`]); }));
+    await world.run(System.create({ readonly: true, components: { with: [cell, position] } }, row => { found.push([row[position], `${row[cell][0]}:${row[position]}`]); }));
     return found.sort((a, b) => a[0] - b[0]).map(([, text]) => text);
 };
 
@@ -132,7 +132,7 @@ describe("reclaiming archetypes of shared values", () => {
         found.length = 0;
         await world.run(System.create({ kernel: false, components: { with: [cell, position] } }, row => { found.push(`body ${row[cell][0]}`); }));
         await world.run(copyCell);
-        await world.run(System.create({ observer: true, components: { with: [cell, seen] } }, row => { found.push(`kernel ${row[seen]}`); }));
+        await world.run(System.create({ readonly: true, components: { with: [cell, seen] } }, row => { found.push(`kernel ${row[seen]}`); }));
         await world.run(atFifty);
         await world.run(atLast);
         expect(found.sort()).toEqual(["body 50", `body ${emptyFor + 2}`, "kernel 50", `kernel ${emptyFor + 2}`, "value 0", "where 100"].sort());

package/src/implementation/world/register.ts

@@ -132,7 +132,7 @@ const observerTargetOf = (state: State, leaf: Leaf): ObserverTarget | undefined
 
 /** A runner for a leaf where it runs now: on the joined thread filling its thread, or that added it, or here. */
 const placedRunner = (state: State, leaf: Leaf, since = 0): Runner => {
-    if (leaf.declaration.observer === true) {
+    if (leaf.declaration.readonly === true) {
         const target = observerTargetOf(state, leaf);
         return target === undefined ? createRunner(state, leaf, since) : createJoinedObserverRunner(state, leaf, target, since);
     }
@@ -394,7 +394,7 @@ export const createRegistrar = (state: State): Registrar => {
 
     const place = (): void => {
         eachRunner((leaf, old, entry) => {
-            if (leaf.declaration.observer === true) {
+            if (leaf.declaration.readonly === true) {
                 if (observerTargetOf(state, leaf) === old.joined?.target) return;
                 replace(leaf, entry, old, placedRunner(state, leaf, old.lastRun()));
                 return;

package/src/implementation/world/remote-objects.test-helper.ts

@@ -72,7 +72,7 @@ export type Observers = "factory" | "observer";
 const observer: { entity: Entity | null; seen: ((odd: boolean, held: boolean, text: string | null | undefined) => void) | null } = { entity: null, seen: null };
 
 /** After each sync point, on the joined thread: the watched entity's phase and caption, and whether it's flagged. */
-export const observerWatch = System.create({ observer: true, lookup: { values: { with: [phase, caption] }, flagged: { with: [flag] } } }, ({ lookup }) => {
+export const observerWatch = System.create({ readonly: true, lookup: { values: { with: [phase, caption] }, flagged: { with: [flag] } } }, ({ lookup }) => {
     if (observer.entity === null) return;
     const row = lookup.values(observer.entity);
     if (row === null) return;

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

@@ -0,0 +1,61 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { expect, it } from "vitest";
+import { Finalizer, System } from "../../index.js";
+import { Observe } from "../../observe/index.js";
+import { createWorld } from "../index.js";
+import { sameValue } from "./resource-changes.js";
+
+const size = Symbol("resourceChanges/size");
+const corner = Symbol("resourceChanges/corner");
+const unwatched = Symbol("resourceChanges/unwatched");
+const log = Symbol("resourceChanges/log");
+const label = Symbol("resourceChanges/label");
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [label]: { type: string };
+    }
+    interface Resources {
+        [size]: { type: number; default: 1 };
+        [corner]: { type: readonly [number, number] };
+        [unwatched]: { type: number };
+        [log]: { type: readonly string[]; default: [] };
+    }
+}
+
+// Watching only resources, it sees no component's changes.
+Finalizer.changes({ watch: [size, corner] }, (changes, { resources }) => {
+    const lines = changes.resources.map(change => change.key === size ? `size ${change.previous} → ${change.next}` : `corner ${change.previous.join(",")} → ${change.next.join(",")}`);
+    resources[log] = [...resources[log], ...changes.groups.map(() => "group"), ...lines];
+});
+
+const resize = System.create({}, ({ resources }, input: { readonly to: number }) => {
+    resources[size] = input.to;
+    resources[size] = input.to + 1;
+});
+const move = System.create({}, ({ resources }, input: { readonly x: number }) => { resources[corner] = [input.x, 0]; });
+const touch = System.create({}, ({ resources }) => { resources[unwatched] += 1; });
+const spawn = System.create({}, ({ commands }) => { commands.spawn([label])({ [label]: "a" }); });
+const read = System.create({ readonly: true }, ({ resources }) => resources[log]);
+
+it("reports each watched resource written since its finalizers last ran, with its first and last value, once", async () => {
+    await using world = createWorld();
+    // A run writing nothing else still has a sync point, so its finalizers see the write.
+    await world.run(resize, { to: 4 });
+    expect(await world.run(read)).toEqual(["size 1 → 5"]);
+    await world.run(spawn);
+    await world.run(touch);
+    expect(await world.run(read)).toEqual(["size 1 → 5"]);
+    await world.run(move, { x: 2 });
+    // Written back to an equal value, leaf by leaf: not reported.
+    await world.run(move, { x: 2 });
+    await world.run(resize, { to: 4 });
+    expect(await world.run(read)).toEqual(["size 1 → 5", "corner 0,0 → 2,0"]);
+    expect(await Observe.toPromise(Observe.resource(world, size))).toBe(5);
+});
+
+it("compares data leaf by leaf and other objects by identity", () => {
+    const map = new Map();
+    expect([sameValue([1, { a: -0 }], [1, { a: -0 }]), sameValue({ a: 1 }, { a: 1, b: 2 }), sameValue(0, -0), sameValue(NaN, NaN), sameValue(map, new Map()), sameValue(map, map)])
+        .toEqual([true, false, false, true, false, true]);
+});

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