@adobe/ecs 0.2.1 → 0.2.3

package/src/implementation/compiler/plugin.test.ts

@@ -645,7 +645,7 @@ export { World as OtherWorld };
 export const runOther = async (key) => {
     const spawn = System.create(({ commands }) => { commands.spawn([key].slice())({ [key]: 10 }); });
     let total = 0;
-    const count = System.create({ observer: true, components: { with: [key] } }, (row) => { total += row[key]; });
+    const count = System.create({ readonly: true, components: { with: [key] } }, (row) => { total += row[key]; });
     const world = World.create();
     await world.run(spawn);
     await world.run(spawn);
@@ -662,7 +662,7 @@ declare$(score, "component", { type: { type: "number" } });
 ${recorder}
 const spawn = System.create(({ commands }) => { commands.spawn([score].slice())({ [score]: 1 }); });
 let counted = 0;
-const count = System.create({ observer: true, components: { with: [score] } }, (row) => { counted += row[score]; });
+const count = System.create({ readonly: true, components: { with: [score] } }, (row) => { counted += row[score]; });
 export const copies = World === OtherWorld ? 1 : 2;
 export const run = async () => {
     const world = World.create();

package/src/implementation/compiler/signature.ts

@@ -120,7 +120,7 @@ export const kernelOf = (declaration: ObjectExpression): KernelRequest | null =>
         }
     }
     if (declaration.properties.some(property => property.type === "SpreadElement")) return null;
-    if (!declares(declaration, "components") || declares(declaration, "observer") || declares(declaration, "target")) return null;
+    if (!declares(declaration, "components") || declares(declaration, "readonly") || declares(declaration, "target")) return null;
     return { target: "cpu", required: false };
 };
 

package/src/implementation/compiler/transform.test.ts

