@adobe/ecs 0.2.1 → 0.2.4

package/src/interface/system/access.ts

@@ -27,6 +27,12 @@ export type ComponentAccess = {
      * change filters, an archetype it skipped keeps its rows unseen until it passes again.
      */
     readonly where?: { readonly [K in Shared]?: Component<K> | ((value: Component<K>, context: { readonly resources: ReadResources }) => boolean) };
+    /**
+     * Takes its row whole, as a body passing it on does, where the build can't follow how it's used: every member counts
+     * as written, for order, conflicts and placement, but references and shared components, which change only through
+     * commands, as read. Without it, a body whose row the build can't follow fails the build.
+     */
+    readonly whole?: true;
 };
 
 /**
@@ -85,6 +91,8 @@ export type ComponentLists = {
     readonly where?: { readonly [key: symbol]: unknown };
     /** The resources its `where`'s predicates read, which the build infers: when one changed, they're evaluated again. */
     readonly whereReads?: readonly Key[];
+    /** Whether it takes its row whole, as its declaration said. */
+    readonly whole?: true;
 };
 
 /** A lookup as the world takes it, with what its body reads of its rows in `read`. */
@@ -105,3 +113,11 @@ export type ResourceLists = {
     readonly is?: readonly Key[];
     readonly not?: readonly Key[];
 };
+
+/** The components a system's commands name, by kind, and whether it despawns, as the build inferred them. */
+export type CommandLists = {
+    readonly spawn?: readonly Key[];
+    readonly add?: readonly Key[];
+    readonly remove?: readonly Key[];
+    readonly despawn?: true;
+};

package/src/interface/system/body.ts

@@ -10,14 +10,15 @@ import type { Commands } from './commands.js';
 import type { Declaration } from './declaration.js';
 import type { Listed, Property } from './property.js';
 import type { RenderContext } from './render.js';
+import type { Tables } from './tables.js';
 import type { ComponentValues, LookupFunction, ResourceValues, Values } from './values.js';
 
 /** The components every entity a declaration matches has: those in `with`, `added` and `changed`. */
 export type Members<D> =
     | Listed<Property<D, "components">, "with"> | Listed<Property<D, "components">, "added"> | Listed<Property<D, "components">, "changed">;
 
-/** Whether a declaration only reads: an observer or a render system. */
-type Reading<D> = D extends { readonly observer: true } | { readonly shader: object } ? true : false;
+/** Whether a declaration only reads: one declared `readonly`, or a render system. */
+type Reading<D> = D extends { readonly readonly: true } | { readonly shader: object } ? true : false;
 
 /** The components a declaration's rows hold only where an entity has them. */
 export type Optional<D> = Exclude<Listed<Property<D, "components">, "optional">, Members<D>>;
@@ -51,8 +52,8 @@ type Is<D> = Listed<Property<D, "resources">, "is">;
 
 /**
  * What a body uses besides its row: every resource, its lookups by name, the resources it may reduce into, its
- * parent's values with `up`, and its commands, there for every system but a GPU kernel, a render system and an
- * observer system. The build infers which of them the body reads and writes.
+ * parent's values with `up`, and its commands, there for every system but a GPU kernel, a render system and one
+ * declared `readonly`. The build infers which of them the body reads and writes.
  */
 export type Context<D extends Declaration> =
     {
@@ -66,7 +67,8 @@ export type Context<D extends Declaration> =
         /** The parent's values the body reads, or null for a row without a parent or whose parent lacks one of them. */
         readonly up: ComponentValues | null;
     } : {})
