@adobe/ecs 0.0.0-stage → 0.2.0

package/src/implementation/world/arrivals.ts

@@ -0,0 +1,165 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { allocateArray } from './arrays.js';
+import type { Memory } from './memory.js';
+
+// The arrivals ring: rows moving between archetypes, a pair of archetypes per block of rows a sync point moves, for
+// systems with `where` and change filters, which keep a point per archetype. A row moved from an archetype the system
+// skipped holds changes it never saw, so its new archetype owes them: its rows pass the system's change filters since
+// the point of the archetype they came from, as of the move (`createDebts`). Written by the world's thread at sync
+// points, while a system with points registered or a joined thread holds claims, and read by each such system as it
+// runs, on the world's thread or a joined one, which finds it by the layout directory's header.
+
+/** The layout directory's header word holding the offset of the ring's control block, 0 before one is written. */
+export const arrivalsWord = 15;
+/**
+ * The control block's words: the entries written, modulo 2^32, stored after each; the capacity; the entries' offset;
+ * and how many times archetypes were reclaimed or reused, modulo 2^32 (`reclaim.ts`), which a joined thread's systems
+ * check to find their matches again.
+ */
+const positionWord = 0;
+const capacityWord = 1;
+const entriesOffsetWord = 2;
+export const membershipWord = 3;
+const controlWords = 16;
+/** An entry: the archetype rows moved from, the one they moved to, and the sync's tick, low and high words. */
+const entryWords = 4;
+/** A power of two, its entries a block of 64 KiB. A system further behind owes, for every archetype, its oldest point. */
+const capacity = 4096;
+
+/** The world's side of the ring: its control block and its entries, each a block of the memory when it's shared. */
+export type Arrivals = { readonly control: Uint32Array; readonly entries: Uint32Array };
+
+/** The ring, allocated with the first arrival logged. */
+export const createArrivals = (memory: Memory): Arrivals => {
+    const entries = allocateArray(memory, Uint32Array, capacity * entryWords).fill(0);
+    const control = allocateArray(memory, Uint32Array, controlWords).fill(0);
+    control[capacityWord] = capacity;
+    control[entriesOffsetWord] = entries.byteOffset;
+    if (memory.shared) Atomics.store(memory.header, arrivalsWord, control.byteOffset);
+    return { control, entries };
+};
+
+/** Logs rows moving from archetype `from` into `to` at a sync point of `tick`. */
+export const logArrival = ({ control, entries }: Arrivals, from: number, to: number, tick: number): void => {
+    const position = control[positionWord];
+    const at = (position & (capacity - 1)) * entryWords;
+    entries[at] = from;
+    entries[at + 1] = to;
+    entries[at + 2] = tick % 0x100000000;
+    entries[at + 3] = Math.floor(tick / 0x100000000);
+    Atomics.store(control, positionWord, (position + 1) >>> 0);
+};
+
+/** Where a reader finds the ring: its control block in `control` from word `controlAt`, its entries likewise. */
+export type ArrivalsView = { readonly control: Uint32Array; readonly controlAt: number; readonly entries: Uint32Array; readonly entriesAt: number };
+
+/** The world's thread's view of its ring. */
+export const viewOfArrivals = ({ control, entries }: Arrivals): ArrivalsView => ({ control, controlAt: 0, entries, entriesAt: 0 });
+
+/** A joined thread's view of the ring whose control block is at byte `offset` of the memory `words` cover. */
+export const viewInMemory = (words: Uint32Array, offset: number): ArrivalsView => {
+    const controlAt = offset >> 2;
+    return { control: words, controlAt, entries: words, entriesAt: words[controlAt + entriesOffsetWord] >> 2 };
+};
+
+/** How many times archetypes were reclaimed or reused, modulo 2^32: 0 before the ring is written. */
+export const membershipOf = (view: ArrivalsView | null): number => view === null ? 0 : Atomics.load(view.control, view.controlAt + membershipWord);
+
+/** The entries written so far, modulo 2^32, as a reader's cursor starts. */
+export const arrivalsPosition = (view: ArrivalsView | null): number => view === null ? 0 : Atomics.load(view.control, view.controlAt + positionWord);
+
+/**
+ * What archetypes owe a system with points: by archetype id, the oldest point rows moved into it since its own point
+ * were last seen at, by the system's point of each archetype they came from, or its last run for a non-match's. A row
+ * is counted changed in its new archetype only if it changed after that, so moves among archetypes the system saw cost
+ * nothing, and a run reads its arrivals once, however many archetypes it goes over.
+ */
+export type Debts = {
+    /** The point an archetype's rows pass change filters after: its own, or older for rows moved in from elsewhere. */
+    readonly sinceOf: (id: number, point: number) => number;
+    /**
+     * Reads arrivals through tick `through`, of `archetypes` archetypes, its last run `latest`; once the ring overwrote
+     * some unread, every archetype owes the oldest of `oldest()`, the system's oldest point, and what any owed.
+     */
+    readonly read: (view: ArrivalsView | null, through: number, archetypes: number, latest: number, oldest: () => number) => void;
+    /** Clears what an archetype owed, as its system runs over it. */
+    readonly settle: (id: number) => void;
+    /** The oldest debt, for what any archetype's rows may pass since; Infinity for none. */
+    readonly oldest: () => number;
+};
+
+/**
+ * The debts of a system with points: `points` by match, and `matchOf` by archetype id, its match or -1, its runner's,
+ * read as they are. Starts reading the ring at entry `start`.
+ */
+export const createDebts = (points: readonly number[], matchOf: readonly number[], start: number): Debts => {
+    /** By archetype id, Infinity for none. */
+    let owed = new Float64Array(64).fill(Infinity);
+    const ensure = (archetypes: number): void => {
+        if (archetypes <= owed.length) return;
+        let length = owed.length * 2;
+        while (length < archetypes) length *= 2;
+        const grown = new Float64Array(length).fill(Infinity);
+        grown.set(owed);
+        owed = grown;
+    };
+    let cursor = start;
+    /**
+     * Once the ring overwrote unread entries, the oldest point as of then, which every archetype owes again at the next
+     * read too: entries skipped may be of syncs after the run's, whose rows that run's archetypes didn't have yet.
+     */
+    let floor = Infinity;
+    const oldestOwed = (): number => {
+        let oldest = Infinity;
+        for (let id = 0; id < owed.length; id++) if (owed[id] < oldest) oldest = owed[id];
+        return oldest;
+    };
+    const owe = (archetypes: number, point: number): void => {
+        for (let id = 0; id < archetypes; id++) if (point < owed[id]) owed[id] = point;
+    };
+    /** Reads entries from the cursor through `through`; false when the ring overwrote some unread, before or while. */
+    const readThrough = (view: ArrivalsView, through: number, latest: number): boolean => {
+        const { control, controlAt, entries, entriesAt } = view;
+        const size = control[controlAt + capacityWord];
+        const pending = (Atomics.load(control, controlAt + positionWord) - cursor) >>> 0;
+        if (pending > size) return false;
+        let read = 0;
+        let debts = owed;
+        const mask = size - 1;
+        for (; read < pending; read++) {
+            const at = entriesAt + ((cursor + read) & mask) * entryWords;
+            if (entries[at + 2] + entries[at + 3] * 0x100000000 > through) break;
+            const from = entries[at];
+            const to = entries[at + 1];
+            if (from >= debts.length || to >= debts.length) {
+                ensure(Math.max(from, to) + 1);
+                debts = owed;
+            }
+            const m = matchOf[from];
+            let point = m >= 0 ? points[m] : latest;
+            if (debts[from] < point) point = debts[from];
+            if (point < debts[to]) debts[to] = point;
+        }
+        if (((Atomics.load(control, controlAt + positionWord) - cursor) >>> 0) > size) return false;
+        cursor = (cursor + read) >>> 0;
+        return true;
+    };
+    return {
+        sinceOf: (id, point) => id < owed.length && owed[id] < point ? owed[id] : point,
+        read: (view, through, archetypes, latest, oldest) => {
+            if (view === null) return;
+            ensure(archetypes);
+            const skipped = floor;
+            floor = Infinity;
+            if (skipped !== Infinity) owe(archetypes, skipped);
+            if (readThrough(view, through, latest)) return;
+            cursor = arrivalsPosition(view);
+            floor = Math.min(oldest(), oldestOwed(), skipped);
+            owe(archetypes, floor);
+        },
+        settle: id => {
+            if (id < owed.length) owed[id] = Infinity;
+        },
+        oldest: oldestOwed,
+    };
+};

