@adobe/ecs 0.0.0-stage → 0.1.0

package/src/implementation/world/terminal.ts

@@ -0,0 +1,13 @@
+/**
+ * The `Symbol.for` name of the global `WeakSet` of system bodies the plugin proved never reach their context's
+ * `commands`. Its version changes with the set's format.
+ */
+export const terminalBodiesName = "@adobe/ecs/terminal@1";
+
+const terminalBodies = Symbol.for(terminalBodiesName);
+
+/** Whether the plugin proved a system's body never reaches its context's `commands`. */
+export const provenTerminal = (body: unknown): boolean => {
+    const set: unknown = Reflect.get(globalThis, terminalBodies);
+    return set instanceof WeakSet && typeof body === "function" && set.has(body);
+};

package/src/implementation/world/thread-directory.ts

@@ -0,0 +1,210 @@
+import { declarationOf, firstKeyOf, keyOfId, labelOf } from '../../interface/registry/index.js';
+import { layoutOf, viewsOf, type Layout, type Views } from '../../interface/registry/layout.js';
+import { writeOf } from './archetype.js';
+import { emptyViews } from './arrays.js';
+import { tableLength } from './entities.js';
+import {
+    archetypeField, capacityField, cursorField, entitiesVersionField, entitiesWord, freeCapacityField, freeField, generationField, linearFlag,
+    recordCapacity, recordCount, recordEntities, recordFlags, recordStorages, recordVersion, recordWords, metaFlag, remoteFlag, resourceEntityWord, resourceFlag,
+    rowField, storageAdded, storageChanged, storageChunkAdded, storageChunkChanged, storageChunks, storageColumn, storageComponent, storageFlags,
+    storageWords, tableLengthWord, tableOffsetWord, threadShift, tickedFlag,
+} from './layout-directory.js';
+import { coveringBuffer, pageBytes, pagesWord } from './memory.js';
+import { createStringReader } from './strings.js';
+import type { Mirror, Mirrored } from './mirror.js';
+import type { Row, RowArchetype, RowHost, RowStorage } from './rows.js';
+import type { Key } from './state.js';
+
+// A joined thread's view of the world's layout directory (threads.md, "Shared layout directory"): archetypes by their
+// records, struct columns and ticks in shared memory, this thread's objects in its mirror, and the entity table, with
+// the world's numbers for the keys its systems name.
+
+/** A joined thread's view of a storage of the world's, in shared memory, or of this thread's objects, in its mirror. */
+export type ThreadStorage = RowStorage & { readonly component: number };
+
+/** A joined thread's view of one of the world's archetypes, by its record, as of its version and the mirror's columns. */
+export type ThreadArchetype = RowArchetype & {
+    readonly record: number;
+    readonly version: number;
+    readonly mirrored: Mirrored | null | undefined;
+    readonly components: readonly number[];
+    readonly resource: boolean;
+    /** Whether it holds reports, which only queries that require a component see. */
+    readonly meta: boolean;
+    readonly storageById: readonly (ThreadStorage | undefined)[];
+};
+
+export type EntityViews = { cursor: Int32Array; free: Int32Array; generation: Uint32Array; archetype: Int32Array; row: Uint32Array; length: number };
+
+/** A setup naming keys by the world's numbers, with their ids. */
+type Named = { readonly keys: readonly (readonly [number, string])[] };
+
+const noTicks = new Float64Array(0);
+const noTags = new Uint32Array(0);
+const noValues: unknown[] = [];
+
+/** The memory as this thread last viewed it: its buffer, its words and its views, made again once it grew. */
+export type Viewed = { buffer: ArrayBufferLike; words: Uint32Array; views: Views };
+
+/**
+ * A joined thread's directory reader over `memory`, its objects in `mirror` where it fills some: one per thread,
+ * shared by the systems the world places there and the observer systems it adds.
+ */
+export const createThreadDirectory = (memory: WebAssembly.Memory, mirror: Mirror | null) => {
+    const viewed: Viewed = { buffer: new ArrayBuffer(0), words: new Uint32Array(0), views: emptyViews };
+    let pages = -1;
+    /** By the world's number: what its key is here, and its layout, for the keys this thread's systems name. */
+    const keys: (Key | undefined)[] = [];
+    const layouts: Layout[] = [];
+    const numbers = new Map<Key, number>();
+    const archetypes: (ThreadArchetype | undefined)[] = [];
+    let entities: EntityViews | null = null;
+    let entitiesVersion = -1;
+    const rows: RowHost & { tick: number } = { layouts, rows: new Map<string, Row>(), tick: 0, records: true };
+    const noMirrored: readonly (Mirrored | null | undefined)[] = [];
+    const thread = mirror?.thread ?? -1;
+    /** The records strings' columns name, which this thread reads. */
+    const strings = createStringReader(memory);
+
+    /** Views of the memory again, once it grew; every archetype's views with them. Returns its buffer. */
+    const refresh = (): ArrayBufferLike => {
+        if (viewed.words.length === 0) viewed.words = new Uint32Array(memory.buffer);
+        const current = Atomics.load(viewed.words, pagesWord);
+        if (current === pages) return viewed.buffer;
+        const latest = coveringBuffer(memory, current * pageBytes);
+        if (latest.byteLength < current * pageBytes) throw new Error(`This thread's memory is ${latest.byteLength} bytes, short of the ${current * pageBytes} the world stored.`);
+        viewed.buffer = latest;
+        viewed.words = new Uint32Array(latest);
+        viewed.views = viewsOf(latest, 0, latest.byteLength);
+        pages = current;
+        archetypes.length = 0;
+        entitiesVersion = -1;
+        return latest;
+    };
+
+    const refreshEntities = (): EntityViews => {
+        const { words, buffer } = viewed;
+        const record = entitiesWord;
+        const version = Atomics.load(words, record + entitiesVersionField);
+        if (entities === null || version !== entitiesVersion) {
+            const capacity = words[record + capacityField];
+            const views: EntityViews = {
+                cursor: new Int32Array(buffer, words[record + cursorField], 4),
+                free: new Int32Array(buffer, words[record + freeField], words[record + freeCapacityField]),
+                archetype: new Int32Array(buffer, words[record + archetypeField], capacity),
+                row: new Uint32Array(buffer, words[record + rowField], capacity),
+                generation: new Uint32Array(buffer, words[record + generationField], capacity),
+                length: 0,
+            };
+            if (entities === null) entities = views;
+            // Spawners hold the table, so it's updated in place.
+            else Object.assign(entities, views);
+            entitiesVersion = version;
+        }
+        entities.length = entities.cursor[tableLength];
+        return entities;
+    };
+
+    /** A storage's view, by its record's words; this thread's objects by their mirror column. */
+    const storageOf = (base: number, capacity: number, mirrored: Mirrored | null | undefined): ThreadStorage | undefined => {
+        const { words, buffer } = viewed;
+        const component = words[base + storageComponent];
+        const layout = layouts[component];
+        if (layout === undefined) return undefined;
+        const flags = words[base + storageFlags];
+        const ticked = (flags & tickedFlag) !== 0;
+        const own = (flags & remoteFlag) !== 0 && flags >>> threadShift === thread;
+        const chunks = words[base + storageChunks];
+        const added = ticked ? new Float64Array(buffer, words[base + storageAdded], capacity) : noTicks;
+        const changed = ticked ? new Float64Array(buffer, words[base + storageChanged], capacity) : noTicks;
+        return {
+            component,
+            layout,
+            ...writeOf(layout),
+            views: (layout.kind === "linear" || layout.kind === "string") && (flags & linearFlag) !== 0 ? viewsOf(buffer, words[base + storageColumn], capacity * layout.stride) : emptyViews,
+            strings: layout.kind === "string" ? strings : null,
+            // Rows only this thread's systems write: a mirror's column, or one of its own while the mirror has none.
+            values: own ? mirrored?.byComponent[component]?.values ?? [] : noValues,
+            tags: own ? new Uint32Array(buffer, words[base + storageColumn], capacity) : noTags,
+            ticked,
+            added,
+            // A constant's `changed` ticks are its `added` ticks.
+            changed: layout.kind === "constant" ? added : changed,
+            chunkAdded: ticked ? new Float64Array(buffer, words[base + storageChunkAdded], chunks) : noTicks,
+            chunkChanged: ticked ? new Float64Array(buffer, words[layout.kind === "constant" ? base + storageChunkAdded : base + storageChunkChanged], chunks) : noTicks,
+        };
+    };
+
+    const viewArchetype = (id: number, record: number, version: number, mirrored: Mirrored | null | undefined): ThreadArchetype => {
+        const { words, buffer } = viewed;
+        const capacity = words[record + recordCapacity];
+        const storageById: (ThreadStorage | undefined)[] = [];
+        const components: number[] = [];
+        for (let s = 0; s < words[record + recordStorages]; s++) {
+            const base = record + recordWords + s * storageWords;
+            components.push(words[base + storageComponent]);
+            const storage = storageOf(base, capacity, mirrored);
+            if (storage !== undefined) storageById[storage.component] = storage;
+        }
+        return {
+            id, record, version, mirrored, components, storageById,
+            resource: (words[record + recordFlags] & resourceFlag) !== 0,
+            meta: (words[record + recordFlags] & metaFlag) !== 0,
+            entities: new Float64Array(buffer, words[record + recordEntities], capacity),
+        };
+    };
+
+    /** An archetype's view: one load of its record's version, and new views only once it, or the mirror, moved on. */
+    const archetypeAt = (id: number): ThreadArchetype | undefined => {
+        const { words } = viewed;
+        const cached = archetypes[id];
+        const mirrored = (mirror?.archetypes ?? noMirrored)[id];
+        if (cached !== undefined && cached.mirrored === mirrored && Atomics.load(words, cached.record + recordVersion) === cached.version) return cached;
+        const offset = cached?.record ?? (id < Atomics.load(words, tableLengthWord) ? words[(words[tableOffsetWord] >> 2) + id] >> 2 : 0);
+        if (offset === 0) return undefined;
+        return archetypes[id] = viewArchetype(id, offset, Atomics.load(words, offset + recordVersion), mirrored);
+    };
+
+    const countOf = (archetype: ThreadArchetype): number => viewed.words[archetype.record + recordCount];
+
+    /** The resource entity's archetype and row, or null before resources exist. */
+    const resourceRow = (): { readonly archetype: ThreadArchetype; readonly row: number } | null => {
+        const word = Atomics.load(viewed.words, resourceEntityWord);
+        if (word === 0) return null;
+        const table = refreshEntities();
+        const index = word - 1;
+        const archetype = archetypeAt(table.archetype[index]);
+        return archetype === undefined ? null : { archetype, row: table.row[index] };
+    };
+
+    const tableCount = (): number => Atomics.load(viewed.words, tableLengthWord);
+
+    /** Takes the world's numbers for the keys of systems or finalizers it places here. */
+    const name = (setups: readonly Named[]): void => {
+        for (const { keys: named } of setups) {
+            for (const [number, id] of named) {
+                const key = keyOfId(id);
+                if (key === undefined || keys[number] !== undefined) continue;
+                keys[number] = key;
+                numbers.set(firstKeyOf(key), number);
+                layouts[number] = layoutOf(declarationOf(key)?.type);
+                // Views hold storages only of components with layouts here, so they're made again.
+                archetypes.length = 0;
+            }
+        }
+    };
+
+    const numberOf = (key: Key): number => {
+        const number = numbers.get(firstKeyOf(key));
+        if (number === undefined) throw new Error(`"${labelOf(key)}" has no number from the world here.`);
+        return number;
+    };
+
+    return {
+        viewed, rows, keys, layouts, numbers, mirror, strings,
+        refresh, refreshEntities, archetypeAt, countOf, resourceRow, tableCount, name, numberOf,
+        layoutOf: (key: Key): Layout | undefined => layouts[numbers.get(firstKeyOf(key)) ?? -1],
+    };
+};
+
+export type ThreadDirectory = ReturnType<typeof createThreadDirectory>;

