@adobe/ecs 0.1.0 → 0.2.0

package/src/implementation/world/runner.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Leaf } from '../../interface/system/leaf.js';
 import type { Archetype } from './archetype.js';
 import { kernelOf } from './attach-kernel.js';
@@ -13,17 +14,20 @@ import { createBlock, endBlock, indexOf, locate, reserveFrom } from './entities.
 import { forEachPassingRange, type Filter } from './ranges.js';
 import { resourceCell } from './resources.js';
 import { createContext, parentBinder, rowBinder } from './rows.js';
-import { scalarValue, scalarValues, type WasmKernel } from './wasm.js';
+import { requiredOf } from './required.js';
+import { scalarValue, scalarValues, type WasmKernel, type WasmScalar } from './wasm.js';
 import { idOf, type State } from './state.js';
+import { isThenable, returnedPromise } from './failures.js';
 import { accessorsOf } from '../../interface/gpu/accessors.js';
 import { recordWords } from './gpu.js';
 import { maximumWorkgroups, workgroupSize, type WgslKernel } from './wgsl.js';
+import { arrivalsPosition, createDebts, viewOfArrivals, type ArrivalsView } from './arrivals.js';
 import { allocateArray, freeArray } from './arrays.js';
 import { combine, identityOf, reductionTargets, type ReductionTarget } from './reductions.js';
 import { samePath, type TypedArray } from '../../interface/registry/layout.js';
 import { inputFor } from './input.js';
 import { createUp, type Run } from './up.js';
-import { labelOf, labelOfItem } from '../../interface/registry/index.js';
+import { labelOf } from '../../interface/registry/index.js';
 import type { RemoteSystem } from './remote-systems.js';
 import type { JoinedObserver } from './joined-observer.js';
 import { releaseDirectory, type Directory } from './directories.js';
@@ -32,6 +36,8 @@ import { acquireLookups, type IndexLookups, type IndexUse } from './indexes.js';
 import { createOrdered, type Ordered, type Passing } from './index-order.js';
 import { blockBase, type SortedTable } from './index-sorted.js';
 import type { Since } from './index-lookups.js';
+import { createOrderedRender } from './render-order.js';
+import { createWhere } from './where.js';
 
 /**
  * One unit of a system's work for a run: the commands it issued, or for a worker's chunk its segment of the worker's
@@ -99,6 +105,16 @@ export type Runner = {
     readonly joined: JoinedObserver | null;
     /** The tick it last ran at, which a runner placing it elsewhere starts from. */
     readonly lastRun: () => number;
+    /**
+     * What its body returned on its last run, for a system without components whose run resolves to it (`State.wanted`),
+     * let go as it's taken; else undefined.
+     */
+    readonly takeResult: () => unknown;
+    /**
+     * Whether its last run ran its body: its conditions held, and for a system with components its filters passed a
+     * row; worked out when asked, for a system reported out of band, from what the filters pass since that run's tick.
+     */
+    readonly didRun: () => boolean;
     /**
      * For a runner the registrar may keep once its system is removed, to run it again when it's registered again: one
      * here, of an observer system, holding nothing beyond its JS values. Makes it as a new runner from tick `since`.
@@ -167,9 +183,16 @@ export const releaseHoldings = (state: State, holdings: Holdings): void => {
 
 /** The resources a declaration writes or reduces into, by id. */
 export const resourceWritesOf = (state: State, declaration: Leaf["declaration"]): readonly number[] =>
-    [...new Set([...declaration.resources?.write ?? [], ...declaration.reduce === undefined ? [] : Object.getOwnPropertySymbols(declaration.reduce)].map(key => idOf(state, key)))];
+    [...new Set([...declaration.resources?.write ?? [], ...declaration.resources?.reduce ?? []].map(key => idOf(state, key)))];
 
 /** A number for each leaf, so the GPU records of every runner made for it are its own, whatever its name. */
