@adobe/ecs 0.1.0 → 0.2.1

package/dist/implementation/world/thread-systems.js

@@ -1,7 +1,8 @@
-import { declarationOf, definitionOf, firstKeyOf, indexOfLookup, isLeaf, itemOfId, kindOf, labelOf, programFinalizers, threadOfDeclaration, watchedBy } from '../../interface/registry/index.js';
+import { declarationOf, definitionOf, firstKeyOf, indexOfLookup, isLeaf, itemOfId, kindOf, labelOf, programFinalizers, threadOfDeclaration, watchedBy, whyUnregistered } from '../../interface/registry/index.js';
 import { layoutOf, objectLayout, viewsOf } from '../../interface/registry/layout.js';
 import { stampChanged, writeOf } from './archetype.js';
 import { emptyViews } from './arrays.js';
+import { arrivalsPosition, createDebts, membershipOf } from './arrivals.js';
 import { readCell, writeCell } from './cells.js';
 import { beginCommand, createRingWriter, dropCommand, encoderOf, endSegment, localNumbers, objectStart, putComponent, putNull, putSlot, putStart, putValue, startSegment, } from './command-ring.js';
 import { addCommand, despawnCommand, removeCommand } from './buffer.js';
@@ -14,14 +15,17 @@ import { applying, rebuild, replay, stage, waitStructure } from './mirror.js';
 import { forEachPassingRange } from './ranges.js';
 import { combine, contributed, identityOf, reductionTargetsOf } from './reductions.js';
 import { changedRowOf, emptyRow, rowBinderOf } from './rows.js';
-import { createBatch, positionalSpawner } from './staging.js';
+import { requiredOf } from './required.js';
+import { createBatch, noValues, positionalSpawner } from './staging.js';
 import { createThreadFinalizers } from './thread-finalizers.js';
+import { createThreadWhere } from './where.js';
 import { createThreadIndex } from './thread-indexes.js';
 import { keptSorted } from './index-keys.js';
-import { chunkShift } from './kernel.js';
+import { blockShift, chunkShift } from './kernel.js';
 import { doneWord, endWord, headExecuted, headRan, progressWord, snapshotFlagsWord, snapshotLayout, snapshotOffsetWord, snapshotResourceArchetypeWord, snapshotResourceRowWord, snapshotRowsWord, snapshotCapacityWord, snapshotted, tailBlockWords, tailChunk, waitingWord, } from './tail-blocks.js';
 import { defaultOf } from './state.js';
-import { completionCapacityWord, completionMessage, completionOffsetWord, completionSystems, executedFlag, failedFlag, payloadCapacityWord, payloadCount, payloadInput, payloadOffsetWord, payloadSequence, payloadSystems, ranFlag, resultEnd, resultFields, resultFlags, resultStart, ringBaseWord, ringCapacityWord, payloadSync, ringCursorWord, ringNeededWord, spilledFlag, systemFields, systemFolds, systemIndex, systemLastRun, systemTail, systemTick, systemTier, taskDoneWord, taskFailedWord, taskPostedWord, } from './thread-tasks.js';
+import { isThenable, returnedPromise } from './failures.js';
+import { completionCapacityWord, completionMessage, completionOffsetWord, completionSystems, executedFlag, failedFlag, payloadCapacityWord, payloadCount, payloadInput, payloadOffsetWord, payloadSequence, payloadSystems, ranFlag, resultEnd, resultFields, resultFlags, resultStart, ringBaseWord, ringCapacityWord, payloadSync, ringCursorWord, ringNeededWord, spilledFlag, systemFields, systemFolds, systemIndex, systemLastRun, systemTail, systemTick, systemTier, systemValued, valuedFlag, taskDoneWord, taskFailedWord, taskPostedWord, } from './thread-tasks.js';
 // A joined thread's systems (threads.md, "Systems on other threads"): runners over the world's archetypes as the layout
 // directory describes them, struct columns and resources in shared memory, this thread's objects in its mirror
 // (`mirror.ts`), with commands and spawns written into its command ring, run as tasks the world posts.
@@ -38,7 +42,7 @@ const noBatches = [];
  */
 export const createThreadSystems = (host) => {
     const { mirror, control, directory } = host;
-    const { viewed, rows: rowHost, numbers, refreshEntities, archetypeAt, countOf, resourceRow, tableCount } = directory;
+    const { viewed, rows: rowHost, numbers, refreshEntities, archetypeAt, countOf, arrivals, resourceRow, tableCount } = directory;
     const refreshMemory = () => { directory.refresh(); };
     const runners = [];
     const inputs = new Map();
@@ -76,7 +80,7 @@ export const createThreadSystems = (host) => {
         }
         const declaration = declarationOf(key);
         if (declaration === undefined || kindOf(key) !== "component")
-            throw new Error(kindOf(key) === "resource" ? `"${labelOf(key)}" is a resource, not a component.` : `"${labelOf(key)}" has no registered schema; import the module that registers it.`);
+            throw new Error(kindOf(key) === "resource" ? `"${labelOf(key)}" is a resource, not a component.` : `"${labelOf(key)}" has no registered schema: ${whyUnregistered(key)}.`);
         if (declaration.derived === true)
             throw new Error(`"${labelOf(key)}" is derived, so only rules add and remove it.`);
         const layout = layoutOf(declaration.type);
@@ -89,6 +93,7 @@ export const createThreadSystems = (host) => {
                 : layout.kind === "object" && !own ? `"${labelOf(key)}" lives on thread "${thread ?? "world"}", so a command on another thread gives it only its start or null.` : null,
             start: layout.kind === "constant" ? layout.value : defaultOf(key),
             transfer: declaration.transfer === true,
+            shared: declaration.shared === true,
         };
         commandKeys.set(first, entry);
         commandKeys.set(key, entry);
@@ -121,12 +126,19 @@ export const createThreadSystems = (host) => {
         }
         return true;
     };
