@adobe/ecs 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,66 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { blockShift, chunkShift } from "./kernel.js";
+import { forEachNewerRow, forEachPassingRange, type Filter } from "./ranges.js";
+
+const rows = 5000;
+
+/** A filter over `rows` rows at tick 1, with `changed` rows at tick 9, their chunks and blocks raised. */
+const filterOf = (changed: readonly number[]): { readonly ticks: Float64Array; readonly chunks: Float64Array; readonly blocks: Float64Array } => {
+    const ticks = new Float64Array(rows).fill(1);
+    const chunks = new Float64Array((rows >> chunkShift) + 1).fill(1);
+    const blocks = new Float64Array(chunks.length << (chunkShift - blockShift)).fill(1);
+    for (const row of changed) {
+        ticks[row] = chunks[row >> chunkShift] = blocks[row >> blockShift] = 9;
+    }
+    return { ticks, chunks, blocks };
+};
+
+const ranges = (filters: readonly Filter[], lastRun: number, start = 0, end = rows): (readonly [number, number])[] => {
+    const found: (readonly [number, number])[] = [];
+    forEachPassingRange(filters, lastRun, start, end, (first, last) => found.push([first, last]));
+    return found;
+};
+
+describe("forEachPassingRange", () => {
+    it("gives each maximal run of rows with a newer tick, across blocks and chunks", () => {
+        const filter = filterOf([3, 4, 5, 63, 64, 1023, 1024, 4999]);
+        expect(ranges([filter], 5)).toEqual([[3, 6], [63, 65], [1023, 1025], [4999, 5000]]);
+        expect(ranges([filter], 5, 4, 1024)).toEqual([[4, 6], [63, 65], [1023, 1024]]);
+        expect(ranges([filter], 9)).toEqual([]);
+    });
+
+    it("skips a chunk or a block whose tick isn't newer without reading its rows", () => {
+        const filter = filterOf([2000]);
+        filter.ticks[2100] = 9;
+        filter.ticks[3100] = 9;
+        // Row 2100's block and row 3100's chunk say nothing in them changed.
+        expect(ranges([filter], 5)).toEqual([[2000, 2001]]);
+    });
+
+    it("passes a row any of several filters passes", () => {
+        const first = filterOf([10, 3000]);
+        const second = filterOf([11, 4000]);
+        expect(ranges([first, second], 5)).toEqual([[10, 12], [3000, 3001], [4000, 4001]]);
+        expect(ranges([first, second], 5, 11, 3001)).toEqual([[11, 12], [3000, 3001]]);
+    });
+
+    it("passes every row with no filters or a lastRun below 0", () => {
+        const filter = filterOf([]);
+        expect(ranges([], 5, 7, 70)).toEqual([[7, 70]]);
+        expect(ranges([filter], -1, 7, 70)).toEqual([[7, 70]]);
+    });
+});
+
+describe("forEachNewerRow", () => {
+    it("gives each row with a newer tick, skipping chunks and blocks whose tick isn't", () => {
+        const { ticks, chunks, blocks } = filterOf([0, 64, 1500, 4999]);
+        ticks[1600] = 9;
+        const found: number[] = [];
+        forEachNewerRow(ticks, chunks, blocks, rows, 5, row => found.push(row));
+        expect(found).toEqual([0, 64, 1500, 4999]);
+        found.length = 0;
+        forEachNewerRow(ticks, chunks, blocks, 1501, 5, row => found.push(row));
+        expect(found).toEqual([0, 64, 1500]);
+    });
+});

package/src/implementation/world/ranges.ts