package/src/implementation/world/async-loading.test.ts

@@ -0,0 +1,86 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { expect, it } from "vitest";
+import { Entity, Finalizer, Rule, type Schema, System, World } from "../../index.js";
+import { Observe } from "../../observe/index.js";
+import { createWorld } from "../index.js";
+
+const meshSource = Symbol("asyncLoading/meshSource");
+const hidden = Symbol("asyncLoading/hidden");
+const meshSlot = Symbol("asyncLoading/meshSlot");
+const meshReady = Symbol("asyncLoading/meshReady");
+const nextToken = Symbol("asyncLoading/nextToken");
+const requests = Symbol("asyncLoading/requests");
+
+type Request = { readonly entity: Entity; readonly token: number; readonly path: string };
+
+declare module "@adobe/ecs" {
+    interface Components {
+        [meshSource]: { type: string };
+        [hidden]: { type: true };
+        /** The token of the slot's load; a new one each time the slot starts over. */
+        [meshSlot]: { type: Schema.Type<{ type: "integer" }>; derived: true; default: 0 };
+        /** The loaded mesh's handle, which exists only while its slot does. */
+        [meshReady]: { type: Schema.Type<{ type: "integer" }>; within: typeof meshSlot };
+    }
+    interface Resources {
+        [nextToken]: { type: Schema.Type<{ type: "integer" }>; default: 1 };
+        [requests]: { type: Schema.Type<{ type: "array"; items: { type: "object"; properties: { entity: { type: "integer"; format: "entity" }; token: { type: "integer" }; path: { type: "string" } } } }>; default: [] };
+    }
+}
+
+
+/** Meshes loaded outside the world, by handle: as GPU buffers are. */
+const loaded = new Map<number, string>();
+let nextHandle = 1;
+const load = async (path: string): Promise<number> => {
+    loaded.set(nextHandle, path);
+    return nextHandle++;
+};
+
+// 1. A rule derives a slot for every visible entity with a mesh source.
+Rule.create({ components: { with: [meshSource], not: [hidden] }, derive: [meshSlot] });
+
+// 2. Each new slot gets a fresh token, and its load is requested; the application starts requested loads.
+const request = System.create({
+    components: { with: [meshSource, meshSlot], added: [meshSlot] },
+}, (row, { resources }) => {
+    const token = resources[nextToken];
+    resources[nextToken] = token + 1;
+    row[meshSlot] = token;
+    resources[requests] = [...resources[requests], { entity: row.entity, token, path: row[meshSource] }];
+});
+
+// 3. A completed load arrives as a run of its own. A slot whose token still matches gets the mesh; a stale one releases it.
+const apply = System.create({
+    lookup: { slots: { with: [meshSlot] } },
+}, ({ lookup, commands }, input: { readonly entity: Entity; readonly token: number; readonly handle: number }) => {
+    if (lookup.slots(input.entity)?.[meshSlot] === input.token) commands.add(input.entity, meshReady, input.handle);
+    else loaded.delete(input.handle);
+});
+
+// 4. When the slot goes, its mesh goes with it, and the finalizer releases what was loaded.
+Finalizer.create({ components: { with: [meshReady] } }, row => { loaded.delete(row[meshReady]); });
+
+const spawn = System.create({}, ({ commands }) => {
+    commands.spawn([meshSource])({ [meshSource]: "ship.glb" });
+    commands.spawn([meshSource])({ [meshSource]: "rock.glb" });
+});
+const hide = System.create({}, ({ commands }, input: { readonly entity: Entity }) => {
+    commands.add(input.entity, hidden);
+});
+
+it("loads resources asynchronously for derived slots, and releases them when the slot goes", async () => {
+    await using world = createWorld();
+    await world.run(spawn);
+    await world.run(request);
+    const [ship, rock] = await Observe.toPromise(Observe.resource(world, requests));
+    // The rock is hidden before its load completes, so its result is stale when it arrives.
+    await world.run(hide, { entity: rock.entity });
+    for (const { entity, token, path } of [ship, rock]) await world.run(apply, { entity, token, handle: await load(path) });
+    const ready = await Observe.toPromise(Observe.select(world, { required: [meshReady] }));
+    expect(await Promise.all(ready.map(async entity => loaded.get((await Observe.toPromise(Observe.entity(world, entity, { required: [meshReady] })))?.[meshReady] ?? 0)))).toEqual(["ship.glb"]);
+    expect([...loaded.values()]).toEqual(["ship.glb"]);
+    await world.run(hide, { entity: ship.entity });
+    expect(await Observe.toPromise(Observe.count(world, { required: [meshReady] }))).toBe(0);
+    expect(loaded.size).toBe(0);
+});

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