+/**
+ * Whether a query of these required and excluded components matches an archetype. Made outside a runner, so what holds
+ * it, such as the tree its `up` shares, doesn't hold the runner.
+ */
+const matcherOf = (required: readonly number[], excluded: readonly number[]) => (archetype: Archetype): boolean =>
+    !archetype.resource && required.every(id => archetype.storageOf.has(id)) && !excluded.some(id => archetype.storageOf.has(id));
+
 const leafNumbers = new WeakMap<Leaf, number>();
 let leafCount = 0;
 const numberOf = (leaf: Leaf): number => {
@@ -182,11 +205,11 @@ const numberOf = (leaf: Leaf): number => {
 export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
     const { declaration } = leaf;
     const leafNumber = numberOf(leaf);
-    const label = labelOfItem(leaf);
+    const label = leaf.name;
     // Method parameters are bivariant, so the runtime can see any leaf's body with erased parameter types.
-    const system: { body(subject: unknown, context?: unknown): void } = leaf;
+    const system: { body(subject: unknown, context?: unknown, input?: unknown): unknown } = leaf;
     const { components: query, resources } = declaration;
-    const required = [...new Set([...query?.read ?? [], ...query?.write ?? [], ...query?.has ?? [], ...query?.added ?? [], ...query?.changed ?? []])].map(key => idOf(state, key));
+    const required = requiredOf(query).map(key => idOf(state, key));
     const excluded = (query?.not ?? []).map(key => idOf(state, key));
     const addedIds = (query?.added ?? []).map(key => idOf(state, key));
     const changedIds = (query?.changed ?? []).map(key => idOf(state, key));
@@ -199,12 +222,12 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
     /** Its `lastRun` while it runs, which its lookups' lists and rows compare with. */
     const lookupSince: Since = { value: since };
     let kernel: BoundKernel | null = null;
-    if (declaration.kernel !== undefined) {
-        const description = kernelOf(leaf);
-        if (description === undefined) {
-            indexLookups.release();
-            throw new Error(`System "${label}" is a kernel but wasn't compiled; add kernelPlugin() to the Vite config.`);
-        }
+    const description = kernelOf(leaf);
+    if (description === undefined && (declaration.kernel === true || declaration.kernel === "gpu")) {
+        indexLookups.release();
+        throw new Error(`System "${label}" is a kernel but wasn't compiled; add Compiler.plugin() to the Vite config.`);
+    }
+    if (description !== undefined) {
         try {
             kernel = bindKernel(state, leaf, description, indexLookups.byName, lookupSince);
         }
@@ -219,10 +242,11 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
     const placement = leaf.kind === "render" ? "render" : declaration.kernel === "gpu" && state.gpu !== null ? "gpu" : "cpu";
     const failPlacement = (message: string): never => { throw new Error(`System "${label}" ${message}.`); };
     // Creating the system and registering its kernel checked its placement, reductions and accessors.
-    const up = declaration.up === undefined ? null : createUp(state, declaration.up, filtered);
+    const isMatch = matcherOf(required, excluded);
+    const up = declaration.up === undefined ? null : createUp(state, declaration.up, filtered, isMatch);
     /** Its rows in its `order` index's order, run by run. */
     const ordered = indexLookups.ordered === null ? null : createOrdered(state.memory);
-    const targets = reductionTargets(state, declaration);
+    const targets = reductionTargets(state, label, declaration);
     /** For each partial of the kernel, the target and leaf it folds into. */
     const partialLeaves = (kernel?.description.reductions ?? []).map(reduced => {
         const index = targets.findIndex(target => target.key === reduced.resource);
@@ -231,6 +255,9 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
     });
     const accessors = declaration.shader === undefined ? [] : accessorsOf(declaration.shader);
     if (typeof accessors === "string") return failPlacement(`can't render: ${accessors}`);
+    /** A render system's one table in its `order` index's order. */
+    const orderedRender = leaf.kind !== "render" || indexLookups.ordered === null || ordered === null ? null
+        : createOrderedRender(indexLookups.ordered, ordered, accessors.map(accessor => idOf(state, accessor.component)), declaration.shader?.group ?? 0, `${leafNumber}:`);
     const touches = [...new Set([...query?.read ?? [], ...query?.write ?? []])].map(key => idOf(state, key));
     const writes = (query?.write ?? []).map(key => idOf(state, key));
     const looks = [...new Set([...Object.values(declaration.lookup ?? {}).flatMap(lookup => lookup.read ?? []), ...declaration.up?.read ?? []])].map(key => idOf(state, key));
@@ -308,10 +335,11 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
     // A kernel's reductions fold in its partials, so only a body that runs as written gets reducer functions. Render
     // bodies, GPU kernels and observer systems issue no commands.
     const ownInput = inputFor(leaf);
+    /** The current run's input, which the body takes after its context; kept until the next run, as its context is. */
+    let runInput: unknown;
     const context = createContext(state, declaration, {
         targets: kernel === null ? targets : [],
         commands: leaf.kind === "render" || declaration.kernel === "gpu" || declaration.observer === true ? undefined : commands,
-        input: declaration.input !== undefined,
         indexes: indexLookups.byName,
         since: lookupSince,
     });
@@ -321,6 +349,11 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
     let slotsUsed = 0;
     /** Whether the current run ran its rows, so its reductions are written. */
     let ran = false;
+    /** The tick the last run's rows passed its change filters after, -1 for every row; and whether a target's row ran. */
+    let ranSince = -1;
+    let targetRan = false;
+    /** What its body returned on its last run, for a system without components, until the run takes it. */
+    let result: unknown = undefined;
     /**
      * The most kernel calls a run gives an archetype: one on the main thread; across workers a piece of at least
      * `chunkAlignment` rows each, at most `claimsPerWorker` per worker.
@@ -332,7 +365,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         if (partialCount === 0) return;
         refreshMatches();
         let needed = 0;
-        for (const archetype of matches) needed += slotsFor(archetype.count);
+        for (let m = 0; m < matches.length; m++) needed += slotsFor(matches[m].count);
         needed = Math.max(1, needed) * partialCount;
         if (slots.length >= needed) return;
         if (slots.length > 0) freeArray(state.memory, slots);
@@ -352,18 +385,171 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
     /** Each target's leaves, folded from the partials in `finish`. */
     const folded = targets.map(target => new Float64Array(target.leaves.length));
     const partialAddress = (slot: number): number => partialCount === 0 ? -1 : slots.byteOffset + slot * partialCount * 8;
-    const matches: Archetype[] = [];
+    /** Its matched archetypes: a new list each time membership changes it, so what's cached by the list is found stale. */
+    let matches: Archetype[] = [];
     let checked = 0;
-    const bindRow = rowBinder(state, query?.read ?? [], query?.write ?? []);
+    const bindRow = rowBinder(state, query?.read ?? [], query?.write ?? [], query?.optional);
+    /** Whether its rows have optional components, so which an archetype has picks its row. */
+    const optional = (query?.optional?.length ?? 0) > 0;
     const bindParent = parentBinder(state, declaration.up?.read ?? []);
     let lastRun = since;
+    /** Its `where`, which keeps its runs to the matched archetypes whose shared values pass; null without one. */
+    const where = query?.where === undefined ? null : createWhere<Archetype>(state, query.where, query.whereReads ?? [], leaf);
+    /**
+     * With `where` and change filters, each matched archetype's own last run, by match: one `where` skipped keeps its
+     * point, so its rows count as changed since the system last ran over it.
+     */
+    const pointed = where !== null && filtered;
+    const points: number[] = [];
+    /** By archetype id, its match, or -1. */
+    const matchOf: number[] = [];
+    /** By match, its archetype's generation as matched (`reclaim.ts`): reused for other values, it's matched anew. */
+    const generations: number[] = [];
+    /** Its position in the world's membership log, which it follows as archetypes are reclaimed and reused. */
+    let followed = state.reshapes;
+    /** What archetypes owe for rows moved in from others it last saw longer ago (`arrivals.ts`). */
+    const debts = pointed ? createDebts(points, matchOf, arrivalsPosition(state.arrivalRing === null ? null : viewOfArrivals(state.arrivalRing))) : null;
+    let arrivals: ArrivalsView | null = null;
+    if (pointed) state.arrivals = true;
+    /** The archetypes a run goes over, and how many: every match, or with `where` those passing. */
+    let runList: readonly Archetype[] = matches;
+    let runCount = 0;
+    /** By position in `runList`, the tick its rows passed its change filters after in the last run, for `didRun`. */
+    const ranSinces: number[] = [];
 
     function refreshMatches(): void {
+        if (followed !== state.reshapes) followMembership();
+        if (checked < state.archetypes.length) discover();
+    }
+
+    /** Matches the archetypes made since it last looked; apart, so a run's check stays small. */
+    const discover = (): void => {
         for (; checked < state.archetypes.length; checked++) {
             const archetype = state.archetypes[checked];
-            if (!archetype.resource && !(archetype.meta && required.length === 0) && required.every(id => archetype.storageOf.has(id)) && !excluded.some(id => archetype.storageOf.has(id))) matches.push(archetype);
+            matchOf[checked] = -1;
+            if (archetype.reclaimed || !isMatch(archetype)) continue;
+            addMatch(archetype);
         }
-    }
+    };
+
+    /** Lists a match; rows moved into one appearing since its last run owe what they came with. */
+    const addMatch = (archetype: Archetype): void => {
+        const m = matches.length;
+        points[m] = lastRun;
+        generations[m] = archetype.generation;
+        matchOf[archetype.id] = m;
+        matches.push(archetype);
+    };
+
+    /** Moves match `from`'s place and what's kept by it to `to`. */
+    const moveMatch = (from: number, to: number): void => {
+        const archetype = matches[from];
+        matches[to] = archetype;
+        points[to] = points[from];
+        generations[to] = generations[from];
+        matchOf[archetype.id] = to;
+        where?.move(from, to);
+    };
+
+    /** Swaps matches `a` and `b`, and what's kept by each. */
+    const swapMatches = (a: number, b: number): void => {
+        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].id] = a;
+        matches[b] = first;
+        points[b] = point;
+        generations[b] = generation;
+        matchOf[first.id] = b;
+        where?.swapped(a, b);
+    };
+
+    /** Drops match `m`, its last taking its place; with `where`, one evaluated stays among those evaluated. */
+    const removeMatch = (m: number): void => {
+        filterCache.delete(matches[m]);
+        matchOf[matches[m].id] = -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;
+    };
+
+    /** Matches `m` anew, reused for other values: its point is its last run's, and `where` evaluates it again. */
+    const renewMatch = (m: number): void => {
+        const archetype = matches[m];
+        filterCache.delete(archetype);
+        points[m] = lastRun;
+        generations[m] = archetype.generation;
+        if (where !== null && m < where.evaluated) {
+            swapMatches(m, where.evaluated - 1);
+            where.forgetLast();
+        }
+    };
+
+    /**
+     * Follows the archetypes reclaimed and reused since it last looked: those it matched and reclaimed leave, those
+     * reused it matches anew, and those it doesn't match it matches once reused. Arrivals are read first, so a row that
+     * left an archetype before it was reclaimed owes that archetype's point as it was.
+     */
+    const followMembership = (): void => {
+        const { membership } = state;
+        if (debts !== null && state.arrivalRing !== null) debts.read(arrivals ??= viewOfArrivals(state.arrivalRing), state.tick, state.archetypes.length, lastRun, oldestPoint);
+        const end = state.reshapes;
+        // Behind the trimmed log, it looks at every archetype it has seen.
+        const changed: readonly Archetype[] = followed < membership.base ? state.archetypes.slice(0, checked) : membership.log.slice(followed - membership.base);
+        followed = end;
+        matches = [...matches];
+        for (const archetype of changed) {
+            if (archetype.id >= checked) continue;
+            const m = matchOf[archetype.id] ?? -1;
+            const { reclaimed } = archetype;
+            if (m >= 0) {
+                if (reclaimed) removeMatch(m);
+                else if (generations[m] !== archetype.generation) renewMatch(m);
+            }
+            else if (!reclaimed && isMatch(archetype)) addMatch(archetype);
+        }
+    };
+
+    /** The oldest point of its matched archetypes, or its last run: what a row moving in may last have been seen at. */
+    const oldestPoint = (): number => {
+        let oldest = lastRun;
+        for (let m = 0; m < matches.length; m++) if (points[m] < oldest) oldest = points[m];
+        return oldest;
+    };
+    /** The oldest of its points and what any archetype owes: what any row may pass its change filters after. */
+    const oldestOwed = (): number => Math.min(oldestPoint(), debts?.oldest() ?? Infinity);
+
+    /** The tick an archetype's rows pass its change filters after, by its own point: -1 when a filter passes every row. */
+    const pointSince = (m: number, archetype: Archetype): number => {
+        // Rows moved in since its point count as changed since their old archetype's.
+        const point = debts === null ? points[m] : debts.sinceOf(archetype.id, points[m]);
+        const all = (resourceChanged.length > 0 && resourcesChangedSince(point)) || (indexFiltered && indexesChangedSince(point));
+        return all ? -1 : point;
+    };
+
+    /** Refreshes the matches and the archetypes a run goes over, evaluating `where` as it needs. */
+    const refreshRunList = (): void => {
+        refreshMatches();
+        if (where === null) {
+            runList = matches;
+            runCount = matches.length;
+            return;
+        }
+        where.refresh(matches);
+        runList = where.passing;
+        runCount = where.count;
+    };
 
     /** Every row of an archetype passes when a `changed` component's whole column changed since `since`. */
     const sinceFor = (archetype: Archetype, since: number): number => {
@@ -373,7 +559,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
     };
 
     /**
-     * By archetype: its change filters, `added` then `changed`, rows and chunks, kept until its arrays are replaced;
+     * By archetype: its change filters, `added` then `changed`, rows, chunks and blocks, kept until its arrays are replaced;
      * and the WASM addresses of its columns and filters, for the WASM kernel `addressed` they were taken for, since a
      * kernel loaded again may stamp a tick column the last one muted.
      */
@@ -386,11 +572,11 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         const filters = addedIds.length + changedIds.length === 0 ? noFilters : [
             ...addedIds.flatMap(id => {
                 const storage = archetype.storageById[id];
-                return storage === undefined ? [] : [{ ticks: storage.added, chunks: storage.chunkAdded }];
+                return storage === undefined ? [] : [{ ticks: storage.added, chunks: storage.chunkAdded, blocks: storage.blockAdded }];
             }),
             ...changedIds.flatMap(id => {
                 const storage = archetype.storageById[id];
-                return storage === undefined ? [] : [{ ticks: storage.changed, chunks: storage.chunkChanged }];
+                return storage === undefined ? [] : [{ ticks: storage.changed, chunks: storage.chunkChanged, blocks: storage.blockChanged }];
             }),
         ];
         const entry: Filtered = { version: archetype.version, filters, addresses: noAddresses, addressed: null };
@@ -400,6 +586,14 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
 
     const filtersOf = (archetype: Archetype): readonly Filter[] => filteredOf(archetype).filters;
 
+    /**
+     * Fails the system for a row or render body that returned a thenable, which nothing awaits; called only for a body
+     * that returned something, so a row returning nothing pays one comparison.
+     */
+    const noPromise = (returned: unknown): void => {
+        if (isThenable(returned)) throw new Error(returnedPromise);
+    };
+
     const { target } = declaration;
     /** Runs the body on `entity`'s row, when it's alive and its archetype matches. */
     const runTarget = (entity: unknown): void => {
@@ -410,27 +604,32 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         if (archetype === undefined || !matches.includes(archetype)) return;
         const row = bindRow(archetype);
         row.index = state.entities.row[index];
-        system.body(row.value, context.value);
+        targetRan = true;
+        const returned = system.body(row.value, context.value, runInput);
+        if (returned !== undefined) noPromise(returned);
     };
 
     const runBody = (archetype: Archetype, since: number): void => {
         const row = bindRow(archetype);
         const { value } = row;
         const values = context.value;
+        const input = runInput;
         const filters = filtersOf(archetype);
         // Every row passes, so nothing is filtered.
         // A body may remove its own system, after which no row of it runs.
         if (since < 0 || filters.length === 0) {
             for (let index = 0, count = archetype.count; index < count && !holdings.removed; index++) {
                 row.index = index;
-                system.body(value, values);
+                const returned = system.body(value, values, input);
+                if (returned !== undefined) noPromise(returned);
             }
             return;
         }
         forEachPassingRange(filters, since, 0, archetype.count, (start, end) => {
             for (let index = start; index < end && !holdings.removed; index++) {
                 row.index = index;
-                system.body(value, values);
+                const returned = system.body(value, values, input);
+                if (returned !== undefined) noPromise(returned);
             }
         });
     };
@@ -449,6 +648,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
                 ...bound.columnsOf(archetype).map(column => column.byteOffset),
                 ...entry.filters.map(filter => filter.ticks.byteOffset),
                 ...entry.filters.map(filter => filter.chunks.byteOffset),
+                ...entry.filters.map(filter => filter.blocks.byteOffset),
             ];
             entry.addressed = bound.wasm;
         }
