@adobe/ecs 0.2.1 → 0.2.3

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/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/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 { readTables } 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';
@@ -506,8 +507,11 @@ 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) Object.defineProperty(value, "tables", { get: () => readTables(state, tables), enumerable: true });
     const { lookup, resources } = declaration;
     const names = Object.keys(lookup ?? {});
     if (names.length > 0) {

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

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

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

@@ -39,7 +39,7 @@ const written = System.create({ kernel: false, components: { with: [scale, cell,
     row[steps] = x * 1000 + y;
 });
 const read: [number, string][] = [];
-const results = System.create({ observer: true, components: { with: [value, out, steps] } }, row => { read.push([row[value], `${row[out]} ${row[steps]}`]); });
+const results = System.create({ readonly: true, components: { with: [value, out, steps] } }, row => { read.push([row[value], `${row[out]} ${row[steps]}`]); });
 
 const outcome = async (system: typeof compute, wasm: boolean): Promise<readonly string[]> => {
     await using world = createWorld({ [workers]: 2 }, { minimumChunk: 2, wasm });
@@ -66,7 +66,7 @@ export const whereOnWorkers = async (wasm: boolean): Promise<{ readonly written:
     await world.run(negative);
     let written = 0;
     let left = 0;
-    await world.run(System.create({ observer: true, components: { with: [value, out] } }, row => {
+    await world.run(System.create({ readonly: true, components: { with: [value, out] } }, row => {
         if (row[out] === 0 && row[value] !== 0) left++;
         else written++;
     }));

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

@@ -39,7 +39,7 @@ const inline = () => createWorld({ [workers]: 0 });
 
 // Systems a joined thread runs, which it names by the ids the build gives them at the top level.
 const heard: string[] = [];
-export const listen = System.create({ observer: true, components: { with: [team, health] } }, row => { heard.push(`${row[team]} ${row[health]}`); });
+export const listen = System.create({ readonly: true, components: { with: [team, health] } }, row => { heard.push(`${row[team]} ${row[health]}`); });
 export const spawnBanners = System.create(({ commands }) => {
     commands.spawn([team, health, banner], { [team]: "red" })({ [health]: 1 });
     commands.spawn([team, health, banner], { [team]: "blue" })({ [health]: 2 });
@@ -60,11 +60,11 @@ export const spawnThere = System.create({ components: { with: [banner] } }, (row
     commands.spawn([health, marker], base)({ [marker]: 1 });
     commands.spawn([health], base)({});
 });
-export const readBanners = System.create({ observer: true, components: { with: [banner] } }, row => { banners.push(row[banner]?.text ?? "none"); });
+export const readBanners = System.create({ readonly: true, components: { with: [banner] } }, row => { banners.push(row[banner]?.text ?? "none"); });
 
 /** Every entity's team and health, and whether it's armed, sorted by health. */
 const rowsOf = async (world: ReturnType<typeof inline>): Promise<readonly string[]> => {
-    const read = System.create({ observer: true, components: { with: [team, health], optional: [armed] } }, (row) => {
+    const read = System.create({ readonly: true, components: { with: [team, health], optional: [armed] } }, (row) => {
         found.push(`${row[team]} ${row[health]}${row[armed] === true ? " armed" : ""}`);
     });
     const found: string[] = [];
@@ -116,7 +116,7 @@ describe("a shared component", () => {
         // Three cells' worth of [1, 2] and [2, 1], three weights and one style.
         expect((await world.tables()).archetypes - before).toBe(2 + 3 + 1);
         const read: string[] = [];
-        await world.run(System.create({ observer: true, components: { with: [health], optional: [cell, weight, style] } }, row => {
+        await world.run(System.create({ readonly: true, components: { with: [health], optional: [cell, weight, style] } }, row => {
             if (row[health] === 0) return;
             read.push(`${row[health]}: ${JSON.stringify(row[cell] ?? row[style] ?? null)} ${String(row[weight])}`);
         }));
@@ -216,8 +216,8 @@ describe("a shared component", () => {
             commands.spawn([team, health], { [team]: "red" })({ [health]: 2 });
         }));
         const changes: string[] = [];
-        const watch = System.create({ observer: true, components: { with: [health], changed: [team] } }, row => { changes.push(`changed ${row[health]}`); });
-        const adds = System.create({ observer: true, components: { with: [health], added: [team] } }, row => { changes.push(`added ${row[health]}`); });
+        const watch = System.create({ readonly: true, components: { with: [health], changed: [team] } }, row => { changes.push(`changed ${row[health]}`); });
+        const adds = System.create({ readonly: true, components: { with: [health], added: [team] } }, row => { changes.push(`added ${row[health]}`); });
         world.add(watch);
         world.add(adds);
         await world.run(System.create(() => {}));
@@ -294,7 +294,7 @@ describe("a shared component", () => {
         }));
         await world.run(System.create({ components: { with: [weight, health] } }, row => { row[health] *= row[weight]; }));
         const read: number[] = [];
-        await world.run(System.create({ observer: true, components: { with: [health] } }, row => { read.push(row[health]); }));
+        await world.run(System.create({ readonly: true, components: { with: [health] } }, row => { read.push(row[health]); }));
         expect(read.sort()).toEqual([2, 3]);
     });
 
@@ -338,7 +338,7 @@ describe("a shared component", () => {
         await world.run(writeBanners);
         await world.run(spawnThere);
         const found: string[] = [];
-        await world.run(System.create({ observer: true, components: { with: [health], optional: [marker, team] } }, row => {
+        await world.run(System.create({ readonly: true, components: { with: [health], optional: [marker, team] } }, row => {
             if (row[team] === undefined) found.push(`${row[health]} ${row[marker] ?? "none"}`);
         }));
         expect(found.sort()).toEqual(["7 1", "7 1", "7 none", "7 none"]);

package/src/implementation/world/sharing.ts

@@ -613,7 +613,7 @@ export const createSharing = (host: SharingHost) => {
             const { components, resources } = declared;
             // Unnamed, so other systems' labels stay as they are; its own is the thread's.
             const declaration: Resolved = {
-                observer: true,
+                readonly: true,
                 // Its `where` runs on its thread; here, an empty one says it has one, which every archetype passes.
                 ...components === null ? {} : { components: { ...listed([["read", components.read], ["has", components.has], ["optional", components.optional], ["not", components.not], ["added", components.added], ["changed", components.changed]]), ...components.where ? { where: {} } : {} } },
                 ...resources === null ? {} : { resources: listed([["read", resources.read], ["changed", resources.changed], ["is", resources.is], ["not", resources.not]]) },

package/src/implementation/world/staging.ts

@@ -69,14 +69,15 @@ export const createBatch = (layouts: readonly Layout[], ids: readonly number[],
     return { ids: sorted, shared, archetype: null, columns: sorted.map(id => columnOf(layouts[id], id, initialCapacity)), entities: new Float64Array(initialCapacity), count: 0, capacity: initialCapacity, revive: null, generation: 0 };
 };
 
-const grow = (batch: SpawnBatch): void => {
+/** Grows a batch to hold at least `needed` rows: twice its capacity, or `needed` where that's more. */
+const grow = (batch: SpawnBatch, needed = batch.count + 1): void => {
     const { revive } = batch;
     if (revive !== null) {
         batch.revive = null;
         revive();
-        if (batch.count < batch.capacity) return;
+        if (needed <= batch.capacity) return;
     }
-    const capacity = batch.capacity * 2;
+    const capacity = Math.max(batch.capacity * 2, needed);
     for (const column of batch.columns) {
         const views = viewsOf(new ArrayBuffer(capacity * column.stride), 0, capacity * column.stride);
         views.u8.set(column.views.u8.subarray(0, batch.count * column.stride));
@@ -146,6 +147,18 @@ export const openRow = (batch: SpawnBatch): number => {
     return batch.count;
 };
 
+/** The first of the `n` rows the batch's next spawns write, growing it first to hold them. */
+export const openRows = (batch: SpawnBatch, n: number): number => {
+    if (batch.count + n > batch.capacity) grow(batch, batch.count + n);
+    return batch.count;
+};
+
+/** Claims the open rows for `entities`, once all their values are written. */
+export const claimRows = (batch: SpawnBatch, entities: Float64Array): void => {
+    batch.entities.set(entities, batch.count);
+    batch.count += entities.length;
+};
+
 /** Claims the open row for `entity`, once all its values are written. */
 export const claim = (batch: SpawnBatch, entity: number): void => {
     batch.entities[batch.count] = entity;

package/src/implementation/world/tables-read.ts

@@ -0,0 +1,59 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { labelOf } from '../../interface/registry/names.js';
+import type { Tables, TablesDeclaration } from '../../interface/system/tables.js';
+import type { Table } from '../../interface/world/table/table.js';
+import type { Storage } from './archetype.js';
+import { readCell } from './cells.js';
+import { resourceCell } from './resources.js';
+import { idOf, type Key, type State } from './state.js';
+
+// Reading tables, apart from spawning them: rows' contexts import it, and what spawning imports would make a cycle.
+
+/** What an archetype's storage of a component gives a table: a copy of its rows `0` to `count`. */
+const columnOf = (key: Key, storage: Storage, count: number): Table.Column => {
+    const { layout } = storage;
+    switch (layout.kind) {
+        case "linear": return { kind: "bytes", bytes: storage.views.u8.slice(0, count * layout.stride), stride: layout.stride };
+        case "constant": return { kind: "value", value: layout.value };
+        case "object":
+            if (storage.remote !== null) throw new Error(`Tables can't read "${labelOf(key)}": a joined thread fills its objects.`);
+            return { kind: "values", values: storage.values.slice(0, count) };
+        case "string": {
+            const values: unknown[] = new Array(count);
+            for (let row = 0; row < count; row++) values[row] = readCell(storage, row);
+            return { kind: "values", values };
+        }
+    }
+};
+
+/**
+ * A readonly system's `tables`: of each archetype matching `with` and `not` and holding any of `components`, its
+ * entities and a copy of the column of each of them it holds; and the value of each resource of `resources`.
+ */
+export const readTables = (state: State, declaration: TablesDeclaration): Tables => {
+    const asked = declaration.components.map(key => ({ key, id: idOf(state, key) }));
+    const required = (declaration.with ?? []).map(key => idOf(state, key));
+    const excluded = (declaration.not ?? []).map(key => idOf(state, key));
+    const archetypes: Table[] = [];
+    for (const archetype of state.archetypes) {
+        const { count } = archetype;
+        if (count === 0 || archetype.reclaimed) continue;
+        const { storageById } = archetype;
+        if (required.some(id => storageById[id] === undefined) || excluded.some(id => storageById[id] !== undefined)) continue;
+        const columns: { [key: symbol]: Table.Column } = {};
+        let held = false;
+        for (const { key, id } of asked) {
+            const storage = storageById[id];
+            if (storage === undefined) continue;
+            columns[key] = columnOf(key, storage, count);
+            held = true;
+        }
+        if (held) archetypes.push({ count, entities: archetype.entities.slice(0, count), columns });
+    }
+    const resources: { [key: symbol]: unknown } = {};
+    for (const key of declaration.resources ?? []) {
+        const cell = resourceCell(state, key);
+        resources[key] = readCell(cell.storage, cell.row);
+    }
+    return { archetypes, resources };
+};