+    /** A key a spawn or add gives a value: never a shared component's, whose value chooses an archetype, which only the world's thread does. */
+    const givenKeyOf = (key) => {
+        const entry = commandKeyOf(key);
+        if (entry.shared)
+            throw new Error(`"${labelOf(key)}" is shared: its value chooses an archetype, so only the world's thread spawns and adds it.`);
+        return entry;
+    };
     /** Spawns this thread stages of a list's components, into a batch per set, reserving entities in blocks. */
     const spawnerOf = (list) => {
         const known = spawners.get(list);
         if (known !== undefined)
             return known;
-        const listed = list.map(commandKeyOf);
+        const listed = list.map(givenKeyOf);
         const ids = listed.map(entry => entry.number);
         const order = ids.join(",");
         const same = spawnersByNumbers.get(order);
@@ -156,7 +168,7 @@ export const createThreadSystems = (host) => {
         const positional = positionalSpawner(reserving, reserveFrom, target, ids, listed.map(entry => entry.layout.kind === "object" || entry.layout.kind === "string" ? objectStart : entry.start));
         const keysOfList = list.filter((key) => typeof key === "symbol");
         const args = new Array(keysOfList.length);
-        const spawn = (values) => {
+        const spawn = (values = noValues) => {
             for (let k = 0; k < keysOfList.length; k++)
                 args[k] = Reflect.get(values, keysOfList[k]);
             if (!usedBatches.includes(target))
@@ -167,13 +179,45 @@ export const createThreadSystems = (host) => {
         spawnersByNumbers.set(order, spawn);
         return spawn;
     };
+    /**
+     * Spawns of a list with constants, which no shared component is among: the same function for one list's components
+     * and one constants object, found by its identity here, reading each component's value from the constants or else
+     * from what each spawn gives, and failing its system for one given in both.
+     */
+    const presetSpawners = new WeakMap();
+    const presetSpawnerOf = (list, preset) => {
+        const spawn = spawnerOf(list);
+        let byPreset = presetSpawners.get(spawn);
+        if (byPreset === undefined)
+            presetSpawners.set(spawn, byPreset = new WeakMap());
+        const known = byPreset.get(preset);
+        if (known !== undefined)
+            return known;
+        const keysOfList = list.filter((key) => typeof key === "symbol");
+        const merged = {};
+        const spawned = (values = noValues) => {
+            for (const key of keysOfList) {
+                const constant = Reflect.get(preset, key);
+                const given = Reflect.get(values, key);
+                if (constant !== undefined && given !== undefined)
+                    throw new Error(`A spawn gives "${labelOf(key)}" in both its calls: each component's value comes from one.`);
+                merged[key] = constant === undefined ? given : constant;
+            }
+            return spawn(merged);
+        };
+        byPreset.set(preset, spawned);
+        return spawned;
+    };
     const empty = {};
     const commands = {
-        spawn: components => spawnerOf(components),
+        // A second parameter rather than a rest one, which would allocate an array each call.
+        spawn: (components, preset) => {
+            return typeof preset === "object" && preset !== null ? presetSpawnerOf(components, preset) : spawnerOf(components);
+        },
         despawn: entity => beginCommand(writer, despawnCommand, entity),
         add: (entity, components, values) => {
             if (typeof components === "symbol") {
-                const key = commandKeyOf(components);
+                const key = givenKeyOf(components);
                 beginCommand(writer, addCommand, entity);
                 if (!putOne(key, entity, values))
                     dropCommand(writer);
@@ -181,7 +225,7 @@ export const createThreadSystems = (host) => {
             }
             // Every key is checked before anything is written.
             for (let k = 0; k < components.length; k++)
-                commandKeyOf(components[k]);
+                givenKeyOf(components[k]);
             const given = typeof values === "object" && values !== null ? values : empty;
             beginCommand(writer, addCommand, entity);
             let crosses = true;
@@ -227,8 +271,8 @@ export const createThreadSystems = (host) => {
         return extent;
     };
     const runnerHost = {
-        rows: rowHost, archetypeAt, countOf, tableCount, resourceRow, refreshEntities, commands, mirror,
-        refresh: directory.refresh,
+        rows: rowHost, archetypeAt, countOf, arrivals, tableCount, resourceRow, refreshEntities, commands, mirror,
+        refresh: directory.refresh, replaced: directory.replaced,
         numberOf: directory.numberOf,
         layoutOf: directory.layoutOf,
         strings: directory.strings,
@@ -300,21 +344,29 @@ export const createThreadSystems = (host) => {
             return { index, leaf: leaf?.kind === "finalizer" ? leaf : null };
         }));
     };
-    /** Brings the mirror up to the last published sync, which runs the finalizers of its stops; false while it can't. */
-    const current = () => {
+    /**
+     * Brings the mirror up to the last published sync, which runs the finalizers of its stops: `"moved"` when its
+     * rebuild found a sync point applying before or during it, so it can rebuild once that's applied, and `"held"`
+     * while it waits for something else.
+     */
+    const bringCurrent = () => {
         const replayed = replay(mirror);
         if (replayed === "held")
-            return false;
-        return replayed !== "lapped" || rebuild(mirror);
+            return "held";
+        if (replayed !== "lapped")
+            return "current";
+        const rebuilt = rebuild(mirror);
+        return rebuilt === "rebuilt" ? "current" : rebuilt;
     };
+    const current = () => bringCurrent() === "current";
     /** Whether a task can run: its systems known here, its input arrived, and the mirror through its sync. */
     const ready = (payload, count) => {
         for (let k = 0; k < count; k++)
             if (runners[payload[payloadSystems + k * systemFields + systemIndex]] === undefined)
-                return false;
+                return "held";
         if (payload[payloadInput] !== 0 && !inputs.has(payload[payloadSequence]))
-            return false;
-        return current();
+            return "held";
+        return bringCurrent();
     };
     /** Views of the payload and completion, kept while the world keeps them where they are. */
     let payload = new Float64Array(0);
@@ -369,16 +421,48 @@ export const createThreadSystems = (host) => {
             tailControls.set(offset, control = new Int32Array(viewed.buffer, offset, tailBlockWords));
         return control;
     };
-    /** A task waiting for a sync point to finish applying, to rebuild its mirror, runs once it has. */
+    /**
+     * A task waiting for a sync point to finish applying, to rebuild its mirror, runs once it has. One whose rebuild
+     * found a sync point applied during it runs again after a turn of the event loop: nothing else may wake this thread
+     * before the task is done, and sync points overlapping every rebuild mustn't keep it from its event loop.
+     */
     let structureWaited = false;
-    const retryAfterStructure = () => {
-        if (structureWaited || !applying(mirror))
+    const retried = () => {
+        structureWaited = false;
+        process();
+    };
+    const retryAfterStructure = (moved) => {
+        if (structureWaited)
             return;
-        structureWaited = true;
-        void waitStructure(mirror).then(() => {
-            structureWaited = false;
-            process();
-        });
+        if (applying(mirror)) {
+            structureWaited = true;
+            void waitStructure(mirror).then(retried);
+        }
+        else if (moved) {
+            structureWaited = true;
+            setTimeout(retried, 0);
+        }
+    };
+    /**
+     * Posts a task's message. A value that can't be posted, as one holding a function, fails its system instead, and
+     * the message goes again without values.
+     */
+    const postCompleted = (sequence, errors, spills, values, transfer) => {
+        const extra = stamps.length > 0 ? { stamps: [...stamps] } : {};
+        try {
+            host.post({ protocol: protocolName, kind: "completed", sequence, errors: errors ?? [], spills: spills ?? [], ...values === null ? {} : { values }, ...extra }, transfer ?? []);
+        }
+        catch (error) {
+            if (values === null)
+                throw error;
+            const failed = errors ?? [];
+            for (const [k] of values) {
+                const at = completionSystems + k * resultFields + resultFlags;
+                completion[at] = (completion[at] & ~valuedFlag) | failedFlag;
+                failed.push([k, errorOf(new Error(`Its value can't be posted to the world's thread: ${error instanceof Error ? error.message : String(error)}`))]);
+            }
+            host.post({ protocol: protocolName, kind: "completed", sequence, errors: failed, spills: spills ?? [], ...extra }, transfer ?? []);
+        }
     };
     const runTask = (posted) => {
         refreshMemory();
@@ -386,8 +470,9 @@ export const createThreadSystems = (host) => {
         const count = payload[payloadCount];
         const sequence = payload[payloadSequence];
         pending = sequence;
-        if (!ready(payload, count)) {
-            retryAfterStructure();
+        const readiness = ready(payload, count);
+        if (readiness !== "current") {
+            retryAfterStructure(readiness === "moved");
             return;
         }
         pending = -1;
@@ -398,6 +483,7 @@ export const createThreadSystems = (host) => {
         let errors = null;
         let spills = null;
         let transfer = null;
+        let values = null;
         let failedTier = -1;
         const folds = completionSystems + count * resultFields;
         stamps.length = 0;
@@ -435,6 +521,11 @@ export const createThreadSystems = (host) => {
                     flags |= failedFlag;
                     (errors ??= []).push([k, errorOf(outcome.error)]);
                 }
+                else if (outcome.value !== undefined && payload[base + systemValued] !== 0) {
+                    flags |= valuedFlag;
+                    (values ??= []).push([k, outcome.value]);
+                }
+                outcome.value = undefined;
                 completion[result + resultFlags] = flags;
                 continue;
             }
@@ -447,6 +538,11 @@ export const createThreadSystems = (host) => {
                 if (outcome.ran)
                     flags |= ranFlag;
                 error = outcome.error ?? running.error;
+                if (error === undefined && outcome.value !== undefined && payload[base + systemValued] !== 0) {
+                    flags |= valuedFlag;
+                    (values ??= []).push([k, outcome.value]);
+                }
+                outcome.value = undefined;
             }
             try {
                 const extent = writeSegment();
@@ -470,10 +566,10 @@ export const createThreadSystems = (host) => {
                 runner.writeFolds(completion, folds + payload[base + systemFolds]);
             completion[result + resultFlags] = flags;
         }
-        const message = errors !== null || spills !== null || stamps.length > 0 || host.numbered() !== numberedBefore || !host.worldWaits;
+        const message = errors !== null || spills !== null || values !== null || stamps.length > 0 || host.numbered() !== numberedBefore || !host.worldWaits;
         completion[completionMessage] = message ? 1 : 0;
         if (message)
-            host.post({ protocol: protocolName, kind: "completed", sequence, errors: errors ?? [], spills: spills ?? [], ...stamps.length > 0 ? { stamps: [...stamps] } : {} }, transfer ?? []);
+            postCompleted(sequence, errors, spills, values, transfer);
         Atomics.store(control, taskDoneWord, posted);
         Atomics.notify(control, taskDoneWord);
     };
@@ -512,6 +608,13 @@ export const createThreadSystems = (host) => {
         systems: () => runners.filter(runner => runner !== undefined).length,
     };
 };
+/** One run's outcome: whether it took its tick, ran its rows, and its error. */
+/** A body's value, or a throw failing its system when it's a promise or another thenable, which nothing awaits. */
+const notThenable = (value) => {
+    if (isThenable(value))
+        throw new Error(returnedPromise);
+    return value;
+};
 const noRecords = new Map();
 /** Runs one system here, as the world's runner runs a main-thread system (`runner.ts`). */
 export const createThreadRunner = (host, leaf, records = noRecords) => {
@@ -520,27 +623,138 @@ export const createThreadRunner = (host, leaf, records = noRecords) => {
     const system = leaf;
     const { components: query, resources } = declaration;
     const numberOf = host.numberOf;
-    const required = [...new Set([...query?.read ?? [], ...query?.write ?? [], ...query?.has ?? [], ...query?.added ?? [], ...query?.changed ?? []])].map(numberOf);
+    const required = requiredOf(query).map(numberOf);
     const excluded = (query?.not ?? []).map(numberOf);
     const addedIds = (query?.added ?? []).map(numberOf);
     const changedIds = (query?.changed ?? []).map(numberOf);
     const resourceChanged = (resources?.changed ?? []).map(numberOf);
     const filtered = addedIds.length + changedIds.length + resourceChanged.length > 0;
-    const bindRow = rowBinderOf(host.rows, numberOf, query?.read ?? [], query?.write ?? []);
+    const bindRow = rowBinderOf(host.rows, numberOf, query?.read ?? [], query?.write ?? [], query?.optional);
     const matches = [];
     let checked = 0;
+    /** Its `where`, run here as on the world's thread (`where.ts`); null without one. */
+    const where = query?.where === undefined ? null : createThreadWhere({ archetypeAt: host.archetypeAt, numberOf, resourceRow: host.resourceRow, tick: () => host.rows.tick - 1 }, query.where, query.whereReads ?? []);
+    /** With `where` and change filters, each match's own last run, as on the world's thread. */
+    const pointed = where !== null && filtered;
+    const points = [];
+    /** By archetype id, its match, or -1. */
+    const matchOf = [];
+    /** Its `lastRun` as of its run here: a new match's point, and a non-match's, whose rows it never saw. */
+    let latest = 0;
+    /** What archetypes owe for rows moved in from others, as on the world's thread. */
+    const debts = pointed ? createDebts(points, matchOf, arrivalsPosition(host.arrivals())) : null;
+    const oldestPoint = () => {
+        let oldest = latest;
+        for (let m = 0; m < matches.length; m++)
+            if (points[m] < oldest)
+                oldest = points[m];
+        return oldest;
+    };
+    /** By match, its archetype's generation as matched: reused for other values (`reclaim.ts`), it's matched anew. */
+    const generations = [];
+    /**
+     * The world's count of archetypes reclaimed and reused as it last looked, which it follows as it changes; null before
+     * its first look, which sees every archetype as it is.
+     */
+    let followed = null;
+    const isMatch = (archetype) => {
+        const has = (id) => archetype.components.includes(id);
+        return !archetype.resource && !archetype.reclaimed && required.every(has) && !excluded.some(has);
+    };
+    const addMatch = (id, archetype) => {
+        const m = matches.length;
+        points[m] = latest;
+        generations[m] = archetype.generation;
+        matchOf[id] = m;
+        matches.push(id);
+    };
+    const moveMatch = (from, to) => {
+        const id = matches[from];
+        matches[to] = id;
+        points[to] = points[from];
+        generations[to] = generations[from];
+        matchOf[id] = to;
+        where?.move(from, to);
+    };
+    const swapMatches = (a, b) => {
+        if (a === b)
+            return;
+        const first = matches[a];
+        const point = points[a];
+        const generation = generations[a];
+        matches[a] = matches[b];
+        points[a] = points[b];
+        generations[a] = generations[b];
+        matchOf[matches[a]] = a;
+        matches[b] = first;
+        points[b] = point;
+        generations[b] = generation;
+        matchOf[first] = b;
+        where?.swapped(a, b);
+    };
+    /** As on the world's thread: one evaluated by `where` stays among those evaluated. */
+    const removeMatch = (m) => {
+        matchOf[matches[m]] = -1;
+        let hole = m;
+        if (where !== null && m < where.evaluated) {
+            const edge = where.evaluated - 1;
+            if (edge !== hole)
+                moveMatch(edge, hole);
+            hole = edge;
+            where.forgetLast();
+        }
+        const last = matches.length - 1;
+        if (hole !== last)
+            moveMatch(last, hole);
+        matches.length = points.length = generations.length = last;
+    };
+    /**
+     * Once archetypes were reclaimed or reused: each match reclaimed leaves, each reused is matched anew, and each it
+     * has seen and doesn't match is matched once reused, reading every record it has seen. Arrivals are read first, as
+     * on the world's thread.
+     */
+    const followMembership = () => {
+        debts?.read(host.arrivals(), host.rows.tick, host.tableCount(), latest, oldestPoint);
+        for (let m = matches.length - 1; m >= 0; m--) {
+            const archetype = host.archetypeAt(matches[m]);
+            if (archetype === undefined || archetype.reclaimed)
+                removeMatch(m);
+            else if (archetype.generation !== generations[m]) {
+                points[m] = latest;
+                generations[m] = archetype.generation;
+                if (where !== null && m < where.evaluated) {
+                    swapMatches(m, where.evaluated - 1);
+                    where.forgetLast();
+                }
+            }
+        }
+        for (let id = 0; id < checked; id++) {
+            if ((matchOf[id] ?? -1) >= 0)
+                continue;
+            const archetype = host.archetypeAt(id);
+            if (archetype !== undefined && isMatch(archetype))
+                addMatch(id, archetype);
+        }
+    };
     const refreshMatches = () => {
+        const membership = membershipOf(host.arrivals());
+        if (followed === null)
+            followed = membership;
+        else if (membership !== followed) {
+            followed = membership;
+            followMembership();
+        }
         for (const count = host.tableCount(); checked < count; checked++) {
             const archetype = host.archetypeAt(checked);
             if (archetype === undefined)
                 break;
-            const has = (id) => archetype.components.includes(id);
-            if (!archetype.resource && !(archetype.meta && required.length === 0) && required.every(has) && !excluded.some(has))
-                matches.push(checked);
+            matchOf[checked] = -1;
+            if (isMatch(archetype))
+                addMatch(checked, archetype);
         }
     };
     const ownInput = inputFor(leaf);
-    const targets = reductionTargetsOf(host.layoutOf, declaration);
+    const targets = reductionTargetsOf(host.layoutOf, leaf.name, declaration);
     const reduced = targets.map(target => new Float64Array(target.leaves.length));
     // The context: resources, lookups, reductions, input and commands, each under its own key when declared.
     const own = () => Object.create({});
@@ -593,11 +807,11 @@ export const createThreadRunner = (host, leaf, records = noRecords) => {
                 found = entityLookupOf(host, declared, lookupSince);
             else {
                 const reads = declared.read ?? [];
-                const threadIndex = createThreadIndex(host.rows, host.archetypeAt, {
+                const threadIndex = createThreadIndex(host.rows, host.archetypeAt, host.replaced, {
                     layouts: index.declaration.key.map(key => {
                         const layout = host.layoutOf(key);
                         if (layout === undefined)
-                            throw new Error(`"${labelOf(key)}" has no registered schema; import the module that registers it.`);
+                            throw new Error(`"${labelOf(key)}" has no registered schema: ${whyUnregistered(key)}.`);
                         return layout;
                     }),
                     sorted: keptSorted(index.declaration),
@@ -629,17 +843,15 @@ export const createThreadRunner = (host, leaf, records = noRecords) => {
         });
         Object.defineProperty(value, "reduce", { value: reducers, enumerable: true });
     }
-    if (declaration.input !== undefined)
-        value.input = undefined;
     // A tail is terminal, so its context has no commands.
     const tailValue = own();
     for (const name of Object.getOwnPropertyNames(value)) {
         const descriptor = Object.getOwnPropertyDescriptor(value, name);
-        if (descriptor !== undefined && name !== "input")
+        if (descriptor !== undefined)
             Object.defineProperty(tailValue, name, descriptor);
     }
-    if (declaration.input !== undefined)
-        tailValue.input = undefined;
+    /** The current run's input, which the body takes after its context; kept until the next run, as its context is. */
+    let runInput;
     Object.defineProperty(value, "commands", { value: host.commands, enumerable: true });
     /** Resolves resource cells for a run: they move only at sync points. */
     const bind = () => {
@@ -688,12 +900,12 @@ export const createThreadRunner = (host, leaf, records = noRecords) => {
         for (const id of addedIds) {
             const storage = archetype.storageById[id];
             if (storage !== undefined)
-                filters.push({ ticks: storage.added, chunks: storage.chunkAdded });
+                filters.push({ ticks: storage.added, chunks: storage.chunkAdded, blocks: storage.blockAdded });
         }
         for (const id of changedIds) {
             const storage = archetype.storageById[id];
             if (storage !== undefined)
-                filters.push({ ticks: storage.changed, chunks: storage.chunkChanged });
+                filters.push({ ticks: storage.changed, chunks: storage.chunkChanged, blocks: storage.blockChanged });
         }
         filterCache.set(archetype.id, { archetype, filters });
         return filters;
@@ -701,27 +913,28 @@ export const createThreadRunner = (host, leaf, records = noRecords) => {
     const runBody = (archetype, count, since) => {
         const row = bindRow(archetype);
         const subject = row.value;
+        const input = runInput;
         const filters = filtersOf(archetype);
         if (since < 0 || filters.length === 0) {
             for (let index = 0; index < count; index++) {
                 row.index = index;
-                system.body(subject, value);
+                system.body(subject, value, input);
             }
             return;
         }
         forEachPassingRange(filters, since, 0, count, (start, end) => {
             for (let index = start; index < end; index++) {
                 row.index = index;
-                system.body(subject, value);
+                system.body(subject, value, input);
             }
         });
     };
-    const outcome = { executed: false, ran: false, error: undefined };
+    const outcome = { executed: false, ran: false, error: undefined, value: undefined };
     /** Set once its system is removed on this thread: no row runs from then on. */
     let halted = false;
     const run = (lastRun, input) => {
         outcome.executed = outcome.ran = false;
-        outcome.error = undefined;
+        outcome.error = outcome.value = undefined;
         lookupSince.value = lastRun;
         try {
             // A system whose conditions don't hold is skipped, successfully, and keeps its `lastRun`.
@@ -733,29 +946,48 @@ export const createThreadRunner = (host, leaf, records = noRecords) => {
             const since = !filtered || resourcesChanged ? -1 : lastRun;
             bind();
             if (threadIndexes.length !== 0) {
+                // Settles the count after `ready()` or `current()` may have rebuilt the mirror, since `runTask` settles before them.
                 const buffer = host.refresh();
                 for (let k = 0; k < threadIndexes.length; k++)
                     threadIndexes[k].refresh(buffer);
             }
-            if (declaration.input !== undefined)
-                value.input = ownInput(input);
+            runInput = ownInput(input);
             if (query === undefined) {
                 outcome.ran = since < 0;
                 if (outcome.ran)
-                    system.body(value);
+                    outcome.value = notThenable(system.body(value, runInput));
                 return outcome;
             }
-            if (since >= 0 && addedIds.length + changedIds.length === 0)
+            if (since >= 0 && addedIds.length + changedIds.length === 0 && !pointed)
                 return outcome;
             outcome.ran = true;
+            latest = lastRun;
             refreshMatches();
-            for (let m = 0; m < matches.length; m++) {
-                const archetype = host.archetypeAt(matches[m]);
+            debts?.read(host.arrivals(), host.rows.tick, host.tableCount(), latest, oldestPoint);
+            if (where !== null)
+                where.refresh(matches);
+            const list = where === null ? matches : where.passing;
+            const listed = where === null ? matches.length : where.count;
+            for (let k = 0; k < listed; k++) {
+                const archetype = host.archetypeAt(list[k]);
                 if (archetype === undefined)
                     continue;
+                let from = since;
+                if (pointed && where !== null) {
+                    const m = where.indices[k];
+                    if (since >= 0) {
+                        // Rows moved in since its point count as changed since their old archetype's.
+                        const point = debts?.sinceOf(list[k], points[m]) ?? points[m];
+                        from = resourceChanged.length > 0 && resourcesChangedSince(point) ? -1 : point;
+                    }
+                    points[m] = host.rows.tick;
+                    debts?.settle(list[k]);
+                    if (from >= 0 && addedIds.length + changedIds.length === 0)
+                        continue;
+                }
                 const count = host.countOf(archetype);
                 if (count > 0)
-                    runBody(archetype, count, since);
+                    runBody(archetype, count, from);
             }
         }
         catch (error) {
@@ -767,6 +999,8 @@ export const createThreadRunner = (host, leaf, records = noRecords) => {
     // thread's, which it reads from its mirror at the snapshot's rows.
     const readKeys = query?.read ?? [];
     const writeKeys = query?.write ?? [];
+    /** Its optional components, which rows from a snapshot have only where their archetype does. */
+    const optionalNumbers = (query?.optional ?? []).map(numberOf);
     const linearReads = [];
     const constantReads = [];
     for (const key of readKeys) {
@@ -777,6 +1011,8 @@ export const createThreadRunner = (host, leaf, records = noRecords) => {
         else if (layout?.kind === "constant")
             constantReads.push({ number: numberOf(key), layout });
     }
+    /** The shared components it reads, whose values a snapshot's rows take from their archetypes. */
+    const sharedReads = constantReads.flatMap(({ number, layout }) => layout.kind === "constant" && layout.shared === true ? [number] : []);
     const objectKeys = [...new Set([...readKeys, ...writeKeys])].filter(key => host.layoutOf(key)?.kind === "object").map(numberOf);
     const writtenObjects = new Set(writeKeys.map(numberOf));
     const snapshotResources = resourceKeys.flatMap((key, k) => {
@@ -797,21 +1033,24 @@ export const createThreadRunner = (host, leaf, records = noRecords) => {
     const runRows = (archetype, start, end, since) => {
         const row = bindRow(archetype);
         const subject = row.value;
+        const input = runInput;
         const filters = filtersOf(archetype);
         if (since < 0 || filters.length === 0) {
             for (let index = start; index < end && !halted; index++) {
                 row.index = index;
-                system.body(subject, tailValue);
+                system.body(subject, tailValue, input);
             }
             return;
         }
         forEachPassingRange(filters, since, start, end, (first, last) => {
             for (let index = first; index < last && !halted; index++) {
                 row.index = index;
-                system.body(subject, tailValue);
+                system.body(subject, tailValue, input);
             }
         });
     };
+    /** By match as of the head, with `where`: the tick its rows pass after, -2 for one `where` skips. */
+    const tailSinces = [];
     /** Runs positions `from` to `to` where their rows are, over the archetypes as of the head. */
     const runPositions = (from, to, since) => {
         let base = 0;
@@ -820,8 +1059,9 @@ export const createThreadRunner = (host, leaf, records = noRecords) => {
             const start = Math.max(from - 1 - base, 0);
             const end = Math.min(to - 1 - base, count);
             const archetype = tailArchetypes[m];
-            if (end > start && archetype !== undefined)
-                runRows(archetype, start, end, since);
+            const passing = where === null ? since : tailSinces[m];
+            if (end > start && archetype !== undefined && passing !== -2)
+                runRows(archetype, start, end, passing);
             base += count;
             if (base >= to - 1)
                 return;
@@ -889,12 +1129,11 @@ export const createThreadRunner = (host, leaf, records = noRecords) => {
                 return;
             outcome.executed = true;
             outcome.ran = (flags & headRan) !== 0;
-            if (declaration.input !== undefined)
-                tailValue.input = ownInput(input);
+            runInput = ownInput(input);
             if (!outcome.ran)
                 return;
             if (query === undefined) {
-                system.body(tailValue);
+                outcome.value = notThenable(system.body(tailValue, runInput));
                 writeBackResources(ownResources, resourceArchetype, resourceRow, tick, at, stamps);
                 return;
             }
@@ -907,8 +1146,10 @@ export const createThreadRunner = (host, leaf, records = noRecords) => {
         linearReads.forEach(({ number, layout: linear }, k) => {
             storageById[number] = localStorage(number, linear, viewsOf(buffer, offset + placed.columns[k], rows * linear.stride), [], 0, host.strings);
         });
+        // A shared component's value is each row's archetype's, bound a run of one archetype's rows at a time.
         for (const { number, layout: constant } of constantReads)
-            storageById[number] = localStorage(number, constant, emptyViews, [], 0, host.strings);
+            if (constant.kind !== "constant" || constant.shared !== true)
+                storageById[number] = localStorage(number, constant, emptyViews, [], 0, host.strings);
         const objects = [];
         for (const number of objectKeys) {
             const values = new Array(rows);
@@ -929,12 +1170,60 @@ export const createThreadRunner = (host, leaf, records = noRecords) => {
         let first = 0;
         while (first < rows && positions[first] < position)
             first++;
-        const row = bindRow({ id: -1, entities, storageById, record: -1, version: -1, mirrored: null, components: [], resource: false, meta: false });
-        const subject = row.value;
+        // With `where`, rows of archetypes it skips don't run: the copy holds every matched row then (`headOf`).
+        const skipped = where === null ? null : new Set(matches.filter((_, m) => tailSinces[m] === -2));
+        const copied = (storages) => ({ id: -1, entities, storageById: storages, record: -1, version: -1, mirrored: null, components: [], resource: false, reclaimed: false, generation: 0 });
+        const ownedInput = runInput;
         try {
-            for (let index = first; index < rows && !halted; index++) {
-                row.index = index;
-                system.body(subject, tailValue);
+            if (optionalNumbers.length === 0 && sharedReads.length === 0) {
+                const row = bindRow(copied(storageById));
+                const subject = row.value;
+                for (let index = first; index < rows && !halted; index++) {
+                    if (skipped !== null && skipped.has(archetypeIds[index]))
+                        continue;
+                    row.index = index;
+                    system.body(subject, tailValue, ownedInput);
+                }
+            }
+            else {
+                // Rows of archetypes that lack optional components run in a row without them, a run of one archetype's rows
+                // at a time, and every archetype with the same ones shares its copy of the snapshot's columns; with
+                // shared components, each archetype has its own, holding its values.
+                const byPattern = new Map();
+                for (let index = first; index < rows && !halted;) {
+                    const id = archetypeIds[index];
+                    let end = index + 1;
+                    while (end < rows && archetypeIds[end] === id)
+                        end++;
+                    if (skipped !== null && skipped.has(id)) {
+                        index = end;
+                        continue;
+                    }
+                    const components = host.archetypeAt(id)?.components ?? [];
+                    let pattern = 0;
+                    for (let k = 0; k < optionalNumbers.length; k++)
+                        if (components.includes(optionalNumbers[k]))
+                            pattern |= 1 << k;
+                    const key = sharedReads.length === 0 ? pattern : -1 - id;
+                    let archetype = byPattern.get(key);
+                    if (archetype === undefined) {
+                        const storages = [...storageById];
+                        optionalNumbers.forEach((number, k) => { if ((pattern & (1 << k)) === 0)
+                            storages[number] = undefined; });
+                        const viewed = sharedReads.length === 0 ? undefined : host.archetypeAt(id);
+                        for (const number of sharedReads) {
+                            const layout = viewed?.storageById[number]?.layout;
+                            storages[number] = layout === undefined ? undefined : localStorage(number, layout, emptyViews, [], 0, host.strings);
+                        }
+                        byPattern.set(key, archetype = copied(storages));
+                    }
+                    const row = bindRow(archetype);
+                    const subject = row.value;
+                    for (; index < end && !halted; index++) {
+                        row.index = index;
+                        system.body(subject, tailValue, ownedInput);
+                    }
+                }
             }
         }
         finally {
@@ -976,7 +1265,7 @@ export const createThreadRunner = (host, leaf, records = noRecords) => {
      */
     const runTail = (lastRun, input, control, sync, at, stamps, first, outcomeAt) => {
         outcome.executed = outcome.ran = false;
-        outcome.error = undefined;
+        outcome.error = outcome.value = undefined;
         lookupSince.value = lastRun;
         let claimed = first ?? Atomics.add(control, progressWord, tailChunk);
         const end = Atomics.load(control, endWord);
@@ -998,24 +1287,44 @@ export const createThreadRunner = (host, leaf, records = noRecords) => {
             const resourcesChanged = resourceChanged.length > 0 && resourcesChangedSince(lastRun);
             const since = !filtered || resourcesChanged ? -1 : lastRun;
             bind();
-            if (declaration.input !== undefined)
-                tailValue.input = ownInput(input);
+            runInput = ownInput(input);
             if (query === undefined) {
                 outcome.ran = since < 0;
                 if (outcome.ran)
-                    system.body(tailValue);
+                    outcome.value = notThenable(system.body(tailValue, runInput));
                 return outcome;
             }
-            if (since >= 0 && addedIds.length + changedIds.length === 0)
+            if (since >= 0 && addedIds.length + changedIds.length === 0 && !pointed)
                 return outcome;
             outcome.ran = true;
+            latest = lastRun;
             refreshMatches();
+            debts?.read(host.arrivals(), host.rows.tick, host.tableCount(), latest, oldestPoint);
             tailArchetypes.length = tailCounts.length = 0;
             for (let m = 0; m < matches.length; m++) {
                 const archetype = host.archetypeAt(matches[m]);
                 tailArchetypes.push(archetype);
                 tailCounts.push(archetype === undefined ? 0 : host.countOf(archetype));
             }
+            if (where !== null) {
+                where.refresh(matches);
+                for (let m = 0; m < matches.length; m++)
+                    tailSinces[m] = -2;
+                for (let k = 0; k < where.count; k++) {
+                    const m = where.indices[k];
+                    const archetype = tailArchetypes[m];
+                    let from = since;
+                    if (pointed && since >= 0 && archetype !== undefined) {
+                        const point = debts?.sinceOf(matches[m], points[m]) ?? points[m];
+                        from = resourceChanged.length > 0 && resourcesChangedSince(point) ? -1 : point;
+                    }
+                    if (pointed) {
+                        points[m] = host.rows.tick;
+                        debts?.settle(matches[m]);
+                    }
+                    tailSinces[m] = pointed && from >= 0 && addedIds.length + changedIds.length === 0 ? -2 : from;
+                }
+            }
             let from = 1;
             for (;;) {
                 const to = Math.min(claimed + tailChunk, end);
@@ -1054,15 +1363,23 @@ export const createThreadRunner = (host, leaf, records = noRecords) => {
 /** A storage over a snapshot's column, or of values only this thread holds, with ticks of its own for `ticked` rows. */
 const localStorage = (component, layout, views, values, ticked, strings) => {
     const chunks = ticked === 0 ? 0 : (ticked >> chunkShift) + 1;
+    const blocks = ticked === 0 ? 0 : (ticked >> blockShift) + 1;
     return {
         component, layout, views, strings: layout.kind === "string" ? strings : null, values, ...writeOf(layout), tags: noTags, ticked: ticked > 0,
         added: ticked === 0 ? noTicks : new Float64Array(ticked), changed: ticked === 0 ? noTicks : new Float64Array(ticked),
         chunkAdded: chunks === 0 ? noTicks : new Float64Array(chunks), chunkChanged: chunks === 0 ? noTicks : new Float64Array(chunks),
+        blockAdded: blocks === 0 ? noTicks : new Float64Array(blocks), blockChanged: blocks === 0 ? noTicks : new Float64Array(blocks),
     };
 };
+/** What a lookup reads and requires: its reads but its optional components, which an entity it finds may lack. */
+const requiredReads = (host, lookup) => {
+    const optional = "optional" in lookup ? lookup.optional ?? [] : [];
+    return (lookup.read ?? []).filter(key => !optional.includes(key)).map(host.numberOf);
+};
 /** A lookup returning `read` values keyed by component, from this thread's views. */
 const lookupOf = (host, lookup) => {
     const read = (lookup.read ?? []).map(host.numberOf);
+    const required = requiredReads(host, lookup);
     const has = ("has" in lookup ? lookup.has ?? [] : []).map(host.numberOf);
     const not = ("not" in lookup ? lookup.not ?? [] : []).map(host.numberOf);
     const keys = lookup.read ?? [];
@@ -1075,7 +1392,7 @@ const lookupOf = (host, lookup) => {
         if (archetype === undefined || archetype.resource)
             return null;
         const { components } = archetype;
-        for (const id of read)
+        for (const id of required)
             if (!components.includes(id))
                 return null;
         for (const id of has)
@@ -1122,6 +1439,7 @@ const emptyLookupOf = (host, lookup) => {
  */
 const changedLookupOf = (host, lookup, watched, since) => {
     const read = (lookup.read ?? []).map(host.numberOf);
+    const required = requiredReads(host, lookup);
     const has = ("has" in lookup ? lookup.has ?? [] : []).map(host.numberOf);
     const not = ("not" in lookup ? lookup.not ?? [] : []).map(host.numberOf);
     const ids = watched.map(host.numberOf);
@@ -1136,7 +1454,7 @@ const changedLookupOf = (host, lookup, watched, since) => {
         if (archetype === undefined || archetype.resource)
             return null;
         const { components, storageById } = archetype;
-        for (const id of read)
+        for (const id of required)
             if (!components.includes(id))
                 return null;
         for (const id of has)