@@ -0,0 +1,110 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { blockShift, chunkShift } from './kernel.js';
+
+/**
+ * One `added` or `changed` filter: per-row ticks, the newest tick of each chunk of rows, and the newest tick of each
+ * block of rows within a chunk.
+ */
+export type Filter = { readonly ticks: Float64Array; readonly chunks: Float64Array; readonly blocks: Float64Array };
+
+/** Whether any filter's chunk tick of `chunk` is newer than `lastRun`. */
+const chunkNewer = (filters: readonly Filter[], chunk: number, lastRun: number): boolean => {
+    for (let i = 0; i < filters.length; i++) if (filters[i].chunks[chunk] > lastRun) return true;
+    return false;
+};
+
+const blockNewer = (filters: readonly Filter[], block: number, lastRun: number): boolean => {
+    for (let i = 0; i < filters.length; i++) if (filters[i].blocks[block] > lastRun) return true;
+    return false;
+};
+
+const rowNewer = (filters: readonly Filter[], row: number, lastRun: number): boolean => {
+    for (let i = 0; i < filters.length; i++) if (filters[i].ticks[row] > lastRun) return true;
+    return false;
+};
+
+/**
+ * Calls `each` with every row below `count` whose tick in `ticks` is newer than `since`, skipping chunks, then blocks,
+ * whose ticks aren't.
+ */
+export const forEachNewerRow = (ticks: Float64Array, chunks: Float64Array, blocks: Float64Array, count: number, since: number, each: (row: number) => void): void => {
+    for (let chunk = 0, last = (count - 1) >> chunkShift; chunk <= last; chunk++) {
+        if (!(chunks[chunk] > since)) continue;
+        for (let block = chunk << (chunkShift - blockShift), end = Math.min((chunk + 1) << (chunkShift - blockShift), ((count - 1) >> blockShift) + 1); block < end; block++) {
+            if (!(blocks[block] > since)) continue;
+            for (let row = block << blockShift, rowEnd = Math.min(count, (block + 1) << blockShift); row < rowEnd; row++) if (ticks[row] > since) each(row);
+        }
+    }
+};
+
+/** `forEachPassingRange` for one filter, whose loops each read one array. */
+const forEachPassingRangeOf = (filter: Filter, lastRun: number, start: number, end: number, call: (start: number, end: number) => void): void => {
+    const { ticks, chunks, blocks } = filter;
+    const lastChunk = (end - 1) >> chunkShift;
+    let row = start;
+    while (row < end) {
+        let chunk = row >> chunkShift;
+        if (!(chunks[chunk] > lastRun)) {
+            do chunk++; while (chunk <= lastChunk && !(chunks[chunk] > lastRun));
+            if (chunk > lastChunk) return;
+            row = chunk << chunkShift;
+        }
+        const chunkEnd = Math.min(end, (chunk + 1) << chunkShift);
+        const lastBlock = (chunkEnd - 1) >> blockShift;
+        let block = row >> blockShift;
+        if (!(blocks[block] > lastRun)) {
+            do block++; while (block <= lastBlock && !(blocks[block] > lastRun));
+            if (block > lastBlock) {
+                row = chunkEnd;
+                continue;
+            }
+            row = block << blockShift;
+        }
+        const blockEnd = Math.min(chunkEnd, (block + 1) << blockShift);
+        while (row < blockEnd && !(ticks[row] > lastRun)) row++;
+        if (row === blockEnd) continue;
+        // A passing range runs on by row ticks alone, past blocks and chunks, until a row doesn't pass.
+        const first = row;
+        do row++; while (row < end && ticks[row] > lastRun);
+        call(first, row);
+    }
+};
+
+/**
+ * Calls `call` for each maximal range of rows in `start` to `end` that passes the change filters: any tick newer
+ * than `lastRun`. Chunks, then blocks, with no newer tick are skipped without reading their rows, so finding the rows
+ * costs a check per chunk, one per block of a chunk that changed, and one per row of a block that changed. With no
+ * filters, or `lastRun` below 0, every row passes.
+ */
+export const forEachPassingRange = (filters: readonly Filter[], lastRun: number, start: number, end: number, call: (start: number, end: number) => void): void => {
+    if (lastRun < 0 || filters.length === 0) return call(start, end);
+    if (start >= end) return;
+    if (filters.length === 1) return forEachPassingRangeOf(filters[0], lastRun, start, end, call);
+    const lastChunk = (end - 1) >> chunkShift;
+    let row = start;
+    while (row < end) {
+        let chunk = row >> chunkShift;
+        if (!chunkNewer(filters, chunk, lastRun)) {
+            do chunk++; while (chunk <= lastChunk && !chunkNewer(filters, chunk, lastRun));
+            if (chunk > lastChunk) return;
+            row = chunk << chunkShift;
+        }
+        const chunkEnd = Math.min(end, (chunk + 1) << chunkShift);
+        const lastBlock = (chunkEnd - 1) >> blockShift;
+        let block = row >> blockShift;
+        if (!blockNewer(filters, block, lastRun)) {
+            do block++; while (block <= lastBlock && !blockNewer(filters, block, lastRun));
+            if (block > lastBlock) {
+                row = chunkEnd;
+                continue;
+            }
+            row = block << blockShift;
+        }
+        const blockEnd = Math.min(chunkEnd, (block + 1) << blockShift);
+        while (row < blockEnd && !rowNewer(filters, row, lastRun)) row++;
+        if (row === blockEnd) continue;
+        const first = row;
+        do row++; while (row < end && rowNewer(filters, row, lastRun));
+        call(first, row);
+    }
+};

