@adobe/ecs 0.2.1 → 0.2.4

package/src/interface/system/describe.ts

@@ -0,0 +1,122 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { indexDefinitionOf } from '../registry/indexes.js';
+import { labelOf } from '../registry/names.js';
+import { requireDefinition } from '../registry/program.js';
+import { isLeaf, placementsOf, scheduleOf, type Placement } from '../registry/schedule.js';
+import type { Leaf } from './leaf.js';
+import type { System } from './system.js';
+
+type Key = symbol;
+
+const none: readonly never[] = [];
+
+/** A leaf as the system value it is. */
+const asSystem = (leaf: Leaf): System<unknown, unknown> => leaf;
+
+/** What the build inferred one system uses, and what placed it, as plain data. */
+const describeLeaf = (leaf: Leaf, placements: readonly Placement[]) => {
+    const { components, resources, lookup, up, order } = leaf.declaration;
+    const { commands } = leaf;
+    return {
+        /** The system, the value its constructor returned. */
+        system: asSystem(leaf),
+        name: leaf.name,
+        components: {
+            read: [...components?.read ?? none, ...up === undefined ? none : [up.through]],
+            write: components?.write ?? none,
+            /** What it requires without reading: `with` members it doesn't use, `added` and `changed` filters' among them. */
+            has: components?.has ?? none,
+            optional: components?.optional ?? none,
+            not: components?.not ?? none,
+            added: components?.added ?? none,
+            changed: components?.changed ?? none,
+            /** What it reads of each row's parent, through `up`. */
+            parent: up?.read ?? none,
+        },
+        resources: {
+            read: resources?.read ?? none,
+            write: resources?.write ?? none,
+            reduce: resources?.reduce ?? none,
+            changed: resources?.changed ?? none,
+            is: resources?.is ?? none,
+            not: resources?.not ?? none,
+        },
+        lookups: Object.entries(lookup ?? {}).map(([name, used]) => ({
+            name,
+            /** The label of the index it looks up through, or null for a lookup by entity. */
+            index: "index" in used && used.index !== undefined ? indexDefinitionOf(used.index)?.name ?? null : null,
+            read: used.read ?? none,
+        })),
+        /** The label of the sorted index ordering its rows, or null. */
+        order: indexDefinitionOf(order)?.name ?? null,
+        /** What its commands name by kind, and whether it despawns; null where the build couldn't follow them. */
+        commands: commands === null ? null : {
+            spawn: commands?.spawn ?? none,
+            add: commands?.add ?? none,
+            remove: commands?.remove ?? none,
+            despawn: commands?.despawn === true,
+        },
+        /** Whether it takes its row whole (`components: { whole: true }`), every member written. */
+        whole: components?.whole === true,
+        /** The systems it follows directly, with what ordered it after each and the keys that need that order. */
+        after: placements.map(placement => ({ system: asSystem(placement.leaf), name: placement.leaf.name, because: placement.because, conflicts: placement.conflicts })),
+    };
+};
+
+type Described = ReturnType<typeof describeLeaf>;
+
+const keys = (list: readonly Key[]): string => list.map(labelOf).join(" ");
+
+/** A system's lines of text, after its name in a column of `width`. */
+const linesOf = (system: Described, width: number): readonly string[] => {
+    const lines: string[] = [];
+    const add = (label: string, text: string): void => { if (text !== "") lines.push(`${label.padEnd(10)}${text}`); };
+    const { components, resources, commands } = system;
+    add("reads", keys(components.read));
+    add("writes", `${keys(components.write)}${system.whole ? " (its whole row)" : ""}`);
+    add("requires", [keys(components.has), components.not.length === 0 ? "" : `not ${keys(components.not)}`, components.optional.length === 0 ? "" : `optional ${keys(components.optional)}`].filter(text => text !== "").join(", "));
+    add("filters", [...components.added.map(key => `added ${labelOf(key)}`), ...components.changed.map(key => `changed ${labelOf(key)}`), ...resources.changed.map(key => `changed ${labelOf(key)}`)].join(", "));
+    add("parent", keys(components.parent));
+    add("resources", [resources.read.length === 0 ? "" : `reads ${keys(resources.read)}`, resources.write.length === 0 ? "" : `writes ${keys(resources.write)}`,
+        resources.reduce.length === 0 ? "" : `reduces ${keys(resources.reduce)}`, resources.is.length === 0 ? "" : `while ${keys(resources.is)}`,
+        resources.not.length === 0 ? "" : `unless ${keys(resources.not)}`].filter(text => text !== "").join(", "));
+    for (const lookup of system.lookups) add("looks up", `${lookup.name}${lookup.index === null ? "" : ` through ${lookup.index}`}${lookup.read.length === 0 ? "" : `: ${keys(lookup.read)}`}`);
+    if (system.order !== null) add("ordered", `by ${system.order}`);
+    if (commands === null) add("commands", "unknown: the build couldn't follow them");
+    else add("commands", [commands.spawn.length === 0 ? "" : `spawn ${keys(commands.spawn)}`, commands.add.length === 0 ? "" : `add ${keys(commands.add)}`,
+        commands.remove.length === 0 ? "" : `remove ${keys(commands.remove)}`, commands.despawn ? "despawn" : ""].filter(text => text !== "").join(", "));
+    add("after", system.after.map(placement => `${placement.name} (${placement.because}${placement.conflicts.length === 0 ? "" : `: ${keys(placement.conflicts)}`})`).join(", "));
+    const indent = " ".repeat(width);
+    return lines.length === 0 ? [system.name] : lines.map((line, i) => `${i === 0 ? system.name.padEnd(width) : indent}${line}`);
+};
+
+/**
+ * Describes how a system or composite runs: its tiers in run order, systems in one tier having no ordering path between
+ * them, each with the sync point after it, if any, and its readonly systems apart, which run after its last sync
+ * point. For each system, what the build inferred it reads, writes, looks up and commands, whether it takes its row
+ * whole, and the systems it follows directly, with what ordered it after each. `text` gives it all to read; the rest
+ * is data to assert on.
+ */
+export const describe = <I, R>(system: System<I, R>) => {
+    const definition = requireDefinition(system);
+    const schedule = scheduleOf(definition);
+    const placements = placementsOf(definition);
+    const tiers = schedule.tiers.map((tier, t) => ({
+        systems: tier.map(leaf => describeLeaf(leaf, placements.get(leaf) ?? none)),
+        /**
+         * Why a sync point follows the tier, applying the commands so far: each system whose commands may change what a
+         * later one that follows it uses, through `keys`, none listed where it despawns or a cascade could; null for none.
+         */
+        sync: schedule.syncs[t]?.map(reason => ({ from: asSystem(reason.from), to: asSystem(reason.to), keys: reason.keys })) ?? null,
+    }));
+    const readonly = schedule.observer.flatMap(member => isLeaf(member) ? [describeLeaf(member, none)] : []);
+    const width = Math.max(0, ...[...tiers.flatMap(tier => tier.systems), ...readonly].map(described => described.name.length)) + 2;
+    const text = [
+        ...tiers.flatMap((tier, t) => [
+            ...tier.systems.flatMap((described, i) => linesOf(described, width).map((line, l) => `${(i === 0 && l === 0 ? `tier ${t}` : "").padEnd(8)}${line}`)),
+            ...(tier.sync ?? none).map((reason, r) => `${(r === 0 ? "sync" : "").padEnd(8)}${reason.from.name}'s commands${reason.keys.length === 0 ? "" : ` of ${keys(reason.keys)}`}, for ${reason.to.name}`),
+        ]),
+        ...readonly.length === 0 ? none : ["readonly", ...readonly.flatMap(described => linesOf(described, width).map(line => `${"".padEnd(8)}${line}`))],
+    ].map(line => line.trimEnd()).join("\n");
+    return { tiers, readonly, text };
+};