@@ -0,0 +1,17 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { expect, it } from "vitest";
+import { kernelOf } from "./attach-kernel.js";
+
+it("rejects a kernel lookup of a string, which kernels don't read, where the kernel is declared", async () => {
+    await expect(import("./kernel-lookup.test-helper.js")).rejects.toThrow(`a lookup reads "kernelLookupTest/label", a string, which kernels don't read yet.`);
+});
+
+it("rejects a compiled kernel that doesn't match its schemas where the kernel is declared", async () => {
+    await expect(import("./kernel-path.test-helper.js")).rejects.toThrow(`"kernelPathTest/pair" has no scalar at [2]; destructure tuples and structs or index their fields.`);
+});
+
+it("compiles an unflagged system whose body fits, and runs as written one whose kernel wouldn't match its schemas", async () => {
+    const { doubled, labels } = await import("./kernel-tried.test-helper.js");
+    expect(kernelOf(doubled)).toBeDefined();
+    expect(kernelOf(labels)).toBeUndefined();
+});

package/src/implementation/world/attach-kernel.ts

@@ -0,0 +1,31 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { definitionOf } from '../../interface/registry/index.js';
+import type { System } from '../../interface/system/system.js';
+import { unreadByKernel } from '../../interface/system/check.js';
+import { checkKernel, kernelMismatch } from './check-kernel.js';
+import type { KernelDescription } from './kernel.js';
+
+/** By the system `System.create` returned, so a lookup doesn't depend on which copy of the package defined it. */
+const kernels = new WeakMap<System<unknown>, KernelDescription>();
+
+/**
+ * The compiler's only hook into the runtime: wraps each kernel system's `System.create` call. Throws for a kernel that
+ * doesn't match its declaration and schemas (`checkKernel`), and for a key that's a list, which a command names as one
+ * component only where its build couldn't read the name's module. A kernel the build only `tried`, for a system
+ * without a `kernel` flag, attaches only where it matches, and the system otherwise runs as written.
+ */
+export const attachKernel = <S extends System<unknown>>(system: S, description: KernelDescription, tried = false): S => {
+    const listed = description.keys.some(key => Array.isArray(key));
+    const leaf = definitionOf(system);
+    if (tried) {
+        if (listed || leaf === undefined || leaf.kind === "composite" || unreadByKernel(leaf) !== null || kernelMismatch(leaf, description) !== null) return system;
+        kernels.set(system, description);
+        return system;
+    }
+    if (listed) throw new Error(`System "${system.name}" names a list of components where a command takes one component; its kernel's build couldn't read the list, so name it from a module the build reads, or as an array literal.`);
+    if (leaf !== undefined && leaf.kind !== "composite") checkKernel(leaf, description);
+    kernels.set(system, description);
+    return system;
+};
+
+export const kernelOf = (system: System<unknown>): KernelDescription | undefined => kernels.get(system);

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

