@adobe/ecs 0.0.0-stage → 0.2.0

package/src/implementation/world/move-log.test.ts

@@ -0,0 +1,429 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { describe, expect, it } from "vitest";
+import { createBuffer, addCommand, pushCommand, pushComponent, removeCommand, type CommandBuffer } from "./buffer.js";
+import { readCell } from "./cells.js";
+import { createCommands } from "./commands.js";
+import { asEntity, indexOf, locate as locateHere } from "./entities.js";
+import { recordCount, structureWord, tableOffsetWord } from "./layout-directory.js";
+import { applying, cellOf, createMirror, nameComponent, rebuild, replay, stage, waitStructure, type Mirror } from "./mirror.js";
+import { createMoveLog, logSyncWord, ownTag, slotValue, type MoveLog } from "./move-log.js";
+import { claimThreads } from "./remote.js";
+import { createState, defaultOf, idOf, startTicking, type State } from "./state.js";
+import { applySync, prepareSync, synchronize } from "./synchronize.js";
+import { createThreadDirectory } from "./thread-directory.js";
+import { createThreadSystems } from "./thread-systems.js";
+import {
+    completionCapacityWord, completionOffsetWord, payloadCapacityWord, payloadCount, payloadInput, payloadOffsetWord, payloadSequence, payloadSync, ringBaseWord,
+    ringCapacityWord, taskBlockWords, taskDoneWord, taskPostedWord,
+} from "./thread-tasks.js";
+
+// The move log on one thread: a world whose objects of thread "moveLogTest" a mirror fills, against an inline world given
+// the same commands, compared after every sync point by each entity's id.
+
+const uid = Symbol("moveLogTest/uid");
+const amount = Symbol("moveLogTest/amount");
+const flag = Symbol("moveLogTest/flag");
+const label = Symbol("moveLogTest/label");
+const note = Symbol("moveLogTest/note");
+const own = Symbol("moveLogTest/own");
+declare module "@adobe/ecs" {
+    export interface Threads {
+        moveLogTest: true;
+    }
+    export interface Components {
+        [uid]: { type: number };
+        [amount]: { type: number };
+        [flag]: { type: true };
+        [label]: { type: Label; thread: "moveLogTest" };
+        [note]: { type: Note | null; thread: "moveLogTest" };
+        [own]: { type: string };
+    }
+}
+/** A value that isn't data. */
+type Note = { readonly text: string; readonly read: () => string };
+/** The label's start, which a command on another thread than its own gives it by this value. */
+const none = { text: "none" } as const;
+/** A label, which starts as `none`, the value commands on other threads give it by identity. */
+type Label = { readonly text: string } | null;
+const Label = { default: none };
+
+const remoteKeys = [label, note] as const;
+
+/** A deterministic generator, so a failure replays. */
+const random = (seed: number) => {
+    let state = seed >>> 0;
+    return (): number => {
+        state = (state * 1664525 + 1013904223) >>> 0;
+        return state / 0x100000000;
+    };
+};
+
+/** A world whose "moveLogTest" objects a mirror on this thread fills, its log holding at least `minimum` entries. */
+const threaded = (minimum: number): { readonly state: State; readonly mirror: Mirror; readonly log: MoveLog } => {
+    const state = createState(true);
+    let mirror: Mirror | null = null;
+    const log = createMoveLog(state.memory, 1, state.starts, component => {
+        const key = state.keys[component];
+        if (mirror !== null && typeof key === "symbol") nameComponent(mirror, component, key, defaultOf);
+    }, minimum);
+    mirror = createMirror(state.memory.memory, log.block, 1);
+    for (const key of [uid, amount, flag, own, ...remoteKeys]) idOf(state, key);
+    claimThreads(state, log, ["moveLogTest"]);
+    return { state, mirror, log };
+};
+
+const inline = (): State => {
+    const state = createState(true);
+    for (const key of [uid, amount, flag, own, ...remoteKeys]) idOf(state, key);
+    // As the threaded world keeps them for the thread's objects.
+    startTicking(state, remoteKeys.map(key => idOf(state, key)));
+    return state;
+};
+
+/** Brings the mirror up to the last sync point, rebuilding when its log lapped it. */
+const follow = (mirror: Mirror): void => {
+    const replayed = replay(mirror);
+    if (replayed === "lapped") expect(rebuild(mirror)).toBe("rebuilt");
+    else expect(replayed).toBe("current");
+};
+
+/** Every live entity of a world with its archetype and row. */
+const liveRows = (state: State): { readonly entity: number; readonly archetype: number; readonly row: number }[] =>
+    state.archetypes.flatMap(archetype => archetype.resource ? [] : Array.from({ length: archetype.count }, (_, row) => ({ entity: archetype.entities[row], archetype: archetype.id, row })));
+
+/** The id an entity's row holds. */
+const idAt = (state: State, archetype: number, row: number): unknown => {
+    const storage = state.archetypes[archetype].storageById[idOf(state, uid)];
+    return storage === undefined ? undefined : readCell(storage, row);
+};
+
+/** The inline world's objects and ticks against the mirror's, by entity id, and the threaded world's rows against the inline's. */
+const compare = (reference: State, world: State, mirror: Mirror): number => {
+    let compared = 0;
+    for (const { entity, archetype, row } of liveRows(reference)) {
+        const index = locateHere(world.entities, entity);
+        expect(index).toBeGreaterThanOrEqual(0);
+        expect([world.entities.archetype[index], world.entities.row[index]]).toEqual([archetype, row]);
+        const storages = reference.archetypes[archetype];
+        expect(idAt(world, archetype, row)).toBe(idAt(reference, archetype, row));
+        for (const key of remoteKeys) {
+            const id = idOf(reference, key);
+            const storage = storages.storageById[id];
+            const cell = cellOf(mirror, archetype, row, id);
+            if (storage === undefined) {
+                expect(cell).toBeNull();
+                continue;
+            }
+            expect(cell).toEqual({ value: readCell(storage, row), added: storage.added[row], changed: storage.changed[row] });
+            // The world holds only tags of the thread's objects.
+            expect(world.archetypes[archetype].storageById[id]?.values.length).toBe(0);
+            compared++;
+        }
+    }
+    return compared;
+};
+
+/** World commands for both worlds, issued the same way, through the commands systems get. */
+const worldCommands = (state: State) => {
+    const target = { buffer: createBuffer() };
+    return { commands: createCommands(state, target), target };
+};
+
+/**
+ * Random spawns, despawns, adds and removes, single and list forms, from the world's thread, which give the thread's
+ * objects only their start or null; then the thread's own values for its objects, staged by the mirror, and world
+ * commands after those, all applied as one sync point in both worlds.
+ */
+const property = (seed: number, minimum: number, steps: number): { readonly compared: number; readonly rebuilds: number } => {
+    const next = random(seed);
+    const pick = <T>(list: readonly T[]): T => list[Math.floor(next() * list.length)];
+    const { state: world, mirror } = threaded(minimum);
+    const reference = inline();
+    let nextUid = 1;
+    let compared = 0;
+    let dead: number[] = [];
+    follow(mirror);
+    for (let step = 0; step < steps; step++) {
+        const before = { here: worldCommands(world), there: worldCommands(reference) };
+        const after = { here: worldCommands(world), there: worldCommands(reference) };
+        const thread: { here: CommandBuffer; there: CommandBuffer } = { here: createBuffer(), there: createBuffer() };
+        const live = liveRows(reference).map(({ entity }) => entity);
+        // Now and then one that's dead, whose commands drop.
+        const someone = () => asEntity(live.length === 0 || (dead.length > 0 && next() < 0.1) ? pick(dead.length > 0 ? dead : [0]) : pick(live));
+        const both = (issue: (commands: ReturnType<typeof createCommands>) => void, phase: typeof before): void => {
+            issue(phase.here.commands);
+            issue(phase.there.commands);
+        };
+        const sync = world.tick + 1;
+        const operations = 1 + Math.floor(next() * 12);
+        for (let o = 0; o < operations; o++) {
+            const phase = next() < 0.7 ? before : after;
+            const choice = next();
+            const id = nextUid;
+            if (choice < 0.2) {
+                nextUid++;
+                const form = Math.floor(next() * 4);
+                const value = next() < 0.5 ? undefined : null;
+                both(commands => {
+                    if (form === 0) commands.spawn([uid, label])({ [uid]: id, [label]: value });
+                    else if (form === 1) commands.spawn([uid, amount, label, note])({ [uid]: id, [amount]: 1, [note]: value });
+                    else if (form === 2) commands.spawn([uid, flag])({ [uid]: id });
+                    else commands.spawn([uid, note, own])({ [uid]: id, [own]: "o" });
+                }, phase);
+            }
+            else if (choice < 0.3) {
+                const entity = someone();
+                both(commands => commands.despawn(entity), phase);
+            }
+            else if (choice < 0.55) {
+                const entity = someone();
+                const form = Math.floor(next() * 4);
+                both(commands => {
+                    if (form === 0) commands.add(entity, label, none);
+                    else if (form === 1) commands.add(entity, note, null);
+                    else if (form === 2) commands.add(entity, [amount, label], { [amount]: 2 });
+                    else commands.add(entity, [flag, note, label], { [label]: null });
+                }, phase);
+            }
+            else if (choice < 0.75) {
+                const entity = someone();
+                const form = Math.floor(next() * 3);
+                both(commands => {
+                    if (form === 0) commands.remove(entity, label);
+                    else if (form === 1) commands.remove(entity, [note, amount]);
+                    else commands.remove(entity, [flag, label, note]);
+                }, phase);
+            }
+            else {
+                // The thread's own value for its object, staged there under a slot the world's command names.
+                const entity = someone();
+                const key = pick(remoteKeys);
+                const text = `v${step}.${o}`;
+                const value = key === label ? { text } : { text, read: () => text };
+                const component = idOf(world, key);
+                pushCommand(thread.here, addCommand, entity);
+                pushComponent(thread.here, component, slotValue(stage(mirror, entity, component, value, sync)));
+                pushCommand(thread.there, addCommand, entity);
+                pushComponent(thread.there, idOf(reference, key), value);
+                if (next() < 0.2) {
+                    // And taken away again in the same sync point, by the thread itself.
+                    pushCommand(thread.here, removeCommand, entity);
+                    pushComponent(thread.here, component, undefined);
+                    pushCommand(thread.there, removeCommand, entity);
+                    pushComponent(thread.there, idOf(reference, key), undefined);
+                }
+            }
+        }
+        for (const [state, buffers] of [[world, [before.here.target.buffer, thread.here, after.here.target.buffer]], [reference, [before.there.target.buffer, thread.there, after.there.target.buffer]]] as const) {
+            for (const buffer of buffers) state.queued.push({ buffer, guarded: true });
+            synchronize(state);
+        }
+        dead = [...dead, ...live.filter(entity => locateHere(reference.entities, entity) < 0)].slice(-20);
+        follow(mirror);
+        compared += compare(reference, world, mirror);
+        // Every staged slot is settled once its sync point applied.
+        expect(mirror.staged.slice(mirror.head).filter(entry => entry.live)).toEqual([]);
+    }
+    return { compared, rebuilds: mirror.rebuilds };
+};
+
+/**
+ * A thread's systems over a mirror the log lapped, so its next task rebuilds it: `post` posts a task of no systems,
+ * which runs once the mirror is current, its input by message when `input`; `refreshes` counts its tries.
+ */
+const lapped = () => {
+    const { state, mirror, log } = threaded(4);
+    const { commands, target } = worldCommands(state);
+    const queue = (): void => { state.queued.push({ buffer: target.buffer, guarded: true }); };
+    const entity = commands.spawn([uid, label])({ [uid]: 1 });
+    queue();
+    synchronize(state);
+    follow(mirror);
+    const { memory } = state;
+    const control = new Int32Array(memory.memory.buffer, memory.allocate(taskBlockWords * 4), taskBlockWords);
+    const payload = memory.allocate(256);
+    Atomics.store(control, payloadOffsetWord, payload);
+    Atomics.store(control, payloadCapacityWord, 256);
+    Atomics.store(control, completionOffsetWord, memory.allocate(256));
+    Atomics.store(control, completionCapacityWord, 256);
+    Atomics.store(control, ringBaseWord, memory.allocate(1 << 16));
+    Atomics.store(control, ringCapacityWord, 1 << 16);
+    const directory = createThreadDirectory(memory.memory, mirror);
+    let refreshed = 0;
+    const counted = { ...directory, refresh: () => { refreshed++; return directory.refresh(); } };
+    const systems = createThreadSystems({
+        memory: memory.memory, mirror, directory: counted, control, claims: new Set(["moveLogTest"]),
+        worldWaits: true, post: () => {}, keyNumber: () => 0, numbered: () => 0,
+    });
+    // More entries than the log holds.
+    for (let k = 0; k < 8; k++) commands.add(entity, amount, k);
+    queue();
+    synchronize(state);
+    const post = (input: boolean): void => {
+        const words = new Float64Array(memory.memory.buffer, payload, 32);
+        words[payloadSequence] = 1;
+        words[payloadSync] = Atomics.load(log.header, logSyncWord) >>> 0;
+        words[payloadCount] = 0;
+        words[payloadInput] = input ? 1 : 0;
+        Atomics.store(control, taskPostedWord, 1);
+    };
+    return { state, mirror, entity, commands, queue, systems, post, done: () => Atomics.load(control, taskDoneWord) === 1, refreshes: () => refreshed };
+};
+
+describe("the move log", () => {
+    it("gives a joined thread's columns the inline world's values and ticks after every sync point, replaying its log", () => {
+        for (const seed of [1, 2, 3, 4]) {
+            const { compared, rebuilds } = property(seed, 4096, 150);
+            expect(compared).toBeGreaterThan(100);
+            // Only the first, at the claim.
+            expect(rebuilds).toBe(1);
+        }
+    });
+    it("rebuilds to the same values and ticks once the log drops entries a thread didn't replay", () => {
+        for (const seed of [5, 6, 7, 8]) {
+            const { compared, rebuilds } = property(seed, 4, 150);
+            expect(compared).toBeGreaterThan(100);
+            expect(rebuilds).toBeGreaterThan(10);
+        }
+    });
+    it("keeps by entity a value the thread's systems wrote, which its row's tag marks, across a rebuild and a move", () => {
+        const { state, mirror } = threaded(4);
+        follow(mirror);
+        const { commands, target } = worldCommands(state);
+        const entity = commands.spawn([uid, label])({ [uid]: 1 });
+        const other = commands.spawn([uid, label])({ [uid]: 2 });
+        state.queued.push({ buffer: target.buffer, guarded: true });
+        synchronize(state);
+        follow(mirror);
+        // A system on the thread writes the entity's label: its value there, its tag the thread's own.
+        const id = idOf(state, label);
+        const index = indexOf(entity);
+        const archetype = state.archetypes[state.entities.archetype[index]];
+        const row = state.entities.row[index];
+        const column = mirror.archetypes[archetype.id]?.byComponent[id];
+        if (column === undefined) throw new Error("The mirror holds no labels.");
+        column.values[row] = { text: "written" };
+        const storage = archetype.storageById[id];
+        if (storage === undefined) throw new Error("The world holds no labels.");
+        storage.tags[row] = ownTag;
+        // More entries than the log holds, and a move: the thread rebuilds, keeping the value by entity.
+        const rebuilds = mirror.rebuilds;
+        commands.add(entity, flag);
+        for (let k = 0; k < 4; k++) commands.add(other, amount, k);
+        commands.despawn(other);
+        state.queued.push({ buffer: target.buffer, guarded: true });
+        synchronize(state);
+        follow(mirror);
+        expect(mirror.rebuilds).toBe(rebuilds + 1);
+        const moved = indexOf(entity);
+        expect(cellOf(mirror, state.entities.archetype[moved], state.entities.row[moved], id)?.value).toEqual({ text: "written" });
+    });
+    it("drops a staged slot whose command names an entity the sync point despawned, without a value", () => {
+        const { state, mirror } = threaded(4096);
+        follow(mirror);
+        const { commands, target } = worldCommands(state);
+        const entity = commands.spawn([uid, label])({ [uid]: 1 });
+        synchronize(state);
+        commands.despawn(entity);
+        const buffer = createBuffer();
+        pushCommand(buffer, addCommand, entity);
+        pushComponent(buffer, idOf(state, label), slotValue(stage(mirror, entity, idOf(state, label), { text: "dropped" }, state.tick + 1)));
+        state.queued.push({ buffer: target.buffer, guarded: true }, { buffer, guarded: true });
+        synchronize(state);
+        follow(mirror);
+        expect(mirror.staged).toEqual([]);
+    });
+    it("shows the thread a sync point applying through the structure epoch, waiting without blocking until it's applied", async () => {
+        const { state, mirror } = threaded(4096);
+        const { commands, target } = worldCommands(state);
+        const entity = commands.spawn([uid, label])({ [uid]: 1 });
+        state.queued.push({ buffer: target.buffer, guarded: true });
+        synchronize(state);
+        expect(applying(mirror)).toBe(false);
+        commands.add(entity, amount, 3);
+        state.queued.push({ buffer: target.buffer, guarded: true });
+        expect(prepareSync(state)).toBe(true);
+        expect(new Int32Array(state.memory.memory.buffer)[structureWord] & 1).toBe(1);
+        expect(applying(mirror)).toBe(true);
+        let waited = false;
+        const waiting = waitStructure(mirror).then(() => { waited = true; });
+        await new Promise(resolve => setTimeout(resolve, 5));
+        expect(waited).toBe(false);
+        applySync(state);
+        await waiting;
+        expect(applying(mirror)).toBe(false);
+    });
+    it("keeps the counts of archetypes holding the thread's objects in the layout directory", () => {
+        const { state } = threaded(4096);
+        const { commands, target } = worldCommands(state);
+        for (let k = 0; k < 5; k++) commands.spawn([uid, label])({ [uid]: k });
+        state.queued.push({ buffer: target.buffer, guarded: true });
+        synchronize(state);
+        const archetype = state.archetypes.find(candidate => candidate.count === 5);
+        if (archetype === undefined) throw new Error("No archetype holds the spawns.");
+        const words = new Uint32Array(state.memory.memory.buffer);
+        const record = words[words[tableOffsetWord] / 4 + archetype.id] / 4;
+        expect(words[record + recordCount]).toBe(5);
+        commands.despawn(asEntity(archetype.entities[0]));
+        state.queued.push({ buffer: target.buffer, guarded: true });
+        synchronize(state);
+        expect(words[record + recordCount]).toBe(4);
+    });
+    it("runs a thread's task once its rebuild failed for a sync point applied during it, with no wake after", async () => {
+        const { state, mirror, entity, commands, queue, systems, post, done } = lapped();
+        // A sync point applies while the thread rebuilds, after it read the structure epoch, and none follows it.
+        const through = mirror.finalize;
+        let applied = false;
+        mirror.finalize = (sync, old) => {
+            if (!applied) {
+                applied = true;
+                commands.add(entity, amount, 9);
+                queue();
+                synchronize(state);
+            }
+            return through === null || through(sync, old);
+        };
+        post(false);
+        expect(systems.process()).toBe(false);
+        expect(applied).toBe(true);
+        await new Promise(resolve => setTimeout(resolve, 5));
+        expect(done()).toBe(true);
+    });
+    it("runs a thread's task once the sync point its rebuild found applying is applied", async () => {
+        const { state, mirror, entity, commands, queue, systems, post, done, refreshes } = lapped();
+        commands.add(entity, amount, 9);
+        queue();
+        expect(prepareSync(state)).toBe(true);
+        expect(rebuild(mirror)).toBe("moved");
+        post(false);
+        expect(systems.process()).toBe(false);
+        const tried = refreshes();
+        await new Promise(resolve => setTimeout(resolve, 5));
+        expect(done()).toBe(false);
+        // It waits on the structure epoch, trying nothing until the sync point is applied.
+        expect(refreshes()).toBe(tried);
+        applySync(state);
+        await new Promise(resolve => setTimeout(resolve, 5));
+        expect(done()).toBe(true);
+    });
+    it("keeps a thread's event loop while its task waits for its input, after a rebuild outside a task found a sync point applying", async () => {
+        const { state, mirror, entity, commands, queue, systems, post, done, refreshes } = lapped();
+        commands.add(entity, amount, 9);
+        queue();
+        expect(prepareSync(state)).toBe(true);
+        // Its finalizers replay, and the rebuild finds the sync point applying.
+        mirror.stagedTransfers = 1;
+        systems.finalize();
+        applySync(state);
+        // A task whose input is posted after it: nothing runs it until the input arrives.
+        post(true);
+        expect(systems.process()).toBe(false);
+        const before = refreshes();
+        for (let k = 0; k < 200; k++) await Promise.resolve();
+        const tries = refreshes() - before;
+        systems.input(1, { given: true });
+        expect(done()).toBe(true);
+        // None while the thread's event loop goes on, so the input's message can arrive.
+        expect(tries).toBe(0);
+    });
+});