@@ -465,19 +665,21 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         for (let k = 0; k < addresses.length; k++) call[at++] = addresses[k];
         for (let k = 0; k < lookups.length; k++) call[at++] = lookups[k];
         for (let k = 0; k < indexParameters.length; k++) call[at++] = indexParameters[k];
-        for (let k = 0; k < scalars.length; k++) call[at++] = scalarValue(scalars[k], values, args);
+        const shared = bound.sharedOf(archetype);
+        for (let k = 0; k < scalars.length; k++) call[at++] = scalarValue(scalars[k], values, args, shared);
         if (partials >= 0) call[at] = partials;
         Reflect.apply(compiled.run, undefined, call);
     };
 
     const runKernelLocally = (bound: BoundKernel, archetype: Archetype, since: number, values: readonly unknown[], args: unknown, tick: number): void => {
         const slot = partialCount === 0 ? 0 : takeSlots(1);
-        if (bound.compiled() !== null && bound.wasm !== null) return runWasm(bound, archetype, 0, archetype.count, since, values, args, tick, partialAddress(slot));
+        if (bound.compiled() !== null && bound.wasm !== null && bound.allPresent(archetype)) return runWasm(bound, archetype, 0, archetype.count, since, values, args, tick, partialAddress(slot));
         const columns = bound.columnsOf(archetype);
         const filters = filtersOf(archetype);
         const run = bound.kernel();
+        const shared = bound.sharedOf(archetype);
         forEachPassingRange(filters, since, 0, archetype.count, (start, end) =>
-            run(columns, start, end, values, bound.lookups, bound.description.keys, args, kernelCommands, tick, slots, slot * partialCount));
+            run(columns, start, end, values, bound.lookups, bound.description.keys, args, kernelCommands, tick, slots, slot * partialCount, undefined, undefined, undefined, undefined, shared));
     };
 
     const noColumns: readonly TypedArray[] = [];
