@adobe/ecs 0.2.3 → 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/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/tables.ts

@@ -1,16 +1,22 @@
 // © 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` and `not` that holds any of
+ * 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[];
 };
 

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

@@ -62,7 +62,17 @@ 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

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

@@ -13,7 +13,8 @@ export type Column =
     | { readonly kind: "value"; readonly value: unknown };
 
 /**
- * What `commands.spawnTables` spawned: each table's new entities in its row order, `Entity.none` for a row it didn't
- * spawn, and how many rows it didn't, those owned by an entity outside the tables.
+ * 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/world.ts

@@ -1,6 +1,9 @@
 // © 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; readonly systems read it after each run's and tick's sync point. Every member's
@@ -23,6 +26,16 @@ export type World = {
      * 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

package/src/perftest/benchmarks.ts

@@ -35,6 +35,7 @@ import { Observe } from "../observe/index.js";
 import { entitiesWith } from "./observer.js";
 import { invariantBenchmarks } from "./invariants.js";
 import { journalBenchmarks } from "./journal.js";
+import { tableBenchmarks } from "./tables.js";
 
 /** A world whose kernels run on this thread, which the benchmarks without a placement measure; `workers` ones use the pool. */
 const inline = (): World => createWorld({ [workers]: 0 });
@@ -648,6 +649,22 @@ export const benchmarks: readonly Benchmark[] = [
             return best;
         },
     },
