@adobe/ecs 0.2.1 → 0.2.4

package/src/implementation/world/tables.ts

@@ -0,0 +1,368 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Layout, Path } from '../../interface/registry/layout.js';
+import { declarationOf, labelOf } from '../../interface/registry/names.js';
+import { isEntity } from '../../interface/registry/schemas.js';
+import type { Schema } from '../../interface/schema/schema.js';
+import type { Table } from '../../interface/world/table/table.js';
+import { batchOf } from './batches.js';
+import { indexOf, locate, reserveRun } from './entities.js';
+import { internShared } from './shared.js';
+import { claimRows, openRows, writerOf, type Column as BatchColumn } from './staging.js';
+import { commandIdOf, type Key, type State } from './state.js';
+
+/** Whether a value of `schema` may hold an entity anywhere in it. */
+const holdsEntity = (schema: Schema): boolean => {
+    if (isEntity(schema)) return true;
+    if ("anyOf" in schema) return schema.anyOf.some(holdsEntity);
+    if ("allOf" in schema) return schema.allOf.some(holdsEntity);
+    if (!("type" in schema)) return false;
+    switch (schema.type) {
+        case "array": case "set": return holdsEntity(schema.items);
+        case "map": return holdsEntity(schema.keys) || holdsEntity(schema.values);
+        case "object": return Object.values(schema.properties).some(holdsEntity);
+        default: return false;
+    }
+};
+
+/** The schema at `path` inside `schema`, through struct fields and tuple items. */
+const schemaAt = (schema: Schema, path: Path): Schema | undefined => {
+    let at: Schema | undefined = schema;
+    for (const step of path) {
+        if (at === undefined || !("type" in at)) return undefined;
+        if (at.type === "object" && typeof step === "string") at = at.properties[step];
+        else if (at.type === "array" && typeof step === "number") at = at.items;
+        else return undefined;
+    }
+    return at;
+};
+
+/** The f64 leaves of a linear layout holding entities: where, in f64 elements, each row's is. */
+const entityLeavesOf = (layout: Layout, schema: Schema | undefined): readonly { readonly unitStride: number; readonly unitOffset: number }[] => {
+    if (layout.kind !== "linear" || schema === undefined) return [];
+    return layout.leaves.filter(leaf => {
+        const leafSchema = schemaAt(schema, leaf.path);
+        return leaf.view === "f64" && leafSchema !== undefined && isEntity(leafSchema);
+    });
+};
+
+/** The entity each entity of the tables given is spawned as, and what a value naming none of them becomes. */
+type Remap = (entity: number) => number;
+
+/** `value` of `schema` with each entity in it replaced by `remap`'s. */
+const remapValue = (schema: Schema, value: unknown, remap: Remap): unknown => {
+    if (isEntity(schema)) return typeof value === "number" ? remap(value) : value;
+    if (!holdsEntity(schema)) return value;
+    if ("anyOf" in schema) {
+        for (const member of schema.anyOf) {
+            if (isEntity(member) && typeof value === "number") return remap(value);
+            if (!("type" in member) || !holdsEntity(member)) continue;
+            if ((member.type === "array" && Array.isArray(value)) || (member.type === "set" && value instanceof Set) || (member.type === "map" && value instanceof Map)
+                || (member.type === "object" && typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof Set) && !(value instanceof Map))) return remapValue(member, value, remap);
+        }
+        return value;
+    }
+    if ("allOf" in schema) return schema.allOf.reduce<unknown>((next, member) => remapValue(member, next, remap), value);
+    if (!("type" in schema)) return value;
+    switch (schema.type) {
+        case "array": return Array.isArray(value) ? value.map(item => remapValue(schema.items, item, remap)) : value;
+        case "set": return value instanceof Set ? new Set(Array.from(value, item => remapValue(schema.items, item, remap))) : value;
+        case "map": return value instanceof Map ? new Map(Array.from(value, ([key, item]) => [remapValue(schema.keys, key, remap), remapValue(schema.values, item, remap)])) : value;
+        case "object": {
+            if (typeof value !== "object" || value === null) return value;
+            const copy: { [name: string]: unknown } = {};
+            for (const name of Object.keys(value)) {
+                const field = schema.properties[name];
+                const item: unknown = Reflect.get(value, name);
+                copy[name] = field === undefined ? item : remapValue(field, item, remap);
+            }
+            return copy;
+        }
+        default: return value;
+    }
+};
+
+/** A table's components with their ids, the columns given for them, and their layouts. */
+type Planned = {
+    readonly table: Table;
+    readonly keys: readonly Key[];
+    readonly ids: readonly number[];
+    readonly shared: (number | undefined)[];
+};
+
+/** Throws, naming the component, for a column that doesn't fit its component's layout or its table's count. */
+const checkColumn = (state: State, key: Key, id: number, column: Table.Column, count: number): void => {
+    const layout = state.layouts[id];
+    const fail = (message: string): never => { throw new Error(`commands.spawnTables: "${labelOf(key)}" ${message}.`); };
+    if (state.shared[id] !== undefined) {
+        if (column.kind !== "value") fail("is a shared component, so its column is one value");
+        return;
+    }
+    if (layout.kind === "constant" || column.kind === "value") return;
+    if (layout.kind === "linear") {
+        if (column.kind !== "bytes") fail("is stored as bytes, so its column gives bytes");
+        else if (column.stride !== layout.stride) fail(`has a stride of ${layout.stride} bytes in this world, not ${column.stride}`);
+        else if (column.bytes.length !== count * layout.stride) fail(`gives ${column.bytes.length} bytes for ${count} rows of ${layout.stride}`);
+        return;
+    }
+    if (column.kind !== "values") fail("is stored as values, so its column gives values");
+    else if (column.values.length !== count) fail(`gives ${column.values.length} values for ${count} rows`);
+};
+
+/** The plan of each table: its keys, their command ids, and the numbers of its shared values. Throws for one that won't spawn. */
+const planOf = (state: State, table: Table): Planned => {
+    const { count, entities, columns } = table;
+    if (!Number.isInteger(count) || count < 0 || entities.length !== count) throw new Error(`commands.spawnTables: a table of ${count} rows gives ${entities.length} entities.`);
+    const keys = Object.getOwnPropertySymbols(columns).filter(key => Reflect.get(columns, key) !== undefined);
+    const ids = keys.map(key => commandIdOf(state, key));
+    const shared: (number | undefined)[] = [];
+    keys.forEach((key, k) => {
+        const column: Table.Column = Reflect.get(columns, key);
+        checkColumn(state, key, ids[k], column, count);
+        const values = state.shared[ids[k]];
+        if (values !== undefined && column.kind === "value") {
+            const number = internShared(values, column.value);
+            if (number < 0) throw new Error(`commands.spawnTables: "${labelOf(key)}", a shared component, isn't given one of its type's values: ${labelOf(column.value)}.`);
+            shared[ids[k]] = number;
+        }
+    });
+    return { table, keys, ids, shared };
+};
+
+/**
+ * Where each entity of the tables is, by its index: the entity itself, to tell it from another of that index, and its
+ * position among all the tables' rows. Throws for an entity two rows name.
+ */
+const placesOf = (plans: readonly Planned[]): { readonly entities: Float64Array; readonly positions: Int32Array } => {
+    let largest = 0;
+    for (const { table } of plans) for (let row = 0; row < table.count; row++) largest = Math.max(largest, indexOf(table.entities[row]));
+    const entities = new Float64Array(largest + 1).fill(-1);
+    const positions = new Int32Array(largest + 1);
+    let position = 0;
+    for (const { table } of plans) {
+        for (let row = 0; row < table.count; row++) {
+            const entity = table.entities[row];
+            const index = indexOf(entity);
+            if (entities[index] === entity) throw new Error(`commands.spawnTables: entity ${entity} is in two rows.`);
+            entities[index] = entity;
+            positions[index] = position++;
+        }
+    }
+    return { entities, positions };
+};
+
+/** A reference column's entity value in each row: the f64 at the row's start, a reference's whole value. */
+const referencesOf = (column: Table.Column): ((row: number) => number) => {
+    if (column.kind !== "bytes") return () => 0;
+    const { bytes } = column;
+    if (bytes.byteOffset % 8 === 0 && column.stride % 8 === 0) {
+        const view = new Float64Array(bytes.buffer, bytes.byteOffset, bytes.byteLength >> 3);
+        const words = column.stride >> 3;
+        return row => view[row * words];
+    }
+    const view = new DataView(column.bytes.buffer, column.bytes.byteOffset, column.bytes.byteLength);
+    const { stride } = column;
+    return row => view.getFloat64(row * stride, true);
+};
+
+/** Copies a table's `rows`, or all of them, of one column into rows `start` on of a batch's column, remapping entities. */
+const copyColumn = (target: BatchColumn, column: Table.Column, schema: Schema | undefined, rows: readonly number[] | null, count: number, start: number, remap: Remap | null): void => {
+    const rowAt = (i: number): number => rows === null ? i : rows[i];
+    const remapped = remap !== null && schema !== undefined && holdsEntity(schema);
+    if (column.kind === "value") {
+        const write = writerOf(target, column.value);
+        const value = remapped ? remapValue(schema, column.value, remap) : column.value;
+        for (let i = 0; i < count; i++) write(start + i, value);
+        return;
+    }
+    if (column.kind === "bytes") {
+        const { stride } = target;
+        if (rows === null) target.views.u8.set(column.bytes, start * stride);
+        else for (let i = 0; i < count; i++) target.views.u8.set(column.bytes.subarray(rows[i] * stride, (rows[i] + 1) * stride), (start + i) * stride);
+        if (!remapped) return;
+        const { f64 } = target.views;
+        for (const leaf of entityLeavesOf(target.layout, schema)) {
+            for (let row = start, end = start + count; row < end; row++) {
+                const index = row * leaf.unitStride + leaf.unitOffset;
+                f64[index] = remap(f64[index]);
+            }
+        }
+        return;
+    }
+    if (target.remote !== null && column.values.some(value => value !== undefined && value !== null)) throw new Error(target.remote);
+    for (let i = 0; i < count; i++) {
+        const value = column.values[rowAt(i)];
+        target.values[start + i] = remapped ? remapValue(schema, value, remap) : value;
+    }
+};
+
+/** Spawns `rows` of a plan's table, or all of them, with the components it holds but `removed`, as `entities`. */
+const spawnRows = (state: State, { table, keys, ids, shared }: Planned, rows: readonly number[] | null, removed: ReadonlySet<Key>, entities: Float64Array, remap: Remap | null): void => {
+    const kept = keys.flatMap((key, k) => removed.has(key) ? [] : [k]);
+    const batch = batchOf(state, kept.map(k => ids[k]), shared.length === 0 ? undefined : shared);
+    const start = openRows(batch, entities.length);
+    for (const k of kept) {
+        const target = batch.columns.find(column => column.id === ids[k]);
+        if (target === undefined || target.layout.kind === "constant") continue;
+        const column: Table.Column = Reflect.get(table.columns, keys[k]);
+        copyColumn(target, column, declarationOf(keys[k])?.type, rows, entities.length, start, remap);
+    }
+    claimRows(batch, entities);
+};
+
+/** Throws for an entity `existing` maps to that isn't alive in this world. */
+const checkExisting = (state: State, existing: ReadonlyMap<number, number>): void => {
+    for (const [source, target] of existing) {
+        if (locate(state.entities, target) < 0) throw new Error(`commands.spawnTables: entity ${source} is given as existing as entity ${target}, which isn't alive.`);
+    }
+};
+
+/**
+ * Spawns an entity for each row of `tables` into the batches of their components, as references would leave them had
+ * the entities outside the tables despawned: a row owned, directly or through others, by an entity outside them isn't
+ * spawned; a weak reference to one is removed; and any other entity value naming one is `Entity.none`. Every entity
+ * value naming an entity spawned names the one spawned for it. A row whose entity `existing` maps isn't spawned: the
+ * entity it maps to stands for it, as it does for an entity outside the tables that `existing` maps.
+ */
+export const spawnTables = (state: State, tables: readonly Table[], existing: ReadonlyMap<number, number> = new Map()): Table.Spawned => {
+    const plans = tables.map(table => planOf(state, table));
+    checkExisting(state, existing);
+    // Entities are mapped only where a value of the tables may hold one, or a row is one that exists.
+    const remapping = existing.size > 0 || plans.some(({ keys }) => keys.some(key => {
+        const schema = declarationOf(key)?.type;
+        return schema !== undefined && holdsEntity(schema);
+    }));
+    const none: ReadonlySet<Key> = new Set();
+    if (!remapping) {
+        const entities = plans.map(({ table }) => {
+            const spawned = new Float64Array(table.count);
+            reserveRun(state.entities, spawned);
+            return spawned;
+        });
+        plans.forEach((plan, t) => spawnRows(state, plan, null, none, entities[t], null));
+        return { entities, dropped: 0 };
+    }
+    const places = placesOf(plans);
+    const positionOf = (entity: number): number => {
+        const index = indexOf(entity);
+        return entity !== 0 && index < places.entities.length && places.entities[index] === entity ? places.positions[index] : -1;
+    };
+    const firsts: number[] = [];
+    let total = 0;
+    for (const { table } of plans) {
+        firsts.push(total);
+        total += table.count;
+    }
+    // The entity standing for each row `existing` maps, 0 for a row spawned.
+    const existingAt = new Float64Array(total);
+    if (existing.size > 0) plans.forEach(({ table }, t) => {
+        for (let row = 0; row < table.count; row++) existingAt[firsts[t] + row] = existing.get(table.entities[row]) ?? 0;
+    });
+    // A row owned by an entity outside the tables isn't spawned, nor anything it owns, as despawning its owner would.
+    const dropped = new Uint8Array(total);
+    const waiting: number[] = [];
+    /**
+     * Calls `each` with each owner reference of a row that doesn't exist: the owned row's position, its owner's among
+     * the tables' rows or -1 for an owner outside them, and the owner.
+     */
+    const forEachOwner = (each: (position: number, at: number, owner: number) => void): void => plans.forEach(({ table, keys }, t) => {
+        for (const key of keys) {
+            if (declarationOf(key)?.reference !== "owner") continue;
+            const ownerAt = referencesOf(Reflect.get(table.columns, key));
+            for (let row = 0; row < table.count; row++) {
+                const owner = ownerAt(row);
+                const position = firsts[t] + row;
+                // A row that exists stands, whatever owns it.
+                if (owner !== 0 && existingAt[position] === 0) each(position, positionOf(owner), owner);
+            }
+        }
+    });
+    forEachOwner((position, at, owner) => {
+        if (at >= 0 || dropped[position] !== 0 || existing.has(owner)) return;
+        dropped[position] = 1;
+        waiting.push(position);
+    });
+    if (waiting.length > 0) {
+        const owned = new Map<number, number[]>();
+        forEachOwner((position, at) => {
+            if (at < 0) return;
+            const list = owned.get(at);
+            if (list === undefined) owned.set(at, [position]);
+            else list.push(position);
+        });
+        for (let next = waiting.pop(); next !== undefined; next = waiting.pop()) {
+            for (const child of owned.get(next) ?? []) {
+                if (dropped[child] !== 0 || existingAt[child] !== 0) continue;
+                dropped[child] = 1;
+                waiting.push(child);
+            }
+        }
+    }
+    // Each row's entity in this world: the one spawned for it, the one existing for it, or 0 for one dropped.
+    const spawnedAt = new Float64Array(total);
+    /** By table, whether every row of it is spawned: none exists or is dropped. */
+    const wholly: boolean[] = [];
+    const entities = plans.map(({ table }, t) => {
+        const first = firsts[t];
+        const spawned = new Float64Array(table.count);
+        let standing = 0;
+        for (let row = 0; row < table.count; row++) if (existingAt[first + row] !== 0 || dropped[first + row] !== 0) standing++;
+        wholly.push(standing === 0);
+        if (standing === 0) {
+            reserveRun(state.entities, spawned);
+            spawnedAt.set(spawned, first);
+            return spawned;
+        }
+        const alive = [];
+        for (let row = 0; row < table.count; row++) {
+            const position = first + row;
+            if (existingAt[position] !== 0) spawnedAt[position] = spawned[row] = existingAt[position];
+            else if (dropped[position] === 0) alive.push(row);
+        }
+        const reserved = new Float64Array(alive.length);
+        reserveRun(state.entities, reserved);
+        alive.forEach((row, i) => {
+            spawned[row] = reserved[i];
+            spawnedAt[first + row] = reserved[i];
+        });
+        return spawned;
+    });
+    /** The entity in this world for one of the tables' or one `existing` maps, or 0 for one that isn't there. */
+    const entityFor = (entity: number): number => {
+        const at = positionOf(entity);
+        return at >= 0 ? spawnedAt[at] : existing.get(entity) ?? 0;
+    };
+    const isSpawned = (entity: number): boolean => entityFor(entity) !== 0;
+    const remap: Remap = entityFor;
+    let droppedCount = 0;
+    plans.forEach((plan, t) => {
+        const { table, keys } = plan;
+        const first = firsts[t];
+        const weak = keys.filter(key => declarationOf(key)?.reference === "weak").map(key => ({ key, targetAt: referencesOf(Reflect.get(table.columns, key)) }));
+        const loses = (row: number): boolean => weak.some(({ targetAt }) => {
+            const target = targetAt(row);
+            return target !== 0 && !isSpawned(target);
+        });
+        let whole = wholly[t];
+        if (weak.length > 0) for (let row = 0; row < table.count && whole; row++) if (loses(row)) whole = false;
+        if (whole) return spawnRows(state, plan, null, none, entities[t], remap);
+        // Rows by the weak references they lose, whose targets aren't spawned: each set of components a batch of its own.
+        const groups = new Map<string, { readonly removed: Set<Key>; readonly rows: number[] }>();
+        for (let row = 0; row < table.count; row++) {
+            if (existingAt[first + row] !== 0) continue;
+            if (dropped[first + row] !== 0) {
+                droppedCount++;
+                continue;
+            }
+            const removed = weak.filter(({ targetAt }) => {
+                const target = targetAt(row);
+                return target !== 0 && !isSpawned(target);
+            }).map(({ key }) => key);
+            const signature = removed.map(key => weak.findIndex(entry => entry.key === key)).join(",");
+            let group = groups.get(signature);
+            if (group === undefined) groups.set(signature, group = { removed: new Set(removed), rows: [] });
+            group.rows.push(row);
+        }
+        for (const { removed, rows } of groups.values()) spawnRows(state, plan, rows, removed, Float64Array.from(rows, row => entities[t][row]), remap);
+    });
+    return { entities, dropped: droppedCount };
+};

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