@@ -496,13 +698,13 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
                 ...indexParameters,
                 rows.byteOffset, parents.byteOffset, parentArchetype >= 0 ? 1 : 0,
                 ...ups.map((_, k) => parentColumns[k]?.byteOffset ?? 0),
-                ...scalarValues(kernel.wasm.scalars, values, args),
+                ...scalarValues(kernel.wasm.scalars, values, args, kernel.sharedOf(archetype)),
                 ...partialCount === 0 ? [] : [partialAddress(slot)]);
             return;
         }
         if (kernel !== null) {
             const parentColumns = parentArchetype < 0 ? noColumns : kernel.upColumnsOf(state.archetypes[parentArchetype]);
-            kernel.kernel()(kernel.columnsOf(archetype), start, end, values, kernel.lookups, kernel.description.keys, args, kernelCommands, tick, slots, slot * partialCount, rows, parents, parentColumns, parentArchetype >= 0);
+            kernel.kernel()(kernel.columnsOf(archetype), start, end, values, kernel.lookups, kernel.description.keys, args, kernelCommands, tick, slots, slot * partialCount, rows, parents, parentColumns, parentArchetype >= 0, kernel.sharedOf(archetype));
             return;
         }
         if (up === null) return;
@@ -510,11 +712,13 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         // The parent's row is bound after the system's own, for the archetype both may share.
         const parentRow = parentArchetype < 0 ? null : bindParent(state.archetypes[parentArchetype]);
         const upContext = context.value;