@@ -0,0 +1,126 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Entity } from "../../interface/entity/entity.js";
+import type { Schema } from "../../interface/schema/schema.js";
+import { System } from "../../interface/system/system.js";
+import { count, read, readEach, readEntity } from "./reads.test-helper.js";
+import { createWorld } from "./create.js";
+import { workers } from "../../interface/resources/workers.js";
+import { Observe } from "../../observe/index.js";
+import { createBuffer } from "./buffer.js";
+import { createCommands } from "./commands.js";
+import { createState } from "./state.js";
+import { runReported } from "./outcomes.test-helper.js";
+import type { F32 } from "../../interface/math/index.js";
+
+type Vec3 = readonly [number, number, number];
+const vec3 = { type: "array", items: { type: "number", precision: 1 }, minItems: 3, maxItems: 3 } as const satisfies Schema;
+const position = Symbol("batchesTest/position");
+const score = Symbol("batchesTest/score");
+const name = Symbol("batchesTest/name");
+const tag = Symbol("batchesTest/tag");
+declare module "@adobe/ecs" {
+    export interface Components {
+        [position]: { type: Schema.Type<{ type: "array"; items: { type: "number"; precision: 1 }; minItems: 3; maxItems: 3 }> };
+        [score]: { type: F32 };
+        [name]: { type: string };
+        [tag]: { type: true };
+    }
+}
+
+describe("staged spawns", () => {
+    it("are seen once by `added` observers in earlier, the same and later tiers, and not before the sync point", async () => {
+        const seen = { early: 0, same: 0, late: 0 };
+        const spawned: Entity[] = [];
+        const early = System.create({ components: { added: [score] } }, () => { seen.early++; });
+        const spawn = System.create({ after: [early] }, ({ commands }) => {
+            if (spawned.length > 0) return;
+            for (let i = 0; i < 100; i++) spawned.push(commands.spawn([position, score, name, tag])({ [position]: [i, i, i], [score]: i, [name]: `${i}`, [tag]: true }));
+        });
+        const same = System.create({ components: { added: [score] }, after: [early] }, () => { seen.same++; });
+        const late = System.create({ components: { added: [score] }, after: [spawn, same] }, () => { seen.late++; });
+        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 });
+        await world.run(frame);
+        await world.run(frame);
+        expect(seen).toEqual({ early: 100, same: 100, late: 100 });
+        expect(await Promise.all(spawned.map(entity => readEntity(world, entity, [position, score, name, tag])))).toEqual(
+            spawned.map((_, i) => ({ [position]: [i, i, i], [score]: i, [name]: `${i}`, [tag]: true })));
+        await world.dispose();
+    });
+
+    it("can be changed, removed, re-added or despawned in the run that spawns them", async () => {
+        const spawned: Entity[] = [];
+        const edit = System.create({}, ({ commands }) => {
+            for (let i = 0; i < 4; i++) spawned.push(commands.spawn([score, name])({ [score]: i, [name]: `${i}` }));
+            commands.add(spawned[0], score, 10);
+            commands.remove(spawned[1], name);
+            commands.remove(spawned[2], name);
+            commands.add(spawned[2], name, "again");
+            commands.despawn(spawned[3]);
+        });
+        const world = createWorld({ [workers]: 0 });
+        await world.run(edit);
+        expect(await Promise.all(spawned.map(async entity => [await read(world, entity, score), await read(world, entity, name)]))).toEqual([[10, "0"], [1, null], [2, "again"], [null, null]]);
+        expect(await count(world, { required: [score] })).toBe(3);
+        await world.dispose();
+    });
+
+    it("keep the spawns before a value that can't be written, and release that one's entity", async () => {
+        const spawned: Entity[] = [];
+        let poison = true;
+        const spawn = System.create({}, ({ commands }) => {
+            for (let i = 0; i < 3; i++) spawned.push(commands.spawn([position, score])({ [position]: [i, 0, 0], [score]: i }));
+            // A symbol can't convert to a number, so writing it throws.
+            if (poison) commands.spawn([position, score])({ [position]: [0, 0, 0], [score]: Symbol("x") as unknown as number });
+        });
+        const world = createWorld({ [workers]: 0 });
+        expect((await runReported(world, spawn)).failures).toHaveLength(1);
+        expect(await readEach(world, spawned, score)).toEqual([0, 1, 2]);
+        poison = false;
+        await world.run(spawn);
+        expect(await count(world, { required: [score] })).toBe(6);
+        expect(await readEach(world, spawned, score)).toEqual([0, 1, 2, 0, 1, 2]);
+        await world.dispose();
+    });
+
+    it("take value objects built before the spawn", async () => {
+        const spawned: Entity[] = [];
+        const spawn = System.create({}, ({ commands }) => {
+            for (let i = 0; i < 20; i++) {
+                const values = i % 2 === 0 ? { [position]: [i, 0, 1] as const, [score]: i, [name]: `${i}` } : { [score]: i, [position]: [i, 0, 1] as const, [name]: `${i}` };
+                spawned.push(commands.spawn([position, score, name])(values));
+            }
+        });
+        const world = createWorld({ [workers]: 0 });
+        await world.run(spawn);
+        expect(await Promise.all(spawned.map(entity => readEntity(world, entity, [position, score, name])))).toEqual(
+            spawned.map((_, i) => ({ [position]: [i, 0, 1], [score]: i, [name]: `${i}` })));
+        await world.dispose();
+    });
+});
+
+describe("spawns keyed by symbols", () => {
+    it("are staged into a batch, not queued as commands", () => {
+        const state = createState();
+        const buffer = createBuffer();
+        const commands = createCommands(state, { buffer });
+        commands.spawn([score, tag])({ [score]: 1 });
+        expect(buffer.count).toBe(0);
+        expect(state.batches.map(batch => batch.count)).toEqual([1]);
+    });
+    it("read only their components' values, as adds do", async () => {
+        let spawned = Entity.none;
+        const edit = System.create({}, ({ commands }) => {
+            const values = { [score]: 1, "batchesTest/score": 2, [name]: "a" };
+            spawned = commands.spawn([score])(values);
+            commands.add(spawned, [score], values);
+        });
+        await using world = createWorld({ [workers]: 0 });
+        await world.run(edit);
+        expect(await Observe.toPromise(Observe.entity(world, spawned, { optional: [position, score, name, tag] }))).toEqual({ [score]: 1 });
+    });
+});

