@adobe/ecs 0.0.0-stage → 0.2.0

package/src/implementation/world/up.ts

@@ -0,0 +1,912 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import type { UpLists } from '../../interface/system/access.js';
+import type { Archetype, Storage } from './archetype.js';
+import { generationOf, indexOf } from './entities.js';
+import { journalEnd } from './journal.js';
+import { forEachNewerRow } from './ranges.js';
+import { idOf, type Key, type State } from './state.js';
+import { allocateArray, freeArray } from './arrays.js';
+import type { Memory } from './memory.js';
+import { createOrder, type Order } from './order.js';
+
+/** Rows `rows[start]` to `rows[end - 1]` of `matches[owner]`, whose parents are rows `parents[n]` of the archetype with id `parent`, or -1. */
+export type Run = { readonly owner: number; readonly parent: number; readonly rows: Int32Array; readonly parents: Int32Array; readonly start: number; readonly end: number };
+
+/** A filtered run's rows, a depth at a time: each call lists the next depth's rows that run, or null after the last. */
+export type Pass = { readonly next: () => readonly Run[] | null; readonly clear: () => void };
+
+/** `levelOf` values: not matched, and on or under a parent cycle, which never runs. Matched rows hold depth + 1. */
+const unmatched = 0;
+const cyclic = -1;
+/** A depth with more marked rows than this share of the matched rows is listed by scanning its groups in order. */
+const denseShare = 1 / 8;
+/** Rows below this many are sorted rather than scanned. */
+const denseMinimum = 4096;
+/** Sort keys pack a row with its parent's archetype: `(parent + 1) * rowLimit + row`. */
+const rowLimit = 2 ** 27;
+
+/** Grows an array in the arena to at least `length`, without keeping its contents, so WASM can address it. */
+const fitArena = (memory: Memory, array: Int32Array, length: number): Int32Array => {
+    if (array.length >= length) return array;
+    if (array.length > 0) freeArray(memory, array);
+    return allocateArray(memory, Int32Array, Math.max(length, 2 * array.length));
+};
+
+/** Grows an array to at least `length`, without keeping its contents. */
+const fit = (array: Int32Array<ArrayBuffer>, length: number): Int32Array<ArrayBuffer> => array.length >= length ? array : new Int32Array(Math.max(length, 2 * array.length));
+
+/** Grows an array to at least `length`, keeping its contents and filling the rest with `value`. */
+const extend = (array: Int32Array<ArrayBuffer>, length: number, value: number): Int32Array<ArrayBuffer> => {
+    if (array.length >= length) return array;
+    const grown = new Int32Array(Math.max(length, 2 * array.length));
+    grown.set(array);
+    grown.fill(value, array.length);
+    return grown;
+};
+
+// Scratch of an order build, shared by every `up` of a thread, since a build runs start to end without yielding: a
+// second system reuses the first one's arrays rather than allocating its own.
+
+/** By index among the matched rows: its entity index, depth, archetype, parent row, and parent's archetype id when readable or -1. */
+let rowEntities = new Int32Array(0);
+let depths = new Int32Array(0);
+let rowParents = new Int32Array(0);
+let keys = new Int32Array(0);
+let owners = new Int32Array(0);
+/** The matched rows' indexes, by depth, and where each depth ends. */
+let sortedRows = new Int32Array(0);
+let counts = new Int32Array(0);
+/** By index in `matches`: the index of its first row among the matched rows. */
+let bases = new Int32Array(0);
+/** The groups of a build, laid out one after another, before the order lays them out with spare slots. */
+let builtRows = new Int32Array(0);
+let builtParents = new Int32Array(0);
+let builtEntities = new Int32Array(0);
+let groupEnds = new Int32Array(0);
+let groupDepths = new Int32Array(0);
+let groupOwners = new Int32Array(0);
+let groupParents = new Int32Array(0);
+
+/** The tree's arrays before its first update. */
+const noTree = { levelOf: new Int32Array(0), parentOf: new Int32Array(0), firstChild: new Int32Array(0), nextChild: new Int32Array(0), ownerOf: new Int32Array(0) };
+
+/**
+ * The tree of `up`s sharing it, kept by entity index, current with the journal of what sync points changed: each
+ * matched entity's parent, its level, and the matched entities holding it as their parent, as linked lists; and the
+ * order of every row by depth, patched for the entities whose row, level or parent changed.
+ */
+const createShared = (state: State, through: number, read: readonly number[], matching: (archetype: Archetype) => boolean) => {
+    state.journal.readers++;
+    /** The `up`s reading it; the first's `read` and matches are the ones the others agree with. */
+    const readers: Reader[] = [];
+    /** Archetypes, by id, every reader was checked to agree on up to. */
+    let agreed = 0;
+
+    /** By entity index: the parent's entity index or -1, the level, and the first child, next and previous sibling as index + 1, or 0. */
+    let parentOf = new Int32Array(0);
+    let levelOf = new Int32Array(0);
+    let firstChild = new Int32Array(0);
+    let nextChild = new Int32Array(0);
+    let previousChild = new Int32Array(0);
+    /** By entity index: the pass that last saw it, for settling levels and reading the journal once per index. */
+    let stamps = new Int32Array(0);
+    let pass = 0;
+    /** The journal's position read up to, or -1 before the tree is first built. */
+    let position = -1;
+    /** By archetype id: its index in `matches`, or -1. */
+    let ownerOf = new Int32Array(0);
+    let ownersFor = -1;
+    let ownersAmong = -1;
+    /** By archetype id: 1 when it has every component `read` lists, 2 when it doesn't, 0 until checked. */
+    let readable = new Int8Array(0);
+    /** Whether some reader is filtered, and so is told which entities' parents changed. */
+    let anyFiltered = false;
+    /**
+     * Tells every filtered reader an entity's parent changed, so it passes their next run. A reader holds at most a
+     * journal's worth: past that, it drops them and runs every row next, which costs about what reading them would.
+     */
+    const touch = (index: number): void => {
+        for (let k = 0; k < readers.length; k++) {
+            const reader = readers[k];
+            if (!reader.filtered || reader.rebuilt) continue;
+            reader.touched.push(index);
+            if (reader.touched.length > Math.max(4096, state.entities.length)) {
+                reader.touched = [];
+                reader.rebuilt = true;
+            }
+        }
+    };
+    /** Tells every filtered reader the tree was built again, so their next run runs every row. */
+    const rebuiltAll = (): void => {
+        for (const reader of readers) {
+            reader.touched = [];
+            reader.rebuilt = reader.filtered;
+        }
+    };
+    /** By entity index: its archetype id when the tree last saw it, or -1. */
+    let archetypeAt = new Int32Array(0);
+    /** Entities whose slot in the order may have changed since it was last patched, once each. */
+    let moved: number[] = [];
+    let movedStamps = new Int32Array(0);
+    let movedPass = 1;
+    /** Whether the order must be built again from every row. */
+    let unordered = true;
+    const order = createOrder(state.memory);
+    /** The arrays readers read, as of the last update. */
+    const tree = { parentOf, levelOf, firstChild, nextChild, ownerOf };
+
+    /** Whether an archetype holds every component `read` lists, so a parent in it has `up` values. */
+    const isReadable = (id: number): boolean => {
+        if (readable.length <= id) {
+            const grown = new Int8Array(Math.max(id + 1, 2 * readable.length));
+            grown.set(readable);
+            readable = grown;
+        }
+        if (readable[id] === 0) {
+            readable[id] = readableBy(state, read, id) ? 1 : 2;
+        }
+        return readable[id] === 1;
+    };
+
+    /** The list owners were found for: a runner's list is new once archetypes left it (`reclaim.ts`). */
+    let ownersList: readonly Archetype[] | null = null;
+    // Readers agree on every archetype, so lists of the same length are the same.
+    const refreshOwners = (matches: readonly Archetype[]): void => {
+        if (ownersList === matches && ownersFor === matches.length && ownersAmong === state.archetypes.length) return;
+        ownersList = matches;
+        ownerOf = fit(ownerOf, state.archetypes.length);
+        ownerOf.fill(-1);
+        matches.forEach((archetype, owner) => { ownerOf[archetype.id] = owner; });
+        ownersFor = matches.length;
+        ownersAmong = state.archetypes.length;
+    };
+
+    /** The entity index of an entity's live parent, or -1. */
+    const parentAt = (index: number): number => {
+        const { entities } = state;
+        const archetype = state.archetypes[entities.archetype[index]];
+        const storage: Storage | undefined = archetype.storageById[through];
+        const layout = storage?.layout;
+        // An entity is one f64, read straight from its column.
+        const leaf = layout?.kind === "linear" ? layout.leaves[0] : undefined;
+        if (storage === undefined || leaf === undefined) return -1;
+        const parent = storage.views[leaf.view][entities.row[index] * leaf.unitStride + leaf.unitOffset];
+        const target = parent >>> 0;
+        if (parent <= 0 || target >= entities.length || entities.archetype[target] < 0 || entities.generation[target] !== generationOf(parent)) return -1;
+        return target;
+    };
+
+    const isMatched = (index: number): boolean => {
+        const archetype = state.entities.archetype[index];
+        return archetype >= 0 && ownerOf[archetype] >= 0;
+    };
+
+    const unlink = (index: number): void => {
+        const parent = parentOf[index];
+        if (parent < 0) return;
+        const previous = previousChild[index];
+        const next = nextChild[index];
+        if (previous !== 0) nextChild[previous - 1] = next;
+        else firstChild[parent] = next;
+        if (next !== 0) previousChild[next - 1] = previous;
+    };
+
+    const link = (index: number, parent: number): void => {
+        parentOf[index] = parent;
+        if (parent < 0) return;
+        const first = firstChild[parent];
+        nextChild[index] = first;
+        previousChild[index] = 0;
+        if (first !== 0) previousChild[first - 1] = index + 1;
+        firstChild[parent] = index + 1;
+    };
+
+    /** Grows the arrays by entity index to the entity table. */
+    const grow = (): void => {
+        const length = state.entities.length;
+        if (parentOf.length >= length) return;
+        parentOf = extend(parentOf, length, -1);
+        levelOf = extend(levelOf, length, unmatched);
+        firstChild = extend(firstChild, length, 0);
+        nextChild = extend(nextChild, length, 0);
+        previousChild = extend(previousChild, length, 0);
+        stamps = extend(stamps, length, 0);
+        movedStamps = extend(movedStamps, length, 0);
+        archetypeAt = extend(archetypeAt, length, -1);
+    };
+
+    /** Notes that an entity's slot in the order may have changed; past a quarter of the rows, the order is built again instead. */
+    const move = (index: number): void => {
+        if (unordered || movedStamps[index] === movedPass) return;
+        movedStamps[index] = movedPass;
+        moved.push(index);
+        if (moved.length > Math.max(1024, order.live() / 4)) {
+            unordered = true;
+            moved = [];
+            movedPass++;
+        }
+    };
+
+    let stack = new Int32Array(0);
+    let queue = new Int32Array(0);
+
+    /**
+     * Sets the levels of the matched entities among `pending`, and of each descendant whose level changes as a result.
+     * Each walks up to a root, or to an entity this call already settled, so every level it sets is exact, and a cycle
+     * is found where a walk meets itself; each entity is walked once per call.
+     */
+    const settle = (pending: readonly number[] | Int32Array, count: number): void => {
+        const waiting = ++pass;
+        const walkedPending = ++pass;
+        const walked = ++pass;
+        const settled = ++pass;
+        for (let k = 0; k < count; k++) if (levelOf[pending[k]] !== unmatched) stamps[pending[k]] = waiting;
+        let queued = 0;
+        const descend = (index: number): void => {
+            const level = levelOf[index];
+            const want = level === cyclic ? cyclic : level + 1;
+            for (let child = firstChild[index]; child !== 0; child = nextChild[child - 1]) {
+                const c = child - 1;
+                if (levelOf[c] === want) {
+                    stamps[c] = settled;
+                    continue;
+                }
+                levelOf[c] = want;
+                stamps[c] = settled;
+                move(c);
+                queue = extend(queue, queued + 1, 0);
+                queue[queued++] = c;
+            }
+        };
+        for (let k = 0; k < count; k++) {
+            const start = pending[k];
+            if (stamps[start] !== waiting) continue;
+            let height = 0;
+            let current = start;
+            for (; current >= 0 && levelOf[current] !== unmatched; current = parentOf[current]) {
+                const stamp = stamps[current];
+                if (stamp === settled || stamp === walkedPending || stamp === walked) break;
+                stamps[current] = stamp === waiting ? walkedPending : walked;
+                stack = extend(stack, height + 1, 0);
+                stack[height++] = current;
+            }
+            const stop = current < 0 || levelOf[current] === unmatched ? -1 : stamps[current];
+            let level = stop === -1 ? 0 : stop === settled ? levelOf[current] : cyclic;
+            // The pending were journaled, so their children may have changed; the rest only if their level did.
+            stack = extend(stack, 2 * height, 0);
+            let descending = 0;
+            for (let h = height - 1; h >= 0; h--) {
+                const node = stack[h];
+                level = level === cyclic ? cyclic : level + 1;
+                const changed = levelOf[node] !== level;
+                if (changed) move(node);
+                if (changed || stamps[node] === walkedPending) stack[descending++ + height] = node;
+                levelOf[node] = level;
+                stamps[node] = settled;
+            }
+            for (let d = 0; d < descending; d++) descend(stack[height + d]);
+            while (queued > 0) descend(queue[--queued]);
+        }
+    };
+
+    /** Builds the tree from every matched row. */
+    const build = (matches: readonly Archetype[]): void => {
+        const length = state.entities.length;
+        parentOf.fill(-1, 0, length);
+        levelOf.fill(unmatched, 0, length);
+        firstChild.fill(0, 0, length);
+        archetypeAt.set(state.entities.archetype.subarray(0, length));
+        let count = 0;
+        for (const archetype of matches) count += archetype.count;
+        const all = new Int32Array(count);
+        let at = 0;
+        const levels = levelOf;
+        for (const archetype of matches) {
+            const rows = archetype.entities;
+            for (let row = 0, end = archetype.count; row < end; row++) {
+                const index = rows[row] >>> 0;
+                levels[index] = 1;
+                all[at++] = index;
+            }
+        }
+        // Each archetype's parent column is found once, as `parentAt` finds it per entity.
+        const { generation, archetype: archetypeOf, length: entityCount } = state.entities;
+        const parents = parentOf;
+        at = 0;
+        for (const archetype of matches) {
+            const storage: Storage | undefined = archetype.storageById[through];
+            const layout = storage?.layout;
+            const leaf = layout?.kind === "linear" ? layout.leaves[0] : undefined;
+            if (storage === undefined || leaf === undefined) {
+                for (let row = 0; row < archetype.count; row++) parents[all[at++]] = -1;
+                continue;
+            }
+            const view = storage.views[leaf.view];
+            const stride = leaf.unitStride, offset = leaf.unitOffset;
+            for (let row = 0, end = archetype.count; row < end; row++) {
+                const index = all[at++];
+                const parent = view[row * stride + offset];
+                const target = parent >>> 0;
+                link(index, parent > 0 && target < entityCount && archetypeOf[target] >= 0 && generation[target] === generationOf(parent) ? target : -1);
+            }
+        }
+        settleAll(all, count);
+    };
+
+    /**
+     * Sets the level of every matched entity in `all`, the whole tree: each walks up to a root or to an entity already
+     * set, then sets the levels on its way back down, so each entity is walked once. A walk meeting itself is a cycle,
+     * and it and everything below it on the walk is cyclic.
+     */
+    const settleAll = (all: Int32Array, count: number): void => {
+        const walking = ++pass;
+        const done = ++pass;
+        stack = extend(stack, count, 0);
+        const levels = levelOf, parents = parentOf, seen = stamps, path = stack;
+        for (let k = 0; k < count; k++) {
+            let current = all[k];
+            if (seen[current] === done) continue;
+            let height = 0;
+            for (; current >= 0 && levels[current] !== unmatched; current = parents[current]) {
+                const stamp = seen[current];
+                if (stamp === done || stamp === walking) break;
+                seen[current] = walking;
+                path[height++] = current;
+            }
+            let level = current < 0 || levels[current] === unmatched ? 0 : seen[current] === done ? levels[current] : cyclic;
+            for (let h = height - 1; h >= 0; h--) {
+                const node = path[h];
+                if (level !== cyclic) level++;
+                levels[node] = level;
+                seen[node] = done;
+            }
+        }
+    };
+
+    /** Brings the tree up to date with the journal. */
+    const update = (matches: readonly Archetype[]): void => {
+        refreshOwners(matches);
+        grow();
+        tree.parentOf = parentOf;
+        tree.levelOf = levelOf;
+        tree.firstChild = firstChild;
+        tree.nextChild = nextChild;
+        tree.ownerOf = ownerOf;
+        const { journal } = state;
+        const end = journalEnd(journal);
+        if (position === end) return;
+        if (position < journal.first) {
+            build(matches);
+            position = end;
+            rebuiltAll();
+            unordered = true;
+            return;
+        }
+        const seen = ++pass;
+        const pending: number[] = [];
+        for (let at = position; at < end; at++) {
+            const index = journal.indexes[at - journal.first];
+            if (stamps[index] === seen) continue;
+            stamps[index] = seen;
+            // Its row may have changed, and so its children's parent row: the order moves them.
+            move(index);
+            for (let child = firstChild[index]; child !== 0; child = nextChild[child - 1]) move(child - 1);
+            const archetype = state.entities.archetype[index];
+            const otherArchetype = archetype !== archetypeAt[index];
+            archetypeAt[index] = archetype;
+            if (!isMatched(index)) {
+                if (levelOf[index] === unmatched) continue;
+                unlink(index);
+                parentOf[index] = -1;
+                levelOf[index] = unmatched;
+                // Its children's parent no longer runs: they're roots now.
+                for (let child = firstChild[index]; child !== 0; child = nextChild[child - 1]) {
+                    pending.push(child - 1);
+                    if (anyFiltered) touch(child - 1);
+                }
+                continue;
+            }
+            const parent = parentAt(index);
+            const fresh = levelOf[index] === unmatched;
+            if (fresh) {
+                levelOf[index] = 1;
+                link(index, parent);
+            }
+            else if (parent !== parentOf[index]) {
+                unlink(index);
+                link(index, parent);
+            }
+            else if (!otherArchetype) continue;
+            pending.push(index);
+            if (!anyFiltered) continue;
+            touch(index);
+            // What its children read of it may differ in another archetype. A child whose reference changed is
+            // journaled itself, as is one whose parent is gone, since `through` has a reference policy.
+            if (otherArchetype) for (let child = firstChild[index]; child !== 0; child = nextChild[child - 1]) touch(child - 1);
+        }
+        position = end;
+        settle(pending, pending.length);
+    };
+
+    /** The matched rows in depth order from the roots. Rows on or under a parent cycle are in none. */
+    const levels = (matches: readonly Archetype[]): Order => {
+        update(matches);
+        if (unordered) buildOrder(matches);
+        else if (moved.length > 0) patch();
+        moved = [];
+        movedPass++;
+        return order.current();
+    };
+
+    /** Moves each entity whose slot may have changed: all removals first, so no two slots of a group share a row. */
+    const patch = (): void => {
+        const { archetype: archetypeOf, row: rowOf } = state.entities;
+        const count = moved.length;
+        const targets = new Int32Array(4 * count);
+        const kept = new Uint8Array(count);
+        for (let k = 0; k < count; k++) {
+            const index = moved[k];
+            const level = levelOf[index];
+            targets[4 * k] = level < 1 ? -1 : level - 1;
+            if (level < 1) {
+                order.remove(index);
+                continue;
+            }
+            const parent = parentOf[index];
+            const owner = ownerOf[archetypeOf[index]];
+            const key = parent < 0 || !isReadable(archetypeOf[parent]) ? -1 : archetypeOf[parent];
+            targets[4 * k + 1] = owner;
+            targets[4 * k + 2] = key;
+            targets[4 * k + 3] = parent < 0 ? 0 : rowOf[parent];
+            if (order.isAt(index, level - 1, owner, key, rowOf[index])) kept[k] = 1;
+            else order.remove(index);
+        }
+        for (let k = 0; k < count; k++) {
+            const depth = targets[4 * k];
+            if (depth < 0) continue;
+            const index = moved[k];
+            if (kept[k] === 1) order.setParent(index, targets[4 * k + 3]);
+            else order.insert(index, depth, targets[4 * k + 1], targets[4 * k + 2], rowOf[index], targets[4 * k + 3]);
+        }
+        order.tidy();
+    };
+
+    /** Builds the order from every matched row. */
+    const buildOrder = (matches: readonly Archetype[]): void => {
+        let count = 0;
+        for (const archetype of matches) count += archetype.count;
+        const deepest = scanRows(matches, count);
+        sortByDepth(count, deepest);
+        const groups = groupRows(matches, deepest);
+        order.load(groups, builtRows, builtParents, builtEntities, groupEnds, groupDepths, groupOwners, groupParents, state.entities.length);
+        unordered = false;
+    };
+
+    // The loops below read typed arrays through local constants: V8 reloads closure variables on every access.
+
+    /**
+     * Records each matched row's depth, archetype, parent row, and parent's archetype when readable or -1, by index
+     * among the matched rows, and flags the parents' archetypes. Returns the deepest depth.
+     */
+    const scanRows = (matches: readonly Archetype[], count: number): number => {
+        const { archetype: archetypeOf, row: rowOf } = state.entities;
+        for (let id = 0; id < state.archetypes.length; id++) isReadable(id);
+        rowEntities = fit(rowEntities, count);
+        depths = fit(depths, count);
+        rowParents = fit(rowParents, count);
+        keys = fit(keys, count);
+        owners = fit(owners, count);
+        const levels = levelOf, parents = parentOf, known = readable;
+        const rowIndexes = rowEntities, rowDepths = depths, rowKeys = keys, rowOwners = owners, rowParentRows = rowParents;
+        let deepest = -1;
+        let global = 0;
+        for (let a = 0; a < matches.length; a++) {
+            const archetype = matches[a];
+            const rows = archetype.entities;
+            rowOwners.fill(a, global, global + archetype.count);
+            for (let row = 0, end = archetype.count; row < end; row++, global++) {
+                const index = rows[row] >>> 0;
+                const depth = levels[index] - 1;
+                rowIndexes[global] = index;
+                rowDepths[global] = depth;
+                if (depth > deepest) deepest = depth;
+                const parent = parents[index];
+                if (parent < 0) {
+                    rowKeys[global] = -1;
+                    continue;
+                }
+                const parentArchetype = archetypeOf[parent];
+                rowParentRows[global] = rowOf[parent];
+                rowKeys[global] = known[parentArchetype] === 1 ? parentArchetype : -1;
+            }
+        }
+        return deepest;
+    };
+
+    /** Orders the matched rows by depth, keeping storage order within each: `counts[d]` ends depth `d` in `sortedRows`. */
+    const sortByDepth = (count: number, deepest: number): void => {
+        sortedRows = fit(sortedRows, count);
+        counts = fit(counts, deepest + 2);
+        counts.fill(0, 0, deepest + 2);
+        const ordered = sortedRows, ends = counts, rowDepths = depths;
+        for (let k = 0; k < count; k++) if (rowDepths[k] >= 0) ends[rowDepths[k] + 1]++;
+        for (let depth = 1; depth <= deepest + 1; depth++) ends[depth] += ends[depth - 1];
+        for (let k = 0; k < count; k++) {
+            const depth = rowDepths[k];
+            if (depth >= 0) ordered[ends[depth]++] = k;
+        }
+    };
+
+    /**
+     * Within each depth and archetype, which `order` already keeps together, groups rows by their parents' archetype,
+     * stably, so a kernel call binds one parent archetype's columns. Returns the number of groups.
+     */
+    const groupRows = (matches: readonly Archetype[], deepest: number): number => {
+        const total = counts[deepest] ?? 0;
+        builtRows = fit(builtRows, total);
+        builtParents = fit(builtParents, total);
+        builtEntities = fit(builtEntities, total);
+        groupEnds = fit(groupEnds, total);
+        groupDepths = fit(groupDepths, total);
+        groupOwners = fit(groupOwners, total);
+        groupParents = fit(groupParents, total);
+        bases = fit(bases, matches.length);
+        bases[0] = 0;
+        for (let a = 1; a < matches.length; a++) bases[a] = bases[a - 1] + matches[a - 1].count;
+        const ordered = sortedRows, rowOwners = owners, rowKeys = keys, rowParentRows = rowParents, rowIndexes = rowEntities, starts = bases;
+        const toRows = builtRows, toParents = builtParents, toEntities = builtEntities;
+        let groups = 0;
+        const close = (end: number, depth: number, owner: number, parent: number): void => {
+            groupEnds[groups] = end;
+            groupDepths[groups] = depth;
+            groupOwners[groups] = owner;
+            groupParents[groups++] = parent;
+        };
+        let depthStart = 0;
+        for (let depth = 0; depth <= deepest; depth++) {
+            const depthEnd = counts[depth];
+            for (let start = depthStart; start < depthEnd;) {
+                const owner = rowOwners[ordered[start]];
+                const base = starts[owner];
+                const first = rowKeys[ordered[start]];
+                let end = start + 1;
+                let uniform = true;
+                for (; end < depthEnd && rowOwners[ordered[end]] === owner; end++) if (rowKeys[ordered[end]] !== first) uniform = false;
+                if (uniform) {
+                    for (let k = start; k < end; k++) {
+                        const global = ordered[k];
+                        toRows[k] = global - base;
+                        toParents[k] = rowParentRows[global];
+                        toEntities[k] = rowIndexes[global];
+                    }
+                    close(end, depth, owner, first);
+                }
+                else {
+                    let slot = start;
+                    const parentKeys = [...new Set(ordered.subarray(start, end).map(k => rowKeys[k]))].sort((a, b) => a - b);
+                    for (const parentKey of parentKeys) {
+                        for (let k = start; k < end; k++) {
+                            const global = ordered[k];
+                            if (rowKeys[global] !== parentKey) continue;
+                            toRows[slot] = global - base;
+                            toEntities[slot] = rowIndexes[global];
+                            toParents[slot++] = rowParentRows[global];
+                        }
+                        close(slot, depth, owner, parentKey);
+                    }
+                }
+                start = end;
+            }
+            depthStart = depthEnd;
+        }
+        return groups;
+    };
+
+    /** Whether `read` and `matches` agree with the first reader's on every archetype so far. */
+    const agreesOn = (other: Reader, id: number): boolean => {
+        const archetype = state.archetypes[id];
+        return other.matching(archetype) === matching(archetype) && readableBy(state, other.read, id) === isReadable(id);
+    };
+    const agrees = (other: Reader): boolean => {
+        for (let id = 0; id < agreed; id++) if (!agreesOn(other, id)) return false;
+        return true;
+    };
+    /** Checks every archetype since the last check; a reader disagreeing on one leaves, to build a tree of its own. */
+    const checkAgreement = (): void => {
+        for (; agreed < state.archetypes.length; agreed++) {
+            for (let k = readers.length - 1; k >= 0; k--) if (!agreesOn(readers[k], agreed)) leave(readers[k]);
+        }
+    };
+    const join = (reader: Reader): void => {
+        readers.push(reader);
+        reader.shared = shared;
+        reader.touched = [];
+        reader.rebuilt = reader.filtered;
+        anyFiltered ||= reader.filtered;
+    };
+    /** Takes `reader` out, releasing what it holds once no reader is left. */
+    const leave = (reader: Reader): void => {
+        const at = readers.indexOf(reader);
+        if (at < 0) return;
+        readers.splice(at, 1);
+        reader.shared = null;
+        anyFiltered = readers.some(each => each.filtered);
+        if (readers.length > 0) return;
+        state.journal.readers--;
+        order.release();
+        const all = sharedOf.get(state);
+        if (all !== undefined) all.splice(all.indexOf(shared), 1);
+    };
+
+    const shared = { through, tree, readers, agrees, checkAgreement, join, leave, update, levels, isReadable };
+    return shared;
+};
+
+type Shared = ReturnType<typeof createShared>;
+
+/** What an `up` keeps of its own: whether it's filtered, what it reads and matches, and what its tree told it. */
+type Reader = {
+    readonly filtered: boolean;
+    readonly read: readonly number[];
+    readonly matching: (archetype: Archetype) => boolean;
+    shared: Shared | null;
+    /** Entities whose parent changed since its last filtered run, which then pass. */
+    touched: number[];
+    /** Whether its tree was built again since its last filtered run, which then runs every row. */
+    rebuilt: boolean;
+};
+
+/** Whether an archetype holds every component `read` lists, so a parent in it has `up` values. */
+const readableBy = (state: State, read: readonly number[], id: number): boolean => {
+    const archetype = state.archetypes[id];
+    return archetype !== undefined && !archetype.resource && read.every(component => archetype.storageById[component] !== undefined);
+};
+
+/** By thread: its trees, each shared by the `up`s whose `through`, matches and readable parents agree. */
+const sharedOf = new WeakMap<State, Shared[]>();
+
+/** The tree `reader` reads: the one it's in while it agrees, else one it agrees with, else a new one. */
+const sharedFor = (state: State, reader: Reader, through: number): Shared => {
+    const current = reader.shared;
+    if (current !== null) {
+        current.checkAgreement();
+        if (reader.shared === current) return current;
+    }
+    let all = sharedOf.get(state);
+    if (all === undefined) sharedOf.set(state, all = []);
+    for (const candidate of all) {
+        if (candidate.through !== through) continue;
+        candidate.checkAgreement();
+        if (candidate.readers.length > 0 && candidate.agrees(reader)) {
+            candidate.join(reader);
+            return candidate;
+        }
+    }
+    const created = createShared(state, through, reader.read, reader.matching);
+    all.push(created);
+    created.join(reader);
+    created.checkAgreement();
+    return created;
+};
+
+/**
+ * Orders an `up` system's rows by depth through its `through` reference. A row's depth is one more than its parent's
+ * when its parent is among the matched rows, and 0 otherwise, so rows of one depth never read each other's writes.
+ * `matching` is whether its query matches an archetype.
+ *
+ * Its tree and order are shared with every `up` of the thread whose `through` is the same and that agrees on which
+ * archetypes match and which parents are readable, so each is built and kept current once. A filtered run marks the
+ * rows that may pass, by depth, and lists only those.
+ */
+export const createUp = (state: State, up: UpLists, isFiltered: boolean, matching: (archetype: Archetype) => boolean) => {
+    const through = idOf(state, up.through);
+    const readKeys: readonly Key[] = up.read ?? [];
+    const self: Reader = { filtered: isFiltered, read: readKeys.map(key => idOf(state, key)), matching, shared: null, touched: [], rebuilt: false };
+
+    /** By entity index: whether the current filtered run marked it. */
+    let dirty = new Uint8Array(0);
+    /** By depth: the entities the current filtered run marked. */
+    const buckets: number[][] = [];
+    let marked: number[] = [];
+    let deepestMarked = -1;
+    /** A filtered run's rows and their parents' rows, in the arena so WASM kernels can address them. */
+    let list: Int32Array = new Int32Array(0);
+    let parentList: Int32Array = new Int32Array(0);
+    let sortKeys = new Float64Array(0);
+
+    /** The tree's arrays, bound once a filtered run brought it up to date. */
+    let { levelOf, parentOf, firstChild, nextChild, ownerOf } = noTree;
+
+    const mark = (index: number): void => {
+        const level = levelOf[index];
+        if (level < 1 || dirty[index] !== 0) return;
+        dirty[index] = 1;
+        marked.push(index);
+        (buckets[level - 1] ??= []).push(index);
+        if (level - 1 > deepestMarked) deepestMarked = level - 1;
+    };
+
+    const markChildren = (index: number): void => {
+        for (let child = firstChild[index]; child !== 0; child = nextChild[child - 1]) mark(child - 1);
+    };
+
+    /** Calls `each` with every row whose ticks of a component are newer than `since`, by its `added` or `changed` ticks. */
+    const changedRows = (archetype: Archetype, id: number, added: boolean, since: number, each: (row: number) => void): void => {
+        const storage = archetype.storageById[id];
+        if (storage === undefined) return;
+        if (storage.columnChanged > since) {
+            for (let row = 0; row < archetype.count; row++) each(row);
+            return;
+        }
+        if (added) forEachNewerRow(storage.added, storage.chunkAdded, storage.blockAdded, archetype.count, since, each);
+        else forEachNewerRow(storage.changed, storage.chunkChanged, storage.blockChanged, archetype.count, since, each);
+    };
+
+    /**
+     * Marks the rows of a filtered run that may pass after `since`: those passing `added` or `changed`, whose parent
+     * reference changed, whose parent's `read` values changed, or that the journal says moved or changed parent. Returns
+     * null when none do. Each listed row marks its children, so a change reaches every row under it.
+     */
+    const filtered = (matches: readonly Archetype[], added: readonly number[], changed: readonly number[], since: number): Pass | null => {
+        const shared = sharedFor(state, self, through);
+        shared.update(matches);
+        // Every row passes after a rebuild, so the pass is the whole order, with nothing to mark.
+        if (self.rebuilt) {
+            self.touched = [];
+            self.rebuilt = false;
+            const ordered = shared.levels(matches);
+            return ordered.levels === 0 ? null : wholePass(ordered);
+        }
+        ({ levelOf, parentOf, firstChild, nextChild, ownerOf } = shared.tree);
+        const { isReadable } = shared;
+        const length = state.entities.length;
+        if (dirty.length < length) dirty = new Uint8Array(Math.max(length, 2 * dirty.length));
+        for (const bucket of buckets) if (bucket !== undefined) bucket.length = 0;
+        marked = [];
+        deepestMarked = -1;
+        for (const archetype of matches) {
+            const { entities } = archetype;
+            const markRow = (row: number): void => mark(entities[row] >>> 0);
+            for (const id of added) changedRows(archetype, id, true, since, markRow);
+            for (const id of [...changed, through]) changedRows(archetype, id, false, since, markRow);
+        }
+        const { read } = self;
+        if (read.length > 0) {
+            for (const archetype of state.archetypes) {
+                if (archetype.count === 0 || !isReadable(archetype.id)) continue;
+                const { entities } = archetype;
+                for (const id of read) changedRows(archetype, id, false, since, row => markChildren(entities[row] >>> 0));
+            }
+        }
+        for (const index of self.touched) mark(index);
+        self.touched = [];
+        if (marked.length === 0) return null;
+        let matched = 0;
+        for (const archetype of matches) matched += archetype.count;
+        list = fitArena(state.memory, list, matched);
+        parentList = fitArena(state.memory, parentList, matched);
+        let listed = 0;
+        let depth = 0;
+        const { archetype: archetypeOf, row: rowOf } = state.entities;
+
+        /** Lists a depth's marked rows by scanning its groups in order. */
+        const scan = (runs: Run[]): void => {
+            const ordered = shared.levels(matches);
+            if (depth >= ordered.levels) return;
+            for (let group = ordered.depthGroups[depth]; group < ordered.depthGroups[depth + 1]; group++) {
+                const owner = ordered.groupOwners[group];
+                const first = listed;
+                for (let slot = ordered.groupStarts[group]; slot < ordered.groupEnds[group]; slot++) {
+                    const index = ordered.entities[slot];
+                    if (dirty[index] === 0) continue;
+                    markChildren(index);
+                    list[listed] = ordered.rows[slot];
+                    parentList[listed++] = ordered.parents[slot];
+                }
+                if (listed > first) runs.push({ owner, parent: ordered.groupParents[group], rows: list, parents: parentList, start: first, end: listed });
+            }
+        };
+
+        /** Lists a depth's marked rows by sorting them by archetype, parent archetype and row. */
+        const sort = (bucket: readonly number[], runs: Run[]): void => {
+            const byOwner = new Map<number, number[]>();
+            for (const index of bucket) {
+                const owner = ownerOf[archetypeOf[index]];
+                let entries = byOwner.get(owner);
+                if (entries === undefined) byOwner.set(owner, entries = []);
+                entries.push(index);
+            }
+            for (const owner of [...byOwner.keys()].sort((a, b) => a - b)) {
+                const entries = byOwner.get(owner) ?? [];
+                if (sortKeys.length < entries.length) sortKeys = new Float64Array(Math.max(entries.length, 2 * sortKeys.length));
+                const sorting = sortKeys.subarray(0, entries.length);
+                for (let k = 0; k < entries.length; k++) {
+                    const index = entries[k];
+                    const parent = parentOf[index];
+                    const key = parent < 0 || !isReadable(archetypeOf[parent]) ? -1 : archetypeOf[parent];
+                    sorting[k] = (key + 1) * rowLimit + rowOf[index];
+                }
+                sorting.sort();
+                const entities = matches[owner].entities;
+                let first = listed;
+                let current = -2;
+                for (let k = 0; k < sorting.length; k++) {
+                    const key = Math.floor(sorting[k] / rowLimit) - 1;
+                    const row = sorting[k] % rowLimit;
+                    if (key !== current) {
+                        if (listed > first) runs.push({ owner, parent: current, rows: list, parents: parentList, start: first, end: listed });
+                        first = listed;
+                        current = key;
+                    }
+                    const index = entities[row] >>> 0;
+                    markChildren(index);
+                    list[listed] = row;
+                    parentList[listed++] = key < 0 ? 0 : rowOf[parentOf[index]];
+                }
+                if (listed > first) runs.push({ owner, parent: current, rows: list, parents: parentList, start: first, end: listed });
+            }
+        };
+
+        const next = (): readonly Run[] | null => {
+            while (depth <= deepestMarked && (buckets[depth]?.length ?? 0) === 0) depth++;
+            if (depth > deepestMarked) return null;
+            const bucket = buckets[depth];
+            const runs: Run[] = [];
+            const dense = bucket.length > Math.max(denseMinimum, matched * denseShare);
+            if (dense || matched >= rowLimit) scan(runs);
+            else sort(bucket, runs);
+            depth++;
+            return runs;
+        };
+        const clear = (): void => {
+            for (const index of marked) dirty[index] = 0;
+        };
+        return { next, clear };
+    };
+
+    /** The matched rows in depth order from the roots. Rows on or under a parent cycle are in none. */
+    const levels = (matches: readonly Archetype[]): Order => {
+        const ordered = sharedFor(state, self, through).levels(matches);
+        // Every row runs, so a filtered `up` needs none of what changed before.
+        if (self.filtered) {
+            self.touched = [];
+            self.rebuilt = false;
+        }
+        return ordered;
+    };
+
+    /** Frees what it holds in the arena and leaves its tree, once nothing runs it again. */
+    const release = (): void => {
+        self.shared?.leave(self);
+        if (list.length > 0) freeArray(state.memory, list);
+        if (parentList.length > 0) freeArray(state.memory, parentList);
+        list = parentList = new Int32Array(0);
+    };
+
+    return { levels, filtered, wholePass, release };
+};
+
+/** Every row of `ordered`, a depth at a time. */
+const wholePass = (ordered: Order): Pass => {
+    let depth = 0;
+    const next = (): readonly Run[] | null => {
+        if (depth >= ordered.levels) return null;
+        const runs: Run[] = [];
+        for (let group = ordered.depthGroups[depth]; group < ordered.depthGroups[depth + 1]; group++) {
+            if (ordered.groupEnds[group] === ordered.groupStarts[group]) continue;
+            runs.push({ owner: ordered.groupOwners[group], parent: ordered.groupParents[group], rows: ordered.rows, parents: ordered.parents, start: ordered.groupStarts[group], end: ordered.groupEnds[group] });
+        }
+        depth++;
+        return runs;
+    };
+    return { next, clear: noClear };
+};
+
+const noClear = (): void => {};
+
+/** For tests: how many entities a thread's filtered `up`s were told changed, held until their next run. */
+export const touchedHeld = (state: State): number => {
+    let held = 0;
+    for (const shared of sharedOf.get(state) ?? []) for (const reader of shared.readers) held += reader.touched.length;
+    return held;
+};