+        const input = runInput;
         upContext.up = parentRow === null ? null : parentRow.value;
         for (let n = start; n < end && !holdings.removed; n++) {
             row.index = rows[n];
             if (parentRow !== null) parentRow.index = parents[n];
-            system.body(row.value, upContext);
+            const returned = system.body(row.value, upContext, input);
+            if (returned !== undefined) noPromise(returned);
         }
     };
 
@@ -534,6 +738,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         const runs = order.runs(sorted, matches, since < 0 ? null : orderPassing);
         const slot = partialCount === 0 ? 0 : takeSlots(1);
         const contextValue = context.value;
+        const input = runInput;
         for (let k = 0; k < runs.length && !holdings.removed; k++) {
             const run = runs[k];
             const archetype = matches[run.owner];
@@ -545,7 +750,8 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
             const { value } = row;
             for (let n = run.start; n < run.end && !holdings.removed; n++) {
                 row.index = run.rows[n];
-                system.body(value, contextValue);
+                const returned = system.body(value, contextValue, input);
+                if (returned !== undefined) noPromise(returned);
             }
         }
     };
@@ -555,6 +761,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         const owners = order.owners(matches);
         const { entries, stride, words, lengths, blocks } = sorted;
         const contextValue = context.value;
+        const input = runInput;
         let current = -1;
         let row: ReturnType<typeof bindRow> | null = null;
         let value: object | null = null;
@@ -567,12 +774,16 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
                 const owner = archetype < owners.length ? owners[archetype] : -1;
                 if (owner < 0) continue;
                 if (owner !== current || row === null || value === null) {
-                    row = bindRow(matches[owner]);
+                    // The row is found once; after, it's bound in place, as often as every row when archetypes interleave,
+                    // unless which optional components an archetype has picks another row.
+                    if (row === null || optional) row = bindRow(matches[owner]);
+                    else row.bind(matches[owner]);
                     value = row.value;
                     current = owner;
                 }
                 row.index = entries[at + 2];
-                system.body(value, contextValue);
+                const returned = system.body(value, contextValue, input);
+                if (returned !== undefined) noPromise(returned);
             }
         }
     };
@@ -586,7 +797,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
             ...indexParameters,
             run.rows.byteOffset, run.parents.byteOffset, run.parent >= 0 ? 1 : 0,
             ...(kernel.description.upColumns ?? []).map((_, k) => parentColumns[k]?.byteOffset ?? 0),