package/src/implementation/world/thread-finalizers.ts

@@ -0,0 +1,318 @@
+import type { Leaf } from '../../interface/finalizer/created.js';
+import { labelOf } from '../../interface/registry/index.js';
+import { objectLayout, viewsOf, type Layout } from '../../interface/registry/layout.js';
+import { writeOf } from './archetype.js';
+import { emptyViews } from './arrays.js';
+import { readCell } from './cells.js';
+import { logFinalizedWord, logStopsWord, nullTag, ownTag, slotTags, startTag } from './move-log.js';
+import { stagedValue, type Mirror, type Previously } from './mirror.js';
+import type { WorkerError } from './protocol.js';
+import { rowBinderOf, type Row, type RowArchetype, type RowHost, type RowStorage } from './rows.js';
+import {
+    archetypesAt, blockGroupsWord, blockHeaderBytes, blockNextWord, blockSyncWord, columnBytes, entitiesAt, groupBytesWord, groupCountWord,
+    groupIndexWord, rowsAt, tagsAt, valuesAt,
+} from './stop-lists.js';
+import type { Key } from './state.js';
+import type { StringStore } from './strings.js';
+
+// A joined thread's finalizers (threads.md, "Finalizers on other threads"): as it replays each sync, before that sync's
+// entries apply, it runs them for the sync's stop list, reading the linear structs the world copied there and its own
+// objects at the rows the stops name, then stores the sync it finalized through.
+
+/** A storage of a joined thread's view, as its finalizers' rows read it. */
+type FinalizedStorage = RowStorage & { readonly component: number };
+/** An archetype of a joined thread's view, as its systems see it. */
+type FinalizedArchetype = RowArchetype & { readonly components: readonly number[]; readonly resource: boolean; readonly meta: boolean; readonly storageById: readonly (FinalizedStorage | undefined)[] };
+
+/** What a joined thread gives its finalizers. */
+export type ThreadFinalizersHost<A extends FinalizedArchetype> = {
+    readonly mirror: Mirror;
+    /** Views of the memory, again once it grew. */
+    readonly refresh: () => ArrayBufferLike;
+    readonly rows: RowHost;
+    readonly numberOf: (key: Key) => number;
+    readonly layoutOf: (key: Key) => Layout | undefined;
+    readonly archetypeAt: (id: number) => A | undefined;
+    readonly countOf: (archetype: A) => number;
+    readonly tableCount: () => number;
+    readonly resourceRow: () => { readonly archetype: A; readonly row: number } | null;
+    /** The records strings' columns name: a stop list's copies, for its strings. */
+    readonly strings: StringStore;
+    /** Posts what finalizers threw, by their index here, for the world's next report. */
+    readonly failed: (errors: readonly (readonly [number, WorkerError])[]) => void;
+};
+
+const errorOf = (error: unknown): WorkerError =>
+    error instanceof Error ? { name: error.name, message: error.message, stack: error.stack } : { name: "Error", message: String(error) };
+
+const noTicks = new Float64Array(0);
+const noTags = new Uint32Array(0);
+
+/** One finalizer here: what it matches and reads, its row binder, and its context. */
+type ThreadFinalizer = {
+    readonly leaf: Leaf;
+    readonly required: readonly number[];
+    readonly excluded: readonly number[];
+    /** Its reads by component: objects, with their starts, linear structs, with their layouts, and constants. */
+    readonly objects: readonly number[];
+    readonly starts: readonly unknown[];
+    readonly linear: readonly number[];
+    readonly layouts: readonly Layout[];
+    readonly constants: readonly number[];
+    readonly constantLayouts: readonly Layout[];
+    readonly bind: (archetype: RowArchetype) => Row;
+    readonly context: object;
+    /** Resolves its resources' cells, as of now. */
+    readonly cells: () => void;
+    readonly body: (row: object, context: object) => void;
+};
+
+/** A storage a stop list's column holds, for a row over its stops. */
+const columnStorage = (component: number, layout: Layout, views: RowStorage["views"], values: unknown[], strings: StringStore | null): FinalizedStorage => ({
+    component, layout, views, strings: layout.kind === "string" ? strings : null, values, ...writeOf(layout), ticked: false, added: noTicks, changed: noTicks, chunkAdded: noTicks, chunkChanged: noTicks, tags: noTags,
+});
+
+/**
+ * The finalizers the world places on this thread, with what they run against: stop lists as the thread replays them,
+ * and every row they match once the world is disposed.
+ */
+export const createThreadFinalizers = <A extends FinalizedArchetype>(host: ThreadFinalizersHost<A>) => {
+    const { mirror } = host;
+    const finalizers: (ThreadFinalizer | null | undefined)[] = [];
+    /** The newest block run, which the next block's offset is read from; 0 before the first. */
+    let anchor = 0;
+    /** The sync finalized through, as stored. */
+    let finalized = 0;
+    let buffer: ArrayBufferLike = new ArrayBuffer(0);
+    let u32: Uint32Array<ArrayBufferLike> = new Uint32Array(0);
+    let f64: Float64Array<ArrayBufferLike> = new Float64Array(0);
+    const errors: [number, WorkerError][] = [];
+
+    const views = (): void => {
+        const latest = host.refresh();
+        if (latest === buffer && u32.length > 0) return;
+        buffer = latest;
+        u32 = new Uint32Array(latest);
+        f64 = new Float64Array(latest, 0, latest.byteLength >> 3);
+    };
+
+    const create = (leaf: Leaf): ThreadFinalizer => {
+        const { components, resources } = leaf.declaration;
+        const reads = components.read ?? [];
+        const objects: number[] = [];
+        const starts: unknown[] = [];
+        const linear: number[] = [];
+        const layouts: Layout[] = [];
+        const constants: number[] = [];
+        const constantLayouts: Layout[] = [];
+        for (const key of reads) {
+            const component = host.numberOf(key);
+            const layout = host.layoutOf(key);
+            if (layout === undefined) throw new Error(`"${labelOf(key)}" has no layout here.`);
+            if (layout.kind === "object") {
+                objects.push(component);
+                starts.push(mirror.starts.get(component) ?? null);
+            }
+            // A string's stop column holds handles of records the world copied for it.
+            else if (layout.kind === "linear" || layout.kind === "string") {
+                linear.push(component);
+                layouts.push(layout);
+            }
+            else {
+                constants.push(component);
+                constantLayouts.push(layout);
+            }
+        }
+        const value: object = Object.create({});
+        const keys = [...new Set<Key>(resources?.read ?? [])];
+        const numbers = keys.map(host.numberOf);
+        const resolved: { storage: FinalizedStorage | undefined; row: number }[] = keys.map(() => ({ storage: undefined, row: 0 }));
+        if (keys.length > 0) {
+            const values: object = Object.create({});
+            keys.forEach((key, k) => {
+                Object.defineProperty(values, key, {
+                    get: () => {
+                        const { storage, row } = resolved[k];
+                        if (storage === undefined) throw new Error(`Resource "${labelOf(key)}" isn't in this world.`);
+                        return readCell(storage, row);
+                    },
+                    enumerable: true,
+                });
+            });
+            Object.defineProperty(value, "resources", { value: values, enumerable: true });
+        }
+        // Method parameters are bivariant, so the runtime can see any finalizer's body with erased parameter types.
+        const untyped: { body(row: object, context: object): void } = leaf;
+        return {
+            leaf, objects, starts, linear, layouts, constants, constantLayouts,
+            required: [...new Set([...reads, ...components.has ?? []])].map(host.numberOf),
+            excluded: (components.not ?? []).map(host.numberOf),
+            bind: rowBinderOf<RowArchetype>(host.rows, host.numberOf, reads, []),
+            context: value,
+            cells: () => {
+                const found = keys.length === 0 ? null : host.resourceRow();
+                for (let k = 0; k < keys.length; k++) {
+                    resolved[k].storage = found?.archetype.storageById[numbers[k]];
+                    resolved[k].row = found?.row ?? 0;
+                }
+            },
+            body: (row, context) => untyped.body(row, context),
+        };
+    };
+
+    /** Records the finalizers the world places here; one this thread never imported fails each group of its stops. */
+    const setup = (placed: readonly { readonly index: number; readonly leaf: Leaf | null }[]): void => {
+        for (const { index, leaf } of placed) finalizers[index] = leaf === null ? null : create(leaf);
+    };
+
+    /** Runs a body, keeping what it throws. */
+    const guarded = (index: number, finalizer: ThreadFinalizer, row: Row): void => {
+        try {
+            finalizer.body(row.value, finalizer.context);
+        }
+        catch (error) {
+            errors.push([index, errorOf(error)]);
+        }
+    };
+
+    /** One of an object read's values for a stop: by its tag, else at its row, or after a rebuild as it was. */
+    const objectOf = (tag: number, start: unknown, entity: number, archetype: number, row: number, component: number, old: Previously | null): unknown => {
+        if (tag === startTag) return start;
+        if (tag === nullTag) return null;
+        if (old === null) {
+            const column = mirror.archetypes[archetype]?.byComponent[component];
+            return column === undefined ? start : column.values[row];
+        }
+        const previous = old(entity, component, start);
+        return tag === ownTag ? previous : stagedValue(mirror, (tag - slotTags) >>> 0, previous);
+    };
+
+    /** Whether every finalizer a block names was set up here, as null for one this thread never imported. */
+    const known = (block: number): boolean => {
+        const groups = u32[(block >> 2) + blockGroupsWord];
+        let group = block + blockHeaderBytes;
+        for (let g = 0; g < groups; g++) {
+            if (finalizers[u32[(group >> 2) + groupIndexWord]] === undefined) return false;
+            group += u32[(group >> 2) + groupBytesWord];
+        }
+        return true;
+    };
+
+    /** Runs each group of a block: the bodies of its finalizer for its stops, over a row reading the block's columns. */
+    const runBlock = (block: number, old: Previously | null): void => {
+        const groups = u32[(block >> 2) + blockGroupsWord];
+        let group = block + blockHeaderBytes;
+        for (let g = 0; g < groups; g++) {
+            const index = u32[(group >> 2) + groupIndexWord];
+            const count = u32[(group >> 2) + groupCountWord];
+            const bytes = u32[(group >> 2) + groupBytesWord];
+            const finalizer = finalizers[index];
+            if (finalizer === null || finalizer === undefined) {
+                // Set up, as null, for one this thread never imported.
+                errors.push([index, errorOf(new Error(`A finalizer the world placed on this thread isn't one this thread imported, so ${count === 1 ? "a stop" : `${count} stops`} didn't run.`))]);
+                group += bytes;
+                continue;
+            }
+            const storageById: FinalizedStorage[] = [];
+            const entityWords = entitiesAt(group) >> 3;
+            const archetypeWords = archetypesAt(group, count) >> 2;
+            const rowWords = rowsAt(group, count) >> 2;
+            const { objects, starts, linear, layouts } = finalizer;
+            for (let k = 0; k < objects.length; k++) {
+                const tags = tagsAt(group, count, k) >> 2;
+                const values: unknown[] = new Array<unknown>(count);
+                for (let i = 0; i < count; i++) {
+                    values[i] = objectOf(u32[tags + i], starts[k], f64[entityWords + i], u32[archetypeWords + i], u32[rowWords + i], objects[k], old);
+                }
+                storageById[objects[k]] = columnStorage(objects[k], objectLayout, emptyViews, values, null);
+            }
+            let column = valuesAt(group, count, objects.length);
+            for (let k = 0; k < linear.length; k++) {
+                const layout = layouts[k];
+                const stride = layout.kind === "linear" || layout.kind === "string" ? layout.stride : 0;
+                storageById[linear[k]] = columnStorage(linear[k], layout, viewsOf(buffer, column, count * stride), [], host.strings);
+                column += columnBytes(count, stride);
+            }
+            for (let k = 0; k < finalizer.constants.length; k++) storageById[finalizer.constants[k]] = columnStorage(finalizer.constants[k], finalizer.constantLayouts[k], emptyViews, [], null);
+            const row = finalizer.bind({ id: -1, entities: new Float64Array(buffer, entitiesAt(group), count), storageById });
+            finalizer.cells();
+            for (let i = 0; i < count; i++) {
+                row.index = i;
+                guarded(index, finalizer, row);
+            }
+            group += bytes;
+        }
+    };
+
+    const report = (): void => {
+        if (errors.length === 0) return;
+        host.failed(errors.splice(0));
+    };
+
+    /** Stores the sync finalized through, once it moved on. */
+    const acknowledge = (sync: number): void => {
+        if (((sync - finalized) | 0) <= 0) return;
+        finalized = sync >>> 0;
+        Atomics.store(mirror.header, logFinalizedWord, finalized);
+    };
+
+    /**
+     * Runs the stop lists of every sync through `sync` not run yet, in order, then stores it as finalized through: with
+     * `old`, after the log lapped, reading this thread's objects as they were before the rebuild. False, having stopped
+     * before it, at a block naming a finalizer whose setup hasn't arrived yet.
+     */
+    const through = (sync: number, old: Previously | null): boolean => {
+        views();
+        const { header } = mirror;
+        let complete = true;
+        for (;;) {
+            const next = anchor === 0 ? Atomics.load(header, logStopsWord) >>> 0 : Atomics.load(u32, (anchor >> 2) + blockNextWord);
+            if (next === 0) break;
+            const blockSync = u32[(next >> 2) + blockSyncWord];
+            if (((sync - blockSync) | 0) < 0) break;
+            if (!known(next)) {
+                acknowledge((blockSync - 1) >>> 0);
+                complete = false;
+                break;
+            }
+            runBlock(next, old);
+            anchor = next;
+        }
+        if (complete) acknowledge(sync);
+        report();
+        return complete;
+    };
+
+    /** Whether a stop list is linked that this thread hasn't run. */
+    const pending = (): boolean => {
+        if (anchor === 0) return Atomics.load(mirror.header, logStopsWord) !== 0;
+        views();
+        return Atomics.load(u32, (anchor >> 2) + blockNextWord) !== 0;
+    };
+
+    /** Once the world is disposed: every finalizer runs for every row it matches, reading this thread's objects there. */
+    const all = (): void => {
+        views();
+        for (let index = 0; index < finalizers.length; index++) {
+            const finalizer = finalizers[index];
+            if (finalizer === null || finalizer === undefined) continue;
+            finalizer.cells();
+            for (let id = 0; id < host.tableCount(); id++) {
+                const archetype = host.archetypeAt(id);
+                if (archetype === undefined || archetype.resource || (archetype.meta && finalizer.required.length === 0)) continue;
+                const { components } = archetype;
+                if (!finalizer.required.every(component => components.includes(component)) || finalizer.excluded.some(component => components.includes(component))) continue;
+                const count = host.countOf(archetype);
+                if (count === 0) continue;
+                const row = finalizer.bind(archetype);
+                for (let i = 0; i < count; i++) {
+                    row.index = i;
+                    guarded(index, finalizer, row);
+                }
+            }
+        }
+        report();
+    };
+
+    return { setup, through, pending, all };
+};

