@adobe/ecs 0.2.1 → 0.2.4

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

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

package/src/implementation/world/sync-points.test.ts

@@ -0,0 +1,135 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Entity } from "../../interface/entity/entity.js";
+import { Index } from "../../interface/indexes/index-type.js";
+import { System } from "../../interface/system/system.js";
+import { workers } from "../../interface/resources/workers.js";
+import { createWorld } from "./create.js";
+import { count as countOf, readEach, select } from "./reads.test-helper.js";
+
+const position = Symbol("syncPointsTest/position");
+const cell = Symbol("syncPointsTest/cell");
+const found = Symbol("syncPointsTest/found");
+const team = Symbol("syncPointsTest/team");
+const member = Symbol("syncPointsTest/member");
+const local = Symbol("syncPointsTest/local");
+const total = Symbol("syncPointsTest/total");
+const parent = Symbol("syncPointsTest/parent");
+const seed = Symbol("syncPointsTest/seed");
+const grown = Symbol("syncPointsTest/grown");
+const children = Symbol("syncPointsTest/children");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [position]: { type: number };
+        [cell]: { type: number };
+        [team]: { type: true };
+        [member]: { type: Entity; reference: "owner" };
+        [local]: { type: number };
+        [total]: { type: number };
+        [parent]: { type: Entity; reference: "weak" };
+        [seed]: { type: number };
+        [grown]: { type: number };
+    }
+    export interface Resources {
+        [found]: { type: number };
+        [children]: { type: number; default: 0 };
+    }
+}
+
+const byCell = Index.create({ key: [cell] });
+
+const spawn = System.create(({ commands }) => { for (let k = 0; k < 3; k++) commands.spawn([position])({ [position]: k }); });
+const counted: number[] = [];
+const count = System.create({ components: { with: [position] }, after: [spawn] }, row => { counted.push(row[position]); });
+const changes: number[] = [];
+const watchChanges = System.create({ components: { with: [position], changed: [position] }, after: [count] }, row => { changes.push(row[position]); });
+const deriveCells = System.create({ components: { with: [position], not: [cell] }, after: [watchChanges] }, (row, { commands }) => { commands.add(row.entity, cell, row[position] % 2); });
+const pick = System.create({ lookup: { cells: { index: byCell } }, after: [deriveCells] }, ({ lookup, resources }) => { resources[found] = lookup.cells(0).length; });
+const readFound = System.create({ readonly: true }, ({ resources }) => resources[found]);
+const frame = System.create([spawn, count, watchChanges, deriveCells, pick]);
+
+const spawnTeams = System.create(({ commands }) => {
+    for (let k = 0; k < 3; k++) {
+        const owner = commands.spawn([team])();
+        for (let m = 0; m < 2; m++) commands.spawn([member])({ [member]: owner });
+    }
+});
+const disband = System.create({ components: { with: [team] }, after: [spawnTeams] }, (row, { commands }) => { commands.despawn(row.entity); });
+const round = System.create([spawnTeams, disband]);
+
+/** Spawns a root, `count` children of it and a child of each. */
+const spawnTree = System.create({}, ({ commands }, input: { readonly count: number }) => {
+    const root = commands.spawn([local, total])({ [local]: 1, [total]: 0 });
+    for (let k = 0; k < input.count; k++) {
+        const child = commands.spawn([local, total, parent])({ [local]: 1, [total]: 0, [parent]: root });
+        commands.spawn([local, total, parent])({ [local]: 1, [total]: 0, [parent]: child });
+    }
+});
+const propagate = System.create({ components: { with: [local, total], changed: [local] }, up: { through: parent }, after: [spawnTree] }, (row, { up }) => {
+    row[total] = (up === null ? 0 : up[total]) + row[local];
+});
+const grow = System.create([spawnTree, propagate]);
+
+const plant = System.create(({ commands }) => { for (let k = 0; k < 64; k++) commands.spawn([seed])({ [seed]: k }); });
+const sprout = System.create({ kernel: true, components: { with: [seed] }, after: [plant] }, (row, { commands }) => {
+    commands.spawn([grown])({ [grown]: row[seed] * 2 });
+});
+const tally = System.create({ components: { with: [grown] }, after: [sprout] }, (row, { resources }) => { resources[children] += row[grown]; });
+const garden = System.create([plant, sprout, tally]);
+const readChildren = System.create({ readonly: true }, ({ resources }) => resources[children]);
+
+describe("sync points within a run", () => {
+    it("apply commands before a later system that depends on what they change, which then sees them in the same run", async () => {
+        const world = createWorld({ [workers]: 0 });
+        await world.run(frame);
+        expect(counted).toEqual([0, 1, 2]);
+        expect(await world.run(readFound)).toBe(2);
+        await world.dispose();
+    });
+    it("keep each change seen once by change filters across runs", async () => {
+        const world = createWorld({ [workers]: 0 });
+        changes.length = 0;
+        await world.run(frame);
+        expect(changes).toEqual([0, 1, 2]);
+        changes.length = 0;
+        counted.length = 0;
+        await world.run(frame);
+        // The second run's spawns are new; the first run's three are seen again by count alone.
+        expect([counted.length, changes]).toEqual([6, [0, 1, 2]]);
+        expect(await world.run(readFound)).toBe(4);
+        await world.dispose();
+    });
+
+    it("despawn what rows spawned at an earlier sync point of the run own, once a later tier despawns their owners", async () => {
+        expect(System.describe(round).tiers.map(tier => tier.sync === null)).toEqual([false, true]);
+        await using world = createWorld({ [workers]: 0 });
+        await world.run(round);
+        expect([await countOf(world, { required: [team] }), await countOf(world, { required: [member] })]).toEqual([0, 0]);
+    });
+
+    it("bring an `up` tree up to date at each, built again or patched, for a tier after it in the same run", async () => {
+        expect(System.describe(grow).tiers.map(tier => tier.sync === null)).toEqual([false, true]);
+        await using world = createWorld({ [workers]: 0 });
+        let spawned = 0;
+        // Past the journal's worth a tree patches, then within it.
+        for (const count of [5_000, 3_000, 10]) {
+            await world.run(grow, { count });
+            spawned += count;
+            const totals = await readEach(world, await select(world, { required: [total] }), total);
+            const byDepth = [1, 2, 3].map(depth => totals.filter(value => value === depth).length);
+            expect([byDepth, totals.length]).toEqual([[totals.length - 2 * spawned, spawned, spawned], totals.length]);
+        }
+    });
+
+    it("commit a kernel's staged spawns at a sync point within the run, for a later tier", async () => {
+        expect(System.describe(garden).tiers.map(tier => tier.sync === null)).toEqual([false, false, true]);
+        await using world = createWorld({ [workers]: 0 });
+        const sum = 63 * 64;
+        await world.run(garden);
+        expect(await world.run(readChildren)).toBe(sum);
+        // The second run's seeds are both runs' plantings, and its tally reads the first run's grown rows too.
+        await world.run(garden);
+        expect(await world.run(readChildren)).toBe(sum + sum + 2 * sum);
+    });
+});

