@adobe/ecs 0.1.0 → 0.2.1

package/src/implementation/world/execute.ts

@@ -1,3 +1,4 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
 import type { Leaf } from '../../interface/system/leaf.js';
 import type { Chunk, ChunkResult, Runner, Workers } from './runner.js';
 import type { Schedule } from '../../interface/registry/schedule.js';
@@ -13,12 +14,11 @@ import { locate } from './entities.js';
 import { clearBuffer, createBuffer } from './buffer.js';
 import { drainSegment, type Segment } from './command-ring.js';
 import { combine, identityOf, writeReduction, type ReductionTarget } from './reductions.js';
-import type { Failure, Warning } from '../../interface/report/failure.js';
-import type { RunReport } from './failures.js';
+import type { Failure, RunReport, Warning } from './failures.js';
 import { liftColumnStamps, type RemoteSystem, type TaskChannel } from './remote-systems.js';
 import { failureOf } from './failures.js';
 import { checkCommands } from './remote.js';
-import { firstKeyOf, labelOfItem } from '../../interface/registry/index.js';
+import { firstKeyOf } from '../../interface/registry/index.js';
 import { mergeUses, refreshUses, type IndexUse } from './indexes.js';
 
 /** Shared by every report without failures or skipped systems: they're read-only, so none needs its own. */
@@ -36,11 +36,6 @@ export type ExecuteContext = {
     readonly publish: () => void;
     /** The last run's tails, posted after its sync point, until the caller takes them; null when it had none. */
     tails: Promise<TailOutcome> | null;
-    /**
-     * Given what went wrong before a run's sync point, each list null or a count of none, queues what its report needs
-     * for them into that sync point.
-     */
-    readonly beforeSync: (failures: readonly Failure[] | null, skipped: readonly string[] | null, warnings: readonly Warning[], warningCount: number) => void;
 };
 
 /**
@@ -49,20 +44,24 @@ export type ExecuteContext = {
  * ran them. A failing system stops the run after its tier finishes: later tiers are skipped, and commands so far still
  * apply. `system` is the one the run was given, which the GPU's errors are reported under.
  */