+    ...[10, 1_000, 100_000].flatMap(n => ([
+        ["rows", "a command per row", structural.despawnDoomedRows, 24],
+        ["where", "one `despawnWhere`", structural.despawnDoomedWhere, 16],
+    ] as const).map(([how, by, system, bytes]): Benchmark => {
+        const name = `despawn tagged ${n >= 1_000 ? `${n / 1_000}K` : n} ${how}`;
+        return {
+            name,
+            operation: `A run despawning the ${n >= 1_000 ? `${n / 1_000}K` : n} entities of a tag beside 100K others, by ${by}: clearing one kind, such as expired effects.`,
+            per: "despawns",
+            n,
+            typical: [10, 100_000],
+            best: { bytes, basis: bytes === 16 ? "Each despawn frees its 8-byte location and entity; the archetype empties, so no row moves." : "Each row reads its entity; each despawn frees its location and entity." },
+            run: () => structuralBest(1, world => world.run(structural.spawnDoomed, { count: n }), world => world.run(system),
+                async world => await countOf(world, [structural.doomed]) === 0, name),
+        };
+    })),
     ...([
         ["add tag", "Adding a tag to 100K entities of one archetype: a state flag set on many at once.", 1, structural.removeFlag, structural.addFlag, [structural.flag], 16],
         ["add tag kernel", "The same adds from a kernel.", 1, structural.removeFlagKernel, structural.addFlagKernel, [structural.flag], 20],
@@ -705,4 +722,5 @@ export const benchmarks: readonly Benchmark[] = [
     ...sharedBenchmarks,
     ...invariantBenchmarks,
     ...journalBenchmarks,
+    ...tableBenchmarks,
 ];

package/src/perftest/structural.ts

@@ -12,6 +12,7 @@ export const flag = Symbol("structural/flag");
 export const amount = Symbol("structural/amount");
 export const extra = Symbol("structural/extra");
 export const spawned = Symbol("structural/spawned");
+export const doomed = Symbol("structural/doomed");
 const source1 = Symbol("structural/source1");
 const source2 = Symbol("structural/source2");
 const t0 = Symbol("structural/t0");
@@ -27,6 +28,7 @@ declare module "@adobe/ecs" {
         [amount]: { type: F32 };
         [extra]: { type: F32 };
         [spawned]: { type: true };
+        [doomed]: { type: true };
         [source1]: { type: true };
         [source2]: { type: true };
         [t0]: { type: true };
@@ -128,6 +130,24 @@ export const removeFlagKernel = System.create({ kernel: true, components: { with
     commands.remove(row.entity, flag);
 });
 
+const doomedList = [index, value, doomed] as const;
+const doomedQuery = { with: [doomed] } as const;
+
+/** `count` spawns of entities tagged `doomed`, beside the seeded ones. */
+export const spawnDoomed = System.create({}, ({ commands }, input: { readonly count: number }) => {
+    for (let i = 0; i < input.count; i++) commands.spawn(doomedList)({ [index]: i, [value]: i });
+});
+
+/** Despawns every `doomed` entity, a command per row. */
+export const despawnDoomedRows = System.create({ kernel: false, components: { with: [doomed] } }, (row, { commands }) => {
+    commands.despawn(row.entity);
+});
+
+/** Despawns every `doomed` entity, by one command. */
+export const despawnDoomedWhere = System.create({}, ({ commands }) => {
+    commands.despawnWhere(doomedQuery);
+});
+
 export const addAmount = System.create({ kernel: false, components: { with: [index], not: [amount, spawned] } }, (row, { commands }) => {
     commands.add(row.entity, amount, row[index]);
 });

package/src/perftest/tables.ts

@@ -0,0 +1,107 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Entity } from "../interface/entity/entity.js";
+import type { Vec3 } from "../interface/math/index.js";
+import { workers } from "../interface/resources/workers.js";
+import { System } from "../interface/system/system.js";
+import type { Tables } from "../interface/system/tables.js";
+import type { Table } from "../interface/world/table/table.js";
+import { createWorld } from "../implementation/index.js";
+import type { Benchmark } from "./benchmark.js";
+
+// Spawning 1M entities into a fresh world in one sync point, each owned by an earlier one or by none: from tables, as
+// loading a snapshot does, and from commands; and the same tables without the owner reference.
+
+const position = Symbol("tables/position");
+const owner = Symbol("tables/owner");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [position]: { type: Vec3 };
+        [owner]: { type: Entity; reference: "owner" };
+    }
+}
+
+const count = 1_000_000;
+
+/** A root and `count - 1` entities, each owned by the one at half its position. */
+const build = System.create(({ commands }) => {
+    const made: Entity[] = [commands.spawn([position])({ [position]: [0, 0, 0] })];
+    const owned = commands.spawn([position, owner]);
+    for (let i = 1; i < count; i++) made.push(owned({ [position]: [i, i, i], [owner]: made[i >> 1] }));
+});
+
+const tablesOf = (components: readonly (typeof position | typeof owner)[]) =>
+    System.create({ readonly: true, tables: { components } }, ({ tables }): Tables => tables);
+
+const given: { tables: readonly Table[] } = { tables: [] };
+const spawnGiven = System.create(({ commands }) => {
+    commands.spawnTables(given.tables);
+});
+
+/** The fastest of a few runs spawning `tables` into a fresh world. */
+const spawnFastest = async (tables: readonly Table[]): Promise<number> => {
+    let best = Infinity;
+    for (let k = 0; k < 7; k++) {
+        const world = createWorld({ [workers]: 0 });
+        given.tables = tables;
+        const start = performance.now();
+        await world.run(spawnGiven);
+        const time = performance.now() - start;
+        // The first runs warm up.
+        if (k >= 2) best = Math.min(best, time);
+        await world.dispose();
+    }
+    given.tables = [];
+    return best;
+};
+
+const tables = async (components: readonly (typeof position | typeof owner)[]): Promise<number> => {
+    const world = createWorld({ [workers]: 0 });
+    await world.run(build);
+    const { archetypes } = await world.run(tablesOf(components));
+    await world.dispose();
+    return spawnFastest(archetypes);
+};
+
+/** The fastest of a few runs of `build` in a fresh world. */
+const commanded = async (): Promise<number> => {
+    let best = Infinity;
+    for (let k = 0; k < 7; k++) {
+        const world = createWorld({ [workers]: 0 });
+        const start = performance.now();
+        await world.run(build);
+        const time = performance.now() - start;
+        if (k >= 2) best = Math.min(best, time);
+        await world.dispose();
+    }
+    return best;
+};
+
+export const tableBenchmarks: readonly Benchmark[] = [
+    {
+        name: "spawn tables 1M owner",
+        operation: "commands.spawnTables of 1M entities into a fresh world, each but one owned by another of them, and its sync point: loading a snapshot of a hierarchy.",
+        per: "spawns",
+        n: count,
+        typical: [1_000, 1_000_000],
+        best: { bytes: 36, basis: "Each entity copies its 12-byte position and 8-byte owner, and writes its 8-byte entity and location." },
+        run: () => tables([position, owner]),
+    },
+    {
+        name: "spawn tables 1M",
+        operation: "As `spawn tables 1M owner`, without the owner reference: its cost is the difference.",
+        per: "spawns",
+        n: count,
+        typical: [1_000, 1_000_000],
+        best: { bytes: 28, basis: "Each entity copies its 12-byte position, and writes its 8-byte entity and location." },
+        run: () => tables([position]),
+    },
+    {
+        name: "spawn owned 1M",
+        operation: "A main-thread system spawning 1M entities through one spawner, each but one owned by an earlier one, and its sync point.",
+        per: "spawns",
+        n: count,
+        typical: [1_000, 1_000_000],
+        best: { bytes: 36, basis: "Each entity writes its 12-byte position and 8-byte owner, its 8-byte entity and location." },
+        run: commanded,
+    },
+];