-            ...scalarValues(kernel.wasm.scalars, values, args),
+            ...scalarValues(kernel.wasm.scalars, values, args, kernel.sharedOf(matches[run.owner])),
         ];
         const count = run.end - run.start;
         const { pool } = workers;
@@ -606,28 +817,9 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
     const runUp = (since: number, values: readonly unknown[], args: unknown, tick: number, workers: Workers | null, index: number): Promise<readonly ChunkResult[]> | null => {
         if (up === null) return null;
         const slot = partialCount === 0 ? 0 : takeSlots(1);
-        let next: () => readonly Run[] | null;
-        let clear = (): void => {};
-        if (since < 0) {
-            const order = up.levels(matches);
-            let depth = 0;
-            next = () => {
-                if (depth >= order.levels) return null;
-                const runs: Run[] = [];
-                for (let group = order.depthGroups[depth]; group < order.depthGroups[depth + 1]; group++) {
-                    if (order.groupEnds[group] === order.groupStarts[group]) continue;
-                    runs.push({ owner: order.groupOwners[group], parent: order.groupParents[group], rows: order.rows, parents: order.parents, start: order.groupStarts[group], end: order.groupEnds[group] });
-                }
-                depth++;
-                return runs;
-            };
-        }
-        else {
-            const pass = up.filtered(matches, addedIds, changedIds, since);
-            if (pass === null) return null;
-            next = pass.next;
-            clear = pass.clear;
-        }
+        const pass = since < 0 ? up.wholePass(up.levels(matches)) : up.filtered(matches, addedIds, changedIds, since);
+        if (pass === null) return null;
+        const { next, clear } = pass;
         const runLocally = (run: Run): void => runUpRows(matches[run.owner], run.parent, run.rows, run.parents, run.start, run.end, values, args, tick, slot);
         const parallel = workers !== null && kernel !== null && kernel.wasm !== null && kernel.compiled() !== null && partialCount === 0
             && kernel.lookupParameters().length + indexParameters.length + 3 + (kernel.description.upColumns?.length ?? 0) + kernel.wasm.scalars.length <= maximumScalars;
@@ -682,8 +874,8 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         const { count } = archetype;
         const { pool } = workers;
         const bound = kernel;
-        const scalars = bound !== null && bound.wasm !== null ? [...bound.lookupParameters(), ...indexParameters, ...scalarValues(bound.wasm.scalars, values, args)] : [];
-        const fast = isFast(bound);
+        const scalars = bound !== null && bound.wasm !== null ? [...bound.lookupParameters(), ...indexParameters, ...scalarValues(bound.wasm.scalars, values, args, bound.sharedOf(archetype))] : [];
+        const fast = isFast(bound) && bound !== null && bound.allPresent(archetype);
         const participants = Math.min(pool.size, Math.ceil(count / minimumFor(workers)));
         const aligned = (rows: number): number => Math.ceil(rows / chunkAlignment) * chunkAlignment;
         // WASM chunks go through shared memory. The main thread doesn't take one: measured, it finishes later than an
@@ -706,6 +898,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
             const message = {
                 kind: "run", kernel: index, archetype: archetype.id, start, end: Math.min(count, start + size), tick, lastRun: since, resources: values, args,
                 partials: partialCount === 0 ? -1 : partialAddress(takeSlots(1)), lookups: bound === null ? noIndexParameters : bound.lookupParameters(), indexes: indexParameters,
+                shared: bound === null ? noValues : bound.sharedOf(archetype),
             } as const;
             const worker = workers.next;
             workers.next = (worker + 1) % pool.size;
@@ -716,6 +909,21 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
 
     const words = new Uint32Array(recordWords);
     const floats = new Float32Array(words.buffer);
+    const integers = new Int32Array(words.buffer);
+
+    /** Writes a dispatch's scalars from `first`: a shared value's leaf keeps its type, as its column would; the rest are f32. */
+    const writeScalars = (bound: BoundKernel, scalars: readonly WasmScalar[], first: number, values: readonly unknown[], args: unknown, archetype: Archetype): void => {
+        const shared = bound.sharedOf(archetype);
+        for (let s = 0; s < scalars.length; s++) {
+            const scalar = scalars[s];
+            const value = scalarValue(scalar, values, args, shared);
+            switch (bound.scalarKind(scalar)) {
+                case "i32": integers[first + s] = value; break;
+                case "u32": case "bool": words[first + s] = value; break;
+                default: floats[first + s] = value;
+            }
+        }
+    };
 
     /** One dispatch per archetype, each with its record of row count, column addresses and scalars. */
     const runOnGpu = (values: readonly unknown[], args: unknown, tick: number): void => {
@@ -723,16 +931,17 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         if (gpu === null || pipeline === null || kernel === null) return failPlacement("isn't loaded on the GPU");
         holdings.gpu = gpu;
         const { sources } = kernel.setup;
-        const scalars = scalarValues(pipeline.kernel.scalars, values, args);
+        const { scalars } = pipeline.kernel;
         const dispatches: { readonly offset: number; readonly count: number }[] = [];
-        for (const archetype of matches) {
+        for (let k = 0; k < runCount; k++) {
+            const archetype = runList[k];
             if (archetype.count === 0) continue;
             words[0] = archetype.count;
             sources.forEach((source, k) => {
                 const storage = source.kind === "field" ? archetype.storageById[source.id] : undefined;
                 words[1 + k] = storage === undefined ? 0 : gpu.upload(archetype, storage, tick);
             });
-            scalars.forEach((value, s) => { floats[1 + sources.length + s] = value; });
+            writeScalars(kernel, scalars, 1 + sources.length, values, args, archetype);
             dispatches.push({ offset: gpu.record(keyOf(archetype), words), count: archetype.count });
         }
         if (dispatches.length === 0) return;
@@ -745,7 +954,8 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
             pass.dispatchWorkgroups(x, Math.ceil(groups / x));
         }
         pass.end();
-        for (const archetype of matches) {
+        for (let k = 0; k < runCount; k++) {
+            const archetype = runList[k];
             if (archetype.count === 0) continue;
             for (const id of writes) {
                 const storage = archetype.storageById[id];
@@ -777,7 +987,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         const parentsAddress = gpu.uploadIndexes(`${leafNumber}:parents`, order.parents, order.size, fresh);
         uploadedOrder = order;
         const { sources } = kernel.setup;
-        const scalars = scalarValues(pipeline.kernel.scalars, values, args);
+        const { scalars } = pipeline.kernel;
         const dispatches: { readonly offset: number; readonly count: number }[] = [];
         for (let group = 0; group < order.groups; group++) {
             const start = order.groupStarts[group];
@@ -799,7 +1009,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
                 const storage = parent?.storageById[id];
                 words[base + 3 + k] = parent === null || storage === undefined ? 0 : gpu.upload(parent, storage, tick);
             });
-            scalars.forEach((value, s) => { floats[base + 3 + upIds.length + s] = value; });
+            writeScalars(kernel, scalars, base + 3 + upIds.length, values, args, archetype);
             dispatches.push({ offset: gpu.record(`${leafNumber}:up:${group}`, words), count });
         }
         if (dispatches.length > 0) {
@@ -830,6 +1040,7 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         if (gpu === null) return failPlacement("needs a world with a gpu device");
         if (typeof accessors === "string") return;
         holdings.gpu = gpu;
+        if (orderedRender !== null) return runOrderedRender(gpu, tick, orderedRender);
         const group = declaration.shader?.group ?? 0;
         const tables = matches.filter(archetype => archetype.count > 0).map(archetype => {
             words[0] = archetype.count;
@@ -843,7 +1054,23 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         // Work recorded so far is submitted first, so a body that fails partway loses only its own.
         gpu.submit();
         try {
-            system.body({ device: gpu.device, encoder: gpu.encoder(), tables }, context.value);
+            const returned = system.body({ device: gpu.device, encoder: gpu.encoder(), tables }, context.value);
+            if (returned !== undefined) noPromise(returned);
+        }
+        catch (error) {
+            gpu.discard();
+            throw error;
+        }
+    };
+
+    /** A render system with `order`: one table, nothing allocated while nothing it reads changed. */
+    const runOrderedRender = (gpu: GpuEngine, tick: number, render: NonNullable<typeof orderedRender>): void => {
+        const failure = render.prepare(gpu, matches, tick);
+        if (failure !== null) return failPlacement(`can't render: ${failure}`);
+        gpu.submit();
+        try {
+            const returned = system.body(render.context(gpu), context.value);
+            if (returned !== undefined) noPromise(returned);
         }
         catch (error) {
             gpu.discard();
@@ -894,13 +1121,49 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         pipeline = { compute, kernel: generated };
     };
 
+    /**
+     * Runs the archetypes `where` passes, each from its own point with change filters, posting large ones to workers:
+     * apart from the loop over every match, which systems without `where` run.
+     */
+    const runPassing = (passing: NonNullable<typeof where>, since: number, values: readonly unknown[], args: unknown, tick: number, workers: Workers | null, index: number, chunks: Chunk[]): void => {
+        passing.refresh(matches);
+        if (debts !== null && state.arrivalRing !== null) debts.read(arrivals ??= viewOfArrivals(state.arrivalRing), tick, state.archetypes.length, lastRun, oldestPoint);
+        runList = passing.passing;
+        runCount = passing.count;
+        const { indices } = passing;
+        for (let k = 0; k < runCount; k++) {
+            const archetype = runList[k];
+            const m = indices[k];
+            const from = sinceFor(archetype, !pointed || since < 0 ? since : pointSince(m, archetype));
+            ranSinces[k] = from;
+            if (pointed) {
+                points[m] = tick;
+                debts?.settle(archetype.id);
+            }
+            if (archetype.count === 0) continue;
+            // Only resource and index filters, none of which changed since this archetype's point: no row passes.
+            if (pointed && from >= 0 && addedIds.length + changedIds.length === 0) continue;
+            if (kernel === null) runBody(archetype, from);
+            else if (workers !== null && archetype.count >= minimumFor(workers)) {
+                chunks.push(...postChunks(workers, index, archetype, from, values, args, tick));
+                chunks.push(nextChunk());
+            }
+            else {
+                if (archetype.count >= state.poolThreshold) state.poolWanted = true;
+                runKernelLocally(kernel, archetype, from, values, args, tick);
+            }
+        }
+    };
+
     const start = (input: unknown, workers: Workers | null, index: number): readonly Chunk[] => {
         ran = false;
+        result = undefined;
         // Removed during the run it's in: its body isn't called again.
         if (holdings.removed) return noChunks;
         // A system whose conditions don't hold is skipped, successfully, and keeps its `lastRun`.
         if (conditioned && !holds()) return noChunks;
-        const indexesChanged = indexFiltered && indexesChangedSince(lastRun);
+        // With points, an index changed since the oldest archetype's may pass that archetype's rows.
+        const indexesChanged = indexFiltered && indexesChangedSince(pointed ? (refreshMatches(), oldestOwed()) : lastRun);
         // One filtered only by indexes, none of which changed, is skipped as when a condition fails.
         if (indexesOnly && !indexesChanged) return noChunks;
         const tick = ++state.tick;
@@ -919,11 +1182,14 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         holder.buffer = owned[0];
         chunks[0] = ownedChunks[0];
         try {
-            const resourcesChanged = indexesChanged || (resourceChanged.length > 0 && resourcesChangedSince(lastRun));
+            // With points, resource and index filters pass an archetype's rows by its own point.
+            const resourcesChanged = !pointed && (indexesChanged || (resourceChanged.length > 0 && resourcesChangedSince(lastRun)));
             /** -1 passes every row. */
             const since = !filtered || resourcesChanged ? -1 : lastRun;
+            ranSince = since;
+            targetRan = false;
             context.bind();
-            if (declaration.input !== undefined) context.value.input = args;
+            runInput = args;
             if (indexed && kernel !== null) indexParameters = kernel.refreshIndexes(lastRun);
             if (placement === "render") {
                 refreshMatches();
@@ -932,11 +1198,16 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
             }
             if (query === undefined) {
                 ran = since < 0;
-                if (ran) system.body(context.value);
+                if (ran) {
+                    const value = system.body(context.value, args);
+                    if (isThenable(value)) throw new Error(returnedPromise);
+                    // Kept only for the run that resolves to it.
+                    if (state.wanted === leaf) result = value;
+                }
                 return chunks;
             }
             // Only resource and index filters, none of which changed: no row passes, unless its parent changed.
-            if (since >= 0 && addedIds.length + changedIds.length === 0 && up === null) return chunks;
+            if (since >= 0 && addedIds.length + changedIds.length === 0 && up === null && !pointed) return chunks;
             ran = true;
             refreshMatches();
             if (target !== undefined) {
@@ -948,11 +1219,13 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
                 return readCell(storage, row);
             });
             if (placement === "gpu") {
+                refreshRunList();
                 if (up !== null) runUpOnGpu(values, args, tick);
                 else runOnGpu(values, args, tick);
                 return chunks;
             }
             if (up !== null) {
+                if (workers === null && kernel !== null) for (const archetype of matches) if (archetype.count >= state.poolThreshold) state.poolWanted = true;
                 const parallel = runUp(since, values, args, tick, workers, index);
                 if (parallel !== null) chunks.push(parallel);
                 return chunks;
@@ -961,6 +1234,10 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
                 runOrdered(ordered, since, values, args, tick);
                 return chunks;
             }
+            if (where !== null) {
+                runPassing(where, since, values, args, tick, workers, index, chunks);
+                return chunks;
+            }
             for (const archetype of matches) {
                 if (archetype.count === 0) continue;
                 const from = sinceFor(archetype, since);
@@ -969,7 +1246,10 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
                     chunks.push(...postChunks(workers, index, archetype, from, values, args, tick));
                     chunks.push(nextChunk());
                 }
-                else runKernelLocally(kernel, archetype, from, values, args, tick);
+                else {
+                    if (archetype.count >= state.poolThreshold) state.poolWanted = true;
+                    runKernelLocally(kernel, archetype, from, values, args, tick);
+                }
             }
             return chunks;
         }
@@ -987,6 +1267,24 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         }
     };
 
+    /** Whether the last run ran its body on a row: a target's, one its parent's change passed, or one its filters passed. */
+    const bodyRanOnRow = (): boolean => {
+        if (target !== undefined) return targetRan;
+        if (up !== null) return true;
+        const list = where === null ? matches : runList;
+        const count = where === null ? matches.length : runCount;
+        for (let k = 0; k < count; k++) {
+            const archetype = list[k];
+            if (archetype.count === 0) continue;
+            const from = where === null ? sinceFor(archetype, ranSince) : ranSince < 0 ? -1 : ranSinces[k];
+            if (from < 0) return true;
+            let passed = false;
+            forEachPassingRange(filtersOf(archetype), from, 0, archetype.count, () => { passed = true; });
+            if (passed) return true;
+        }
+        return false;
+    };
+
     const finish = (failed: boolean): readonly Float64Array[] | null => {
         if (!ran || failed || targets.length === 0) return null;
         if (kernel === null) return context.reduced;
@@ -1039,6 +1337,12 @@ export const createRunner = (state: State, leaf: Leaf, since = 0): Runner => {
         remote: null,
         joined: null,
         lastRun: () => lastRun,
+        takeResult: () => {
+            const taken = result;
+            result = undefined;
+            return taken;
+        },
+        didRun: () => ran && (query === undefined || bodyRanOnRow()),
         restart: declaration.observer !== true || !holdsNothing(holdings) ? null : since => {
             lastRun = since;
             holdings.removed = false;
@@ -1069,5 +1373,7 @@ export const removedRunner: Runner = {
     remote: null,
     joined: null,
     lastRun: () => 0,
+    takeResult: () => undefined,
+    didRun: () => false,
     restart: null,
 };