package/src/implementation/world/reads.test-helper.ts

@@ -0,0 +1,30 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Component } from '../../interface/component/component.js';
+import type { ReadonlyValue } from '../../interface/component/value.js';
+import type { Entity } from '../../interface/entity/entity.js';
+import type { Resource } from '../../interface/resource/resource.js';
+import type { ReadonlyValue as ReadonlyResourceValue } from '../../interface/resource/value.js';
+import type { World } from '../../interface/world/world.js';
+import { Observe } from '../../observe/index.js';
+
+// Tests' reads: each is the first value of an observer factory of `src/observe`.
+
+/** One component of an entity, or `null` if it's dead or lacks it. */
+export const read = async <C extends Component.Key>(world: World, entity: Entity, component: C): Promise<ReadonlyValue<C> | null> => {
+    const values: { readonly [K in C]: ReadonlyValue<K> } | null = await Observe.toPromise(Observe.entity(world, entity, { required: [component] }));
+    return values === null ? null : values[component];
+};
+
+/** The listed components of an entity, or `null` if it's dead or lacks any of them. */
+export const readEntity = <const C extends readonly Component.Key[]>(world: World, entity: Entity, components: C) =>
+    Observe.toPromise(Observe.entity(world, entity, { required: components }));
+
+export const readResource = <R extends Resource.Key>(world: World, name: R): Promise<ReadonlyResourceValue<R>> => Observe.toPromise(Observe.resource(world, name));
+
+export const select = <const R extends readonly Component.Key[] = []>(world: World, query: Observe.Query<R>): Promise<readonly Entity[]> => Observe.toPromise(Observe.select(world, query));
+
+export const count = <const R extends readonly Component.Key[] = []>(world: World, query: Omit<Observe.Query<R>, "order">): Promise<number> => Observe.toPromise(Observe.count(world, query));
+
+/** One component of each of these entities, `null` for one that's dead or lacks it. */
+export const readEach = <C extends Component.Key>(world: World, entities: readonly Entity[], component: C): Promise<(ReadonlyValue<C> | null)[]> =>
+    Promise.all(entities.map(entity => read(world, entity, component)));

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