package/src/implementation/world/batches.ts

@@ -0,0 +1,185 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { ensureCapacity, noShared, type Archetype } from './archetype.js';
+import type { CommandBuffer } from './buffer.js';
+import { indexOf } from './entities.js';
+import { blockShift, chunkShift } from './kernel.js';
+import { createBatch, type SpawnBatch } from './staging.js';
+import { archetypeOf, type State } from './state.js';
+import { gainsOf } from './structure.js';
+import { remoteError } from './remote.js';
+import { countChanged } from './layout-directory.js';
+import { logRange, logSet, startTag, tagOf } from './move-log.js';
+import { writeDefault } from './synchronize.js';
+import { writeString } from './strings.js';
+import { cacheShared, internShared } from './shared.js';
+
+/** Batches of at most this many rows commit element by element. */
+const smallCopy = 8;
+
+/**
+ * The batch of main-thread spawns of exactly these components, with these shared values by component id, made on first
+ * use.
+ */
+export const batchOf = (state: State, ids: readonly number[], shared: readonly (number | undefined)[] = noShared): SpawnBatch => {
+    const sorted = [...ids].sort((a, b) => a - b);
+    const key = shared === noShared ? sorted.join(",") : keyOf(sorted, shared);
+    let batch = state.batchByKey.get(key);
+    if (batch === undefined) {
+        batch = createBatch(state.layouts, ids, shared);
+        for (const column of batch.columns) if (state.remote[column.id] !== undefined) column.remote = remoteError(state, column.id).message;
+        state.batchByKey.set(key, batch);
+        state.batches.push(batch);
+        if (shared !== noShared) letGoWith(state, batch, key);
+    }
+    return batch;
+};
+
+/** A batch's key: its sorted component ids, each shared one with the number of its value. */
+const keyOf = (sorted: readonly number[], shared: readonly (number | undefined)[]): string =>
+    sorted.map(id => shared[id] === undefined ? `${id}` : `${id}=${shared[id]}`).join(",");
+
+/**
+ * Lets go of a batch of shared values, keyed `key`, once any of them is dropped, so batches don't pile up as values
+ * come and go. A spawner still holding it revives it as it next spawns: its values are interned again and it's listed
+ * once more, with numbers that may be new.
+ */
+const letGoWith = (state: State, batch: SpawnBatch, key: string): void => {
+    const held = batch.ids.flatMap(id => {
+        const number = batch.shared[id];
+        const values = state.shared[id];
+        return number === undefined || values === undefined ? [] : [{ id, values, value: values.values[number], number }];
+    });
+    const unregister: (() => void)[] = [];
+    const drop = (): void => {
+        for (const letGo of unregister) letGo();
+        if (state.batchByKey.get(key) === batch) state.batchByKey.delete(key);
+        const at = state.batches.indexOf(batch);
+        if (at >= 0) state.batches.splice(at, 1);
+        batch.archetype = null;
+        batch.capacity = batch.count;
+        batch.revive = () => {
+            const shared: (number | undefined)[] = [];
+            for (const { id, values, value } of held) shared[id] = internShared(values, value);
+            batch.shared = shared;
+            batch.capacity = batch.entities.length;
+            const again = keyOf(batch.ids, shared);
+            if (!state.batchByKey.has(again)) state.batchByKey.set(again, batch);
+            state.batches.push(batch);
+            letGoWith(state, batch, again);
+        };
+    };
+    for (const { values, number } of held) unregister.push(cacheShared(values, number, drop));
+};
+
+/**
+ * A batch's archetype, found the first time it commits, and again once it was reclaimed or reused for other values
+ * (`reclaim.ts`), which its generation tells.
+ */
+const archetypeOfBatch = (state: State, batch: SpawnBatch): Archetype => {
+    const known = batch.archetype;
+    if (known !== null && !known.reclaimed && known.generation === batch.generation) return known;
+    const archetype = archetypeOf(state, batch.ids, batch.shared);
+    batch.archetype = archetype;
+    batch.generation = archetype.generation;
+    return archetype;
+};
+
+/**
+ * Copies rows `first` to `first + n` of a batch into its archetype, or into its closure under `close` when rules or
+ * `within` apply, places their entities, writes the defaults of derived components the target gains, and stamps their
+ * ticks with the sync point's tick, as a commanded spawn would be. `born` records the first row each target gains.
+ */
+const commitRows = (state: State, batch: SpawnBatch, first: number, n: number, tick: number, born: Map<number, number>, close: ((archetype: Archetype) => Archetype) | null): void => {
+    const spawned = archetypeOfBatch(state, batch);
+    const target = close === null ? spawned : close(spawned);
+    ensureCapacity(state.memory, target, target.count + n);
+    const start = target.count;
+    if (!born.has(target.id)) born.set(target.id, start);
+    if (close !== null) {
+        for (const id of gainsOf(state.structure, state.derived, null, target)) {
+            const storage = target.storageById[id];
+            if (storage !== undefined) for (let row = start; row < start + n; row++) writeDefault(state, storage, row, tick);
+        }
+    }
+    // A few rows copy element by element: a subarray to copy from costs more than they do.
+    if (n <= smallCopy) for (let i = 0; i < n; i++) target.entities[start + i] = batch.entities[first + i];
+    else target.entities.set(batch.entities.subarray(first, first + n), start);
+    if (target.logs !== null) for (const log of target.logs) logRange(log, target.id, start, n, batch.entities, first);
+    if (state.counting) countChanged(state.counted, target);
+    for (const column of batch.columns) {
+        const storage = target.storageById[column.id];
+        if (storage === undefined) continue;
+        if (column.layout.kind === "linear") {
+            const bytes = n * column.stride;
+            const from = first * column.stride;
+            const offset = start * column.stride;
+            if (n <= smallCopy) for (let i = 0; i < bytes; i++) storage.views.u8[offset + i] = column.views.u8[from + i];
+            else storage.views.u8.set(column.views.u8.subarray(from, from + bytes), offset);
+        }
+        else if (column.layout.kind === "object") {
+            if (storage.remote === null) for (let i = 0; i < n; i++) storage.values[start + i] = column.values[first + i];
+            else {
+                // A joined thread's objects start at their starts there, as the rows' range says: a tag set otherwise.
+                const log = storage.remote;
+                const begin = log.starts[column.id];
+                for (let i = 0; i < n; i++) {
+                    const tag = Math.max(startTag, tagOf(column.values[first + i], begin));
+                    storage.tags[start + i] = tag;
+                    if (tag !== startTag) logSet(log, target.id, start + i, column.id, tag, true);
+                }
+            }
+            column.values.fill(undefined, first, first + n);
+        }
+        // Rows past the count hold no record, so nothing is let go.
+        else if (column.layout.kind === "string") {
+            for (let i = 0; i < n; i++) writeString(storage, start + i, column.values[first + i]);
+            column.values.fill(undefined, first, first + n);
+        }
+        if (!storage.ticked) continue;
+        storage.added.fill(tick, start, start + n);
+        if (storage.changed !== storage.added) storage.changed.fill(tick, start, start + n);
+        // Ticks only increase, so the newest tick in each chunk and block the rows reach is this one.
+        storage.blockAdded.fill(tick, start >> blockShift, ((start + n - 1) >> blockShift) + 1);
+        if (storage.blockChanged !== storage.blockAdded) storage.blockChanged.fill(tick, start >> blockShift, ((start + n - 1) >> blockShift) + 1);
+        storage.chunkAdded.fill(tick, start >> chunkShift, ((start + n - 1) >> chunkShift) + 1);
+        if (storage.chunkChanged !== storage.chunkAdded) storage.chunkChanged.fill(tick, start >> chunkShift, ((start + n - 1) >> chunkShift) + 1);
+    }
+    const { entities } = state;
+    for (let i = 0; i < n; i++) {
+        const index = indexOf(batch.entities[first + i]);
+        entities.archetype[index] = target.id;
+        entities.row[index] = start + i;
+    }
+    target.count += n;
+    state.touched?.add(target);
+};
+
+/** At a sync point, before the plan: commits and empties every main-thread batch. Returns the entities committed. */
+export const commitBatches = (state: State, tick: number, born: Map<number, number>, close: ((archetype: Archetype) => Archetype) | null): number => {
+    let committed = 0;
+    for (const batch of state.batches) {
+        const n = batch.count;
+        if (n === 0) continue;
+        commitRows(state, batch, 0, n, tick, born, close);
+        batch.count = 0;
+        committed += n;
+    }
+    return committed;
+};
+
+/**
+ * Then, in merge order, the kernel spawns each queued buffer staged; their runner or worker empties the batches before
+ * staging into them again. Returns the entities committed.
+ */
+export const commitStaged = (state: State, queued: readonly { readonly buffer: CommandBuffer }[], tick: number, born: Map<number, number>, close: ((archetype: Archetype) => Archetype) | null): number => {
+    let committed = 0;
+    for (let b = 0; b < queued.length; b++) {
+        const { buffer } = queued[b];
+        for (let s = 0; s < buffer.stagedCount; s++) {
+            const { batch, start, end } = buffer.staged[s];
+            commitRows(state, batch, start, end - start, tick, born, close);
+            committed += end - start;
+        }
+    }
+    return committed;
+};