@@ -335,7 +335,7 @@ describe("kernels by default", () => {
     test("runs as written, without failing, a body that leaves the subset or a declaration a kernel can't have", async () => {
         expect(await attached(`const log = []; const kernel = System.create({ components: { with: [mass] } }, row => { log.push(row[mass]); });`)).toBe(false);
         expect(await attached(`const kernel = System.create({ components: { with: [mass] } }, (row, { resources }) => { resources[delta] = row[mass]; });`)).toBe(false);
-        expect(await attached(`const kernel = System.create({ observer: true, components: { with: [mass] } }, row => { void row[mass]; });`)).toBe(false);
+        expect(await attached(`const kernel = System.create({ readonly: true, components: { with: [mass] } }, row => { void row[mass]; });`)).toBe(false);
         expect(await attached(`const kernel = System.create({ target: "entity", components: { with: [score] } }, row => { row[score] = 1; });`)).toBe(false);
         expect(await attached(`const make = () => System.create({ components: { with: [score] } }, row => { row[score] = 1; });`)).toBe(false);
     });
@@ -1418,11 +1418,11 @@ describe("inferred access", () => {
     });
 
     test("an observer's row it can't follow as unknown without a warning, since the world takes an observer's as read", async () => {
-        const result = await transform(system("observer: true, components: { with: [position] }", "(row) => { helper(row); }"));
+        const result = await transform(system("readonly: true, components: { with: [position] }", "(row) => { helper(row); }"));
         expect(result !== null && "code" in result ? [result.code.includes("components: null"), result.warnings] : null).toEqual([true, []]);
     });
 
-    test("a row it can't follow with a warning unless the declaration says observer: true, as the world reads it", async () => {
+    test("a row it can't follow with a warning unless the declaration says readonly: true, as the world reads it", async () => {
         for (const observer of ["observer: false, ", "observer: watching, "]) {
             const result = await transform(`const watching = true;\n${system(`${observer}components: { with: [position] }`, "(row) => { helper(row); }")}`);
             expect(result !== null && "code" in result ? result.warnings.length : null).toBe(1);

package/src/implementation/compiler/transform.ts

@@ -141,7 +141,7 @@ export const functionOf = (binding: ModuleBinding | undefined): Node | undefined
 const empty: ObjectExpression = { type: "ObjectExpression", properties: [], start: 0, end: 0 };
 
 /** Whether a declaration has property `name`, written out. */
-/** Whether a declaration gives `name` the literal `true`, as the world takes `observer`. */
+/** Whether a declaration gives `name` the literal `true`, as the world takes `readonly`. */
 const declaresTrue = (declaration: ObjectExpression, name: string): boolean => declaration.properties.some(property =>
     property.type === "Property" && !property.computed && property.key.type === "Identifier" && property.key.name === name
     && property.value.type === "Literal" && property.value.value === true);
@@ -313,9 +313,9 @@ export const transformKernels = async (
             const used = kernel?.used ?? inOrder(usedBy(declared, body, module.bindings, positions), declared);
             requireRequired(used, declared, body);
             const where = at(body);
-            // An observer's row, and a lookup's rows, it can't follow are taken as read whole, which is what their
+            // A readonly system's row, and a lookup's rows, it can't follow are taken as read whole, which is what their
             // declarations already say; only a row taken as written whole costs what the author should know of.
-            if (used.query === null && !declaresTrue(declared, "observer")) warnings.push(`${where}: the build can't follow how this body uses its row, so it takes every component in with, added and changed as written: index the row by key directly, or destructure it by key, to let it tell what the body reads and writes.`);
+            if (used.query === null && !declaresTrue(declared, "readonly")) warnings.push(`${where}: the build can't follow how this body uses its row, so it takes every component in with, added and changed as written: index the row by key directly, or destructure it by key, to let it tell what the body reads and writes.`);
             accessing = true;
             const access = accessText(used, where, whereReads.has(node) ? whereReads.get(node) ?? null : undefined);
             if (kernel !== undefined) {

package/src/implementation/world/change-blocks.test.ts

@@ -89,7 +89,7 @@ const setGroup = System.create({ target: "entity", components: { with: [group] }
 // Readers.
 let found: number[] = [];
 const onMain = System.create({ components: { with: [at], changed: [value] } }, row => { found.push(row[at]); });
-const observed = System.create({ observer: true, components: { with: [at], changed: [value] } }, row => { found.push(row[at]); });
+const observed = System.create({ readonly: true, components: { with: [at], changed: [value] } }, row => { found.push(row[at]); });
 const ofTwo = System.create({ components: { with: [at], changed: [group, value] } }, row => { found.push(row[at]); });
 const inKernel = System.create({ kernel: true, components: { with: [seen], changed: [value] } }, row => { row[seen] += 1; });
 const inUp = System.create({ components: { with: [at], changed: [value] }, up: { through: parent } }, row => { found.push(row[at]); });

package/src/implementation/world/commands.ts

@@ -1,8 +1,12 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Commands } from '../../interface/system/commands.js';
-import { addCommand, despawnCommand, pushCommand, pushComponent, removeCommand, type CommandBuffer } from './buffer.js';
+import { addCommand, createBuffer, despawnCommand, pushCommand, pushComponent, removeCommand, spawnCommand, type CommandBuffer } from './buffer.js';
+import { reserve } from './entities.js';
 import { listShapeOf, presetSpawnerOf, spawnerOf, type ListShape } from './lists.js';
 import { commandIdOf, idOf, storedShared, type Key, type State } from './state.js';
+import { spawnTables } from './tables.js';
+import { declarationOf, isWorldWritten, kindOf, labelOf, threadOfDeclaration, whyUnregistered } from '../../interface/registry/index.js';
+import { matchesSchema } from '../../interface/registry/schemas.js';
 
 const collect = (state: State, buffer: CommandBuffer, key: Key, value: unknown): void => {
     if (value !== undefined) pushComponent(buffer, idOf(state, key), value);
@@ -44,6 +48,38 @@ const addShared = (state: State, buffer: CommandBuffer, entity: number, shape: L
     for (let k = 0; k < keys.length; k++) pushComponent(buffer, ids[k], values[k]);
 };
 
+/**
+ * Throws for a key of `resources` that isn't a resource, is one only the world writes or one living on another thread,
+ * or is given a value its schema doesn't take.
+ */
+const checkResources = (resources: object): void => {
+    for (const key of Object.getOwnPropertySymbols(resources)) {
+        const fail = (message: string): never => { throw new Error(`commands.spawnTables: "${labelOf(key)}" ${message}.`); };
+        if (kindOf(key) !== "resource") fail(`isn't a registered resource: ${whyUnregistered(key)}`);
+        if (isWorldWritten(key)) fail("is written only by the world");
+        const declaration = declarationOf(key);
+        if (declaration === undefined) continue;
+        const thread = threadOfDeclaration(declaration);
+        if (thread !== null && thread !== "world") fail(`lives on thread "${thread}", not the world's`);
+        if (declaration.type !== undefined && !matchesSchema(declaration.type, Reflect.get(resources, key))) fail("is given a value its type doesn't take");
+    }
+};
+
+/**
+ * Queues `resources`' values for the sync point as the world's own change to its resource entity, which it reserves
+ * when the world has none yet: a buffer of their own, since the sync point skips systems' commands to that entity.
+ */
+const queueResources = (state: State, resources: object): void => {
+    if (Object.getOwnPropertySymbols(resources).length === 0) return;
+    const buffer = createBuffer();
+    if (state.resourceEntity < 0) {
+        state.resourceEntity = reserve(state.entities);
+        pushValues(state, buffer, spawnCommand, state.resourceEntity, resources);
+    }
+    else pushValues(state, buffer, addCommand, state.resourceEntity, resources);
+    state.queued.push({ buffer, guarded: false });
+};
+
 /** Values of a list add given none, which only an untyped caller does. */
 const empty = {};
 
@@ -83,6 +119,13 @@ export const createCommands = (state: State, target: { readonly buffer: CommandB
             pushComponent(buffer, ids[k], value === undefined ? starts[k] : value);
         }
     },
+    spawnTables: (tables, resources) => {
+        if (resources === undefined) return spawnTables(state, tables);
+        checkResources(resources);
+        const spawned = spawnTables(state, tables);
+        queueResources(state, resources);
+        return spawned;
+    },
     remove: (entity: number, components: symbol | readonly symbol[]) => {
         const { buffer } = target;
         if (typeof components === "symbol") {

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

@@ -56,7 +56,7 @@ describe("a derived component declared without a default", () => {
             commands.spawn([tagged])({});
         });
         const seen: unknown[] = [];
-        const read = System.create({ observer: true, components: { with: [index] } }, row => { seen.push(row[index]); });
+        const read = System.create({ readonly: true, components: { with: [index] } }, row => { seen.push(row[index]); });
         await using first = createWorld();
         await using second = createWorld();
         for (const world of [first, second]) {

package/src/implementation/world/entities.ts

@@ -70,6 +70,12 @@ export const createEntities = (memory: Memory): Entities => {
 /** Reserves an entity. Safe to call from any thread between sync points. */
 export const reserve = ({ cursor, free, generation }: Reservations): Entity => entityAt(cursor, free, generation, Atomics.add(cursor, taken, 1));
 
+/** Reserves an entity for each of `into`'s elements, with one atomic add. Safe to call from any thread between sync points. */
+export const reserveRun = ({ cursor, free, generation }: Reservations, into: Float64Array): void => {
+    const first = Atomics.add(cursor, taken, into.length);
+    for (let i = 0; i < into.length; i++) into[i] = entityAt(cursor, free, generation, first + i);
+};
+
 /**
  * Reservations a thread takes in blocks of positions, so threads spawning together don't contend for the cursor.
  * Positions a block leaves unused are reserved entities that never spawn, which the sync point releases.

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

@@ -137,7 +137,7 @@ describe("finalizers", () => {
         const reads = System.create({}, ({ resources }) => { void resources[level]; });
         // Read after every run, as a read through a run of its own would apply the commands left for it.
         let seen: string | null = null;
-        const watch = System.create({ observer: true, lookup: { labels: { with: [label] } } }, ({ lookup }) => {
+        const watch = System.create({ readonly: true, lookup: { labels: { with: [label] } } }, ({ lookup }) => {
             seen = lookup.labels(other)?.[label] ?? null;
         });
         const world = createWorld({ [workers]: 0 });

package/src/implementation/world/index-changed.test.ts

@@ -109,7 +109,7 @@ describe("an index lookup's changed: true", () => {
         await using world = inline();
         spawned = [];
         const orders: string[] = [];
-        const ordering = System.create({ observer: true, lookup: { inOrder: { index: inOrder, changed: true } } }, ({ lookup }) => {
+        const ordering = System.create({ readonly: true, lookup: { inOrder: { index: inOrder, changed: true } } }, ({ lookup }) => {
             const all = lookup.inOrder();
             const groups: number[] = [];
             for (let i = 0; i < all.length; i++) groups.push(all.at(i).entity === spawned[0] ? -1 : 0);
@@ -205,7 +205,7 @@ describe("an index lookup's changed: true", () => {
         await using world = inline();
         spawned = [];
         const totals: number[] = [];
-        const readTotals = System.create({ observer: true, components: { with: [total] } }, row => {
+        const readTotals = System.create({ readonly: true, components: { with: [total] } }, row => {
             totals.push(row[total]);
         });
         const totalsOf = async (): Promise<number[]> => {

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

@@ -87,7 +87,7 @@ const stirBands = System.create({ components: { with: [serial, band] } }, (row,
 /** An observer system of the joined thread's labels: the serials of each reader's band, in entity order, by reader. */
 let observedBands: string[] = [];
 const observeBands = System.create({
-    observer: true,
+    readonly: true,
     components: { with: [target, bandReader, label] },
     lookup: { inBand: { index: bands } },
 }, (row, { lookup }) => {
@@ -219,14 +219,14 @@ const inOrder = System.create({ components: { with: [rank, label] }, order: rank
 const countWhenMoved = System.create({ components: { with: [cell, label] }, lookup: { near: { index: grid, changed: true } } }, (row, { lookup }) => {
     row[label] = { text: String(lookup.near(row[cell]).length) };
 });
-const readWhenMoved = System.create({ observer: true, components: { with: [label] }, lookup: { near: { index: grid, changed: true } } }, row => {
+const readWhenMoved = System.create({ readonly: true, components: { with: [label] }, lookup: { near: { index: grid, changed: true } } }, row => {
     void row[label];
 });
-const ownWhenMoved = System.create({ observer: true, lookup: { near: { index: grid, changed: true } } }, () => {});
+const ownWhenMoved = System.create({ readonly: true, lookup: { near: { index: grid, changed: true } } }, () => {});
 
 /** The entities `readLabels` reads, and their labels. */
 const reading: { entities: readonly Entity[]; labels: readonly string[] } = { entities: [], labels: [] };
-const readLabels = System.create({ observer: true, lookup: { labeled: { with: [label] } } }, ({ lookup }) => {
+const readLabels = System.create({ readonly: true, lookup: { labeled: { with: [label] } } }, ({ lookup }) => {
     reading.labels = reading.entities.map(entity => lookup.labeled(entity)?.[label].text ?? "missing");
 });
 
@@ -279,7 +279,7 @@ const heldSerials = Index.create({ key: [serial], unique: true, components: { wi
 let observedHeld = "";
 /** An observer system reading every held row through the keyless index, and serial 3's through the unique one. */
 const observeHeld = System.create({
-    observer: true,
+    readonly: true,
     lookup: { all: { index: held }, bySerial: { index: heldSerials } },
 }, ({ lookup }) => {
     const all = lookup.all();

package/src/implementation/world/index-order.test.ts

@@ -72,7 +72,7 @@ const expected = async (world: CreatedWorld, only?: (weighed: number) => boolean
 };
 
 const markerValues: number[] = [];
-const readMarkers = System.create({ observer: true, components: { with: [marker] } }, row => { markerValues.push(row[marker]); });
+const readMarkers = System.create({ readonly: true, components: { with: [marker] } }, row => { markerValues.push(row[marker]); });
 
 /** Markers' values in the order they were spawned: their archetype's rows', in storage order. */
 const markers = async (world: CreatedWorld): Promise<number[]> => {

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

@@ -57,16 +57,16 @@ const idle = System.create({}, () => {});
 const totalPlus = System.create({}, ({ resources }, input: { readonly plus: number }) => resources[total] + input.plus);
 const described = System.create(({ resources }) => ({ total: resources[total], names: resources[names] }));
 const unpostable = System.create(() => () => "a function");
-const readTotal = System.create({ observer: true }, ({ resources }) => resources[total]);
+const readTotal = System.create({ readonly: true }, ({ resources }) => resources[total]);
 /** Writes levels, an object of joinTestAudio, so it runs on the thread claiming it. */
 const mix = System.create({}, ({ resources }, input: { readonly level: number }) => {
     resources[levels] = [...resources[levels], input.level];
 });
 /** An observer system recording each total it reads into `into`. */
-const totalsInto = (into: number[]) => System.create({ observer: true }, ({ resources }) => { into.push(resources[total]); });
+const totalsInto = (into: number[]) => System.create({ readonly: true }, ({ resources }) => { into.push(resources[total]); });
 /** An observer system recording how many levels it reads into `into`. */
-const levelsInto = (into: number[]) => System.create({ observer: true }, ({ resources }) => { into.push(resources[levels].length); });
-const failingRead = System.create({ observer: true }, () => { throw new Error("joinTest read failure"); });
+const levelsInto = (into: number[]) => System.create({ readonly: true }, ({ resources }) => { into.push(resources[levels].length); });
+const failingRead = System.create({ readonly: true }, () => { throw new Error("joinTest read failure"); });
 
 /** A world shared with a thread joined through a channel, and the joined world, once both say it joined. */
 const joined = async (threads: readonly ("main")[] = []): Promise<{ readonly world: CreatedWorld; readonly remote: World; readonly channel: MessageChannel }> => {

package/src/implementation/world/join.ts

@@ -33,6 +33,12 @@ const observerLeavesOf = (definition: Definition): readonly Leaf[] | null => {
     return schedule.tiers.length === 0 && schedule.observer.length > 0 ? schedule.observer : null;
 };
 
+/** Throws for a readonly system reading tables, which only the world's thread gives. */
+const refuseTables = (leaves: readonly Leaf[]): void => {
+    const reading = leaves.find(leaf => leaf.declaration.tables !== undefined);
+    if (reading !== undefined) throw new Error(`System "${reading.name}" reads tables, which only the world's thread gives: run or add it there.`);
+};
+
 /** A run not yet settled: how to settle it, and its rejection once posted. */
 type Run = { readonly resolve: (value: unknown) => void; readonly reject: (error: unknown) => void; message: ToJoined | null; error: unknown; readonly local: Local | null };
 
@@ -659,6 +665,7 @@ export const joinWorld = (port: Parameters<World["share"]>[0], options: { readon
             // This thread's own observer systems run here, after the sync point of an empty run of the world's.
             const leaves = observerLeavesOf(definition);
             if (leaves !== null) {
+                refuseTables(leaves);
                 if (failure !== null) return Promise.reject(failure);
                 const locals = leaves.map(localOf);
                 if (locals.length === 1 && definition.kind !== "composite") return runNumbered(locals[0].number, locals[0].leaf, undefined, locals[0]);
@@ -680,7 +687,8 @@ export const joinWorld = (port: Parameters<World["share"]>[0], options: { readon
         add: system => {
             const definition = requireDefinition(system);
             const leaves = observerLeavesOf(definition);
-            if (leaves === null) throw new Error("A joined thread adds only observer systems; others are added to ticks on the world's thread.");
+            if (leaves === null) throw new Error(`System "${definition.name}" isn't readonly, and a joined thread adds only readonly systems: declare it readonly: true to read the world from this thread, or add it on the world's thread.`);
+            refuseTables(leaves);
             if (added.has(definition) || failure !== null) return;
             const locals = leaves.map(localOf);
             added.set(definition, locals);
@@ -692,7 +700,7 @@ export const joinWorld = (port: Parameters<World["share"]>[0], options: { readon
         },
         remove: system => {
             const definition = requireDefinition(system);
-            if (observerLeavesOf(definition) === null) throw new Error("A joined thread removes only observer systems; others are removed from ticks on the world's thread.");
+            if (observerLeavesOf(definition) === null) throw new Error(`System "${definition.name}" isn't readonly, and a joined thread removes only readonly systems: others are removed on the world's thread.`);
             const locals = added.get(definition);
             if (locals === undefined) return;
             added.delete(definition);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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