@@ -75,7 +75,7 @@ describe("tails", () => {
         const { world, remote } = await joined({ loop: driver }, { [always]: true });
         await world.run(seed, { count: 10 });
         const counters: number[] = [];
-        const values = System.create({ observer: true }, ({ resources }) => { counters.push(resources[counter]); });
+        const values = System.create({ readonly: true }, ({ resources }) => { counters.push(resources[counter]); });
         world.add(ticked);
         world.add(values);
         await until(Observe.resource(world, counter), value => value >= 5);

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

@@ -24,8 +24,8 @@ const remove = System.create({ target: "entity", components: { with: [tagged] }
 });
 let amounts: number[] = [];
 let changed: number[] = [];
-const readAmounts = System.create({ observer: true, components: { with: [amount] } }, row => { amounts.push(row[amount]); });
-const watchChanged = System.create({ observer: true, components: { with: [amount], changed: [amount] } }, row => { changed.push(row[amount]); });
+const readAmounts = System.create({ readonly: true, components: { with: [amount] } }, row => { amounts.push(row[amount]); });
+const watchChanged = System.create({ readonly: true, components: { with: [amount], changed: [amount] } }, row => { changed.push(row[amount]); });
 
 const inline = () => createWorld({ [workers]: 0 });
 const amountsOf = async (world: ReturnType<typeof inline>): Promise<number[]> => {

package/src/implementation/world/thread-observer.ts

@@ -69,7 +69,7 @@ const errorOf = (error: unknown): WorkerError =>
 
 const refuse = (): never => { throw new Error("An observer system issues no commands."); };
 /** An observer system's context has no commands, so these are never called. */
-const noCommands: Commands = { spawn: refuse, despawn: refuse, add: refuse, remove: refuse };
+const noCommands: Commands = { spawn: refuse, despawn: refuse, despawnWhere: refuse, add: refuse, remove: refuse, spawnTables: refuse };
 const noStamps: number[] = [];
 
 export const createThreadObserver = (host: ThreadObserverHost) => {

package/src/implementation/world/thread-systems.test-helper.ts

@@ -172,7 +172,7 @@ const reading: { entities: readonly Entity[]; objects: readonly { readonly [name
 
 /** Each entity's objects of the thread, as data, a note by its text: none for an entity that's dead or has no uid. */
 const readObjects = System.create({
-    observer: true,
+    readonly: true,
     lookup: { ids: { with: [uid] }, captions: { with: [caption] }, notes: { with: [note] } },
 }, ({ lookup }) => {
     reading.objects = reading.entities.map(entity => {
@@ -322,9 +322,9 @@ export const paintReader = System.create(({ resources }) => () => resources[pain
 /** A composite of systems on the thread returning values, which no run resolves to. */
 export const paintsTogether = System.create([paintReader, paintLengthThere]);
 /** An observer system on the thread, as it reads the thread's paint: what a run of it resolves to. */
-export const paintObserved = System.create({ observer: true }, ({ resources }) => resources[paint].text);
+export const paintObserved = System.create({ readonly: true }, ({ resources }) => resources[paint].text);
 /** An observer system on the thread, throwing there. */
-export const paintObservedFails = System.create({ observer: true }, ({ resources }) => {
+export const paintObservedFails = System.create({ readonly: true }, ({ resources }) => {
     if (resources[paint].text !== "never") throw new Error("threadSystemsTest observer failure there");
     return 0;
 });

package/src/implementation/world/thread-systems.ts

@@ -279,6 +279,8 @@ export const createThreadSystems = (host: ThreadSystemsHost) => {
             return typeof preset === "object" && preset !== null ? presetSpawnerOf(components, preset) : spawnerOf(components);
         },
         despawn: entity => beginCommand(writer, despawnCommand, entity),
+        spawnTables: () => { throw new Error("commands.spawnTables runs on the world's thread: run the system there."); },
+        despawnWhere: () => { throw new Error("commands.despawnWhere runs on the world's thread: run the system there."); },
         add: (entity: number, components: symbol | readonly symbol[], values?: unknown) => {
             if (typeof components === "symbol") {
                 const key = givenKeyOf(components);
@@ -989,18 +991,19 @@ export const createThreadRunner = (host: RunnerHost, leaf: Leaf, records: Readon
         const row = bindRow(archetype);
         const subject = row.value;
         const input = runInput;
+        const { body } = system;
         const filters = filtersOf(archetype);
         if (since < 0 || filters.length === 0) {
             for (let index = 0; index < count; index++) {
                 row.index = index;
-                system.body(subject, value, input);
+                body(subject, value, input);
             }
             return;
         }
         forEachPassingRange(filters, since, 0, count, (start, end) => {
             for (let index = start; index < end; index++) {
                 row.index = index;
-                system.body(subject, value, input);
+                body(subject, value, input);
             }
         });
     };
@@ -1102,18 +1105,19 @@ export const createThreadRunner = (host: RunnerHost, leaf: Leaf, records: Readon
         const row = bindRow(archetype);
         const subject = row.value;
         const input = runInput;
+        const { body } = system;
         const filters = filtersOf(archetype);
         if (since < 0 || filters.length === 0) {
             for (let index = start; index < end && !halted; index++) {
                 row.index = index;
-                system.body(subject, tailValue, input);
+                body(subject, tailValue, input);
             }
             return;
         }
         forEachPassingRange(filters, since, start, end, (first, last) => {
             for (let index = first; index < last && !halted; index++) {
                 row.index = index;
-                system.body(subject, tailValue, input);
+                body(subject, tailValue, input);
             }
         });
     };
@@ -1232,6 +1236,7 @@ export const createThreadRunner = (host: RunnerHost, leaf: Leaf, records: Readon
         const copied = (storages: readonly (ThreadStorage | undefined)[]): ThreadArchetype =>
             ({ id: -1, entities, storageById: storages, record: -1, version: -1, mirrored: null, components: [], resource: false, reclaimed: false, generation: 0 });
         const ownedInput = runInput;
+        const { body } = system;
         try {
             if (optionalNumbers.length === 0 && sharedReads.length === 0) {
                 const row = bindRow(copied(storageById));
@@ -1239,7 +1244,7 @@ export const createThreadRunner = (host: RunnerHost, leaf: Leaf, records: Readon
                 for (let index = first; index < rows && !halted; index++) {
                     if (skipped !== null && skipped.has(archetypeIds[index])) continue;
                     row.index = index;
-                    system.body(subject, tailValue, ownedInput);
+                    body(subject, tailValue, ownedInput);
                 }
             }
             else {
@@ -1274,7 +1279,7 @@ export const createThreadRunner = (host: RunnerHost, leaf: Leaf, records: Readon
                     const subject = row.value;
                     for (; index < end && !halted; index++) {
                         row.index = index;
-                        system.body(subject, tailValue, ownedInput);
+                        body(subject, tailValue, ownedInput);
                     }
                 }
             }

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

@@ -190,7 +190,7 @@ describe("up", () => {
         expect(await read(ecs, entities.grandchild, world)).toBe(100);
     });
 
-    it("runs every row after a spawn outruns the journal, with change filters, then only the rows that changed", async () => {
+    it("runs every row after spawning more than a patch takes, with change filters, then only the rows that changed", async () => {
         await using ecs = createWorld({ [workers]: 0 });
         await ecs.run(spawn);
         await ecs.run(nest);
@@ -211,6 +211,18 @@ describe("up", () => {
         expect(ran).toEqual([]);
     });
 
+    it("runs only the rows spawned in bulk, which the journal holds once each, with change filters", async () => {
+        await using ecs = createWorld({ [workers]: 0 });
+        await ecs.run(spawn);
+        await ecs.run(nest);
+        await ecs.run(propagateChanged);
+        await ecs.run(bulkUnder, { count: 3000 });
+        ran.length = 0;
+        await ecs.run(propagateChanged);
+        expect(ran.length).toBe(3000);
+        expect(await readEach(ecs, bulk.slice(0, 3), world)).toEqual([112, 112, 112]);
+    });
+
     it("finds a cycle a reparent closes after the tree was built, and runs its rows again once it opens", async () => {
         await using ecs = createWorld({ [workers]: 0 });
         await ecs.run(spawn);

package/src/implementation/world/up.ts

@@ -22,6 +22,9 @@ const cyclic = -1;
 const denseShare = 1 / 8;
 /** Rows below this many are sorted rather than scanned. */
 const denseMinimum = 4096;
+/** Past this many journal entries, and past this share of the matched rows, the tree is built again rather than patched. */
+const patchMinimum = 4096;
+const patchShare = 1 / 8;
 /** Sort keys pack a row with its parent's archetype: `(parent + 1) * rowLimit + row`. */
 const rowLimit = 2 ** 27;
 
@@ -375,7 +378,9 @@ const createShared = (state: State, through: number, read: readonly number[], ma
         const { journal } = state;
         const end = journalEnd(journal);
         if (position === end) return;
-        if (position < journal.first) {
+        let matched = 0;
+        for (let k = 0; k < matches.length; k++) matched += matches[k].count;
+        if (position < journal.first || end - position > Math.max(patchMinimum, matched * patchShare)) {
             build(matches);
             position = end;
             rebuiltAll();

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

@@ -62,10 +62,10 @@ export const noteInView = System.create({ components: { with: [position, note],
     row[note] = { text: `${row[position]}` };
 });
 const heard: number[] = [];
-export const hearInView = System.create({ observer: true, components: { with: [position], changed: [position], where: { [cell]: (at, { resources }) => visible(at, resources[camera].x, resources[camera].radius) } } }, row => { heard.push(row[position]); });
+export const hearInView = System.create({ readonly: true, components: { with: [position], changed: [position], where: { [cell]: (at, { resources }) => visible(at, resources[camera].x, resources[camera].radius) } } }, row => { heard.push(row[position]); });
 // Filtered by a resource the predicate doesn't read: a culled archetype coming into view catches up on its change.
 const signalled: number[] = [];
-export const signalInView = System.create({ observer: true, components: { with: [position], where: { [cell]: (at, { resources }) => visible(at, resources[camera].x, resources[camera].radius) } }, resources: { changed: [other] } }, row => { signalled.push(row[position]); });
+export const signalInView = System.create({ readonly: true, components: { with: [position], where: { [cell]: (at, { resources }) => visible(at, resources[camera].x, resources[camera].radius) } }, resources: { changed: [other] } }, row => { signalled.push(row[position]); });
 // A system moving the camera its own predicate reads: its next run sees the new view.
 const followed: number[] = [];
 export const follow = System.create({ components: { with: [position], where: { [cell]: (at, { resources }) => visible(at, resources[camera].x, resources[camera].radius) } } }, (row, { resources }) => {
@@ -79,7 +79,7 @@ export const noteChanged = System.create({ components: { with: [position, note],
     row[note] = { text: `${row[position]}` };
 });
 const notes: string[] = [];
-export const readNotes = System.create({ observer: true, components: { with: [note] } }, row => { if (row[note] !== null) notes.push(row[note].text); });
+export const readNotes = System.create({ readonly: true, components: { with: [note] } }, row => { if (row[note] !== null) notes.push(row[note].text); });
 export const nudgeNoted = System.create({ components: { with: [position, note] } }, row => { row[position] += 0.5; });
 
 /** Waits a turn at a time until `done`, for two seconds at most. */
@@ -91,7 +91,7 @@ const until = async (done: () => boolean): Promise<void> => {
 /** Every row's position and how often it was seen, by position. */
 const seenOf = async (world: ReturnType<typeof createWorld>): Promise<readonly string[]> => {
     const read: [number, string][] = [];
-    await world.run(System.create({ observer: true, components: { with: [position, seen] } }, row => { read.push([row[position], `${row[position]}:${row[seen]}`]); }));
+    await world.run(System.create({ readonly: true, components: { with: [position, seen] } }, row => { read.push([row[position], `${row[position]}:${row[seen]}`]); }));
     return read.sort((a, b) => a[0] - b[0]).map(([, text]) => text).filter(text => !text.endsWith(":0"));
 };
 

package/src/implementation/world/where.ts

@@ -115,22 +115,50 @@ const predicateOf = (given: unknown): ((value: unknown, context: object) => unkn
     typeof given === "function" ? (value, context) => Reflect.apply(given, undefined, [value, context]) : null;
 
 /**
- * A system's `where` in a world: its values interned there, by number, its predicates' context reading `reads`,
- * evaluated again once one of them changed since they last were.
+ * `where`'s conditions in a world, each value interned there, by number, and with `pinned`, pinned, so its number stays
+ * while no archetype holds it and one that comes to hold it again matches; or the key of a component that isn't shared.
+ * A value interned unpinned keeps its number to the end of the sync point.
  */
-export const createWhere = <A extends Valued>(state: State, where: { readonly [key: symbol]: unknown }, reads: readonly symbol[], leaf: Leaf): Where<A> => {
-    const conditions: Condition[] = Object.getOwnPropertySymbols(where).map(key => {
+const conditionsOf = (state: State, where: { readonly [key: symbol]: unknown }, pinned: boolean): Condition[] | symbol => {
+    const conditions: Condition[] = [];
+    for (const key of Object.getOwnPropertySymbols(where)) {
         const id = idOf(state, key);
         const given: unknown = Reflect.get(where, key);
         const predicate = predicateOf(given);
-        if (predicate !== null) return { id, number: -1, predicate };
+        if (predicate !== null) {
+            conditions.push({ id, number: -1, predicate });
+            continue;
+        }
         const values = state.shared[id];
-        if (values === undefined) throw new Error(`System "${leaf.name}": where names "${labelOf(key)}", which isn't a shared component.`);
+        if (values === undefined) return key;
         const number = internShared(values, given);
-        // Pinned, so its number stays while no archetype holds it: one that comes to hold it again matches.
-        if (number >= 0) holdShared(values, number);
-        return { id, number, predicate: null };
-    });
+        if (pinned && number >= 0) holdShared(values, number);
+        conditions.push({ id, number, predicate: null });
+    }
+    return conditions;
+};
+
+/**
+ * Whether an archetype holds each of `where`'s values, as a system's `where` of values passes it, for a `where` naming
+ * only shared components and giving no predicate; or the key of one that isn't shared. Its values are pinned with
+ * `pinned`, and otherwise only interned, for a `where` used before the sync point ends.
+ */
+export const holdsValuesOf = (state: State, where: { readonly [key: symbol]: unknown }, pinned: boolean): ((archetype: Valued) => boolean) | symbol => {
+    const conditions = conditionsOf(state, where, pinned);
+    if (typeof conditions === "symbol") return conditions;
+    return archetype => {
+        for (let c = 0; c < conditions.length; c++) if (archetype.shared[conditions[c].id] !== conditions[c].number) return false;
+        return true;
+    };
+};
+
+/**
+ * A system's `where` in a world: its values interned there, by number, its predicates' context reading `reads`,
+ * evaluated again once one of them changed since they last were.
+ */
+export const createWhere = <A extends Valued>(state: State, where: { readonly [key: symbol]: unknown }, reads: readonly symbol[], leaf: Leaf): Where<A> => {
+    const conditions = conditionsOf(state, where, true);
+    if (typeof conditions === "symbol") throw new Error(`System "${leaf.name}": where names "${labelOf(conditions)}", which isn't a shared component.`);
     const readIds = reads.map(key => idOf(state, key));
     // Its predicates' context: each resource read once per evaluation, since a struct's read copies it out.
     const cached: unknown[] = reads.map(() => undefined);