package/src/implementation/world/move-log.ts

@@ -0,0 +1,216 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { Archetype } from './archetype.js';
+import type { Memory } from './memory.js';
+
+// The move log: how a joined thread's object columns follow the world's rows. For archetypes holding objects a joined
+// thread fills, every path that moves or fills a row appends, in apply order, entries the thread replays on its own
+// columns. Shared by the world's thread, which writes it, and the joined thread, which reads it (`mirror.ts`).
+
+/**
+ * The log's header, a block of its own that never moves: the ring's version, bumped when it's replaced, its offset
+ * and capacity in entries, a power of two; the position the writer may have written up to; the position published
+ * through, and the sync published through, modulo 2^32; then the thread's first stop list and the sync it finalized
+ * through; a tail's bound; then the runs finished. Positions count entries from the start, modulo 2^32.
+ */
+export const logVersionWord = 0;
+export const logOffsetWord = 1;
+export const logCapacityWord = 2;
+export const logLimitWord = 3;
+export const logPublishedWord = 4;
+export const logSyncWord = 5;
+/** The offset of the thread's first stop list (`stop-lists.ts`), 0 before one is written. */
+export const logStopsWord = 6;
+/** The sync the thread finalized through, which it stores once its finalizers ran for every stop through it. */
+export const logFinalizedWord = 7;
+/**
+ * While a tail is in flight on the thread, 1, and the sync it names, which the thread's replay stops at so the tail's
+ * rows stay those of that sync; the world stores them as it posts the tail and clears the flag once it's done.
+ */
+export const logBoundedWord = 8;
+export const logBoundWord = 9;
+/** The runs and ticks whose tiers the world finished, modulo 2^32: a joined thread returns to its event loop once each. */
+export const logRunWord = 10;
+export const logHeaderBytes = 64;
+
+/** An entry is four words; its first holds its kind in the low four bits, the added flag, and an archetype from bit 8. */
+export const entryWords = 4;
+export const kindMask = 15;
+export const addedFlag = 16;
+export const archetypeShift = 8;
+
+/** A sync's first entry for the thread: its tick, low and high words. */
+export const syncEntry = 1;
+/** A row moving between archetypes both holding the thread's objects: from archetype and row, to archetype and row. */
+export const moveEntry = 2;
+/** A row filled in an archetype holding the thread's objects, every one of them at its start: its row and entity. */
+export const appendEntry = 3;
+/** Rows filled from `row`, `count` of them, each at its starts, followed by their entities, two to an entry. */
+export const rangeEntry = 4;
+/** A row removed, the last row moved into it: the last row, then the row; equal when the removed row was last. */
+export const swapEntry = 5;
+/** A value given to the thread's object in a row: the row, the component, and its tag; added when it starts there. */
+export const setEntry = 6;
+
+/**
+ * Tags: the component's start, `null`, a value the thread's systems wrote, which it keeps by entity, or a staged slot's
+ * value, by the slot's id plus `slotTags`.
+ */
+export const startTag = 0;
+export const nullTag = 1;
+export const ownTag = 2;
+export const slotTags = 3;
+
+/** Entries a log holds at least. */
+export const minimumEntries = 4096;
+/** Entries the writer may write past what it last stored as its limit. */
+const limitStep = 64;
+
+/** A value the thread that fills a component gave it, staged there under its slot's id: no other thread holds one. */
+export type SlotValue = { readonly [slotOf]: number };
+const slotOf = Symbol("slot");
+
+export const slotValue = (slot: number): SlotValue => ({ [slotOf]: slot });
+
+/** A value's tag in its storage, or -1 for a value another thread can't give an object it doesn't hold. */
+export const tagOf = (value: unknown, start: unknown): number => {
+    if (value === start || value === undefined) return startTag;
+    if (value === null) return nullTag;
+    return typeof value === "object" && slotOf in value ? (Number(Reflect.get(value, slotOf)) + slotTags) >>> 0 : -1;
+};
+
+/** The world's end of a joined thread's log. */
+export type MoveLog = {
+    /** The joined thread's number, which storage flags in the layout directory name. */
+    readonly thread: number;
+    readonly memory: Memory;
+    readonly header: Int32Array;
+    /** The header block's offset, which the thread is posted. */
+    readonly block: number;
+    ring: Uint32Array;
+    ringEntities: Float64Array;
+    mask: number;
+    /** The next entry's position, and the limit last stored. */
+    position: number;
+    limit: number;
+    /** The current sync's tick, and whether its sync entry is written. */
+    tick: number;
+    headed: boolean;
+    /** By component id, what each starts at, as the world resolves it. */
+    readonly starts: readonly unknown[];
+    /** Archetypes holding the thread's objects, whose rows size the ring. */
+    readonly archetypes: Archetype[];
+    readonly minimum: number;
+    /** Tells the thread a component it fills, once the world met it. */
+    readonly announce: (component: number) => void;
+};
+
+const powerOfTwo = (entries: number): number => 2 ** Math.ceil(Math.log2(Math.max(entries, 1)));
+
+const placeRing = (log: MoveLog, capacity: number): void => {
+    const { memory, header } = log;
+    const offset = memory.allocate(capacity * entryWords * 4);
+    const buffer = memory.memory.buffer;
+    log.ring = new Uint32Array(buffer, offset, capacity * entryWords);
+    log.ringEntities = new Float64Array(buffer, offset, capacity * 2);
+    log.mask = capacity - 1;
+    header[logOffsetWord] = offset;
+    header[logCapacityWord] = capacity;
+    Atomics.add(header, logVersionWord, 1);
+};
+
+/** A log in shared memory for joined thread `thread`, its ring holding `minimum` entries at least. */
+export const createMoveLog = (memory: Memory, thread: number, starts: readonly unknown[], announce: (component: number) => void, minimum = minimumEntries): MoveLog => {
+    const block = memory.allocate(logHeaderBytes);
+    const header = new Int32Array(memory.memory.buffer, block, logHeaderBytes / 4).fill(0);
+    const log: MoveLog = {
+        thread, memory, header, block, ring: new Uint32Array(0), ringEntities: new Float64Array(0), mask: 0, position: 0, limit: 0,
+        tick: -1, headed: false, starts, archetypes: [], minimum: powerOfTwo(minimum), announce,
+    };
+    placeRing(log, log.minimum);
+    return log;
+};
+
+/** Returns the log's blocks to the memory, once its thread left: a thread that died may still be reading it. */
+export const freeMoveLog = (log: MoveLog): void => {
+    log.memory.free(log.header[logOffsetWord], (log.mask + 1) * entryWords * 4);
+    log.memory.free(log.block, logHeaderBytes);
+};
+
+/**
+ * At the start of a sync point: its tick, and a ring holding the rows of the archetypes with the thread's objects,
+ * replaced while it's too small. The old block is freed, so a thread reading it sees the version move, and rebuilds.
+ */
+export const beginLog = (log: MoveLog, tick: number): void => {
+    log.tick = tick;
+    log.headed = false;
+    let rows = 0;
+    for (const archetype of log.archetypes) rows += archetype.count;
+    if (rows <= log.mask + 1) return;
+    const old = log.header[logOffsetWord];
+    const oldBytes = (log.mask + 1) * entryWords * 4;
+    placeRing(log, Math.max(log.minimum, powerOfTwo(rows)));
+    log.memory.free(old, oldBytes);
+};
+
+/** Stores a limit past the next entries before writing them, so a reader copying older entries can tell they lapped. */
+const extendLimit = (log: MoveLog): void => {
+    log.limit = (log.position + limitStep) >>> 0;
+    Atomics.store(log.header, logLimitWord, log.limit);
+};
+
+const put = (log: MoveLog, first: number, second: number, third: number, fourth: number): void => {
+    if (log.position === log.limit) extendLimit(log);
+    const at = (log.position & log.mask) * entryWords;
+    const { ring } = log;
+    ring[at] = first;
+    ring[at + 1] = second;
+    ring[at + 2] = third;
+    ring[at + 3] = fourth;
+    log.position = (log.position + 1) >>> 0;
+};
+
+/** An entry, after the sync's own the first time. */
+const entry = (log: MoveLog, first: number, second: number, third: number, fourth: number): void => {
+    if (!log.headed) {
+        log.headed = true;
+        put(log, syncEntry, log.tick >>> 0, Math.floor(log.tick / 0x100000000), 0);
+    }
+    put(log, first, second, third, fourth);
+};
+
+export const logMove = (log: MoveLog, from: number, fromRow: number, to: number, toRow: number): void =>
+    entry(log, moveEntry | (from << archetypeShift), fromRow, to, toRow);
+
+export const logAppend = (log: MoveLog, archetype: number, row: number, entity: number): void =>
+    entry(log, appendEntry | (archetype << archetypeShift), row, entity >>> 0, Math.floor(entity / 0x100000000));
+
+/** Rows `row` to `row + count` filled with `entities[first]` on. */
+export const logRange = (log: MoveLog, archetype: number, row: number, count: number, entities: Float64Array, first: number): void => {
+    entry(log, rangeEntry | (archetype << archetypeShift), row, count, 0);
+    for (let k = 0; k < count; k += 2) {
+        put(log, 0, 0, 0, 0);
+        const at = ((log.position - 1) & log.mask) * 2;
+        log.ringEntities[at] = entities[first + k];
+        log.ringEntities[at + 1] = k + 1 < count ? entities[first + k + 1] : 0;
+    }
+};
+
+export const logSwap = (log: MoveLog, archetype: number, last: number, row: number): void =>
+    entry(log, swapEntry | (archetype << archetypeShift), last, row, 0);
+
+export const logSet = (log: MoveLog, archetype: number, row: number, component: number, tag: number, added: boolean): void =>
+    entry(log, setEntry | (added ? addedFlag : 0) | (archetype << archetypeShift), row, component, tag);
+
+/** At the end of a sync point: its entries, then the sync, published, each by a store the thread loads. */
+export const publishLog = (log: MoveLog): void => {
+    if (log.tick < 0) return;
+    if (log.headed) Atomics.store(log.header, logPublishedWord, log.position);
+    Atomics.store(log.header, logSyncWord, log.tick >>> 0);
+    log.tick = -1;
+    log.headed = false;
+};
+
+/** Once a run's or tick's tiers are done, before its sync point and tails. */
+export const markRun = (log: MoveLog): void => {
+    Atomics.add(log.header, logRunWord, 1);
+};