@@ -0,0 +1,214 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { Entity, System, workers } from "../../index.js";
+import type { F32, Vec2 } from "../../interface/math/index.js";
+import type { Commands } from "../../interface/system/commands.js";
+import { createWorld, join } from "./create.js";
+import { emptyFor } from "./reclaim.js";
+import { whereOf } from "./where.js";
+
+const cell = Symbol("reclaimTest/cell");
+const position = Symbol("reclaimTest/position");
+const seen = Symbol("reclaimTest/seen");
+const note = Symbol("reclaimTest/note");
+const camera = Symbol("reclaimTest/camera");
+declare module "@adobe/ecs" {
+    interface Components {
+        [cell]: { type: Vec2.I32; shared: true };
+        [position]: { type: F32 };
+        [seen]: { type: F32 };
+        [note]: { type: { readonly text: string } | null; thread: "reclaimTest" };
+    }
+    interface Threads {
+        reclaimTest: true;
+    }
+    interface Resources {
+        [camera]: { type: number; default: 0 };
+    }
+}
+
+const inline = () => createWorld({ [workers]: 0 });
+
+// Systems reading what an archetype holds of its value: a kernel, `where` by predicate and by value.
+export const copyCell = System.create({ kernel: true, components: { with: [cell, seen] } }, row => { row[seen] = row[cell][0]; });
+const found: string[] = [];
+export const atFifty = System.create({ components: { with: [position], where: { [cell]: at => at[0] === 50 } } }, row => { found.push(`where ${row[position]}`); });
+export const atLast = System.create({ components: { with: [position], where: { [cell]: [emptyFor + 2, 0] } } }, row => { found.push(`value ${row[position]}`); });
+// Kept to the cell the camera names.
+export const visiting = System.create({ components: { with: [position], where: { [cell]: (at, { resources }) => at[0] === resources[camera] } } }, () => {});
+const visited: number[] = [];
+export const visit = System.create({ components: { with: [cell, position], where: { [cell]: (at, { resources }) => at[0] === resources[camera] } } }, row => { visited.push(row[cell][0]); });
+const caught: number[] = [];
+export const catchUp = System.create({ kernel: false, components: { with: [position], changed: [position], where: { [cell]: (at, { resources }) => at[0] === resources[camera] } } }, row => { caught.push(row[position]); });
+// On a joined thread.
+const heard: number[] = [];
+export const hear = System.create({ observer: true, components: { with: [cell, position], where: { [cell]: at => at[0] === 50 } } }, row => { heard.push(row[cell][0] * 1000 + row[position]); });
+
+/** Moves an entity to cell `[x, 0]`. */
+const step = System.create({}, ({ commands }, input: { readonly entity: Entity; readonly x: number }) => { commands.add(input.entity, cell, [input.x, 0]); });
+
+/** Spawns an entity at `[x, 0]`, returning it. */
+const spawnAt = (world: ReturnType<typeof inline>, x: number, components: readonly symbol[] = [cell, position]): Promise<Entity> => {
+    let spawned = Entity.none;
+    return world.run(System.create(({ commands }) => {
+        const untyped: (list: readonly symbol[], constants: object) => (values: object) => Entity = (list, constants) => Reflect.apply(commands.spawn, commands, [list, constants]);
+        spawned = untyped(components, { [cell]: [x, 0] })({ [position]: x });
+    })).then(() => spawned);
+};
+
+/** Every row's cell and position, by position. */
+const cellsOf = async (world: ReturnType<typeof inline>): Promise<readonly string[]> => {
+    const found: [number, string][] = [];
+    await world.run(System.create({ observer: true, components: { with: [cell, position] } }, row => { found.push([row[position], `${row[cell][0]}:${row[position]}`]); }));
+    return found.sort((a, b) => a[0] - b[0]).map(([, text]) => text);
+};
+
+describe("reclaiming archetypes of shared values", () => {
+    it(`keeps an emptied archetype for ${emptyFor} sync points, then reclaims it and reuses it for another value`, async () => {
+        await using world = inline();
+        const walker = await spawnAt(world, 0);
+        const archetypes = (await world.tables()).archetypes;
+        await world.run(step, { entity: walker, x: 1 });
+        // Cell 0's archetype is empty: kept for now, so a row coming back finds it.
+        for (let k = 1; k < emptyFor; k++) await world.run(step, { entity: walker, x: 1 + (k % 2) });
+        expect((await world.tables()).sharing.pooled).toBe(0);
+        await world.run(step, { entity: walker, x: 3 });
+        // Reclaimed as that sync point ends, cell 3's archetype made before it.
+        const reclaimed = await world.tables();
+        expect(reclaimed.sharing.pooled).toBe(1);
+        expect(reclaimed.sharing.membership).toBe(1);
+        await world.run(step, { entity: walker, x: 4 });
+        // Cell 4 takes cell 0's archetype rather than a new one.
+        const reused = await world.tables();
+        expect(reused.sharing.pooled).toBe(0);
+        expect(reused.sharing.membership).toBe(2);
+        expect(reused.archetypes).toBe(reclaimed.archetypes);
+        expect(reused.archetypes).toBe(archetypes + 3);
+        expect(await cellsOf(world)).toEqual(["4:0"]);
+    });
+
+    it("keeps an archetype a row leaves and enters again each sync point", async () => {
+        await using world = inline();
+        const walker = await spawnAt(world, 0);
+        for (let k = 1; k <= 40; k++) await world.run(step, { entity: walker, x: k % 2 });
+        const { sharing, archetypes } = await world.tables();
+        expect(sharing.membership).toBe(0);
+        expect(archetypes).toBe(3);
+    });
+
+    it("holds as much after 100,000 cells walked, and spawners with constants for each, as after 1,000", async () => {
+        await using world = inline();
+        const walker = await spawnAt(world, 0);
+        const walk = System.create({}, ({ commands }, input: { readonly from: number; readonly to: number }) => {
+            for (let x = input.from; x < input.to; x++) commands.add(walker, cell, [x, 0]);
+            // A spawner of the last cell, its spawn moving with the walker.
+            const at = commands.spawn([cell, position], { [cell]: [input.to - 1, 0] })({ [position]: -1 });
+            commands.despawn(at);
+        });
+        const walked = async (from: number, to: number): Promise<void> => {
+            for (let x = from; x < to; x += 1) await world.run(walk, { from: x, to: x + 1 });
+        };
+        await walked(1, 1_000);
+        const early = await world.tables();
+        await walked(1_000, 100_000);
+        const late = await world.tables();
+        expect(late.archetypes).toBe(early.archetypes);
+        expect(late.arena).toBe(early.arena);
+        expect(late.sharing.values).toBe(early.sharing.values);
+        expect(late.sharing.batches).toBe(early.sharing.batches);
+        expect(late.sharing.presets).toBe(early.sharing.presets);
+        expect(late.sharing.values).toBeLessThan(2 * emptyFor + 4);
+        expect(await cellsOf(world)).toEqual(["99999:0"]);
+    }, 60_000);
+
+    it("reads a reused archetype's own value in rows, kernels, where and lookups", async () => {
+        await using world = inline();
+        const walker = await spawnAt(world, 0, [cell, position, seen]);
+        const other = await spawnAt(world, 100, [cell, position, seen]);
+        for (let x = 1; x <= emptyFor + 2; x++) await world.run(step, { entity: walker, x });
+        // The other's archetype is cell 0's, reused.
+        await world.run(step, { entity: other, x: 50 });
+        expect((await world.tables()).sharing.membership).toBeGreaterThan(0);
+        found.length = 0;
+        await world.run(System.create({ kernel: false, components: { with: [cell, position] } }, row => { found.push(`body ${row[cell][0]}`); }));
+        await world.run(copyCell);
+        await world.run(System.create({ observer: true, components: { with: [cell, seen] } }, row => { found.push(`kernel ${row[seen]}`); }));
+        await world.run(atFifty);
+        await world.run(atLast);
+        expect(found.sort()).toEqual(["body 50", `body ${emptyFor + 2}`, "kernel 50", `kernel ${emptyFor + 2}`, "value 0", "where 100"].sort());
+    });
+
+    it("leaves a system's matches as archetypes go, and matches one reused for a value it passes", async () => {
+        await using world = inline();
+        const walker = await spawnAt(world, 0);
+        await world.run(visiting);
+        for (let x = 1; x <= 60; x++) {
+            await world.run(step, { entity: walker, x });
+            await world.run(visiting);
+        }
+        const where = whereOf(visiting);
+        // Its matches are those not reclaimed: as many as the world keeps of the walk.
+        expect(where?.evaluated).toBeLessThanOrEqual(emptyFor + 3);
+        await world.run(System.create(({ resources }) => { resources[camera] = 60; }));
+        visited.length = 0;
+        await world.run(visit);
+        expect(visited).toEqual([60]);
+    });
+
+    it("counts a row moved out of an archetype before it was reclaimed as changed by that archetype's point", async () => {
+        await using world = inline();
+        caught.length = 0;
+        const far = await spawnAt(world, 5);
+        await spawnAt(world, 0);
+        await world.run(catchUp);
+        // Out of view, it changes, then moves into view's cell, and its old archetype is reclaimed and reused.
+        await world.run(System.create({ components: { with: [position] } }, row => { row[position] += 0.5; }));
+        caught.length = 0;
+        await world.run(catchUp);
+        expect(caught).toEqual([0.5]);
+        await world.run(step, { entity: far, x: 0 });
+        const walker = await spawnAt(world, 7);
+        for (let x = 8; x < 8 + emptyFor + 2; x++) await world.run(step, { entity: walker, x });
+        await world.run(step, { entity: walker, x: 5 });
+        caught.length = 0;
+        await world.run(catchUp);
+        expect(caught).toContain(5.5);
+    });
+
+    it("revives a spawner's batch let go with its value, spawning into that value's archetype", async () => {
+        await using world = inline();
+        let kept: ((values: { readonly [position]: number }) => Entity) | null = null;
+        await world.run(System.create(({ commands }: { readonly commands: Commands }) => {
+            kept = commands.spawn([cell, position], { [cell]: [9, 0] });
+        }));
+        // Nothing holds cell 9: its value, spawner and batch are let go of.
+        await spawnAt(world, 1);
+        expect((await world.tables()).sharing.batches).toBe(1);
+        await world.run(System.create(() => { kept?.({ [position]: 9 }); }));
+        expect(await cellsOf(world)).toEqual(["1:1", "9:9"]);
+    });
+
+    it("reads a reused archetype's own value on a joined thread, in where and rows", async () => {
+        const channel = new MessageChannel();
+        await using world = inline();
+        heard.length = 0;
+        const [joined] = await Promise.all([
+            join(channel.port2, { threads: ["reclaimTest"] }).then(thread => {
+                thread.add(hear);
+                return thread;
+            }),
+            world.share(channel.port1),
+        ]);
+        await using thread = joined;
+        const walker = await spawnAt(world, 0);
+        const other = await spawnAt(world, 100);
+        for (let x = 1; x <= emptyFor + 2; x++) await world.run(step, { entity: walker, x });
+        await world.run(step, { entity: other, x: 50 });
+        expect((await world.tables()).sharing.membership).toBeGreaterThan(0);
+        const idle = System.create(() => {});
+        const end = performance.now() + 2000;
+        while (!heard.includes(50_100) && performance.now() < end) await world.run(idle);
+        expect(heard).toEqual([50_100]);
+        void thread;
+    });
+});