package/src/interface/system/index.ts

@@ -1,4 +1,5 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 export type { Commands } from './commands.js';
 export * from './create.js';
+export { describe } from './describe.js';
 export { render, type RenderContext, type RenderTable } from './render.js';

package/src/interface/system/leaf.ts

@@ -1,5 +1,6 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Schema } from '../schema/schema.js';
+import type { CommandLists } from './access.js';
 import type { Resolved } from './declaration.js';
 import type { Name } from './name.js';
 
@@ -17,4 +18,9 @@ export type Leaf = {
     readonly declaration: Resolved;
     readonly input: InputSchema | undefined;
     readonly body: (...parameters: never[]) => void;
+    /**
+     * What its body's commands name, as the build inferred them: null where it couldn't follow them, undefined for
+     * none. Apart from its declaration, so a module evaluated again with other commands declares the same system.
+     */
+    readonly commands?: CommandLists | null;
 };

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

@@ -23,7 +23,7 @@ export const Particle = [position, velocity] as const;
 expectType<Equal<typeof Particle, readonly [typeof position, typeof velocity]>>();
 export const one: readonly Component.Key[] = Particle;
 export const move = System.create({ components: { with: [...Particle] } }, row => { row[position] += row[velocity]; });
-export const read = System.create({ observer: true, components: { with: [...Particle] } }, row => { void row[velocity]; });
+export const read = System.create({ readonly: true, components: { with: [...Particle] } }, row => { void row[velocity]; });
 
 // Declared without `as const`, a list's keys widen to `symbol`, which no list of components takes.
 const loose = [position, velocity];

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