-    & (D extends { readonly kernel: "gpu" } | { readonly shader: object } | { readonly observer: true } ? {} : { readonly commands: Commands });
+    & (D extends { readonly kernel: "gpu" } | { readonly shader: object } | { readonly readonly: true } ? {} : { readonly commands: Commands })
+    & (D extends { readonly tables: object } ? { readonly tables: Tables } : {});
 
 /**
  * `(row, context, input)` for a system with `components`, `(context, input)` for one without, and `(gpu, context)` for

package/src/interface/system/check.ts

@@ -138,24 +138,36 @@ const checkWhere = (leaf: Leaf): void => {
     const where = declaration.components?.where;
     if (where === undefined) return;
     if (declaration.up !== undefined || declaration.order !== undefined || declaration.target !== undefined) throw new Error(`System "${name}" uses where with up, order or a target, which run rows across archetypes.`);
+    checkWhereValues(`System "${name}"`, "where", "a system", where, true);
+};
+
+/**
+ * Throws for a `where`, the one `named` says of `subject`, which keeps what `keeps` says to archetypes, naming what
+ * isn't a shared component or giving one a value not of its type, or a predicate unless `predicates`.
+ */
+export const checkWhereValues = (subject: string, named: string, keeps: string, where: { readonly [key: symbol]: unknown }, predicates: boolean): void => {
     for (const key of Object.getOwnPropertySymbols(where)) {
         const found = declarationOf(key);
-        if (kindOf(key) !== "component" || found?.shared !== true) throw new Error(`System "${name}": where names "${labelOf(key)}", which isn't a shared component: where keeps a system to archetypes by their shared values.`);
+        if (kindOf(key) !== "component" || found?.shared !== true) throw new Error(`${subject}: ${named} names "${labelOf(key)}", which isn't a shared component: where keeps ${keeps} to archetypes by their shared values.`);
         const value: unknown = Reflect.get(where, key);
-        if (typeof value !== "function" && found.type !== undefined && !matchesSchema(found.type, value)) throw new Error(`System "${name}": where gives "${labelOf(key)}" ${labelOf(value)}, which isn't one of its type's values.`);
+        if (typeof value === "function") {
+            if (!predicates) throw new Error(`${subject}: ${named} gives "${labelOf(key)}" a predicate, and takes only values.`);
+            continue;
+        }
+        if (found.type !== undefined && !matchesSchema(found.type, value)) throw new Error(`${subject}: ${named} gives "${labelOf(key)}" ${labelOf(value)}, which isn't one of its type's values.`);
     }
 };
 
 /**
- * Throws for what an observer system can't declare: it only reads, after a sync point, so it writes and reduces into
+ * Throws for what a readonly system can't declare: it only reads, after a sync point, so it writes and reduces into
  * nothing, takes no input, isn't a kernel or a render system, has no `up`, and is ordered with nothing.
  */