package/src/implementation/world/synchronize.ts

@@ -2,10 +2,10 @@
 import type { Views } from '../../interface/registry/layout.js';
 import { copyValue, ensureCapacity, swapRemove, writeF32, writeF32Lanes, writeF64, writeI32, writeU32, type Archetype, type Storage } from './archetype.js';
 import { blockShift, chunkShift } from './kernel.js';
-import { addCommand, clearBuffer, despawnCommand, endOf, referenceAt, removeCommand, spawnCommand, type CommandBuffer } from './buffer.js';
+import { addCommand, clearBuffer, despawnCommand, despawnWhereCommand, despawnWhereHolds, endOf, referenceAt, removeCommand, spawnCommand, type CommandBuffer } from './buffer.js';
 import { readCell, writeCell } from './cells.js';
 import { commitBatches, commitStaged } from './batches.js';
-import { applyIndexChanges, cascadeReferences, indexChangesOf, type IndexChanges, type Written } from './cascade.js';
+import { applyIndexChanges, cascadeReferences, indexChangesOf, linkBorn, type IndexChanges, type Written } from './cascade.js';
 import { refreshDirectories } from './directories.js';
 import { createArrivals, logArrival } from './arrivals.js';
 import { noteEdge, noteEmptied, reclaimEmptied } from './reclaim.js';