@@ -36,7 +36,7 @@ System.create({
 }, row => { void row[velocity]; });
 
 // An observer system reads its optional components and writes nothing.
-System.create({ observer: true, components: { with: [position], optional: [velocity] } }, row => {
+System.create({ readonly: true, components: { with: [position], optional: [velocity] } }, row => {
     void row[velocity];
     // @ts-expect-error an observer system's row is read-only
     row[velocity] = 1;

package/src/interface/system/render.ts

@@ -96,6 +96,7 @@ export const render = <const D extends RenderDeclaration, B extends Body<D>>(
         },
         input: undefined,
         body,
+        commands: undefined,
     };
     if (uses.write.length > 0 || uses.reduce.length > 0) throw new Error(`${what} writes or reduces into resources; a render system only reads.`);
     checkLeaf(system);

package/src/interface/system/resolve.ts

@@ -3,7 +3,7 @@ import { takeAccessOf } from '../registry/ids.js';
 import { indexDefinitionOf } from '../registry/indexes.js';
 import { declarationOf, labelOf } from '../registry/names.js';
 import { isString, isStruct } from '../registry/schemas.js';
-import type { ComponentAccess, ComponentLists, Lookup, SystemLookup, SystemLookupLists } from './access.js';
+import type { CommandLists, ComponentAccess, ComponentLists, Lookup, SystemLookup, SystemLookupLists } from './access.js';
 
 type Key = symbol;
 
@@ -23,11 +23,23 @@ export type Access = {
     readonly up: readonly Key[] | null;
     /** The resources the predicates of its declaration's `where` read; absent without predicates. */
     readonly where?: readonly Key[] | null;
+    /** What its commands name, keys or lists of them, by kind, and whether it despawns; absent where no build said. */
+    readonly commands?: unknown;
     readonly at: string;
 };
 
+type Named = readonly (Key | readonly Key[])[];
+type Commanded = { readonly spawn: Named; readonly add: Named; readonly remove: Named; readonly despawn: boolean };
+
 const isKeys = (value: unknown): value is readonly Key[] => Array.isArray(value) && value.every(key => typeof key === "symbol");
 
+const isNamed = (value: unknown): value is Named => Array.isArray(value) && value.every(item => typeof item === "symbol" || isKeys(item));
+
+/** A binding a command named that holds neither a key nor a list of them, as one declared below its system, isn't followed. */
+const isCommanded = (value: unknown): value is Commanded => typeof value === "object" && value !== null
+    && isNamed(Reflect.get(value, "spawn")) && isNamed(Reflect.get(value, "add")) && isNamed(Reflect.get(value, "remove"))
+    && typeof Reflect.get(value, "despawn") === "boolean";
+
 const isUsed = (value: unknown): value is Used => typeof value === "object" && value !== null
     && isKeys(Reflect.get(value, "read")) && isKeys(Reflect.get(value, "write"))
     && (Reflect.get(value, "mutate") === undefined || isKeys(Reflect.get(value, "mutate")));
@@ -106,7 +118,7 @@ export const componentLists = (components: ComponentAccess, used: Used | null, r
         : used.write;
     const read = used === null ? without(held, write) : without(used.read, write);
     const has = [...without(members, read, write), ...without(filtered, read, write)];
-    return compact({ read, write, has, optional, not: components.not, added: components.added, changed: components.changed, where, whereReads });
+    return compact({ read, write, has, optional, not: components.not, added: components.added, changed: components.changed, where, whereReads, whole: components.whole });
 };
 
 /**
@@ -161,5 +173,16 @@ export const whereReadsOf = (what: string, components: ComponentAccess | undefin
     return reads;
 };
 
+/** What a body's commands name, as the world takes it: null where the build couldn't follow them, nothing for none. */
+export const commandLists = (access: Access): CommandLists | null | undefined => {
+    const { commands } = access;
+    if (commands === undefined) return undefined;
+    if (!isCommanded(commands)) return null;
+    if (!commands.despawn && commands.spawn.length + commands.add.length + commands.remove.length === 0) return undefined;
+    const flat = (named: Named): Key[] => [...new Set(named.flat())];
+    const lists = compact({ spawn: flat(commands.spawn), add: flat(commands.add), remove: flat(commands.remove), despawn: commands.despawn ? true as const : undefined });
+    return Object.keys(lists).length === 0 ? undefined : lists;
+};
+
 /** What a body reads of its parent's values. */
 export const upReads = (what: string, access: Access): readonly Key[] => followed(what, access.up, "its parent's values", access);

package/src/interface/system/shared-only.ts

@@ -0,0 +1,5 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Shared } from '../component/value.js';
+
+/** A `where`'s keys that aren't shared components, each an error: `where` names only shared components. */
+export type SharedOnly<W> = { readonly [K in Exclude<keyof W, Shared>]: { readonly "error: where names only shared components, which each archetype holds one value of": K } };

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

@@ -126,7 +126,7 @@ System.create({ components: { with: [health], optional: [team] } }, row => {
     // @ts-expect-error nor an optional one
     row[team] = "red";
 });
-System.create({ observer: true, components: { with: [team] } }, row => {
+System.create({ readonly: true, components: { with: [team] } }, row => {
     check<Equal<typeof row[typeof team], "red" | "blue">>();
 });
 

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

@@ -367,7 +367,7 @@ System.render({ shader: { accessors: { place: position } } }, gpu => { void gpu.
 
 // Observer systems read what a sync point left, after it: rows, resources, lookups and change filters, and no commands.
 export const watchPositions = System.create({
-    observer: true,
+    readonly: true,
     components: { with: [position], changed: [position] },
     lookup: { targets: { with: [velocity] } },
 }, (row, context) => {
@@ -379,33 +379,39 @@ export const watchPositions = System.create({
     void context.commands;
 });
 check<Equal<typeof watchPositions, System>>();
-export const watchTime = System.create({ observer: true, resources: { changed: [time] } }, ({ resources }) => { void resources[time]; });
+export const watchTime = System.create({ readonly: true, resources: { changed: [time] } }, ({ resources }) => { void resources[time]; });
 // A composite may hold observer members, which run after its sync point.
 export const withWatch = System.create([integrate, watchTime]);
 check<Equal<typeof withWatch, System>>();
-// @ts-expect-error observer is true or left out
-System.create({ observer: false }, () => {});
-System.create({ observer: true, components: { with: [position] } }, (row, { resources }) => {
-    // @ts-expect-error an observer system writes no components
+// @ts-expect-error observer isn't a declaration's: readonly is
+System.create({ observer: true }, () => {});
+// @ts-expect-error readonly is true or left out
+System.create({ readonly: false }, () => {});
+System.create({ readonly: true, components: { with: [position] } }, (row, { resources }) => {
+    // @ts-expect-error a readonly system writes no components
     row[position] = 0;
-    // @ts-expect-error an observer system writes no resources
+    // @ts-expect-error a readonly system writes no resources
     resources[score] = 0;
 });
-System.create({ observer: true }, context => {
-    // @ts-expect-error an observer system reduces into nothing
+System.create({ readonly: true }, context => {
+    // @ts-expect-error a readonly system reduces into nothing
     void context.reduce;
+    // @ts-expect-error a readonly system has no commands
+    void context.commands;
 });
-// @ts-expect-error an observer system takes no input
-System.create({ observer: true }, (_context, input: { readonly count: number }) => { void input; });
-// @ts-expect-error an observer system isn't a kernel
-System.create({ observer: true, kernel: true, components: { with: [position] } }, () => {});
-System.create({ observer: true, kernel: false, components: { with: [position] } }, () => {});
-// @ts-expect-error an observer system is ordered with nothing
-System.create({ observer: true, after: [integrate] }, () => {});
-// @ts-expect-error an observer system is ordered with nothing
-System.create({ observer: true, before: [integrate] }, () => {});
-// @ts-expect-error an observer system is ordered with nothing
-System.create({ observer: true, during: [integrate] }, () => {});
+// @ts-expect-error a readonly system takes no input
+System.create({ readonly: true }, (_context, input: { readonly count: number }) => { void input; });
+// @ts-expect-error a readonly system isn't a kernel
+System.create({ readonly: true, kernel: true, components: { with: [position] } }, () => {});
+// @ts-expect-error a readonly system isn't a GPU kernel
+System.create({ readonly: true, kernel: "gpu", components: { with: [position] } }, () => {});
+System.create({ readonly: true, kernel: false, components: { with: [position] } }, () => {});
+// @ts-expect-error a readonly system is ordered with nothing
+System.create({ readonly: true, after: [integrate] }, () => {});
+// @ts-expect-error a readonly system is ordered with nothing
+System.create({ readonly: true, before: [integrate] }, () => {});
+// @ts-expect-error a readonly system is ordered with nothing
+System.create({ readonly: true, during: [integrate] }, () => {});
 
 // A system on one entity: its input names the entity, and its body runs on that entity's row.
 type OnOne = { readonly entity: Entity; readonly by: number };

package/src/interface/system/tables.ts

@@ -0,0 +1,27 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component } from '../component/component.js';
+import type { Shared } from '../component/value.js';
+import type { Resource } from '../resource/resource.js';
+import type { Table } from '../world/table/table.js';
+
+/**
+ * What a readonly system's `tables` reads: of every archetype matching `with`, `not` and `where` that holds any of
+ * `components`, a table of those it holds; and, with `resources`, each resource's value.
+ */
+export type TablesDeclaration = {
+    readonly components: readonly Component.Key[];
+    readonly with?: readonly Component.Key[];
+    readonly not?: readonly Component.Key[];
+    /**
+     * Keeps the tables to the archetypes holding these values of shared components, each one required as `with`
+     * requires it, as a system's `where` of values keeps its system to them.
+     */
+    readonly where?: { readonly [K in Shared]?: Component<K> };
+    readonly resources?: readonly Resource.Key[];
+};
+
+/** A readonly system's `tables`: a table of each archetype its declaration reads, and the values of the resources it reads. */
+export type Tables = {
+    readonly archetypes: readonly Table[];
+    readonly resources: { readonly [K in Resource.Key]?: Resource<K> };
+};

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

@@ -62,6 +62,6 @@ System.create({
     up: { through: parent },
 }, () => {});
 
-// An observer system reads what a sync point left, in no order.
-// @ts-expect-error an observer system has no up
-System.create({ observer: true, components: { with: [local] }, up: { through: parent } }, () => {});
+// A readonly system reads what a sync point left, in no order.
+// @ts-expect-error a readonly system has no up
+System.create({ readonly: true, components: { with: [local] }, up: { through: parent } }, () => {});

package/src/interface/world/index.ts

@@ -1,3 +1,3 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
-// The `World` namespace's members: none, since a consumer declares nothing more with it.
-export {};
+// The `World` namespace's types.
+export type { Table } from './table/table.js';

package/src/interface/world/run.type-test.ts

@@ -19,7 +19,7 @@ declare module '@adobe/ecs' {
 }
 
 // A run resolves to its per-run body's value: a one-off read is an observer system returning it.
-const count = System.create({ observer: true }, ({ resources }) => resources[frames]);
+const count = System.create({ readonly: true }, ({ resources }) => resources[frames]);
 check<Equal<typeof count, System<undefined, number>>>();
 const counted: Promise<number> = world.run(count);
 // @ts-expect-error a run of it resolves to a number
@@ -32,7 +32,7 @@ const scaled = System.create({}, ({ resources }, input: { readonly by: number })
 const scaledValue: Promise<{ scaled: number }> = world.run(scaled, { by: 2 });
 
 // A body that may be skipped, as one whose conditions or resource change filters can fail, may give undefined.
-const changedFrames = System.create({ observer: true, resources: { changed: [frames] } }, ({ resources }) => resources[frames]);
+const changedFrames = System.create({ readonly: true, resources: { changed: [frames] } }, ({ resources }) => resources[frames]);
 check<Equal<typeof changedFrames, System<undefined, number | undefined>>>();
 const whileDevice = System.create({ resources: { is: [gpuDevice] } }, () => "drawn");
 const drawn: Promise<string | undefined> = world.run(whileDevice);
@@ -62,13 +62,23 @@ void ecs.Report;
 // @ts-expect-error no run numbers
 const numbered: Promise<number> = world.run(main);
 
-void [counted, notText, nextValue, scaledValue, drawn, rows, composite, input, nothing, numbered, time];
+// Asked for its changes, after its input, a run resolves to them, in the shape changes finalizers take.
+const changes = world.run(move, { distance: 1 }, { changes: true });
+const alone = world.run(main, { changes: true });
+check<Equal<typeof changes, typeof alone>>();
+check<Equal<Awaited<typeof alone>["resources"][number]["key"], Ecs.Resource.Key>>();
+// @ts-expect-error its input comes first
+void world.run(move, { changes: true }, { distance: 1 });
+// @ts-expect-error a run asks only for its changes
+void world.run(main, { changes: false });
+
+void [counted, notText, nextValue, scaledValue, drawn, rows, composite, input, nothing, numbered, time, changes];
 
 // A body returns no promise: it starts the work, and a later run finishes it.
 // @ts-expect-error a body returns no promise
 System.create(() => Promise.resolve(1));
 // @ts-expect-error a body returns no promise
-System.create({ observer: true }, () => Promise.resolve(1));
+System.create({ readonly: true }, () => Promise.resolve(1));
 // @ts-expect-error a body returns no promise, a row system's neither
 System.create({ components: { with: [position] } }, () => Promise.resolve());
 // @ts-expect-error a body returns no promise, a render system's neither

package/src/interface/world/table/index.ts

@@ -0,0 +1,20 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+
+/**
+ * One component's values in a table, copies taken as a readonly system reads `tables`:
+ * - `bytes`: a struct's or number's, `stride` bytes per row in the world's layout for it, which is a function of the
+ *   component's schema alone;
+ * - `values`: a string's or an object's, one per row;
+ * - `value`: one value every row holds, for a shared component or one whose schema is a constant.
+ */
+export type Column =
+    | { readonly kind: "bytes"; readonly bytes: Uint8Array; readonly stride: number }
+    | { readonly kind: "values"; readonly values: readonly unknown[] }
+    | { readonly kind: "value"; readonly value: unknown };
+
+/**
+ * What `commands.spawnTables` spawned: each table's entities in its row order, the one spawned for each row, the one
+ * existing for a row its `existing` maps, and `Entity.none` for a row it didn't spawn; and how many rows it didn't,
+ * those owned by an entity outside the tables.
+ */
+export type Spawned = { readonly entities: readonly Float64Array[]; readonly dropped: number };

package/src/interface/world/table/table.ts

@@ -0,0 +1,12 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component } from '../../component/component.js';
+import type { Column } from './index.js';
+
+/** The rows of one archetype: their entities in row order, and a column for each component asked for that it holds. */
+export type Table = {
+    readonly count: number;
+    readonly entities: Float64Array;
+    readonly columns: { readonly [K in Component.Key]?: Column };
+};
+
+export type * as Table from './index.js';

package/src/interface/world/world.ts

@@ -1,35 +1,48 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Input } from '../system/input.js';
 import type { System } from '../system/system.js';
+import type { ChangeSet } from '../finalizer/body.js';
+import type { Essential } from '../component/value.js';
+import type { Resource } from '../resource/resource.js';
 
 /**
- * A world. Systems read and change it; observer systems read it after each run's and tick's sync point. Every member's
+ * A world. Systems read and change it; readonly systems read it after each run's and tick's sync point. Every member's
  * type is named from the package root, so declarations a consumer emits for its results name no internal module.
  */
 export type World = {
     /**
      * The one way to change state. Runs are sequential in call order; physically, any that don't conflict overlap. Each
-     * runs a system or composite, ending in a sync point, then observer systems, the run's and those added, and
+     * runs a system or composite, ending in a sync point, then readonly systems, the run's and those added, and
      * resolves to what a per-run body returns: a system without components resolves to its body's value, or
      * `undefined` when its body was skipped, and any other system or composite to nothing. So a one-off read is a run
-     * of an observer system returning what it read; one that runs on a joined thread, as it reads objects there, runs
-     * there before the run resolves, to its value as structured clone. A run of observer systems alone runs them once
+     * of a readonly system returning what it read; one that runs on a joined thread, as it reads objects there, runs
+     * there before the run resolves, to its value as structured clone. A run of readonly systems alone runs them once
      * after an empty sync point, and doesn't wake the loop.
      *
      * When a system or finalizer of the run fails, later tiers are skipped, the sync point still applies what was done,
-     * and once its observer systems ran the run rejects with an `Error` naming each failure, its system's label and id,
+     * and once its readonly systems ran the run rejects with an `Error` naming each failure, its system's label and id,
      * message and cause. It rejects too when the run can't happen or finish: registration fails, the world is disposed,
-     * its GPU device is lost, or its sync point can't apply a command's value. What fails after it, an observer system
+     * its GPU device is lost, or its sync point can't apply a command's value. What fails after it, a readonly system
      * added or GPU work, is reported out of band, as ticks' failures are (see `add`).
      */
     run<I, R>(system: System<I, R>, ...input: Input<NoInfer<I>>): Promise<R>;
+    /**
+     * Runs as `run` does, and resolves to this run's own changes, in the shape `Finalizer.changes` gives, rather than its
+     * value: the structural changes its commands made, rules and cascades included, to every component that isn't
+     * derived or an object a joined thread fills, the values its adds gave components entities had before and after, and
+     * each resource its systems write or reduce into whose value changed, compared as `Finalizer.changes` compares them;
+     * `previous` and `next` give values before and after the run. Commands the finalizers of an earlier sync point
+     * queued apply first, at a sync point of their own. Values written to rows aren't structural changes, so they're in
+     * none. The run pays for this only when asked. Only on the world's thread: a joined thread's rejects.
+     */
+    run<I, R>(system: System<I, R>, ...input: [...Input<NoInfer<I>>, options: { readonly changes: true }]): Promise<ChangeSet<Essential, Resource.Key>>;
     /**
      * Adds a system to every tick, from the next one on, ordered with those already added by its constraints, as a
      * composite's members are. A tick runs on a beat of the `cadence` resource where `always` is set, `wake` is due or
      * a run arrived since the last tick, and only while some system is added. Throws for a system with no ordering path
-     * to one already added that conflicts with it. An observer system runs after every run's and tick's sync point
+     * to one already added that conflicts with it. A readonly system runs after every run's and tick's sync point
      * instead. It never conflicts and doesn't count as an added system for ticking. On a joined thread `add` takes only
-     * observer systems, whose keys need ids: each runs on that thread after the world's sync points, once for the
+     * readonly systems, whose keys need ids: each runs on that thread after the world's sync points, once for the
      * newest when the thread fell behind, reading structs and the objects of the threads it fills as of one sync point.
      *
      * What added systems throw, and what fails in ticks, is reported out of band on the world's thread, as an `Error`
@@ -43,14 +56,14 @@ export type World = {
      * released. A system added both alone and within an added composite stays until both are removed; constraints
      * naming a removed system are ignored. Removing a value that isn't added does nothing. Throws, removing nothing,
      * when the systems left would conflict with no ordering path between them, as `add` does. On a joined thread it
-     * takes only observer systems.
+     * takes only readonly systems.
      */
     remove(system: System<void>): void;
     /**
      * Lets another thread join this world through `port`, one end of a channel to it, of the browser or node: a
      * `MessagePort`, a `Worker`, or a worker's own scope, `self` or node's `parentPort`. That thread joins through the
      * other end, claiming the logical threads it fills. Resolves once it has joined: the threads it claims are its own,
-     * and the observer systems it added as its join resolved, before awaiting anything else, are added, so a run
+     * and the readonly systems it added as its join resolved, before awaiting anything else, are added, so a run
      * started afterwards runs on it and reaches them; one it adds later reaches the runs after its add arrived.
      * Rejects with an `Error` saying why it didn't join: the world refused its claim, as of a thread claimed twice, the
      * world was disposed, the port is shared already, or that thread ended first, as the platform reports it: a

package/src/observe/entity.ts

@@ -129,14 +129,14 @@ const createShape = (state: WorldState, byShape: Map<string, EntityShape>, id: s
     let finders: Finders | null = null;
     let source: object | null = null;
     const system = optional.length === 0
-        ? System.create(labelled({ observer: true, lookup: { presence: { with: required, changed: required }, values: { with: required }, members: { index: membersOf(required), changed: required } } }, name, { lookup: { values: required } }), ({ lookup }) => {
+        ? System.create(labelled({ readonly: true, lookup: { presence: { with: required, changed: required }, values: { with: required }, members: { index: membersOf(required), changed: required } } }, name, { lookup: { values: required } }), ({ lookup }) => {
             if (source !== lookup || finders === null) {
                 source = lookup;
                 finders = { presence: lookup.presence, values: lookup.values, optional: noOptional };
             }
             pass(lookup.members().changed, finders);
         })
-        : System.create(labelled({ observer: true, lookup: optionalLookups(required, optional) }, name, { lookup: optionalReads(required, optional) }), ({ lookup }) => {
+        : System.create(labelled({ readonly: true, lookup: optionalLookups(required, optional) }, name, { lookup: optionalReads(required, optional) }), ({ lookup }) => {
             if (source !== lookup || finders === null) {
                 source = lookup;
                 finders = { presence: lookup.presence, values: lookup.values, optional: (index, entity) => lookup[index](entity) };

package/src/observe/resource.ts

@@ -31,14 +31,14 @@ const createShape = (state: WorldState, byKey: Map<Resource.Key, ResourceShape>,
     const label = `Observe.resource(${key.description ?? "?"})`;
     // On a joined thread, first values come once a run of this system resolved, never in its pass: none to skip.
     const { joined } = state;
-    const notifier = System.create(labelled({ observer: true, resources: { changed: [key] } }, label, { resources: [key] }), ({ resources }) => {
+    const notifier = System.create(labelled({ readonly: true, resources: { changed: [key] } }, label, { resources: [key] }), ({ resources }) => {
         passed(state);
         entry.value = resources[key];
         entry.valid = true;
         if (entry.stopped > 0) sweepSubscribers(entry);
         throwFailed(give(entry, 0, true, state.pass, joined ? -1 : state.pass, none));
     });
-    const reader = System.create(labelled({ observer: true }, label, { resources: [key] }), ({ resources }) => {
+    const reader = System.create(labelled({ readonly: true }, label, { resources: [key] }), ({ resources }) => {
         const through = shape.called.shift() ?? 0;
         entry.value = resources[key];
         entry.valid = true;

package/src/observe/select.ts

@@ -403,16 +403,16 @@ const createShape = (state: WorldState, byShape: Map<string, QueryShape>, id: st
     };
 
     const tracker = ordered !== null
-        ? System.create(labelled({ observer: true, lookup: { list: { index: ordered, changed: reads } } }, name, { lookup: { list: reads } }), ({ lookup }) => {
+        ? System.create(labelled({ readonly: true, lookup: { list: { index: ordered, changed: reads } } }, name, { lookup: { list: reads } }), ({ lookup }) => {
             track(lookup.list(), null, fromSorted);
         })
         : byRange !== null
-            ? System.create(labelled({ observer: true, lookup: { list: { index: byRange, changed: reads } } }, name, { lookup: { list: reads } }), ({ lookup }) => {
+            ? System.create(labelled({ readonly: true, lookup: { list: { index: byRange, changed: reads } } }, name, { lookup: { list: reads } }), ({ lookup }) => {
                 // A range is of a `where` condition on the index's key, which the query's type checked against its
                 // values.
                 track(null, entry => ownRange(entry, range => lookup.list(range as Parameters<typeof lookup.list>[0]), () => lookup.list()), fromSorted);
             })
-            : System.create(labelled({ observer: true, lookup: { list: { index: keylessOf(has, not), changed: reads } } }, name, { lookup: { list: reads } }), ({ lookup }) => {
+            : System.create(labelled({ readonly: true, lookup: { list: { index: keylessOf(has, not), changed: reads } } }, name, { lookup: { list: reads } }), ({ lookup }) => {
                 track(lookup.list(), null, fromKeyless);
             });
 
@@ -466,7 +466,7 @@ const createShape = (state: WorldState, byShape: Map<string, QueryShape>, id: st
         for (const entry of scan.entries) entry.gather.start();
         accept = acceptOf(scan.entries);
     };
-    const scanner = System.create(labelled({ observer: true, components: { with: [...reads, ...required.filter(key => !reads.includes(key))], not } }, name, { components: reads }), row => {
+    const scanner = System.create(labelled({ readonly: true, components: { with: [...reads, ...required.filter(key => !reads.includes(key))], not } }, name, { components: reads }), row => {
         if (accept === null) start();
         if (direct === 0) {
             accept?.(row);

package/src/observe/world-state.ts

@@ -116,7 +116,7 @@ const ignore = (): void => {
 };
 
 /** Runs nothing: a run of it resolves while its world lives. */
-const alive = System.create(labelled({ observer: true }, "Observe/alive"), () => {});
+const alive = System.create(labelled({ readonly: true }, "Observe/alive"), () => {});
 
 /**
  * What a rejected run of the factories' own does: nothing for a disposed world, whose first values never come, and for
@@ -232,7 +232,7 @@ export const stateOf = (world: World): WorldState => {
         deliveries: [],
         idle: [],
         rejected: rejectedOf(world),
-        deliver: System.create(labelled({ observer: true }, "Observe/deliver"), () => {
+        deliver: System.create(labelled({ readonly: true }, "Observe/deliver"), () => {
             const delivery = created.deliveries.shift();
             if (delivery === undefined) return;
             created.delivered = delivery.batch;
@@ -243,7 +243,7 @@ export const stateOf = (world: World): WorldState => {
     states.set(world, created);
     if (joined) return created;
     // Added before any shape's system, so in each pass it counts the pass before they run.
-    world.add(System.create(labelled({ observer: true }, "Observe/maintain"), () => {
+    world.add(System.create(labelled({ readonly: true }, "Observe/maintain"), () => {
         created.pass++;
         if (created.idle.length > 0) sweepShapes(created);
     }));