package/src/implementation/world/thread-indexes.ts

@@ -0,0 +1,90 @@
+import type { Layout } from '../../interface/registry/layout.js';
+import { recordKey, type HashView } from './index-hash.js';
+import { keyPartsOf } from './index-keys.js';
+import { lookupFunction, type IndexView, type LookupArchetype, type Since } from './index-lookups.js';
+import { sortedStride, type SortedView } from './index-sorted.js';
+import type { RowHost } from './rows.js';
+import type { Key } from './state.js';
+
+/** How many f64 words a lookup's index record takes, as `writeIndexParameters` (`kernel-indexes.ts`) writes it. */
+export const recordWordsOf = (sorted: boolean, watched: number): number => (sorted ? 11 : 7) + watched;
+
+/**
+ * A joined thread's lookup through one of the world's indexes, which lives in the memory: the function its body calls,
+ * and `refresh`, which points its views at the index's arrays as the world wrote them into its record before the task.
+ */
+export type ThreadIndex = { readonly lookup: (...key: unknown[]) => unknown; readonly refresh: (buffer: ArrayBufferLike) => void };
+
+/** What a joined thread knows of a lookup through an index: its key's layouts, the index's kind, its rows' reads and its record. */
+export type ThreadIndexSetup = {
+    readonly layouts: readonly Layout[];
+    readonly sorted: boolean;
+    readonly unique: boolean;
+    readonly reads: readonly Key[];
+    readonly readIds: readonly number[];
+    readonly watched: number;
+    /** The byte offset of the record the world writes before each task. */
+    readonly record: number;
+};
+
+const none32 = new Uint32Array(0);
+const noneI32 = new Int32Array(0);
+const none64 = new Float64Array(0);
+
+/** A view from `at` to the end of the memory, the same one while neither changed. */
+const spanning = <A extends Uint32Array | Int32Array | Float64Array>(current: A, buffer: ArrayBufferLike, at: number, make: (buffer: ArrayBufferLike, at: number) => A): A =>
+    current.buffer === buffer && current.byteOffset === at ? current : make(buffer, at);
+const u32From = (buffer: ArrayBufferLike, at: number): Uint32Array => new Uint32Array(buffer, at);
+const i32From = (buffer: ArrayBufferLike, at: number): Int32Array => new Int32Array(buffer, at);
+const f64From = (buffer: ArrayBufferLike, at: number): Float64Array => new Float64Array(buffer, at);
+
+export const createThreadIndex = (rows: RowHost, archetypeAt: (id: number) => LookupArchetype | undefined, setup: ThreadIndexSetup): ThreadIndex => {
+    const { parts, words } = keyPartsOf(setup.layouts);
+    const watchedPositions = Array.from({ length: setup.watched }, (_, k) => k);
+    const hashWatched = new Map<number, Float64Array>();
+    const sortedWatched = new Map<number, { tree: Float64Array }>();
+    const hash: HashView | null = setup.sorted ? null : { words, stride: recordKey + words, slots: none32, records: none32, ticks: none64, cleared: 0, entries: noneI32, watched: hashWatched };
+    const sorted: SortedView | null = !setup.sorted ? null : {
+        words, stride: sortedStride(words), parts, objects: false, entries: none32, lengths: noneI32, order: noneI32, blocks: 0, counts: noneI32, tree: none64, leaves: 1,
+        fences: none32, size: 0, cleared: 0, watched: sortedWatched,
+    };
+    const index: IndexView = { parts, words, unique: setup.unique, hash, sorted };
+    const since: Since = { value: 0 };
+    const lookup = lookupFunction({ rows, archetypeAt, index, unique: setup.unique, reads: setup.reads, readIds: setup.readIds, watched: watchedPositions, since, replaced: null });
+    const count = recordWordsOf(setup.sorted, setup.watched);
+    let record: Float64Array = none64;
+    const refresh = (buffer: ArrayBufferLike): void => {
+        if (record.buffer !== buffer) record = new Float64Array(buffer, setup.record, count);
+        if (hash !== null) {
+            const slots = record[0];
+            const length = (record[1] + 1) * 2;
+            if (hash.slots.buffer !== buffer || hash.slots.byteOffset !== slots || hash.slots.length !== length) hash.slots = new Uint32Array(buffer, slots, length);
+            hash.records = spanning(hash.records, buffer, record[2], u32From);
+            hash.entries = spanning(hash.entries, buffer, record[3], i32From);
+            hash.ticks = spanning(hash.ticks, buffer, record[4], f64From);
+            hash.cleared = record[5];
+            since.value = record[6];
+            for (let k = 0; k < setup.watched; k++) hashWatched.set(k, spanning(hashWatched.get(k) ?? none64, buffer, record[7 + k], f64From));
+            return;
+        }
+        if (sorted === null) return;
+        sorted.fences = spanning(sorted.fences, buffer, record[0], u32From);
+        sorted.blocks = record[1];
+        sorted.order = spanning(sorted.order, buffer, record[2], i32From);
+        sorted.lengths = spanning(sorted.lengths, buffer, record[3], i32From);
+        sorted.entries = spanning(sorted.entries, buffer, record[4], u32From);
+        sorted.counts = spanning(sorted.counts, buffer, record[5], i32From);
+        sorted.size = record[6];
+        sorted.tree = spanning(sorted.tree, buffer, record[7], f64From);
+        sorted.leaves = record[8];
+        sorted.cleared = record[9];
+        since.value = record[10];
+        for (let k = 0; k < setup.watched; k++) {
+            const watch = sortedWatched.get(k);
+            const at = record[11 + k];
+            if (watch === undefined) sortedWatched.set(k, { tree: f64From(buffer, at) });
+            else watch.tree = spanning(watch.tree, buffer, at, f64From);
+        }
+    };
+    return { lookup, refresh };
+};