@@ -21,6 +21,8 @@ import type { Plan } from './plan.js';
 import type { MoveLog } from './move-log.js';
 import { archetypeOf, movesOf, sharedNumberOf, withComponent, withoutComponent, withShared, type State } from './state.js';
 import { releaseValue } from './transfers.js';
+import { resourcesWritten } from './resource-changes.js';
+import { recordPlan } from './run-changes.js';
 
 /** Buffers queued for the next sync point, in merge order. Commands in guarded buffers can't touch the resource entity. */
 export type Queued = { readonly buffer: CommandBuffer; readonly guarded: boolean };
@@ -127,6 +129,56 @@ const releaseDropped = (state: State, buffer: CommandBuffer, command: number): v
     }
 };
 
+/**
+ * Whether `archetype` has each component of `ids` from `start` to `middle` and none from there to `end`, and holds the
+ * values `holds` tells it holds, when it isn't null.
+ */
+const matches = (archetype: Archetype, ids: Int32Array, start: number, middle: number, end: number, holds: Function | null): boolean => {
+    const { storageById } = archetype;
+    for (let k = start; k < middle; k++) if (storageById[ids[k]] === undefined) return false;
+    for (let k = middle; k < end; k++) if (storageById[ids[k]] !== undefined) return false;
+    return holds === null || Reflect.apply(holds, undefined, [archetype]) === true;
+};
+
+/** The archetype an entity planned into `archetype` ends up in once derived. */
+const closedOf = (state: State, archetype: Archetype): Archetype => {
+    const cached = state.structure.closures[archetype.id] ?? -1;
+    return cached >= 0 ? state.archetypes[cached] : closureOf(state.structure, state.derived, archetype, (components, shared) => archetypeOf(state, components, shared), state.archetypes);
+};
+
+/**
+ * Despawns each entity a `despawnWhere` command selects given the plan so far: those planned, by where they're going,
+ * then the rest, by the archetype they're in. Never the resource entity.
+ */
+const despawnWhere = (state: State, buffer: CommandBuffer, command: number, within: boolean): void => {
+    const { plan, archetypes } = state;
+    const { ids } = buffer;
+    const start = buffer.starts[command];
+    const middle = start + buffer.entities[command];
+    const last = endOf(buffer, command);
+    const where = ids[last - 1] === despawnWhereHolds ? buffer.values[last - 1] : null;
+    const holds = typeof where === "function" ? where : null;
+    const end = holds === null ? last : last - 1;
+    for (let entry = 0; entry < plan.count; entry++) {
+        if (plan.despawned[entry] === 1 || plan.entity[entry] === state.resourceEntity) continue;
+        const to = archetypes[plan.to[entry]];
+        if (matches(within && plan.to[entry] !== plan.from[entry] ? closedOf(state, to) : to, ids, start, middle, end, holds)) plan.despawned[entry] = 1;
+    }
+    const { slots } = plan;
+    const count = archetypes.length;
+    for (let id = 0; id < count; id++) {
+        const archetype = archetypes[id];
+        if (archetype.resource || archetype.count === 0 || !matches(archetype, ids, start, middle, end, holds)) continue;
+        ensurePlanCapacity(state, plan.count + archetype.count);
+        const { entities } = archetype;
+        for (let row = 0; row < archetype.count; row++) {
+            const entity = entities[row];
+            const index = indexOf(entity);
+            if (slots[index] < 0) plan.despawned[addPlanned(state, entity, index, id, id)] = 1;
+        }
+    }
+};
+
 /**
  * Plan: the net change for each entity, in issue order. Commands against dead entities do nothing. Reference values
  * written by commands go to `written`, to check once despawns are known.
@@ -146,6 +198,11 @@ const planOf = (state: State, queued: readonly Queued[], written: Written): void
         ensurePlanCapacity(state, plan.count + buffer.count);
         for (let command = 0; command < buffer.count; command++) {
             const kind = kinds[command];
+            if (kind === despawnWhereCommand) {
+                despawnWhere(state, buffer, command, within);
+                ensurePlanCapacity(state, plan.count + buffer.count - command);
+                continue;
+            }
             const entity = entities[command];
             if (guarded && entity === state.resourceEntity) continue;
             const index = indexOf(entity);
@@ -631,7 +688,9 @@ const noneQueued: readonly Queued[] = [];
 export const syncPending = (state: State, queued: readonly Queued[] = state.queued): boolean =>
     anyCommands(queued) || reserved(state.entities) || state.carried !== null || state.structure.rederive
     // Failures for its run, as a gone thread's stops it never finalized are.
-    || state.unplaced.length > 0;
+    || state.unplaced.length > 0
+    // A watched resource written, which its changes finalizers see at a sync point.
+    || (state.resourcesSeen.size > 0 && resourcesWritten(state));
 
 /**
  * The first half of a sync point: commits batch spawns, plans every command, cascades references and closes the plan
@@ -688,22 +747,9 @@ const preparePending = (state: State, queued: readonly Queued[], isolated: boole
         if (deriving) for (let entry = 0; entry < plan.count; entry++) if (plan.despawned[entry] === 0) plan.to[entry] = close(state.archetypes[plan.to[entry]]).id;
         let index: IndexChanges | null = null;
         if (structure.referenceIds.length > 0) {
-            for (const [id, first] of born) {
-                const archetype = state.archetypes[id];
-                for (const component of structure.referenceIds) {
-                    const storage = archetype.storageById[component];
-                    if (storage === undefined) continue;
-                    for (let row = first; row < archetype.count; row++) written.push(archetype.entities[row], component, Number(readCell(storage, row)));
-                }
-            }
+            linkBorn(state, born, written, tick);
             cascadeReferences(state, queued, written, entity => entryOf(state, entity));
-            const fromOf = (entry: number): Archetype | null => {
-                const from = plan.from[entry];
-                if (from < 0) return null;
-                const first = born.get(from);
-                return first !== undefined && state.entities.row[indexOf(plan.entity[entry])] >= first ? null : state.archetypes[from];
-            };
-            index = indexChangesOf(state, queued, fromOf, [...born].map(([id, first]) => [state.archetypes[id], first] as const));
+            index = indexChangesOf(state, queued, entry => plan.from[entry] < 0 ? null : state.archetypes[plan.from[entry]]);
         }
         // References change only here: each component written to is stamped, and each holder journaled, as are spawns.
         for (let k = 1; k < written.length; k += 3) state.referencesWritten[written[k]] = tick;
@@ -741,6 +787,7 @@ export const applySync = (state: State): readonly Thrown[] => {
     let errors = nothingThrown;
     try {
         if (state.unplaced.length > 0 && !isolated) errors = state.unplaced.splice(0);
+        if (state.recording !== null && !isolated) recordPlan(state, state.recording, queued, born);
         if (state.finalizers.length > 0 && !isolated) {
             const thrown = runFinalizers(state, queued, born, tick);
             errors = errors.length === 0 ? thrown : [...errors, ...thrown];

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

@@ -0,0 +1,70 @@
+// © 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 { Archetype, Storage } from './archetype.js';
+import { readCell } from './cells.js';
+import { resourceCell } from './resources.js';
+import { idOf, type Key, type State } from './state.js';
+import { holdsValuesOf } from './where.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`, read by the function this returns, once per read: of each archetype matching `with`,
+ * `not` and `where` 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`. `where` holds its values as a system's does, and an archetype
+ * matches it as one matches a system's `where`, required as `with` requires them.
+ */
+export const tablesReader = (state: State, declaration: TablesDeclaration): (() => Tables) => {
+    const holds = declaration.where === undefined ? null : holdsValuesOf(state, declaration.where, true);
+    if (typeof holds === "symbol") throw new Error(`Tables' where names "${labelOf(holds)}", which isn't a shared component.`);
+    const where = declaration.where === undefined ? [] : Object.getOwnPropertySymbols(declaration.where);
+    return () => readTables(state, declaration, [...where, ...declaration.with ?? []], holds);
+};
+
+const readTables = (state: State, declaration: TablesDeclaration, requiring: readonly Key[], holds: ((archetype: Archetype) => boolean) | null): Tables => {
+    const asked = declaration.components.map(key => ({ key, id: idOf(state, key) }));
+    const required = requiring.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;
+        if (holds !== null && !holds(archetype)) 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 };
+};