-export const execute = async (context: ExecuteContext, schedule: Schedule, args: unknown, system: { readonly name: string }): Promise<RunReport> => {
+export const execute = (context: ExecuteContext, schedule: Schedule, args: unknown, system: { readonly name: string }): RunReport | Promise<RunReport> => {
     const { gpu } = context.state;
-    if (gpu === null) return executeTiers(context, schedule, args, null);
+    if (gpu === null) return executeTiers(context, schedule, args);
+    return executeOnDevice(context, gpu, schedule, args, system);
+};
+
+/**
+ * `execute` with a GPU device, within error scopes, whose errors are reported out of band once the GPU gives them:
+ * waiting for them would hold every run until the GPU process catches up.
+ */
+const executeOnDevice = async (context: ExecuteContext, gpu: GpuEngine, schedule: Schedule, args: unknown, system: { readonly name: string }): Promise<RunReport> => {
     const lost = gpu.lost();
     // Lost since the run started; the world sets gpuDevice to null before the next one.
     if (lost !== null) throw new Error(`The world's GPU device was lost during this run: ${lost}.`);
-    // An earlier run's GPU work reports its errors to this run: waiting for them there would hold every run until the
-    // GPU process catches up.
-    const earlier = gpu.takeError();
-    const failures = earlier === null ? null : [failureOf("gpu", earlier.name, earlier.message)];
     gpu.device.pushErrorScope("out-of-memory");
     gpu.device.pushErrorScope("validation");
     try {
-        return await executeTiers(context, schedule, args, failures);
+        return await executeTiers(context, schedule, args);
     }
     finally {
         gpu.reportErrors(system, gpu.device.popErrorScope(), gpu.device.popErrorScope());
@@ -121,6 +120,14 @@ type Prepared = {
     /** The placement its tails were found for, and they: the schedule without them, and them in schedule order. */
     placement: number;
     tailing: Tailing | null;
+    /**
+     * Where settling the tier in progress is: the runner, its chunk, the runner's first error so far, and whether a
+     * runner of the tier failed, so settling can stop at a promise and go on once it settles.
+     */
+    settling: number;
+    chunk: number;
+    error: unknown;
+    tierFailed: boolean;
 };
 
 /** A schedule's tails: the schedule without them, and their runners, leaves and tiers in schedule order. */
@@ -145,7 +152,7 @@ const tailingOf = (context: ExecuteContext, schedule: Schedule): Tailing | null
     return { schedule: { tiers: rest, reductions: schedule.reductions, observer: schedule.observer }, runners: leaves.map(context.runnerOf), leaves, tiers };
 };
 
-type Outcome = { failures: Failure[] | null; skipped: string[] | null };
+type Outcome = { failures: Failure[] | null; skipped: Leaf[] | null };
 const preparedBy = new WeakMap<ExecuteContext, WeakMap<Schedule, Prepared>>();
 
 const preparedFor = (context: ExecuteContext, schedule: Schedule): Prepared => {
@@ -157,7 +164,7 @@ const preparedFor = (context: ExecuteContext, schedule: Schedule): Prepared => {
             runners: schedule.tiers.map(tier => tier.map(context.runnerOf)), remotes: schedule.tiers.map(() => 0), uses: schedule.tiers.map(() => []), version: -1,
             started: schedule.tiers.map(tier => new Array<readonly Chunk[]>(tier.length)),
             systems: [], tiers: [], tasks: new Map(), warnings: [], warningCount: 0, warned: null, outcome: { failures: null, skipped: null },
-            placement: -1, tailing: null,
+            placement: -1, tailing: null, settling: 0, chunk: 0, error: undefined, tierFailed: false,
         };
         bySchedule.set(schedule, prepared);
     }
@@ -249,16 +256,15 @@ const isResults = (result: ChunkResult | readonly ChunkResult[]): result is read
  * A system's outcome in `outcome`: a failure, or a skip with a `"thread"` failure, and its fold. Returns whether it
  * failed, which stops the run after its tier.
  */
-const settled = (state: State, folds: ReadonlyMap<unknown, Fold> | null, outcome: Outcome, runner: Runner, leaf: { readonly name: string }, error: unknown): boolean => {
+const settled = (state: State, folds: ReadonlyMap<unknown, Fold> | null, outcome: Outcome, runner: Runner, leaf: Leaf, error: unknown): boolean => {
     if (error === gone) {
-        const label = labelOfItem(leaf);
-        (outcome.failures ??= []).push(failureOf("thread", label, runner.remote?.channel.goneError()));
-        (outcome.skipped ??= []).push(label);
+        (outcome.failures ??= []).push(failureOf("thread", leaf, runner.remote?.channel.goneError()));
+        (outcome.skipped ??= []).push(leaf);
         if (folds !== null && runner.targets.length > 0) contribute(state, folds, runner, null, true);
         return false;
     }
     const failed = error !== undefined;
-    if (failed) (outcome.failures ??= []).push(failureOf("system", labelOfItem(leaf), error));
+    if (failed) (outcome.failures ??= []).push(failureOf("system", leaf, error));
     if (folds !== null && runner.targets.length > 0) contribute(state, folds, runner, runner.finish(failed), failed);
     return failed;
 };
@@ -279,6 +285,7 @@ const gather = (prepared: Prepared, runners: readonly Runner[], channel: TaskCha
             result.flags = 0;
             result.segment = undefined;
             result.error = undefined;
+            result.value = undefined;
             continue;
         }
         liftColumnStamps(runners[i]);
@@ -337,16 +344,99 @@ const runFused = async (context: ExecuteContext, schedule: Schedule, prepared: P
         }
         if (gpu !== null) markWrites(state, gpu, runners);
         if (failed) {
-            for (let later = v + 1; later < schedule.tiers.length; later++) for (const leaf of schedule.tiers[later]) (outcome.skipped ??= []).push(labelOfItem(leaf));
+            for (let later = v + 1; later < schedule.tiers.length; later++) for (const leaf of schedule.tiers[later]) (outcome.skipped ??= []).push(leaf);
             return -1;
         }
     }
     return last;
 };
 
-const executeTiers = async (context: ExecuteContext, whole: Schedule, args: unknown, earlier: Failure[] | null): Promise<RunReport> => {
-    const { state, kernelIndexOf, workers, publish } = context;
-    const { gpu } = state;
+/** Nothing given back: settling starts, or goes on past what it waited for without a value. */
+const nothing = Symbol("nothing");
+/** What a wait `settleTier` returned settles to: a chunk's results, or whether a joined thread's task was done. */
+type Settled = ChunkResult | readonly ChunkResult[] | boolean | typeof nothing;
+
+/** Starts tier `t`: its kernels first, so workers run while this thread runs its main-thread systems. */
+const startTier = (context: ExecuteContext, prepared: Prepared, t: number, args: unknown): void => {
+    const { workers, kernelIndexOf } = context;
+    const runners = prepared.runners[t];
+    const started = prepared.started[t];
+    prepared.settling = 0;
+    prepared.chunk = 0;
+    prepared.error = undefined;
+    prepared.tierFailed = false;
+    for (let i = 0; i < runners.length; i++) if (runners[i].kernel !== null) started[i] = runners[i].start(args, workers, kernelIndexOf(runners[i]));
+    for (let i = 0; i < runners.length; i++) if (runners[i].kernel === null && runners[i].remote === null) started[i] = runners[i].start(args, null, -1);
+};
+
+/**
+ * Settles tier `t`'s runners from where `prepared` says settling is, queuing each chunk's commands and recording each
+ * system's failure and fold. Returns what to wait for, whose value the caller passes back as `value`, or null once
+ * every runner settled. Every chunk settles, even a failed one, so no worker is still writing at the sync point.
+ * Chunks the main thread ran are settled already, so only those workers and joined threads run are waited for.
+ */
+const settleTier = (state: State, folds: ReadonlyMap<unknown, Fold> | null, prepared: Prepared, tier: readonly Leaf[], t: number, value: Settled): Promise<Settled> | null => {
+    const runners = prepared.runners[t];
+    const started = prepared.started[t];
+    const { outcome } = prepared;
+    let given = value;
+    for (; prepared.settling < runners.length; prepared.settling++) {
+        const i = prepared.settling;
+        const runner = runners[i];
+        const remoteSystem = runner.remote;
+        if (remoteSystem !== null) {
+            if (typeof given !== "boolean") return prepared.tasks.get(remoteSystem.channel) ?? notDone;
+            if (settled(state, folds, outcome, runner, tier[i], settleRemote(state, remoteSystem, given))) prepared.tierFailed = true;
+            given = nothing;
+            continue;
+        }
+        const chunks = started[i];
+        for (; prepared.chunk < chunks.length; prepared.chunk++) {
+            const chunk = chunks[prepared.chunk];
+            let result: ChunkResult | readonly ChunkResult[];
+            if (chunk instanceof Promise) {
+                if (given === nothing || typeof given === "boolean") return chunk;
+                result = given;
+                given = nothing;
+            }
+            else result = chunk;
+            // Every chunk's commands queue, a failed system's included; its first error stands for it.
+            if (isResults(result)) for (const each of result) prepared.error = firstOf(prepared.error, queue(state, each));
+            else prepared.error = firstOf(prepared.error, queue(state, result));
+        }
+        const { error } = prepared;
+        prepared.chunk = 0;
+        prepared.error = undefined;
+        started[i] = noChunks;
+        const failed = error !== undefined;
+        if (failed) {
+            (outcome.failures ??= []).push(failureOf("system", tier[i], error));
+            prepared.tierFailed = true;
+        }
+        if (folds !== null && runner.targets.length > 0) contribute(state, folds, runner, runner.finish(failed), failed);
+    }
+    return null;
+};
+
+/** Once tier `t` settled: counts what it ran and marks its writes. Returns whether it failed, every later tier then skipped. */
+const endTier = (state: State, gpu: GpuEngine | null, prepared: Prepared, schedule: Schedule, t: number): boolean => {
+    const runners = prepared.runners[t];
+    if (prepared.remotes[t] > 0) prepared.tasks.clear();
+    countRan(state, runners);
+    if (gpu !== null) markWrites(state, gpu, runners);
+    if (!prepared.tierFailed) return false;
+    const { outcome } = prepared;
+    for (let later = t + 1; later < schedule.tiers.length; later++) for (const leaf of schedule.tiers[later]) (outcome.skipped ??= []).push(leaf);
+    return true;
+};
+
+/**
+ * Runs a schedule tier by tier, then applies one sync point, and reports what went wrong (`execute`). Runs with no GPU,
+ * tails or observer posts awaiting nothing, so a run that waits for nothing allocates no async frame: at the first
+ * tier on a joined thread, index build across the pool or chunk on workers, `executeFrom` goes on from there.
+ */
+const executeTiers = (context: ExecuteContext, whole: Schedule, args: unknown): RunReport | Promise<RunReport> => {
+    const { state, workers } = context;
     context.tails = null;
     startRan(state.ran);
     let schedule = whole;
@@ -361,91 +451,133 @@ const executeTiers = async (context: ExecuteContext, whole: Schedule, args: unkn
         prepared = preparedFor(context, schedule);
     }
     let folds: Map<unknown, Fold> | null = null;
-    for (const [key, contributors] of schedule.reductions) (folds ??= new Map()).set(key, { target: null, values: [], remaining: contributors, ran: false, failed: false });
-    let dropped = 0;
+    if (schedule.reductions.size !== 0) for (const [key, contributors] of schedule.reductions) (folds ??= new Map()).set(key, { target: null, values: [], remaining: contributors, ran: false, failed: false });
     const { outcome } = prepared;
     prepared.warningCount = 0;
-    outcome.failures = earlier;
+    outcome.failures = null;
     outcome.skipped = null;
+    if (state.gpu !== null || tailing !== null || state.tails.length !== 0 || state.observer.posts.length !== 0) return executeFrom(context, schedule, prepared, folds, args, tailing, 0, null, null);
+    let handed: Promise<RunReport> | null = null;
+    let dropped = 0;
     try {
         for (let t = 0; t < schedule.tiers.length; t++) {
-            const tier = schedule.tiers[t];
             // A tick in progress takes up runners replaced since it started from its next tier on.
             if (prepared.version !== state.runnersVersion) refresh(context, schedule, prepared);
-            const runners = prepared.runners[t];
-            const remote = prepared.remotes[t];
-            if (state.tails.length !== 0) {
-                const waiting = settleRunners(state, runners);
-                if (waiting !== null) await waiting;
-            }
-            if (state.observer.posts.length !== 0) {
-                const waiting = settleObserverRunners(state, runners);
-                if (waiting !== null) await waiting;
-            }
+            if (prepared.remotes[t] !== 0 || state.tails.length !== 0 || state.observer.posts.length !== 0) return handed = executeFrom(context, schedule, prepared, folds, args, null, t, null, null);
             const uses = prepared.uses[t];
             if (uses.length !== 0) {
                 const building = refreshUses(state, uses, workers?.pool ?? null);
-                if (building !== null) await building;
+                if (building !== null) return handed = executeFrom(context, schedule, prepared, folds, args, null, t, building, null);
                 if (state.indexFailures.length !== 0) (outcome.failures ??= []).push(...state.indexFailures.splice(0));
             }
-            const only = remote === runners.length ? runners[0]?.remote?.channel : undefined;
-            if (only !== undefined && allOn(runners, only)) {
-                const last = await runFused(context, schedule, prepared, folds, args, t, only);
-                if (last < 0) break;
-                t = last;
-                continue;
-            }
-            const started = prepared.started[t];
-            if (gpu !== null) await readAhead(state, gpu, runners);
-            // Systems on joined threads start first, so their threads run while this one does.
-            if (remote > 0) {
-                const { tasks } = prepared;
-                tasks.clear();
-                for (let i = 0; i < runners.length; i++) {
-                    const channel = runners[i].remote?.channel;
-                    if (channel === undefined || tasks.has(channel)) continue;
-                    if (channel.busy()) await channel.idle();
-                    gather(prepared, runners, channel, 0);
-                    tasks.set(channel, post(state, prepared, channel, args));
+            startTier(context, prepared, t, args);
+            const waiting = settleTier(state, folds, prepared, schedule.tiers[t], t, nothing);
+            if (waiting !== null) return handed = executeFrom(context, schedule, prepared, folds, args, null, t, null, waiting);
+            if (endTier(state, null, prepared, schedule, t)) break;
+        }
+    }
+    finally {
+        if (handed === null) dropped = finishSync(context, prepared);
+    }
+    return reportOf(state, prepared, dropped);
+};
+
+/**
+ * A run's sync point with nothing to wait for: no GPU, tails or observer posts, which `executeTiers` checked before
+ * each tier and bodies can't add. Returns how many commands it dropped.
+ */
+const finishSync = (context: ExecuteContext, prepared: Prepared): number => {
+    const { state, workers, publish } = context;
+    const { outcome } = prepared;
+    let dropped = 0;
+    // This run's tasks on joined threads are done: they return to their event loops while its sync point applies.
+    for (let k = 0; k < state.logs.length; k++) markRun(state.logs[k]);
+    try {
+        if (prepareSync(state)) {
+            dropped = state.plan.dropped;
+            for (const { finalizer, error, kind } of applySync(state)) (outcome.failures ??= []).push(failureOf(kind ?? "finalizer", finalizer, error));
+        }
+    }
+    finally {
+        // Strings let go before the last run's sync point have no reader left: this run's waited for every one.
+        state.strings?.settle();
+        rewind(state, workers);
+        publish();
+    }
+    return dropped;
+};
+
+/**
+ * `executeTiers` from tier `first` on, awaiting what it needs to: from the tier's start, or once `building`, its
+ * indexes' build, is done, or once `settling`, what settling it waits for, settles.
+ */
+const executeFrom = async (context: ExecuteContext, schedule: Schedule, prepared: Prepared, folds: Map<unknown, Fold> | null, args: unknown, tailing: Tailing | null, first: number, building: Promise<void> | null, settling: Promise<Settled> | null): Promise<RunReport> => {
+    const { state, workers, publish } = context;
+    const { gpu } = state;
+    const { outcome } = prepared;
+    let built = building;
+    let waited = settling;
+    let dropped = 0;
+    try {
+        for (let t = first; t < schedule.tiers.length; t++) {
+            const tier = schedule.tiers[t];
+            if (waited === null) {
+                if (built === null) {
+                    // A tick in progress takes up runners replaced since it started from its next tier on.
+                    if (prepared.version !== state.runnersVersion) refresh(context, schedule, prepared);
+                    const runners = prepared.runners[t];
+                    if (state.tails.length !== 0) {
+                        const waiting = settleRunners(state, runners);
+                        if (waiting !== null) await waiting;
+                    }
+                    if (state.observer.posts.length !== 0) {
+                        const waiting = settleObserverRunners(state, runners);
+                        if (waiting !== null) await waiting;
+                    }
+                    const uses = prepared.uses[t];
+                    if (uses.length !== 0) {
+                        const refreshing = refreshUses(state, uses, workers?.pool ?? null);
+                        if (refreshing !== null) await refreshing;
+                        if (state.indexFailures.length !== 0) (outcome.failures ??= []).push(...state.indexFailures.splice(0));
+                    }
                 }
-            }
-            for (let i = 0; i < runners.length; i++) if (runners[i].kernel !== null) started[i] = runners[i].start(args, workers, kernelIndexOf(runners[i]));
-            for (let i = 0; i < runners.length; i++) if (runners[i].kernel === null && runners[i].remote === null) started[i] = runners[i].start(args, null, -1);
-            // Every chunk settles, even a failed one, so no worker is still writing at the sync point. Chunks the main
-            // thread ran are settled already, so only those workers run are awaited.
-            let tierFailed = false;
-            for (let i = 0; i < runners.length; i++) {
-                const runner = runners[i];
-                const remoteSystem = runner.remote;
-                if (remoteSystem !== null) {
-                    if (settled(state, folds, outcome, runner, tier[i], settleRemote(state, remoteSystem, await (prepared.tasks.get(remoteSystem.channel) ?? notDone)))) tierFailed = true;
-                    continue;
+                else {
+                    await built;
+                    built = null;
+                    if (state.indexFailures.length !== 0) (outcome.failures ??= []).push(...state.indexFailures.splice(0));
                 }
-                let error: unknown = undefined;
-                // Indexed: an iterator kept across an await would be allocated for every system.
-                const chunks = started[i];
-                for (let c = 0; c < chunks.length; c++) {
-                    const chunk = chunks[c];
-                    const result = chunk instanceof Promise ? await chunk : chunk;
-                    // Every chunk's commands queue, a failed system's included; its first error stands for it.
-                    if (isResults(result)) for (const each of result) error = firstOf(error, queue(state, each));
-                    else error = firstOf(error, queue(state, result));
+                const runners = prepared.runners[t];
+                const remote = prepared.remotes[t];
+                const only = remote === runners.length ? runners[0]?.remote?.channel : undefined;
+                if (only !== undefined && allOn(runners, only)) {
+                    const last = await runFused(context, schedule, prepared, folds, args, t, only);
+                    if (last < 0) break;
+                    t = last;
+                    continue;
                 }
-                started[i] = noChunks;
-                const failed = error !== undefined;
-                if (failed) {
-                    (outcome.failures ??= []).push(failureOf("system", labelOfItem(tier[i]), error));
-                    tierFailed = true;
+                if (gpu !== null) await readAhead(state, gpu, runners);
+                // Systems on joined threads start first, so their threads run while this one does.
+                if (remote > 0) {
+                    const { tasks } = prepared;
+                    tasks.clear();
+                    for (let i = 0; i < runners.length; i++) {
+                        const channel = runners[i].remote?.channel;
+                        if (channel === undefined || tasks.has(channel)) continue;
+                        if (channel.busy()) await channel.idle();
+                        gather(prepared, runners, channel, 0);
+                        tasks.set(channel, post(state, prepared, channel, args));
+                    }
                 }
-                if (folds !== null && runner.targets.length > 0) contribute(state, folds, runner, runner.finish(failed), failed);
+                startTier(context, prepared, t, args);
             }
-            if (remote > 0) prepared.tasks.clear();
-            countRan(state, runners);
-            if (gpu !== null) markWrites(state, gpu, runners);
-            if (tierFailed) {
-                for (let later = t + 1; later < schedule.tiers.length; later++) for (const leaf of schedule.tiers[later]) (outcome.skipped ??= []).push(labelOfItem(leaf));
-                break;
+            let value: Settled = nothing;
+            if (waited !== null) {
+                value = await waited;
+                waited = null;
             }
+            let waiting = settleTier(state, folds, prepared, tier, t, value);
+            while (waiting !== null) waiting = settleTier(state, folds, prepared, tier, t, await waiting);
+            if (endTier(state, gpu, prepared, schedule, t)) break;
         }
     }
     finally {
@@ -457,8 +589,6 @@ const executeTiers = async (context: ExecuteContext, whole: Schedule, args: unkn
                 gpu.beforeSync();
             }
             try {
-                // The report's errors known so far join this sync point.
-                context.beforeSync(outcome.failures, outcome.skipped, prepared.warnings, prepared.warningCount);
                 // A sync point counts as a write to everything a tail still reads.
                 if (state.tails.length !== 0) {
                     activate(state);
@@ -484,7 +614,7 @@ const executeTiers = async (context: ExecuteContext, whole: Schedule, args: unkn
                         // Applied even when the readback fails, which only a lost device makes it do: the CPU state
                         // stays whole.
                         dropped = state.plan.dropped;
-                        for (const { finalizer, error, kind } of applySync(state)) (outcome.failures ??= []).push(failureOf(kind ?? "finalizer", labelOfItem(finalizer), error));
+                        for (const { finalizer, error, kind } of applySync(state)) (outcome.failures ??= []).push(failureOf(kind ?? "finalizer", finalizer, error));
                     }
                 }
             }
@@ -514,6 +644,12 @@ const executeTiers = async (context: ExecuteContext, whole: Schedule, args: unkn
             countRan(state, tailing.runners);
         }
     }
+    return reportOf(state, prepared, dropped);
+};
+
+/** A run's report once its sync point applied, its index conflicts included: a shared one when nothing went wrong. */
+const reportOf = (state: State, prepared: Prepared, dropped: number): RunReport => {
+    const { outcome } = prepared;
     // Conflicts unique indexes found while refreshing for finalizers.
     if (state.indexFailures.length !== 0) (outcome.failures ??= []).push(...state.indexFailures.splice(0));
     const { failures, skipped } = outcome;

package/src/implementation/world/failing-worker.fixture.ts

@@ -0,0 +1,3 @@
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+// A worker that fails as it starts, so it never shares or joins a world.
+throw new Error("failing worker");

package/src/implementation/world/failures.ts

@@ -1,14 +1,71 @@
-import type { Failure, Warning } from '../../interface/report/failure.js';
+// © 2026 Adobe. MIT License. See /LICENSE for details.
+import { idOrNull } from '../../interface/registry/index.js';
 
-/** What went wrong in a run or tick, before the world spawns its report: empty lists and a zero when it's clean. */
+/** What failed in a run or tick: a system, finalizer, GPU work, thread or unique index. */
+export type Failure = {
+    /**
+     * A system or finalizer that threw, GPU work, a system whose thread is gone, which didn't run, a unique index
+     * found holding two entities for one key, or the kernel pool's workers, failing to load kernels.
+     */
+    readonly kind: "system" | "finalizer" | "gpu" | "thread" | "index" | "workers";
+    /** The label of what failed: for GPU work, of the system whose run submitted it. */
+    readonly name: string;
+    /** The id the plugin gave it; null without one. */
+    readonly id: string | null;
+    /** An Error's message, or String() of anything else thrown. */
+    readonly message: string;
+    /** What was thrown, the cause of the Error that reports it; undefined for an index's conflict. */
+    readonly error: unknown;
+    /** What failed, by identity: what's reported out of band is reported once while it keeps failing. */
+    readonly subject: object;
+};
+
+/** Whether a body's value is a promise or another thenable, which a run never waits for. */
+export const isThenable = (value: unknown): boolean =>
+    (typeof value === "object" || typeof value === "function") && value !== null && typeof Reflect.get(value, "then") === "function";
+
+/** What fails a system whose body returned a thenable. */
+export const returnedPromise = "its body returned a promise, which nothing awaits: a body returns no promise; start the work, and finish it in a later run";
+
+/** What ran but slowed a run: a system whose tier waited for the joined thread it runs on, as it isn't terminal. */
+export type Warning = { readonly kind: "blocking"; readonly name: string; readonly id: string | null; readonly message: string };
+
+/** What went wrong in a run or tick: empty lists and a zero when it's clean. `skipped` holds the systems not run. */
 export type RunReport = {
     readonly failures: readonly Failure[];
-    readonly skipped: readonly string[];
+    readonly skipped: readonly { readonly name: string }[];
     readonly dropped: number;
     readonly warnings: readonly Warning[];
 };
 
-/** A failure as data: an Error's message and stack, or String() of anything else thrown. */
-export const failureOf = (kind: Failure["kind"], name: string, error: unknown): Failure => error instanceof Error
-    ? { kind, name, message: error.message, stack: typeof error.stack === "string" ? error.stack : null }
-    : { kind, name, message: String(error), stack: null };
+/**
+ * A failure of `of` as data, labeled by its `name` and its `id`, or for an item without `id` the id the plugin gave it:
+ * an Error's message, or String() of anything else thrown. `subject` is what failed, `of` unless given.
+ */
+export const failureOf = (kind: Failure["kind"], of: { readonly name: string; readonly id?: string | null }, error: unknown, subject: object = of): Failure => {
+    const { name } = of;
+    const id = of.id !== undefined ? of.id : idOrNull(of);
+    return { kind, name, id, message: error instanceof Error ? error.message : String(error), error, subject };
+};
+
+const kinds = { system: "System", finalizer: "Finalizer", gpu: "GPU work of system", thread: "System" } as const;
+
+/** One failure as an Error: what failed, by its label and id, and its message, with what was thrown as its cause. */
+export const errorOfFailure = (failure: Failure): Error => {
+    const text = failure.kind === "index" ? failure.message
+        : failure.kind === "workers" ? `The kernel pool's workers failed: ${failure.message}`
+        : `${kinds[failure.kind]} "${failure.name}"${failure.id === null ? "" : ` (${failure.id})`} failed: ${failure.message}`;
+    return failure.error === undefined ? new Error(text) : new Error(text, { cause: failure.error });
+};
+
+/**
+ * What a run whose systems failed rejects with: its one failure's Error, or an AggregateError of each's, its message
+ * naming them all and the systems skipped.
+ */
+export const errorOfRun = (report: RunReport): Error => {
+    const errors = report.failures.map(errorOfFailure);
+    const skipped = report.skipped.length === 0 ? "" : `; skipped: ${report.skipped.map(system => `"${system.name}"`).join(", ")}`;
+    if (errors.length === 1 && skipped === "") return errors[0];
+    if (errors.length === 1) return new Error(`${errors[0].message}${skipped}`, { cause: report.failures[0].error });
+    return new AggregateError(errors, `${errors.length} failures: ${errors.map(error => error.message).join("; ")}${skipped}`);
+};