@adobe/ecs 0.2.3 → 0.2.4

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

@@ -29,7 +29,7 @@ declare module "@adobe/ecs" {
 }
 
 describe("staged spawns", () => {
-    it("are seen once by `added` observers in earlier, the same and later tiers, and not before the sync point", async () => {
+    it("are seen once by `added` observers in earlier, the same and later tiers, from the sync point after them", async () => {
         const seen = { early: 0, same: 0, late: 0 };
         const spawned: Entity[] = [];
         const early = System.create({ components: { added: [score] } }, () => { seen.early++; });
@@ -42,8 +42,8 @@ describe("staged spawns", () => {
         const frame = System.create({ systems: [early, spawn, same, late] });
         const world = createWorld({ [workers]: 0 });
         await world.run(frame);
-        // Nothing saw the spawns during their own run.
-        expect(seen).toEqual({ early: 0, same: 0, late: 0 });
+        // Only what follows the spawn saw them in their own run, after the sync point it needs.
+        expect(seen).toEqual({ early: 0, same: 0, late: 100 });
         await world.run(frame);
         await world.run(frame);
         expect(seen).toEqual({ early: 100, same: 100, late: 100 });

package/src/implementation/world/buffer.ts

@@ -7,6 +7,13 @@ export const spawnCommand = 0;
 export const despawnCommand = 1;
 export const addCommand = 2;
 export const removeCommand = 3;
+/**
+ * Names the ids of its query's `with`, then of its `not`, and with a `where`, last, `despawnWhereHolds`, whose value is
+ * whether an archetype holds the `where`'s values; its entity is how many are of `with`.
+ */
+export const despawnWhereCommand = 4;
+/** The id a `despawnWhere` names its `where` by, which no component has. */
+export const despawnWhereHolds = -1;
 
 /** Rows `start` to `end` of a kernel's spawn batch, committed in its buffer's place in merge order. */
 export type Staged = { batch: SpawnBatch; start: number; end: number };

package/src/implementation/world/cascade.ts

@@ -1,7 +1,7 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Archetype } from './archetype.js';
 import { readCell } from './cells.js';
-import { indexOf, locate } from './entities.js';
+import { generationOf, indexOf, locate } from './entities.js';
 import { commandValue, isMissing } from './finalizers.js';
 import { createHolders, fitHolders, forEachHolder, linkHolder, unlinkHolder } from './holders.js';
 import { closureOf, owner } from './structure.js';
@@ -9,8 +9,8 @@ import { archetypeOf, withoutComponent, type State } from './state.js';
 import type { Queued } from './synchronize.js';
 
 /**
- * A reference value written in this sync point: by spawn or add commands, or a batch spawn. `holder`, `component`
- * and `target` triples, checked once the plan's despawns are known.
+ * A reference value written in this sync point to check: by spawn or add commands, or of a row spawned that `linkBorn`
+ * leaves to the cascade. `holder`, `component` and `target` triples, checked once the plan's despawns are known.
  */
 export type Written = number[];
 
@@ -41,6 +41,48 @@ const aliveAfter = (state: State, target: number): boolean => {
     return locate(entities, target) >= 0;
 };
 
+/**
+ * Links each reference the rows spawned in this sync point hold to its target, before the cascade, so a target it
+ * despawns finds them as it finds any holder. One naming an entity that won't be alive isn't linked, and goes to
+ * `written` to cascade, as does every reference of a row a command touched, which the command may point elsewhere.
+ * The rows spawned into an archetype are those from `first`, by archetype id; an entity is one f64.
+ */
+export const linkBorn = (state: State, born: ReadonlyMap<number, number>, written: Written, tick: number): void => {
+    const { plan, structure, archetypes, entities, referencesWritten } = state;
+    const { slots } = plan;
+    for (const [id, first] of born) {
+        const archetype = archetypes[id];
+        const { count } = archetype;
+        if (first >= count) continue;
+        const rows = archetype.entities;
+        for (const component of structure.referenceIds) {
+            const storage = archetype.storageById[component];
+            if (storage === undefined) continue;
+            referencesWritten[component] = tick;
+            const lists = structure.holders[component] ??= createHolders();
+            fitHolders(lists, entities.length);
+            const { unitStride, unitOffset } = storage;
+            const values = storage.views.f64;
+            // `aliveAfter`, through locals, since it runs for each row spawned.
+            const { archetype: archetypeOfIndex, generation, length } = entities;
+            const { entity: planned, despawned } = plan;
+            for (let row = first; row < count; row++) {
+                const target = values[row * unitStride + unitOffset];
+                if (target === 0) continue;
+                const holder = rows[row];
+                const index = indexOf(holder);
+                const commanded = index < slots.length && slots[index] >= 0;
+                const into = indexOf(target);
+                const entry = into < slots.length ? slots[into] : -1;
+                const alive = entry >= 0 && planned[entry] === target ? despawned[entry] === 0
+                    : into < length && archetypeOfIndex[into] >= 0 && generation[into] === generationOf(target);
+                if (alive) linkHolder(lists, target, holder);
+                if (commanded || !alive) written.push(holder, component, target);
+            }
+        }
+    }
+};
+
 /**
  * Despawns the holders that own a reference to an entity that is despawned or never lives, and removes `weak`
  * references to one, transitively, before rules close the plan. A holder acts only if its value once the plan applies
@@ -91,7 +133,7 @@ export const cascadeReferences = (state: State, queued: readonly Queued[], writt
  */
 export type IndexChanges = { readonly remove: number[]; readonly add: number[] };
 
-export const indexChangesOf = (state: State, queued: readonly Queued[], fromOf: (entry: number) => Archetype | null, bornRows: readonly (readonly [Archetype, number])[]): IndexChanges => {
+export const indexChangesOf = (state: State, queued: readonly Queued[], fromOf: (entry: number) => Archetype | null): IndexChanges => {
     const { plan, structure, entities } = state;
     const changes: IndexChanges = { remove: [], add: [] };
     for (let entry = 0; entry < plan.count; entry++) {
@@ -106,24 +148,6 @@ export const indexChangesOf = (state: State, queued: readonly Queued[], fromOf:
             if (typeof after === "number" && after !== 0) changes.add.push(after, holder, component);
         }
     }
-    // Batch spawns no command touched still hold the references they were spawned with. An entity is one f64.
-    const { slots } = plan;
-    for (const [archetype, first] of bornRows) {
-        for (const component of structure.referenceIds) {
-            const storage = archetype.storageById[component];
-            if (storage === undefined) continue;
-            const { unitStride, unitOffset } = storage;
-            const values = storage.views.f64;
-            const rows = archetype.entities;
-            for (let row = first; row < archetype.count; row++) {
-                const holder = rows[row];
-                const index = indexOf(holder);
-                if (index < slots.length && slots[index] >= 0) continue;
-                const value = values[row * unitStride + unitOffset];
-                if (value !== 0) changes.add.push(value, holder, component);
-            }
-        }
-    }
     return changes;
 };
 

package/src/implementation/world/commands.ts

@@ -1,10 +1,13 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Commands } from '../../interface/system/commands.js';
-import { addCommand, createBuffer, despawnCommand, pushCommand, pushComponent, removeCommand, spawnCommand, type CommandBuffer } from './buffer.js';
+import { addCommand, createBuffer, despawnCommand, despawnWhereCommand, despawnWhereHolds, pushCommand, pushComponent, removeCommand, spawnCommand, type CommandBuffer } from './buffer.js';
+import type { Archetype } from './archetype.js';
 import { reserve } from './entities.js';
 import { listShapeOf, presetSpawnerOf, spawnerOf, type ListShape } from './lists.js';
-import { commandIdOf, idOf, storedShared, type Key, type State } from './state.js';
+import { commandIdOf, idOf, queryIdOf, storedShared, type Key, type State } from './state.js';
 import { spawnTables } from './tables.js';
+import { holdsValuesOf } from './where.js';
+import { checkWhereValues } from '../../interface/system/check.js';
 import { declarationOf, isWorldWritten, kindOf, labelOf, threadOfDeclaration, whyUnregistered } from '../../interface/registry/index.js';
 import { matchesSchema } from '../../interface/registry/schemas.js';
 
@@ -83,6 +86,32 @@ const queueResources = (state: State, resources: object): void => {
 /** Values of a list add given none, which only an untyped caller does. */
 const empty = {};
 
+const noKeys: readonly unknown[] = [];
+
+/**
+ * Queues a `despawnWhere`, its ids resolved and its `where` checked first, so a key that isn't a component, or a `where`
+ * that isn't of shared values, queues nothing.
+ */
+const pushDespawnWhere = (state: State, buffer: CommandBuffer, query: Parameters<Commands["despawnWhere"]>[0]): void => {
+    const including: readonly unknown[] = query.with;
+    const excluding: readonly unknown[] = query.not ?? noKeys;
+    const { where } = query;
+    if (including.length === 0) throw new Error("commands.despawnWhere's `with` names at least one component.");
+    for (let k = 0; k < including.length; k++) queryIdOf(state, including[k]);
+    for (let k = 0; k < excluding.length; k++) queryIdOf(state, excluding[k]);
+    let holds: ((archetype: Archetype) => boolean) | null = null;
+    if (where !== undefined && Object.getOwnPropertySymbols(where).length > 0) {
+        checkWhereValues("commands.despawnWhere", "where", "a despawn", where, false);
+        const found = holdsValuesOf(state, where, false);
+        if (typeof found === "symbol") throw new Error(`commands.despawnWhere: where names "${labelOf(found)}", which isn't a shared component.`);
+        holds = found;
+    }
+    pushCommand(buffer, despawnWhereCommand, including.length);
+    for (let k = 0; k < including.length; k++) pushComponent(buffer, queryIdOf(state, including[k]), undefined);
+    for (let k = 0; k < excluding.length; k++) pushComponent(buffer, queryIdOf(state, excluding[k]), undefined);
+    if (holds !== null) pushComponent(buffer, despawnWhereHolds, holds);
+};
+
 /**
  * Commands that queue for the next sync point. A key that isn't a component commands may name throws here, inside the
  * issuing system, before anything is queued. Values are immutable by convention, so they aren't copied.
@@ -97,6 +126,7 @@ export const createCommands = (state: State, target: { readonly buffer: CommandB
     despawn: entity => {
         pushCommand(target.buffer, despawnCommand, entity);
     },
+    despawnWhere: query => pushDespawnWhere(state, target.buffer, query),
     add: (entity: number, components: symbol | readonly symbol[], values?: unknown) => {
         const { buffer } = target;
         if (typeof components === "symbol") {
@@ -119,10 +149,11 @@ export const createCommands = (state: State, target: { readonly buffer: CommandB
             pushComponent(buffer, ids[k], value === undefined ? starts[k] : value);
         }
     },
-    spawnTables: (tables, resources) => {
-        if (resources === undefined) return spawnTables(state, tables);
+    spawnTables: (tables, options) => {
+        const resources = options?.resources;
+        if (resources === undefined) return spawnTables(state, tables, options?.existing);
         checkResources(resources);
-        const spawned = spawnTables(state, tables);
+        const spawned = spawnTables(state, tables, options?.existing);
         queueResources(state, resources);
         return spawned;
     },

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

@@ -71,28 +71,28 @@ const positions = async (world: World): Promise<Vec2[]> =>
     (await readEach(world, await select(world, { required: [position], order: { [position]: true } }), position)).map(value => value ?? [NaN, NaN]);
 
 describe("World.create", () => {
-    it("spawns once from a changed resource, then integrates", async () => {
+    it("spawns once from a changed resource, then integrates, from the run that spawns", async () => {
         const world = createWorld();
         await world.run(main);
-        expect(await positions(world)).toEqual([[0, 0], [1, 0], [2, 0]]);
-        await world.run(main);
         expect(await positions(world)).toEqual([[0, 1], [1, 1], [2, 1]]);
+        await world.run(main);
+        expect(await positions(world)).toEqual([[0, 2], [1, 2], [2, 2]]);
         expect(await readResource(world, spawnCount)).toBe(3);
     });
 
     it("reports each change to a system exactly once", async () => {
         const world = createWorld();
         await world.run(main);
-        // Spawned at the sync point, after watch ran: seen on the next run.
-        expect(await readResource(world, seen)).toBe(0);
-        await world.run(main);
+        // Spawned at the sync point before move, which watch follows: seen in the same run.
         expect(await readResource(world, seen)).toBe(3);
+        await world.run(main);
+        expect(await readResource(world, seen)).toBe(6);
         // Moved before watch in the last run, so already reported.
         await world.run(watch);
-        expect(await readResource(world, seen)).toBe(3);
+        expect(await readResource(world, seen)).toBe(6);
         await world.run(move);
         await world.run(watch);
-        expect(await readResource(world, seen)).toBe(6);
+        expect(await readResource(world, seen)).toBe(9);
     });
 
     it("applies the net structural change of a sync point", async () => {

package/src/implementation/world/create.ts

@@ -1,7 +1,7 @@
 // © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Finalizer } from '../../interface/finalizer/created.js';
 import type { Rule } from '../../interface/rule/created.js';
-import { requireDefinition, type Definition } from '../../interface/registry/index.js';
+import { definitionOf, requireDefinition, type Definition } from '../../interface/registry/index.js';
 import type { World } from '../../interface/world/world.js';
 import type { Input } from '../../interface/system/input.js';
 import type { System } from '../../interface/system/system.js';
@@ -43,6 +43,10 @@ import { stampChanged } from './archetype.js';
 import { createLoop, platformFrame, platformTimer, type Clock, type LoopPlatform } from './loop.js';
 import { presetLevelsOf } from './lists.js';
 import { createState, defaultOf, idOf, reside, startTicking, type Key } from './state.js';
+import { asksForChanges, changesOf, resourcesWrittenBy, startRecording, takesInput } from './run-changes.js';
+import type { ChangeSet } from '../../interface/finalizer/body.js';
+import type { Essential } from '../../interface/component/value.js';
+import type { Resource } from '../../interface/resource/resource.js';
 import { indexOf } from './entities.js';
 import { touchedHeld } from './up.js';
 import { isHeld } from './transfers.js';
@@ -53,6 +57,9 @@ type Queue = <T>(task: () => T | Promise<T>) => Promise<T>;
 
 /** A task's failure as the queue's own chain carries it, which never rejects: made only when a task fails. */
 type Carried = { readonly thrown: unknown };
+/** A schedule of nothing, whose run is its sync point alone. */
+const noTiers: Schedule = { tiers: [], reductions: new Map(), observer: [], syncs: [] };
+
 const thrownValues = new WeakSet<object>();
 const thrownOf = (error: unknown): Carried => {
     const wrapped = { thrown: error };
@@ -956,9 +963,57 @@ export const createWorld = (resources: InitialResources = {}, options: WorldOpti
         },
     });
 
+    /**
+     * Runs a system or composite, recording its own changes, which it resolves to: what earlier finalizers queued
+     * applies first, at a sync point of its own, and the recording covers the run's sync points alone.
+     */
+    const runChanging = (definition: Definition, value: unknown): Promise<unknown> => {
+        const started = enqueue(() => startChanges(definition));
+        const ran = runWith(definition, value);
+        const taken = enqueue(takeChanges);
+        return Promise.all([started, ran, taken]).then(([, , changes]) => changes);
+    };
+    const startChanges = (definition: Definition): unknown => {
+        checkLive();
+        const flushed = execution(definition, undefined, noTiers);
+        if (flushed instanceof Promise) return flushed.then(report => startRecordingOf(definition, report));
+        startRecordingOf(definition, flushed);
+        return undefined;
+    };
+    const startRecordingOf = (definition: Definition, flushed: RunReport): void => {
+        outOfBand.reportAll(flushed.failures);
+        state.recording = startRecording(state, resourcesWrittenBy(definition));
+    };
+    const takeChanges = (): unknown => {
+        const { recording } = state;
+        state.recording = null;
+        if (recording === null) throw new Error("The run's changes weren't recorded.");
+        return changesOf(state, recording);
+    };
+
+    function run<I, R>(system: System<I, R>, ...input: Input<NoInfer<I>>): Promise<R>;
+    function run<I, R>(system: System<I, R>, ...input: [...Input<NoInfer<I>>, options: { readonly changes: true }]): Promise<ChangeSet<Essential, Resource.Key>>;
+    function run(system: System<unknown, unknown>, ...args: readonly unknown[]): Promise<unknown> {
+        // Options come last, so a run not asking for changes reads one value more.
+        const { length } = args;
+        if (length === 0 || !asksForChanges(args[length - 1])) return runWith(system, args[0]);
+        const definition = definitionOf(system);
+        let input = false;
+        try {
+            input = definition !== undefined && takesInput(definition);
+        }
+        catch {
+            // A composite whose schedule can't be made fails its run, as `runWith` finds.
+            return runWith(system, args[0]);
+        }
+        // A system taking input whose input is all it was given runs with it.
+        if (definition === undefined || (input && args.length < 2)) return runWith(system, args[0]);
+        return runChanging(definition, input ? args[0] : undefined);
+    }
+
     const world: CreatedWorld = {
         // A run gives what its system's body returned, `R` by the system's type.
-        run: <I, R>(system: System<I, R>, ...input: Input<NoInfer<I>>) => runWith(system, input[0]) as Promise<R>,
+        run,
         share: port => {
             if (disposed) return Promise.reject(new Error("The world is disposed."));
             if (!state.memory.shared) return Promise.reject(new Error("Without cross-origin isolation memory can't be shared, so no thread can join."));

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

@@ -0,0 +1,287 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Entity } from "../../interface/entity/entity.js";
+import { Finalizer } from "../../interface/finalizer/finalizer.js";
+import { Rule } from "../../interface/rule/rule.js";
+import type { Commands } from "../../interface/system/commands.js";
+import { System } from "../../interface/system/system.js";
+import type { World } from "../../interface/world/world.js";
+import { workers } from "../../interface/resources/workers.js";
+import { Observe } from "../../observe/index.js";
+import { createWorld } from "./create.js";
+import { runReported } from "./outcomes.test-helper.js";
+import { count, read, readResource } from "./reads.test-helper.js";
+
+const mark = Symbol("despawnWhereTest/mark");
+const kept = Symbol("despawnWhereTest/kept");
+const value = Symbol("despawnWhereTest/value");
+const extra = Symbol("despawnWhereTest/extra");
+const host = Symbol("despawnWhereTest/host");
+const derivedFrom = Symbol("despawnWhereTest/derivedFrom");
+const slot = Symbol("despawnWhereTest/slot");
+const parent = Symbol("despawnWhereTest/parent");
+const finalized = Symbol("despawnWhereTest/finalized");
+const watched = Symbol("despawnWhereTest/watched");
+const trigger = Symbol("despawnWhereTest/trigger");
+const level = Symbol("despawnWhereTest/level");
+const journal = Symbol("despawnWhereTest/journal");
+const chunk = Symbol("despawnWhereTest/chunk");
+// Never declared, so never registered.
+const unregistered = Symbol("despawnWhereTest/unregistered");
+
+declare module "@adobe/ecs" {
+    export interface Components {
+        [mark]: { type: true };
+        [kept]: { type: true };
+        [value]: { type: number };
+        [extra]: { type: true };
+        [host]: { type: true };
+        [derivedFrom]: { type: true };
+        [slot]: { type: number; derived: true };
+        [parent]: { type: Entity; reference: "owner" };
+        [finalized]: { type: number };
+        [watched]: { type: number };
+        [trigger]: { type: true };
+        [chunk]: { type: number; shared: true };
+    }
+    export interface Resources {
+        [level]: { type: number };
+        [journal]: { type: readonly string[]; default: [] };
+    }
+}
+
+Rule.create({ components: { with: [host, derivedFrom] }, derive: [slot] });
+
+const seen: number[] = [];
+Finalizer.create({ components: { with: [finalized] } }, row => { seen.push(row[finalized]); });
+
+Finalizer.changes({ watch: [watched, mark] }, (changes, { resources }) => {
+    const lines = changes.groups.map(group => `${group.entities.map(entity => changes.previous(entity, watched)).join(",")}: +${group.added.length} -${group.removed.length}`);
+    resources[journal] = [...resources[journal], ...lines];
+});
+
+/** A world, and a function running `body` once in a system with the world's commands, rejecting with what it threw. */
+const withCommands = () => {
+    const world = createWorld({ [workers]: 0 });
+    let body: (commands: Commands) => void = () => {};
+    const issue = System.create({}, ({ commands }) => body(commands));
+    const run = async (next: (commands: Commands) => void): Promise<void> => {
+        body = next;
+        const [failure] = (await runReported(world, issue)).failures;
+        if (failure !== undefined) throw new Error(failure.message);
+    };
+    return { world, run };
+};
+
+const alive = async (world: World, entity: Entity): Promise<boolean> =>
+    (await Observe.toPromise(Observe.entity(world, entity, { optional: [mark] }))) !== null;
+
+const aliveEach = (world: World, entities: readonly Entity[]): Promise<boolean[]> => Promise.all(entities.map(entity => alive(world, entity)));
+
+describe("despawnWhere", () => {
+    it("despawns every entity with each `with` component and no `not` one, across archetypes", async () => {
+        const { world, run } = withCommands();
+        const spawned: Entity[] = [];
+        await run(commands => {
+            for (let i = 0; i < 3; i++) {
+                spawned.push(commands.spawn([mark])());
+                spawned.push(commands.spawn([mark, value])({ [value]: i }));
+                spawned.push(commands.spawn([mark, value, extra])({ [value]: i }));
+                spawned.push(commands.spawn([value])({ [value]: i }));
+                spawned.push(commands.spawn([mark, kept])());
+            }
+        });
+        await run(commands => commands.despawnWhere({ with: [mark], not: [kept] }));
+        expect(await aliveEach(world, spawned)).toEqual([0, 1, 2].flatMap(() => [false, false, false, true, true]));
+        await run(commands => commands.despawnWhere({ with: [value, mark] }));
+        expect(await count(world, { required: [value] })).toBe(3);
+        await world.dispose();
+    });
+
+    it("selects by the commands issued before it at the sync point; later ones to a despawned entity do nothing", async () => {
+        const { world, run } = withCommands();
+        let gains = Entity.none, loses = Entity.none, gainsAfter = Entity.none, changedAfter = Entity.none;
+        await run(commands => {
+            gains = commands.spawn([value])({ [value]: 1 });
+            loses = commands.spawn([mark, value])({ [value]: 2 });
+            gainsAfter = commands.spawn([value])({ [value]: 3 });
+            changedAfter = commands.spawn([mark, value])({ [value]: 4 });
+        });
+        await run(commands => {
+            commands.add(gains, mark);
+            commands.remove(loses, mark);
+            commands.despawnWhere({ with: [mark] });
+            commands.add(gainsAfter, mark);
+            commands.add(changedAfter, extra);
+        });
+        expect(await aliveEach(world, [gains, loses, gainsAfter, changedAfter])).toEqual([false, true, true, false]);
+        expect(await read(world, gainsAfter, mark)).toBe(true);
+        await world.dispose();
+    });
+
+    it("despawns matching entities spawned at the same sync point, whenever spawned, since spawns commit first", async () => {
+        const { world, run } = withCommands();
+        const spawned: Entity[] = [];
+        await run(commands => {
+            spawned.push(commands.spawn([mark, value])({ [value]: 1 }));
+            commands.despawnWhere({ with: [mark] });
+            spawned.push(commands.spawn([mark, value])({ [value]: 2 }));
+            spawned.push(commands.spawn([value])({ [value]: 3 }));
+        });
+        expect(await aliveEach(world, spawned)).toEqual([false, false, true]);
+        await world.dispose();
+    });
+
+    it("matches derived components, by where earlier commands leave an entity once derived", async () => {
+        const { world, run } = withCommands();
+        let derived = Entity.none, deriving = Entity.none, underived = Entity.none;
+        await run(commands => {
+            derived = commands.spawn([host, derivedFrom])();
+            deriving = commands.spawn([host])();
+            underived = commands.spawn([host, derivedFrom])();
+        });
+        expect(await read(world, derived, slot)).not.toBeNull();
+        await run(commands => {
+            commands.add(deriving, derivedFrom);
+            commands.remove(underived, derivedFrom);
+            commands.despawnWhere({ with: [slot] });
+        });
+        expect(await aliveEach(world, [derived, deriving, underived])).toEqual([false, false, true]);
+        await world.dispose();
+    });
+
+    it("runs finalizers for each entity it despawns, reading its values", async () => {
+        const { world, run } = withCommands();
+        seen.length = 0;
+        await run(commands => {
+            for (let i = 0; i < 4; i++) commands.spawn(i % 2 === 0 ? [finalized, mark] : [finalized])({ [finalized]: i });
+        });
+        await run(commands => commands.despawnWhere({ with: [mark, finalized] }));
+        expect(seen.sort()).toEqual([0, 2]);
+        await world.dispose();
+        seen.length = 0;
+    });
+
+    it("gives a changes finalizer the same changes as a despawn of each", async () => {
+        const journals: (readonly string[])[] = [];
+        for (const despawn of [
+            (commands: Commands, entities: readonly Entity[]) => { for (const entity of entities) commands.despawn(entity); },
+            (commands: Commands) => commands.despawnWhere({ with: [mark] }),
+        ]) {
+            const { world, run } = withCommands();
+            const entities: Entity[] = [];
+            await run(commands => {
+                for (let i = 0; i < 3; i++) entities.push(commands.spawn([watched, mark])({ [watched]: i }));
+                entities.push(commands.spawn([watched, mark, extra])({ [watched]: 9 }));
+                commands.spawn([watched])({ [watched]: 5 });
+            });
+            await run(commands => despawn(commands, entities));
+            journals.push(await readResource(world, journal));
+            await world.dispose();
+        }
+        expect(journals[1]).toEqual(journals[0]);
+        expect(journals[1]).toContain("0,1,2: +0 -2");
+    });
+
+    it("cascades owner references as a despawn does", async () => {
+        const { world, run } = withCommands();
+        let root = Entity.none, child = Entity.none, other = Entity.none;
+        await run(commands => {
+            root = commands.spawn([mark])();
+            child = commands.spawn([parent, value])({ [parent]: root, [value]: 1 });
+            other = commands.spawn([value])({ [value]: 2 });
+        });
+        await run(commands => commands.despawnWhere({ with: [mark] }));
+        expect(await aliveEach(world, [root, child, other])).toEqual([false, false, true]);
+        await world.dispose();
+    });
+
+    it("never despawns the resource entity", async () => {
+        const { world, run } = withCommands();
+        const set = System.create({}, ({ resources, commands }) => {
+            resources[level] = 3;
+            commands.spawn([mark])();
+            commands.despawnWhere({ with: [mark] });
+        });
+        await world.run(set);
+        await run(commands => commands.despawnWhere({ with: [mark] }));
+        expect(await readResource(world, level)).toBe(3);
+        expect(await count(world, { required: [mark] })).toBe(0);
+        await world.dispose();
+    });
+
+    it("throws in the issuing system, queuing nothing, for an empty `with` or a key that isn't a component", async () => {
+        const { world, run } = withCommands();
+        let entity = Entity.none;
+        await run(commands => { entity = commands.spawn([mark])(); });
+        // @ts-expect-error `with` names at least one component
+        await expect(run(commands => commands.despawnWhere({ with: [] }))).rejects.toThrow("names at least one component");
+        // @ts-expect-error never registered
+        await expect(run(commands => commands.despawnWhere({ with: [mark], not: [unregistered] }))).rejects.toThrow("no registered schema");
+        // @ts-expect-error a resource
+        await expect(run(commands => commands.despawnWhere({ with: [level] }))).rejects.toThrow("is a resource");
+        expect(await alive(world, entity)).toBe(true);
+        await world.dispose();
+    });
+
+    it("runs in a system over rows, which isn't a kernel", async () => {
+        const { world, run } = withCommands();
+        const clear = System.create({ components: { with: [trigger] } }, (_row, { commands }) => {
+            commands.despawnWhere({ with: [mark] });
+        });
+        await run(commands => {
+            for (let i = 0; i < 5; i++) commands.spawn([mark, value])({ [value]: i });
+            commands.spawn([trigger])();
+            commands.spawn([trigger])();
+        });
+        const { failures } = await runReported(world, clear);
+        expect(failures).toEqual([]);
+        expect(await count(world, { required: [mark] })).toBe(0);
+        expect(await count(world, { required: [trigger] })).toBe(2);
+        await world.dispose();
+    });
+
+    it("keeps to the archetypes holding where's shared values, each required as with requires it", async () => {
+        const { world, run } = withCommands();
+        const spawned: Entity[] = [];
+        await run(commands => {
+            spawned.push(commands.spawn([mark, chunk], { [chunk]: 1 })());
+            spawned.push(commands.spawn([mark, value, chunk], { [chunk]: 1 })({ [value]: 1 }));
+            spawned.push(commands.spawn([mark, chunk], { [chunk]: 2 })());
+            spawned.push(commands.spawn([mark])());
+            spawned.push(commands.spawn([value, chunk], { [chunk]: 1 })({ [value]: 2 }));
+        });
+        await run(commands => commands.despawnWhere({ with: [mark], where: { [chunk]: 1 } }));
+        expect(await aliveEach(world, spawned)).toEqual([false, false, true, true, true]);
+        await world.dispose();
+    });
+
+    it("despawns by where the entities spawned at the same sync point, and none for a value no archetype holds", async () => {
+        const { world, run } = withCommands();
+        const spawned: Entity[] = [];
+        await run(commands => {
+            spawned.push(commands.spawn([mark, chunk], { [chunk]: 1 })());
+            commands.despawnWhere({ with: [mark], where: { [chunk]: 1 } });
+            spawned.push(commands.spawn([mark, chunk], { [chunk]: 2 })());
+            commands.despawnWhere({ with: [mark], where: { [chunk]: 3 } });
+        });
+        expect(await aliveEach(world, spawned)).toEqual([false, true]);
+        await run(commands => commands.despawnWhere({ with: [mark], where: {} }));
+        expect(await aliveEach(world, spawned)).toEqual([false, false]);
+        await world.dispose();
+    });
+
+    it("throws for a where that isn't values of shared components, queuing nothing", async () => {
+        const { world, run } = withCommands();
+        let entity = Entity.none;
+        await run(commands => { entity = commands.spawn([mark, chunk], { [chunk]: 1 })(); });
+        // @ts-expect-error where names only shared components
+        await expect(run(commands => commands.despawnWhere({ with: [mark], where: { [value]: 1 } }))).rejects.toThrow(/where names "despawnWhereTest\/value", which isn't a shared component/);
+        // @ts-expect-error where takes values, not predicates
+        await expect(run(commands => commands.despawnWhere({ with: [mark], where: { [chunk]: (given: number) => given === 1 } }))).rejects.toThrow(/gives "despawnWhereTest\/chunk" a predicate/);
+        // @ts-expect-error a value of the component's type
+        await expect(run(commands => commands.despawnWhere({ with: [mark], where: { [chunk]: "1" } }))).rejects.toThrow(/isn't one of its type's values/);
+        expect(await alive(world, entity)).toBe(true);
+        await world.dispose();
+    });
+});