-const checkObserver = (leaf: Leaf): void => {
+const checkReadonly = (leaf: Leaf): void => {
     const { name, declaration } = leaf;
-    const { observer } = declaration;
-    if (observer === undefined) return;
-    const fail = (message: string): never => { throw new Error(`System "${name}" is an observer, so it ${message}.`); };
-    if (observer !== true) throw new Error(`System "${name}": observer is true or left out.`);
+    const { readonly } = declaration;
+    if (readonly === undefined) return;
+    const fail = (message: string): never => { throw new Error(`System "${name}" is readonly, so it ${message}.`); };
+    if (readonly !== true) throw new Error(`System "${name}": readonly is true or left out.`);
     if (leaf.kind === "render") fail("records no GPU work");
     if (declaration.kernel === true || declaration.kernel === "gpu") fail("isn't a kernel");
     if ((declaration.components?.write?.length ?? 0) + (declaration.resources?.write?.length ?? 0) > 0) fail("writes nothing");
@@ -165,9 +177,23 @@ const checkObserver = (leaf: Leaf): void => {
     if ((declaration.before?.length ?? 0) + (declaration.after?.length ?? 0) + (declaration.during?.length ?? 0) > 0) fail("is ordered with nothing");
 };
 
+/** Throws for `tables` on a system that isn't readonly or has components, or naming keys that aren't registered as their kind. */
+const checkTables = (leaf: Leaf): void => {
+    const { name, declaration } = leaf;
+    const { tables } = declaration;
+    if (tables === undefined) return;
+    if (declaration.readonly !== true) throw new Error(`System "${name}" reads tables, which only a readonly system reads.`);
+    if (declaration.components !== undefined) throw new Error(`System "${name}" reads tables, so it has no components.`);
+    requireRegistered("System", name, "component", tables.components);
+    requireRegistered("System", name, "component", tables.with);
+    requireRegistered("System", name, "component", tables.not);
+    requireRegistered("System", name, "resource", tables.resources);
+    if (tables.where !== undefined) checkWhereValues(`System "${name}"`, "tables' where", "tables", tables.where, false);
+};
+
 /**
  * Throws for a leaf that names a component or resource that isn't registered as one, lists a key in both `read` and
- * `write`, writes a reference, has a lookup reading a component it writes, uses object components and resources of different threads, declares what an observer system can't, or whose
+ * `write`, writes a reference, has a lookup reading a component it writes, uses object components and resources of different threads, declares what a readonly system can't, or whose
  * reductions, conditions, `up` or placement can't hold.
  */
 export const checkLeaf = (leaf: Leaf): void => {
@@ -190,6 +216,7 @@ export const checkLeaf = (leaf: Leaf): void => {
         if (writes.has(key)) throw new Error(`System "${name}": its rows are ordered by an index keyed by "${labelOf(key)}", which the system writes.`);
     }
     checkTarget(leaf);
+    checkTables(leaf);
     threadOf(declaration, "System", name);
     requireRegistered("System", name, "component", components?.has);
     requireRegistered("System", name, "component", components?.not);
@@ -202,7 +229,7 @@ export const checkLeaf = (leaf: Leaf): void => {
         if (declarationOf(key)?.reference !== undefined) throw new Error(`System "${name}" writes "${labelOf(key)}", a reference, which changes only through commands.`);
         if (declarationOf(key)?.shared === true) throw new Error(`System "${name}" writes "${labelOf(key)}", a shared component, whose value is its archetype's: give it another with commands.add.`);
     }
-    checkObserver(leaf);
+    checkReadonly(leaf);
     checkWhere(leaf);
     checkReductions(leaf);
     checkConditions(leaf);

package/src/interface/system/commands.ts

@@ -2,6 +2,8 @@
 import type { Component } from '../component/component.js';
 import type { Entity } from '../entity/entity.js';
 import type { Essential, Shared } from '../component/value.js';
+import type { Table } from '../world/table/table.js';
+import type { SharedOnly } from './shared-only.js';
 import type { ValuesOf } from './values-of.js';
 
 /** The value an `add` of one component takes: none for a tag. */
@@ -62,10 +64,41 @@ export type Commands = {
         ...constant: RequiresPreset<C> extends true ? [constant?: P & SharedPreset<C> & Named<C, P>] : [constant?: P & Named<C, P>]
     ): (...values: SpawnValues<C, P>) => Entity;
     despawn(entity: Entity): void;
+    /**
+     * Despawns, as a `despawn` of each would, every entity that has each component of `with` and none of `not` once the
+     * commands issued before it apply, and every entity spawned at the same sync point that does, whenever spawned.
+     * Derived components may be named. `where` keeps it to the archetypes holding these values of shared components,
+     * each one required as `with` requires it, as a system's `where` of values does. Never the resource entity. Only on
+     * the world's thread: a joined thread's throws.
+     */
+    despawnWhere<const W extends object = {}>(query: {
+        readonly with: readonly [Component.Key, ...Component.Key[]];
+        readonly not?: readonly Component.Key[];
+        readonly where?: W & SharedOnly<NoInfer<W>> & { readonly [K in Shared]?: Component<K> };
+    }): void;
     /** Adds or replaces one component's value, marking it changed. */
     add<K extends Essential>(entity: Entity, component: K, ...value: ValueArgument<K>): void;
     /** Adds or replaces the values of `components`, marking them changed. */
     add<const C extends readonly Essential[]>(entity: Entity, components: C, values: ValuesOf<C>): void;
     remove(entity: Entity, component: Essential): void;
     remove(entity: Entity, components: readonly Essential[]): void;
+    /**
+     * Spawns an entity for each row of `tables`, as a readonly system's `tables` gives them, of each table's components
+     * with its columns' values: a block copy per column. Entity values are rewritten as the world's references would
+     * leave them had the entities outside the tables despawned: each naming an entity of the tables, a reference, a
+     * struct's field or an array's item, names the one spawned for it; a row whose owner reference names an entity
+     * outside them isn't spawned, nor anything it owns, through owner references, as despawning its owner would; a
+     * weak reference to one is left out of its row, which is spawned without it; any other value naming one is
+     * `Entity.none`. Returns, at once, each table's new entities, alive at the sync point. A column's stride must be its
+     * component's in this world, and its length its table's count. On the world's thread only.
+     * - `existing` maps entities to ones already alive in this world, which stand for them: a row whose entity it maps
+     *   isn't spawned, its entry in the result is the entity it maps to, and every value naming one it maps names that
+     *   entity, whether or not it's in the tables. Fails for one that isn't alive.
+     * - `resources` sets each resource it names, by key, at the sync point, as commands apply, each value checked
+     *   against its resource's schema; not one only the world writes, nor one living on another thread.
+     */
+    spawnTables(tables: readonly Table[], options?: {
+        readonly resources?: { readonly [key: symbol]: unknown };
+        readonly existing?: ReadonlyMap<Entity, Entity>;
+    }): Table.Spawned;
 };

package/src/interface/system/commands.type-test.ts

@@ -13,6 +13,7 @@ const label = Symbol("commandsTypeTest/label");
 const player = Symbol("commandsTypeTest/player");
 const slot = Symbol("commandsTypeTest/slot");
 const time = Symbol("commandsTypeTest/time");
+const chunk = Symbol("commandsTypeTest/chunk");
 declare module '@adobe/ecs' {
     export interface Components {
         [position]: { type: number };
@@ -20,6 +21,7 @@ declare module '@adobe/ecs' {
         [label]: { type: string | null };
         [player]: { type: true };
         [slot]: { type: number; derived: true };
+        [chunk]: { type: number; shared: true };
     }
     export interface Resources {
         [time]: { type: number };
@@ -84,4 +86,33 @@ export const issue = (commands: Commands, entity: Entity): void => {
     // @ts-expect-error commands never remove a derived component
     commands.remove(entity, slot);
     commands.despawn(entity);
+
+    // `despawnWhere` takes a query of at least one component, derived ones included.
+    commands.despawnWhere({ with: [player] });
+    commands.despawnWhere({ with: [position, slot], not: [player] });
+    commands.despawnWhere({ with: particle });
+    // @ts-expect-error `with` names at least one component
+    commands.despawnWhere({ with: [] });
+    // @ts-expect-error a query names components, not resources
+    commands.despawnWhere({ with: [time] });
+    // @ts-expect-error in `not` too
+    commands.despawnWhere({ with: [player], not: [time] });
+    // @ts-expect-error it takes a query, not an entity
+    commands.despawnWhere(entity);
+    // Its `where` gives values of shared components, as a system's `where` of values does.
+    commands.despawnWhere({ with: [position], where: { [chunk]: 3 } });
+    const unloaded = { [chunk]: 4 } as const;
+    commands.despawnWhere({ with: [position], where: unloaded });
+    // @ts-expect-error a value of the component's type
+    commands.despawnWhere({ with: [position], where: { [chunk]: "3" } });
+    // @ts-expect-error where names only shared components
+    commands.despawnWhere({ with: [position], where: { [position]: 3 } });
+    // @ts-expect-error where takes values, not predicates
+    commands.despawnWhere({ with: [position], where: { [chunk]: (value: number) => value > 3 } });
+    const placed = { [position]: 3 } as const;
+    // @ts-expect-error where names only shared components, in a constant too
+    commands.despawnWhere({ with: [position], where: placed });
+    const mixed = { [chunk]: 3, [position]: 3 } as const;
+    // @ts-expect-error and in a constant naming a shared one beside it
+    commands.despawnWhere({ with: [position], where: mixed });
 };

package/src/interface/system/create-resolved.ts

@@ -14,7 +14,7 @@ import type { System } from './system.js';
 export const createResolved = (declaration: Resolved, body: Leaf["body"], input?: unknown): System<unknown> => {
     const name = nameOf(declaration, undefined, "system");
     const schema = inputSchemaOf(name, body, declaration.components === undefined ? 1 : 2, input);
-    const system: Leaf & System<unknown> = { kind: "system", name, declaration, input: schema, body };
+    const system: Leaf & System<unknown> = { kind: "system", name, declaration, input: schema, body, commands: undefined };
     checkLeaf(system);
     claimSystem(system, undefined);
     return system;

package/src/interface/system/create.test.ts

@@ -105,17 +105,17 @@ describe("System.create", () => {
             [{ kernel: "gpu", components: { write: [position], changed: [position] } }, "can't run on the GPU: GPU kernels don't support change filters yet"],
             [{ kernel: "gpu", components: { read: [position] }, lookup: { others: { read: [position] } } }, "can't run on the GPU: GPU kernels don't support lookups yet"],
             [{ kernel: "gpu", components: { has: [position] }, resources: { reduce: [total] } }, "can't run on the GPU: GPU kernels don't support reductions yet"],
-            [{ observer: false, resources: { read: [time] } }, "observer is true or left out"],
-            [{ observer: true, components: { write: [position] } }, "is an observer, so it writes nothing"],
-            [{ observer: true, resources: { write: [time] } }, "is an observer, so it writes nothing"],
-            [{ observer: true, components: { has: [position] }, resources: { reduce: [total] } }, "is an observer, so it reduces into nothing"],
-            [{ observer: true, kernel: true, components: { read: [position] } }, "is an observer, so it isn't a kernel"],
-            [{ observer: true, components: { read: [position] }, up: { through: parent } }, "is an observer, so it has no up"],
-            [{ observer: true, resources: { read: [time] }, after: [System.create(() => {})] }, "is an observer, so it is ordered with nothing"],
-            [{ observer: true, resources: { read: [time] }, before: [System.create(() => {})] }, "is an observer, so it is ordered with nothing"],
-            [{ observer: true, resources: { read: [time] }, during: [System.create(() => {})] }, "is an observer, so it is ordered with nothing"],
+            [{ readonly: false, resources: { read: [time] } }, "readonly is true or left out"],
+            [{ readonly: true, components: { write: [position] } }, "is readonly, so it writes nothing"],
+            [{ readonly: true, resources: { write: [time] } }, "is readonly, so it writes nothing"],
+            [{ readonly: true, components: { has: [position] }, resources: { reduce: [total] } }, "is readonly, so it reduces into nothing"],
+            [{ readonly: true, kernel: true, components: { read: [position] } }, "is readonly, so it isn't a kernel"],
+            [{ readonly: true, components: { read: [position] }, up: { through: parent } }, "is readonly, so it has no up"],
+            [{ readonly: true, resources: { read: [time] }, after: [System.create(() => {})] }, "is readonly, so it is ordered with nothing"],
+            [{ readonly: true, resources: { read: [time] }, before: [System.create(() => {})] }, "is readonly, so it is ordered with nothing"],
+            [{ readonly: true, resources: { read: [time] }, during: [System.create(() => {})] }, "is readonly, so it is ordered with nothing"],
         ];
-        expect(() => createTaking({ observer: true }, { type: "object", properties: {} })).toThrow("is an observer, so it takes no input");
+        expect(() => createTaking({ readonly: true }, { type: "object", properties: {} })).toThrow("is readonly, so it takes no input");
         rejected.forEach(([declaration, message], index) => {
             expect(() => create({ ...declaration })).toThrow(message);
         });
@@ -171,9 +171,17 @@ describe("System.create of a composite", () => {
         const looped = System.create({ before: [first], after: [second] }, () => {});
         expect(() => System.create({ systems: [first, second, looped] })).toThrow("Ordering cycle");
     });
-    it("runs observer members after its sync point, in no tier, never conflicting and ignoring constraints naming them", () => {
+    it("takes a row declared whole as written, every member but references, and says so in a conflict", () => {
+        const pass = (row: object): void => { void row; };
+        const whole = System.create({ components: { with: [position, parent], whole: true } }, row => { pass(row); });
+        const reader = System.create({ components: { with: [position] } }, row => { void row[position]; });
+        const definition = definitionOf(whole);
+        expect(definition?.kind === "system" ? definition.declaration.components : null).toEqual({ read: [parent], write: [position], whole: true });
+        expect(() => System.create([whole, reader])).toThrow('both access "typesSystemTest/position" and one writes it; order them with before or after. "whole" takes its row whole (components.whole), so it writes every member.');
+    });
+    it("runs readonly members after its sync point, in no tier, never conflicting and ignoring constraints naming them", () => {
         const write = System.create({ components: { with: [position] } }, row => { row[position] += 1; });
-        const watch = System.create({ observer: true, components: { with: [position] } }, row => { void row[position]; });
+        const watch = System.create({ readonly: true, components: { with: [position] } }, row => { void row[position]; });
         const later = System.create({ components: { with: [position] }, after: [watch, write] }, row => { void row[position]; });
         const free = System.create({ after: [watch] }, ({ resources }) => { void resources[time]; });
         const schedule = scheduleOf(requireDefinition(System.create([write, watch, later, free])));
@@ -205,6 +213,6 @@ describe("System.render", () => {
         const render = (declaration: object, uses: Parameters<typeof giveAccess>[1] = {}): unknown => Reflect.apply(System.render, undefined, [giveAccess(declaration, uses), () => {}]);
         expect(() => System.render({ shader: { accessors: { loop: height } } }, () => {})).toThrow(`can't render: "loop" isn't usable as a WGSL function name.`);
         expect(() => render({ shader: { accessors: {} } }, { resources: { reduce: [total] } })).toThrow("writes or reduces into resources; a render system only reads");
-        expect(() => render({ shader: { accessors: {} }, observer: true })).toThrow("is an observer, so it records no GPU work");
+        expect(() => render({ shader: { accessors: {} }, readonly: true })).toThrow("is readonly, so it records no GPU work");
     });
 });

package/src/interface/system/create.ts

@@ -16,8 +16,9 @@ import type { Listed, Property } from './property.js';
 import type { System } from './system.js';
 import type { OneThread, ThreadedBy, ThreadsOf } from './threads.js';
 import type { HeldBy } from './values.js';
+import type { SharedOnly } from './shared-only.js';
 import type { Shared } from '../component/value.js';
-import { accessOf, compact, componentLists, lookupsLists, resourceUses, upReads, whereReadsOf } from './resolve.js';
+import { accessOf, commandLists, compact, componentLists, lookupsLists, resourceUses, upReads, whereReadsOf } from './resolve.js';
 
 type Lookups<D> = Property<D, "lookup">;
 
@@ -50,10 +51,10 @@ type GpuKernel = {
 };
 
 /**
- * An observer system only reads, after a sync point: its row and resources are read-only, and it never compiles to a
+ * A readonly system only reads, after a sync point: its row and resources are read-only, and it never compiles to a
  * kernel, has no `up`, and is ordered with nothing. That it takes no input is checked at its body.
  */
-type Observer = {
+type Readonly = {
     readonly kernel?: false;
     readonly up?: never;
     readonly before?: never;
@@ -68,9 +69,10 @@ type Targeted = {
     readonly order?: never;
 };
 
+
 /** `where` names only shared components, and keeps rows unordered across archetypes, so it's without `up`, `order` and a target. */
 type Where<D> = D extends { readonly components: { readonly where: infer W } }
-    ? { readonly components?: { readonly where?: { readonly [K in Exclude<keyof W, Shared>]: { readonly "error: where names only shared components, which each archetype holds one value of": K } } } }
+    ? { readonly components?: { readonly where?: SharedOnly<W> } }
         & (D extends { readonly up: object } | { readonly order: object } | { readonly target: string }
             ? { readonly components?: { readonly where?: { readonly "error: where can't be used with up, order or a target, which run rows across archetypes": true } } } : {})
     : {};
@@ -97,7 +99,13 @@ type Validate<D extends Declaration> =
     // GPU kernels don't read components an archetype may lack yet.
     & (D extends { readonly components: { readonly optional: readonly [unknown, ...unknown[]] } }
         ? { readonly kernel?: boolean | { readonly "error: a GPU kernel can't have optional components yet": true } } : {})
-    & (D extends { readonly observer: true } ? Observer : {})
+    & (D extends { readonly readonly: true } ? Readonly : {})
+    // Tables are copies a readonly system without components reads.
+    & (D extends { readonly tables: { readonly where: infer W } } ? { readonly tables?: { readonly where?: SharedOnly<W> } } : {})
+    & (D extends { readonly tables: object }
+        ? (D extends { readonly readonly: true } ? {} : { readonly tables?: { readonly "error: tables are read by a readonly system": true } })
+        & (Property<D, "components"> extends undefined ? {} : { readonly tables?: { readonly "error: a system reading tables has no components": true } })
+        : {})
     & (D extends { readonly target: string } ? Targeted : {})
     & (D extends { readonly target: string } ? Property<D, "components"> extends undefined ? { readonly target?: { readonly "error: a system on one entity runs on its row, so it needs components": true } } : {} : {})
     // A body's input is the type of its parameter after its context, not part of its declaration.
@@ -109,7 +117,7 @@ type EntityFields<I> = { [K in keyof I]-?: [Exclude<I[K], undefined>] extends [E
 /**
  * What a declaration requires of the input its body takes, checked at the body, since the input is known only once the
  * body is: a target names an entity field of it, and a system with input doesn't filter on added or changed, as its
- * runs pass different input, nor is it an observer. Every check passes for `never`, the input before the body is
+ * runs pass different input, nor is it a readonly system. Every check passes for `never`, the input before the body is
  * inferred.
  */
 type Checks<D, I> = [I] extends [never] ? unknown :
@@ -119,7 +127,7 @@ type Checks<D, I> = [I] extends [never] ? unknown :
         : unknown)
     & ([I] extends [undefined] ? unknown
         : (D extends { readonly components: { readonly added: object } | { readonly changed: object } } ? { readonly "error: a system with input can't filter on added or changed, as its runs pass different input; pass it through a resource": true } : unknown)
-        & (D extends { readonly observer: true } ? { readonly "error: an observer system takes no input": true } : unknown));
+        & (D extends { readonly readonly: true } ? { readonly "error: a readonly system takes no input": true } : unknown));
 
 /** The body of a system that declares nothing, which runs once per run with its resources and commands. */
 type Alone = (context: Context<{}>) => void;
@@ -144,10 +152,10 @@ type Checked<C> = C extends Alone ? ReturnsNoPromise<C> : C extends CompositeDec
  * input, with every field of theirs. Throws if a system names a key that isn't registered as its kind, its body writes
  * a reference, a lookup's rows are read where it writes them or it goes through an index keyed by what it writes, its
  * rows are ordered by an index it isn't sorted or keyed by what it writes, its object components and resources live on
- * different threads, or its reductions, conditions, `up`, `order` or placement can't hold, or it's an observer and
+ * different threads, or its reductions, conditions, `up`, `order` or placement can't hold, or it's a readonly system and
  * writes, reduces, takes input, is a kernel, has `up` or is ordered; if the build couldn't follow how its body uses its
  * resources, lookups or parent; or if a composite's member isn't a system a constructor returned, or two members
- * declare an input field with different schemas. A composite's observer members run after its sync point, ordered
+ * declare an input field with different schemas. A composite's readonly members run after its sync point, ordered
  * with nothing.
  *
  * A run of a system without components resolves to what its body returns, or `undefined` when its conditions, resource
@@ -170,9 +178,10 @@ export function create(first: Declaration | Leaf["body"] | readonly System<unkno
     const body = typeof first === "function" ? first : second;
     if (body === undefined) throw new Error("A system needs a body, and a composite its systems.");
     const name = nameOf(first, id, "system");
-    const declaration = resolve(`System "${name}"`, declared, accessOf(`System "${name}"`, first));
+    const access = accessOf(`System "${name}"`, first);
+    const declaration = resolve(`System "${name}"`, declared, access);
     const schema = inputSchemaOf(name, body, declaration.components === undefined ? 1 : 2, input);
-    const system: Leaf & System<unknown> = { kind: "system", name, declaration, input: schema, body };
+    const system: Leaf & System<unknown> = { kind: "system", name, declaration, input: schema, body, commands: commandLists(access) };
     checkLeaf(system);
     claimSystem(system, id);
     return system;
@@ -180,16 +189,16 @@ export function create(first: Declaration | Leaf["body"] | readonly System<unkno
 
 /** A declaration as the world takes it, with what the build inferred its body uses. */
 const resolve = (what: string, declared: Declaration, access: ReturnType<typeof accessOf>): Resolved => {
-    const reading = declared.observer === true;
+    const reading = declared.readonly === true;
     const { components, lookup, up, resources, ...rest } = declared;
     const uses = resourceUses(what, access, resources?.is);
-    // What `where`'s predicates read counts as the system's reads, for its order, conflicts and placement.
     const whereReads = whereReadsOf(what, components, access);
     const conditions: readonly symbol[] = resources?.is ?? [];
-    for (const key of whereReads) if (!uses.read.includes(key) && !uses.write.includes(key) && !conditions.includes(key)) uses.read.push(key);
+    // What `where`'s predicates and `tables` read counts as the system's reads, for its order, conflicts and placement.
+    for (const key of [...whereReads, ...declared.tables?.resources ?? []]) if (!uses.read.includes(key) && !uses.write.includes(key) && !conditions.includes(key)) uses.read.push(key);
     const resolved: Resolved = {
         ...rest,
-        ...components === undefined ? {} : { components: componentLists(components, access.components, reading, whereReads) },
+        ...components === undefined ? {} : { components: componentLists(components, components.whole === true ? null : access.components, reading, whereReads) },
         ...lookup === undefined ? {} : { lookup: lookupsLists(lookup, access) },
         ...up === undefined ? {} : { up: { through: up.through, read: upReads(what, access) } },
     };

package/src/interface/system/declaration.ts

@@ -4,6 +4,7 @@ import type { Resource } from '../resource/resource.js';
 import type { ComponentAccess, ComponentLists, ResourceAccess, ResourceLists, SystemLookup, SystemLookupLists, Up, UpLists } from './access.js';
 import type { Shader } from './render.js';
 import type { System } from './system.js';
+import type { TablesDeclaration } from './tables.js';
 
 /**
  * A system never declares its thread: it runs on the one its object components and resources live on, those it
@@ -59,9 +60,15 @@ export type Declaration = {
     readonly during?: readonly System<unknown>[];
     /**
      * Runs after the last sync point of each run and tick (a tick is a run of the added composite), reading the settled
-     * state; changes nothing; never ordered; doesn't keep the loop ticking.
+     * state, on the thread that added or ran it; changes nothing, its row and resources typed read-only and its context
+     * without `commands`; takes no input; never ordered; doesn't keep the loop ticking. A joined thread adds only these.
      */
-    readonly observer?: true;
+    readonly readonly?: true;
+    /**
+     * For a readonly system without components: gives its context `tables`, copies of whole archetypes' columns, as
+     * `TablesDeclaration` says, read on the world's thread. Its components and resources count as what it reads.
+     */
+    readonly tables?: TablesDeclaration;
 };
 
 /** A declaration as the world takes it: the build's inferred reads, writes and reductions joined with what it declares. */

package/src/interface/system/describe.test.ts

@@ -0,0 +1,79 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Index } from "../indexes/index-type.js";
+import { System } from "./system.js";
+
+const position = Symbol("describeTest/position");
+const cell = Symbol("describeTest/cell");
+const speed = Symbol("describeTest/speed");
+const hover = Symbol("describeTest/hover");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [position]: { type: number };
+        [cell]: { type: number };
+    }
+    export interface Resources {
+        [speed]: { type: number };
+        [hover]: { type: number };
+    }
+}
+
+const byCell = Index.create({ key: [cell] });
+
+const spawnCells = System.create(({ commands }) => { commands.spawn([position])({ [position]: 1 }); });
+const move = System.create({ components: { with: [position] }, after: [spawnCells] }, (row, { resources }) => { row[position] += resources[speed]; });
+const deriveCells = System.create({ components: { with: [position], not: [cell] }, after: [move] }, (row, { commands }) => { commands.add(row.entity, cell, row[position]); });
+const pick = System.create({ lookup: { cells: { index: byCell } }, after: [deriveCells] }, ({ lookup, resources }) => { resources[hover] = lookup.cells(1).length; });
+const nudge = System.create({ components: { with: [position], whole: true } }, row => { Reflect.set(row, position, 0); });
+const watch = System.create({ readonly: true, components: { with: [position] } }, row => { void row[position]; });
+const frame = System.create([spawnCells, move, deriveCells, pick, watch]);
+
+describe("System.describe", () => {
+    it("gives tiers in run order, readonly systems apart, and what each system uses, as data", () => {
+        const described = System.describe(frame);
+        expect(described.tiers.map(tier => tier.systems.map(system => system.name))).toEqual([["spawnCells"], ["move"], ["deriveCells"], ["pick"]]);
+        expect(described.readonly.map(system => system.system)).toEqual([watch]);
+        const [[spawning], [moving], [deriving], [picking]] = described.tiers.map(tier => tier.systems);
+        expect(spawning?.commands).toEqual({ spawn: [position], add: [], remove: [], despawn: false });
+        expect([moving?.components.write, moving?.resources.read, moving?.commands?.add]).toEqual([[position], [speed], []]);
+        expect([deriving?.components.read, deriving?.components.not, deriving?.commands?.add]).toEqual([[position], [cell], [cell]]);
+        expect([picking?.lookups, picking?.resources.write]).toEqual([[{ name: "cells", index: "byCell", read: [] }], [hover]]);
+        expect(moving?.after).toEqual([{ system: spawnCells, name: "spawnCells", because: "after", conflicts: [] }]);
+        expect(deriving?.after).toEqual([{ system: move, name: "move", because: "after", conflicts: [position] }]);
+        expect(System.describe(nudge).tiers[0]?.systems[0]?.whole).toBe(true);
+    });
+    it("gives the fewest sync points between tiers whose commands a later system depends on, and why", () => {
+        expect(System.describe(frame).tiers.map(tier => tier.sync)).toEqual([
+            [{ from: spawnCells, to: move, keys: [position] }, { from: spawnCells, to: deriveCells, keys: [position] }],
+            null,
+            [{ from: deriveCells, to: pick, keys: [cell] }],
+            null,
+        ]);
+        // Despawning may change anything a later system matches; writing values needs no sync point.
+        const clear = System.create({ components: { with: [cell] } }, (row, { commands }) => { commands.despawn(row.entity); });
+        const count = System.create({ components: { with: [position] }, after: [clear] }, row => { void row[position]; });
+        const tally = System.create({ after: [count] }, ({ resources }) => { resources[hover] = resources[speed]; });
+        expect(System.describe(System.create([clear, count, tally])).tiers.map(tier => tier.sync)).toEqual([[{ from: clear, to: count, keys: [] }], null, null]);
+    });
+    it("gives a text form to read", () => {
+        expect(System.describe(frame).text).toBe([
+            "tier 0  spawnCells   commands  spawn describeTest/position",
+            "sync    spawnCells's commands of describeTest/position, for move",
+            "        spawnCells's commands of describeTest/position, for deriveCells",
+            "tier 1  move         writes    describeTest/position",
+            "                     resources reads describeTest/speed",
+            "                     after     spawnCells (after)",
+            "tier 2  deriveCells  reads     describeTest/position",
+            "                     requires  not describeTest/cell",
+            "                     commands  add describeTest/cell",
+            "                     after     move (after: describeTest/position)",
+            "sync    deriveCells's commands of describeTest/cell, for pick",
+            "tier 3  pick         resources writes describeTest/hover",
+            "                     looks up  cells through byCell",
+            "                     after     deriveCells (after)",
+            "readonly",
+            "        watch        reads     describeTest/position",
+        ].join("\n"));
+    });
+});