package/src/implementation/world/reclaim.ts

@@ -0,0 +1,170 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Layout } from '../../interface/registry/layout.js';
+import { bump, noShared, release, type Archetype, type Edge } from './archetype.js';
+import { createArrivals, membershipWord } from './arrivals.js';
+import { forgetTexts } from './layout-directory.js';
+import { holdShared, releaseShared, sweepShared } from './shared.js';
+import type { State } from './state.js';
+
+// Reclaiming archetypes of shared values (design.md, "Reclaiming"): one found empty at a sync point is reclaimed once
+// it stayed empty for `emptyFor` sync points and every joined thread finalized past it. Reclaimed, it leaves the
+// world's lookup by key and systems' match lists, lets go of its arrays and of each value only it held, and the edges
+// cached to and from it are cleared. It waits in its component set's pool, under its id, until an archetype of those
+// components and other values is wanted: then it's reused for them, its id and storages kept, so what's cached by id of
+// its components stays true, and everything that read its values reads them again.
+
+/**
+ * Sync points an archetype stays empty before it's reclaimed, so one emptied and filled again soon, as a cell is while
+ * entities cross it, isn't reclaimed and reused over and over: a reclaim and reuse costs a sync point about 1.7 µs
+ * (perf.md), and each walker leaves at most this many empty behind it. A tail ends before the second sync point after
+ * the one it reads, so none reads a reclaimed archetype's rows.
+ */
+export const emptyFor = 8;
+
+/** The component set an archetype's pool is found by: its components, whatever its values. */
+const poolKeyOf = (components: readonly number[]): string => components.join(",");
+
+/** The membership log's length past which it's trimmed by half: a reader further behind reads every archetype again. */
+const membershipLog = 4096;
+
+/** Notes a change of archetype's membership, reclaimed or reused, for systems' match lists and joined threads. */
+const noteMembership = (state: State, archetype: Archetype): void => {
+    const { membership } = state;
+    membership.log.push(archetype);
+    state.reshapes++;
+    if (membership.log.length > membershipLog) {
+        const dropped = membership.log.length >> 1;
+        membership.log.splice(0, dropped);
+        membership.base += dropped;
+    }
+    if (state.memory.shared) {
+        const ring = state.arrivalRing ??= createArrivals(state.memory);
+        Atomics.add(ring.control, membershipWord, 1);
+    }
+};
+
+/** Archetypes whose rows left in the sync point just applied that are now empty, with shared values, as candidates. */
+export const noteEmptied = (state: State): void => {
+    const { plan, archetypes } = state;
+    for (let entry = 0; entry < plan.count; entry++) {
+        const from = plan.from[entry];
+        if (from < 0) continue;
+        const archetype = archetypes[from];
+        if (archetype.shared === noShared || archetype.emptiedAt >= 0 || archetype.count !== 0 || archetype.reclaimed) continue;
+        archetype.emptiedAt = state.syncs;
+        archetype.emptiedTick = state.tick;
+        state.emptied.push(archetype);
+    }
+};
+
+/**
+ * Whether every joined thread acknowledged its stop lists through the sync point of `tick`, an archetype's last with
+ * rows: a stop list names its stops' archetypes, whose values the thread reads by id as it finalizes them.
+ */
+const stopsSettledThrough = (state: State, tick: number): boolean => {
+    for (const channel of state.channels) {
+        for (const block of channel.stops.written) if (((block.sync - (tick >>> 0)) | 0) <= 0 && !block.acknowledged) return false;
+    }
+    return true;
+};
+
+/**
+ * At the end of a sync point: reclaims the candidates that stayed empty long enough, keeps those that may be later,
+ * drops those filled again, then drops the values interned since the last sync point that nothing came to hold.
+ */
+export const reclaimEmptied = (state: State): void => {
+    const { emptied } = state;
+    let kept = 0;
+    for (let k = 0; k < emptied.length; k++) {
+        const archetype = emptied[k];
+        if (archetype.reclaimed) continue;
+        if (archetype.count > 0) {
+            archetype.emptiedAt = -1;
+            continue;
+        }
+        // An archetype holding a joined thread's objects is kept: its rows' moves are in that thread's log, by its id.
+        if (state.syncs - archetype.emptiedAt < emptyFor || archetype.logs !== null || !stopsSettledThrough(state, archetype.emptiedTick)) {
+            emptied[kept++] = archetype;
+            continue;
+        }
+        reclaim(state, archetype);
+    }
+    emptied.length = kept;
+    for (const values of state.sharedList) if (values.fresh.length > 0) sweepShared(values);
+};
+
+/** Clears each edge cached to or from an archetype, removing it from the other end's. */
+const clearEdges = (archetype: Archetype): void => {
+    const { edges } = archetype;
+    if (edges === null) return;
+    archetype.edges = null;
+    for (const edge of edges) {
+        if (Reflect.get(edge.holder, edge.key) !== undefined) Reflect.set(edge.holder, edge.key, edge.cleared);
+        for (const end of edge.ends) {
+            if (end === archetype || end.edges === null) continue;
+            const at = end.edges.indexOf(edge);
+            if (at >= 0) end.edges.splice(at, 1);
+        }
+    }
+};
+
+/**
+ * Notes an edge `holder[key]` cached between archetypes `from` and `to`, so it's cleared, set to `cleared`, once either
+ * is reclaimed. Only edges with an end of shared values are kept, so worlds without them keep none.
+ */
+export const noteEdge = (holder: object, key: PropertyKey, cleared: unknown, from: Archetype, to: Archetype): void => {
+    const toShared = to !== from && to.shared !== noShared;
+    if (from.shared === noShared && !toShared) return;
+    const ends = from.shared === noShared ? [to] : toShared ? [from, to] : [from];
+    const edge: Edge = { holder, key, cleared, ends };
+    for (const end of ends) (end.edges ??= []).push(edge);
+};
+
+const reclaim = (state: State, archetype: Archetype): void => {
+    archetype.reclaimed = true;
+    archetype.emptiedAt = -1;
+    state.archetypeByKey.delete(archetype.key);
+    clearEdges(archetype);
+    archetype.adding.length = archetype.removing.length = archetype.sharing.length = 0;
+    release(state.memory, archetype);
+    state.gpu?.forget(archetype);
+    const pool = state.pools.get(poolKeyOf(archetype.components));
+    if (pool === undefined) state.pools.set(poolKeyOf(archetype.components), [archetype]);
+    else pool.push(archetype);
+    for (const id of archetype.components) {
+        const number = archetype.shared[id];
+        const values = state.shared[id];
+        if (number !== undefined && values !== undefined) releaseShared(values, number);
+    }
+    // Listed, so the record is written flagged; its version moved on as its arrays went.
+    bump(archetype);
+    noteMembership(state, archetype);
+};
+
+/**
+ * A reclaimed archetype of `components` reused for the shared values `held` holds, their layouts and texts by
+ * component id; null where its component set's pool is empty.
+ */
+export const reuseArchetype = (state: State, key: string, components: readonly number[], held: readonly (number | undefined)[], layouts: readonly (Layout | undefined)[], texts: readonly (string | undefined)[]): Archetype | null => {
+    const archetype = state.pools.get(poolKeyOf(components))?.pop();
+    if (archetype === undefined) return null;
+    archetype.reclaimed = false;
+    archetype.generation++;
+    archetype.key = key;
+    archetype.shared = held.length === 0 ? noShared : held;
+    archetype.texts = texts;
+    for (const storage of archetype.storages) {
+        const layout = layouts[storage.component];
+        if (layout !== undefined) storage.layout = layout;
+    }
+    for (const id of components) {
+        const number = held[id];
+        const values = state.shared[id];
+        if (number !== undefined && values !== undefined) holdShared(values, number);
+    }
+    if (state.directory !== null) forgetTexts(state.directory, archetype);
+    // Its values changed: what read them by its version reads them again, and the directory writes its record.
+    bump(archetype);
+    noteMembership(state, archetype);
+    return archetype;
+};

package/src/implementation/world/reductions.cases.ts

@@ -0,0 +1,23 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import type * as Fixture from "./reductions.fixture.js";
+
+/** Reductions fold every row once, deterministically, across workers: the cases, over the fixture built or from source. */
+export const reductionsCases = (load: () => Promise<typeof Fixture>) => describe("reductions across workers", () => {
+    for (const wasm of [true, false]) {
+        it(`fold every row exactly once, in the same order each run (${wasm ? "WASM" : "JS"})`, async () => {
+            const fixture = await load();
+            const { rows, weightAt } = fixture;
+            const runs = await fixture.reduced(wasm);
+            for (const [count, largest] of runs) {
+                expect(count).toBe(rows);
+                expect(largest).toBe(Math.max(...Array.from({ length: rows }, (_, i) => weightAt(i))));
+            }
+            // Each piece folds into its own partial, combined in piece order, so float sums repeat bit for bit.
+            const sums = runs.map(([, , total]) => total);
+            expect(new Set(sums).size).toBe(1);
+            const direct = Array.from({ length: rows }, (_, i) => weightAt(i)).reduce((total, value) => total + value, 0);
+            expect(Math.abs((sums[0] ?? NaN) - direct)).toBeLessThan(1e-6 * rows);
+        });
+    }
+});