@evolu/common 8.2.0 → 8.3.1

package/dist/src/Task.js

@@ -51,8 +51,650 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
     return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
 });
 /**
+ * ## Intro
+ *
  * JavaScript-native structured concurrency.
  *
+ * Structured concurrency makes ownership of asynchronous work explicit.
+ * Operations form a tree where every child belongs to a parent. A parent waits
+ * for its children before it completes, and abort follows the tree: aborting a
+ * parent requests abort of all its descendants. Races and fail-fast operations
+ * also abort their remaining sibling branches.
+ *
+ * With plain {@link AbortController} code, these guarantees depend on call-site
+ * discipline: someone must remember the `finally` that aborts started work and
+ * the await that waits for cleanup. {@link Run} makes both structural:
+ * `run(task)` registers every child before it starts, and the parent settles
+ * only after child cleanup finishes.
+ *
+ * Evolu models structured concurrency with ordinary JavaScript:
+ *
+ * - A {@link Task} describes an asynchronous operation and its dependencies.
+ * - A {@link Run} starts Tasks and owns their lifetimes.
+ * - A {@link Fiber} is the Promise-backed handle returned when a Run starts a
+ *   Task.
+ * - An {@link AbortableFiber} adds explicit abort and async disposal.
+ *
+ * The runtime core is deliberately small: ordinary functions, a callable Run
+ * with closed-over state, Promise-backed Fibers, {@link AbortSignal}
+ * propagation, and JavaScript resource management. Together, these primitives
+ * provide abort, cleanup, defect handling, dependency injection, monitoring,
+ * concurrency, and resource bracketing.
+ *
+ * Tasks return domain success or failure as {@link Result}. Abort is control
+ * flow represented by {@link AbortError}. If a Task throws or rejects with
+ * anything else, that is a defect: the root Run reports it and shuts down its
+ * tree so code does not continue in a potentially invalid state.
+ *
+ * ```ts
+ * import {
+ *   createRun,
+ *   err,
+ *   ok,
+ *   type Result,
+ *   type Task,
+ *   type Typed,
+ * } from "@evolu/common";
+ *
+ * interface User {
+ *   readonly id: string;
+ *   readonly name: string;
+ * }
+ *
+ * interface Db {
+ *   readonly usersById: ReadonlyMap<string, User>;
+ * }
+ *
+ * interface DbDep {
+ *   readonly db: Db;
+ * }
+ *
+ * const getUser =
+ *   (id: string): Task<User, UserNotFoundError, DbDep> =>
+ *   (run) => {
+ *     const user = run.deps.db.usersById.get(id);
+ *     return user ? ok(user) : err({ type: "UserNotFound", id });
+ *   };
+ *
+ * // Typed declares the `type` discriminant without repeating the property.
+ * interface UserNotFoundError extends Typed<"UserNotFound"> {
+ *   readonly id: string;
+ * }
+ *
+ * const user: User = { id: "user-1", name: "Ada" };
+ *
+ * // Provide dependencies at the composition root. `await using` disposes the
+ * // Run and waits for its child Tasks before leaving this scope.
+ * await using run = createRun({
+ *   db: { usersById: new Map([[user.id, user]]) },
+ * });
+ *
+ * const result = await run(getUser(user.id));
+ * expectTypeOf(result).toEqualTypeOf<Result<User, UserNotFoundError>>();
+ * expectOk(result, user);
+ * ```
+ *
+ * In composition roots, prefer the lifecycle API from the matching Evolu
+ * platform package:
+ *
+ * - Node.js: `@evolu/nodejs`
+ * - Web: `@evolu/web`
+ * - React Native: `@evolu/react-native`
+ *
+ * ## Composition
+ *
+ * | Category     | Helper                    | Description                                           |
+ * | ------------ | ------------------------- | ----------------------------------------------------- |
+ * | Collection   | {@link all}               | Return {@link Ok} values or stop on first {@link Err} |
+ * |              | {@link allSettled}        | Return every Task Result                              |
+ * |              | {@link each}              | Handle each Task Result                               |
+ * | Interop      | {@link callback}          | Wrap callback APIs                                    |
+ * |              | {@link fetch}             | Native fetch with bounded Response use                |
+ * | Timing       | {@link sleep}             | Pause execution                                       |
+ * |              | {@link timeout}           | Time-bounded execution                                |
+ * | Resilience   | {@link retry}             | Retry domain errors with a schedule                   |
+ * | Repetition   | {@link repeat}            | Repeat successes with a schedule                      |
+ * | Racing       | {@link any}               | First Ok wins                                         |
+ * |              | {@link race}              | First settled Result wins                             |
+ * |              | {@link firstN}            | First n Ok values win                                 |
+ * |              | {@link firstNSettled}     | First n Results win                                   |
+ * | Scheduling   | {@link prioritized}       | Assign scheduler priority                             |
+ * |              | {@link yieldNow}          | Yield to the host scheduler                           |
+ * | Lifetime     | {@link daemon}            | Run under root ownership                              |
+ * |              | {@link acquireUseRelease} | Bracket acquire, use, and release                     |
+ * | Abortability | {@link unabortable}       | Mask abort after a Task starts                        |
+ * |              | {@link unabortableMask}   | Mask abort and selectively restore it                 |
+ *
+ * Helpers that process multiple Tasks run sequentially by default. Use a
+ * `concurrency` option to run more than one Task at a time.
+ *
+ * ### Sequential composition
+ *
+ * For ordinary sequential composition, use imperative code:
+ *
+ * ```ts
+ * import {
+ *   createRun,
+ *   err,
+ *   ok,
+ *   type Result,
+ *   type Task,
+ *   type Typed,
+ * } from "@evolu/common";
+ *
+ * interface User {
+ *   readonly id: string;
+ *   readonly profileId: string;
+ * }
+ *
+ * interface Profile {
+ *   readonly id: string;
+ * }
+ *
+ * const getUser =
+ *   (id: string): Task<User, UserNotFoundError> =>
+ *   () =>
+ *     id === "user-1"
+ *       ? ok({ id, profileId: "profile-1" })
+ *       : err({ type: "UserNotFound", id });
+ *
+ * interface UserNotFoundError extends Typed<"UserNotFound"> {
+ *   readonly id: string;
+ * }
+ *
+ * const getProfile =
+ *   (id: string): Task<Profile, ProfileNotFoundError> =>
+ *   () =>
+ *     id === "profile-1"
+ *       ? ok({ id })
+ *       : err({ type: "ProfileNotFound", id });
+ *
+ * interface ProfileNotFoundError extends Typed<"ProfileNotFound"> {
+ *   readonly id: string;
+ * }
+ *
+ * const getUserWithProfile =
+ *   (
+ *     id: string,
+ *   ): Task<
+ *     { readonly user: User; readonly profile: Profile },
+ *     UserNotFoundError | ProfileNotFoundError
+ *   > =>
+ *   async (run) => {
+ *     const user = await run(getUser(id));
+ *     if (!user.ok) return user;
+ *
+ *     const profile = await run(getProfile(user.value.profileId));
+ *     if (!profile.ok) return profile;
+ *
+ *     return ok({ user: user.value, profile: profile.value });
+ *   };
+ *
+ * await using run = createRun();
+ * const result = await run(getUserWithProfile("user-1"));
+ * expectTypeOf(result).toEqualTypeOf<
+ *   Result<
+ *     { readonly user: User; readonly profile: Profile },
+ *     UserNotFoundError | ProfileNotFoundError
+ *   >
+ * >();
+ * expectOk(result, {
+ *   user: { id: "user-1", profileId: "profile-1" },
+ *   profile: { id: "profile-1" },
+ * });
+ * ```
+ *
+ * Evolu intentionally avoids pipe APIs, chainable methods, and generator-based
+ * effect DSLs. Plain async/await with early returns is easier to read, review,
+ * and debug, and it lets TypeScript narrow Result values through ordinary
+ * control flow.
+ *
+ * ### Resilient fetch
+ *
+ * {@link fetch} with a body mode already returns a plain value, so resilience is
+ * ordinary Task composition. Combine {@link timeout} and {@link retry} to bound
+ * each attempt and retry recoverable domain failures:
+ *
+ * ```ts
+ * import {
+ *   exponential,
+ *   fetch,
+ *   jitter,
+ *   maxDelay,
+ *   retry,
+ *   take,
+ *   timeout,
+ *   type FetchError,
+ *   type RetryTaskError,
+ *   type Task,
+ *   type TimeoutError,
+ * } from "@evolu/common";
+ *
+ * const fetchWithRetry = (url: string) =>
+ *   retry(
+ *     timeout(fetch(url, "text"), "30s"),
+ *     // A jittered, capped, limited exponential backoff.
+ *     jitter("100%")(maxDelay("20s")(take(2)(exponential("100ms")))),
+ *   );
+ *
+ * expectTypeOf(fetchWithRetry).returns.toEqualTypeOf<
+ *   Task<string, RetryTaskError<FetchError | TimeoutError>>
+ * >();
+ * ```
+ *
+ * ### Concurrent composition
+ *
+ * Run composed Tasks with a `concurrency` option and {@link all}:
+ *
+ * ```ts
+ * import { all, createRun, ok, sleep, type Task } from "@evolu/common";
+ *
+ * await using run = createRun();
+ *
+ * const urls = [
+ *   "https://api.example.com/users",
+ *   "https://api.example.com/posts",
+ *   "https://api.example.com/comments",
+ * ];
+ * let activeRequests = 0;
+ * let maxActiveRequests = 0;
+ * const fetchUrl =
+ *   (url: string): Task<string> =>
+ *   async (run) => {
+ *     activeRequests += 1;
+ *     maxActiveRequests = Math.max(maxActiveRequests, activeRequests);
+ *     await run.ok(sleep("1ms"));
+ *     activeRequests -= 1;
+ *     return ok(url);
+ *   };
+ *
+ * // At most 2 concurrent requests.
+ * const result = await run(all(urls, fetchUrl, { concurrency: 2 }));
+ * expectOk(result, urls);
+ * expect(maxActiveRequests).toBe(2);
+ * ```
+ *
+ * Task helpers compose Tasks; concurrency primitives are stateful objects that
+ * coordinate Tasks across call sites. Create them with their `createX`
+ * factories and share them where coordination is needed.
+ *
+ * | Primitive              | Description                                  |
+ * | ---------------------- | -------------------------------------------- |
+ * | {@link Deferred}       | One-shot value resolved from outside         |
+ * | {@link Gate}           | Block and release Tasks repeatedly           |
+ * | {@link Semaphore}      | Limit concurrent Tasks with permits          |
+ * | {@link Mutex}          | Run Tasks one at a time                      |
+ * | {@link SemaphoreByKey} | Per-key permits with automatic cleanup       |
+ * | {@link MutexByKey}     | Per-key one-at-a-time execution              |
+ * | {@link MutexRef}       | {@link Ref} with serialized Task transitions |
+ *
+ * ## Dependency injection
+ *
+ * Task DI is
+ * {@link https://www.evolu.dev/docs/dependency-injection | Evolu Pure DI}
+ * applied to {@link Run}. A {@link Task} declares required capabilities with its
+ * `D` type parameter and reads them from {@link Run.deps}.
+ *
+ * {@link createRun} supplies dependencies to the root Run and its children. A
+ * Run can also start one child Task with runtime-created dependencies by
+ * calling `run(task, deps)`, where `deps` is checked as {@link RunCustomDeps}.
+ *
+ * Use normal Task arguments for per-call values and `D` for capabilities,
+ * resources, or services shared by all code running inside a Run.
+ *
+ * ```ts
+ * import { createRun, ok, type Task } from "@evolu/common";
+ *
+ * interface GreetingFormatter {
+ *   readonly format: (name: string) => string;
+ * }
+ *
+ * interface GreetingFormatterDep {
+ *   readonly greetingFormatter: GreetingFormatter;
+ * }
+ *
+ * const greet =
+ *   (name: string): Task<string, never, GreetingFormatterDep> =>
+ *   (run) =>
+ *     ok(run.deps.greetingFormatter.format(name));
+ *
+ * const formal: GreetingFormatter = {
+ *   format: (name) => `Hello, ${name}`,
+ * };
+ * const casual: GreetingFormatter = {
+ *   format: (name) => `Hi, ${name}`,
+ * };
+ *
+ * await using run = createRun({ greetingFormatter: formal });
+ *
+ * // Root dependencies are inherited.
+ * expectOk(await run(greet("Ada")), "Hello, Ada");
+ *
+ * // Child-specific dependencies replace the root's custom dependencies.
+ * expectOk(
+ *   await run(greet("Ada"), { greetingFormatter: casual }),
+ *   "Hi, Ada",
+ * );
+ * ```
+ *
+ * ### Default dependencies
+ *
+ * {@link createRun} provides default {@link RunDefaultDeps} available to all
+ * Tasks without declaring `D`:
+ *
+ * - {@link Console} — logging with hierarchical context via `child()`
+ * - {@link LeakDetector} — development-time leaked-handle detection
+ * - {@link NativeFetch} — WHATWG-compatible native fetch
+ * - {@link Random} — random number generation
+ * - {@link RandomBytes} — cryptographic random bytes
+ * - {@link ReportDefect} — defect reporting
+ * - {@link Time} — current time
+ *
+ * For testing, use {@link testCreateRun} to get deterministic, controllable
+ * implementations of all RunDefaultDeps.
+ *
+ * ## Resource management
+ *
+ * JavaScript provides standard
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Resource_management | resource management}.
+ * Evolu adds {@link DisposableRun.defer} for closure-held state owned by a
+ * reusable Run.
+ *
+ * Choose the ownership primitive by where the resource is reachable:
+ *
+ * - Synchronous stack frame: `using` or {@link DisposableStack}
+ * - Async Task stack frame: `await using` or {@link AsyncDisposableStack}
+ * - Closure-held state bounded by a reusable {@link DisposableRun}:
+ *   {@link DisposableRun.defer}
+ *
+ * ### Returning resources from Tasks
+ *
+ * A Task that successfully returns a disposable resource transfers ownership of
+ * a live resource to its caller. The resource must remain live after the Task
+ * settles. Do not register its disposal with the creating Task's
+ * {@link DisposableRun.defer}, because that child Run is disposed when the Task
+ * settles.
+ *
+ * Use {@link AsyncDisposableStack} while creating a resource. On a Result error,
+ * abort, or defect, stack unwinding disposes partially created resources. On
+ * success, {@link AsyncDisposableStack.move} transfers ownership to the returned
+ * resource. A recoverable creation failure should be a typed Result error;
+ * `undefined` should represent valid absence, not failure.
+ *
+ * ```ts
+ * import { createRun, ok, type Task, type Typed } from "@evolu/common";
+ *
+ * interface Socket extends AsyncDisposable {
+ *   readonly send: (message: string) => string;
+ * }
+ *
+ * interface Connection extends AsyncDisposable {
+ *   readonly send: (message: string) => string;
+ * }
+ *
+ * let socketDisposed = false;
+ * const openSocket: Task<Socket, ConnectionFailedError> = () =>
+ *   ok({
+ *     send: (message) => message,
+ *     [Symbol.asyncDispose]: async () => {
+ *       socketDisposed = true;
+ *     },
+ *   });
+ *
+ * interface ConnectionFailedError extends Typed<"ConnectionFailed"> {}
+ *
+ * const handshake =
+ *   (_socket: Socket): Task<void, ConnectionFailedError> =>
+ *   () =>
+ *     ok();
+ *
+ * const createConnection: Task<Connection, ConnectionFailedError> = async (
+ *   run,
+ * ) => {
+ *   await using disposer = new AsyncDisposableStack();
+ *
+ *   const socketResult = await run(openSocket);
+ *   if (!socketResult.ok) return socketResult;
+ *   const socket = disposer.use(socketResult.value);
+ *
+ *   const handshakeResult = await run(handshake(socket));
+ *   if (!handshakeResult.ok) return handshakeResult;
+ *
+ *   const disposables = disposer.move();
+ *   return ok({
+ *     send: (message) => socket.send(message),
+ *     [Symbol.asyncDispose]: () => disposables.disposeAsync(),
+ *   });
+ * };
+ *
+ * await using run = createRun();
+ * const result = await run(createConnection);
+ * assert(result.ok);
+ * expect(socketDisposed).toBe(false);
+ * expect(result.value.send("hello")).toBe("hello");
+ * await result.value[Symbol.asyncDispose]();
+ * expect(socketDisposed).toBe(true);
+ * ```
+ *
+ * Use {@link Run.ok} with `await using` when an infallible Task returns a
+ * disposable value. Use {@link acquireUseRelease} when acquisition and release
+ * are separate operations rather than a disposable value.
+ *
+ * ## Awaitable
+ *
+ * A {@link Task} returns {@link Awaitable}, so its body may produce a
+ * {@link Result} immediately or asynchronously. {@link Run} is always async and
+ * returns a {@link Fiber}; callers use the same ownership model either way.
+ *
+ * - **Sync** → {@link Result}, native `using` / `DisposableStack`
+ * - **Async** → Task, Run, {@link Fiber}, `await using` / `AsyncDisposableStack`
+ *
+ * A Task is an async ownership boundary, not a general unit of program
+ * decomposition. Calling `run(task)` always creates a child Run by design. Use
+ * ordinary promises when an async operation does not need its own Run.
+ *
+ * A unified sync/async effect API is technically possible. It can detect
+ * Promise-like values with {@link isPromiseLike}, dispose synchronous resources
+ * first, continue with asynchronous disposal when necessary, and track whether
+ * callers must await the result. Evolu deliberately keeps the two models
+ * separate instead: plain functions and Result for synchronous code, Task and
+ * Run for asynchronous ownership. Most effects involve inherently asynchronous
+ * I/O, while synchronous code benefits from a simpler API and no Task
+ * overhead.
+ *
+ * Keep synchronous computation as plain functions returning Result. Prefer
+ * passing values rather than dependencies, following the
+ * {@link https://blog.ploeh.dk/2017/02/02/dependency-rejection/ | impure/pure/impure sandwich}
+ * pattern where impure code gathers data, pure functions process it, and impure
+ * code performs effects with the result. For example, a pure function can
+ * accept a {@link RandomNumber} value instead of depending on {@link Random}.
+ *
+ * Large CPU-bound operations, such as parsing large JSON, sorting millions of
+ * items, or complex cryptography, belong in a worker. Model the asynchronous
+ * call to that worker as a Task so Run can provide timeout, abort, cleanup, and
+ * monitoring.
+ *
+ * ## Glossary
+ *
+ * - **Defect** — a thrown or rejected value other than {@link AbortError}, rather
+ *   than a declared {@link Result} error.
+ * - **Outcome** — a Fiber's settlement: resolution with the Task {@link Result},
+ *   or rejection with {@link AbortError}. The original defect is reported
+ *   through {@link ReportDefectDep} whether or not the Fiber is observed; the
+ *   Fiber boundary represents the panic with AbortError whose reason is
+ *   {@link PanicAbortReason}.
+ * - **Create** — construct a new value or a resource.
+ * - **Acquire** — obtain a usable resource. Acquisition may create a new
+ *   resource, borrow one, open one, or take a lease/lock.
+ * - **Release** — relinquish a previously acquired resource or lease. Release
+ *   pairs with acquire and need not mean disposal; examples include unlock,
+ *   logout, or returning a pooled resource.
+ * - **Dispose / disposal** — owner-driven resource finalization via JavaScript
+ *   resource management (`Symbol.dispose`, `Symbol.asyncDispose`, `using`,
+ *   `AsyncDisposableStack`).
+ *
+ * ## FAQ
+ *
+ * ### Why is AbortError not part of every Task error type?
+ *
+ * The `E` type parameter represents declared domain errors. Abort is
+ * structured-concurrency control flow, not a domain error. A direct `run(task)`
+ * rejects with {@link AbortError} when the Task observes abort. Use
+ * `run.abortable(task)` when abort should be handled as an ordinary
+ * {@link Result} error at the Fiber boundary, or `daemon(task)` when waiting for
+ * a Task should stop immediately after abort.
+ *
+ * ### Do I have to await every Fiber?
+ *
+ * No. Awaiting a Fiber is join: it makes the child outcome part of the current
+ * control flow. When the outcome does not matter — a fire-and-forget side
+ * effect — discard the Fiber explicitly with `void run(task)`.
+ *
+ * That is safe because the Run tree supervises every Fiber it creates. A
+ * discarded Fiber whose Task observes abort (for example during Run disposal)
+ * never surfaces as an unhandled rejection, and cleanup is not lost — disposal
+ * already aborts and awaits the child. Defects are different: they still panic
+ * the root Run and are reported through {@link ReportDefectDep}, so discarding a
+ * Fiber never hides bugs.
+ *
+ * Choose the boundary explicitly:
+ *
+ * - `void run(task)` — the outcome does not matter. Abort is silent; defects are
+ *   still reported.
+ * - `await run(task)` — the continuation depends on the Result, so abort rejects
+ *   into the awaiter and the boundary must handle it.
+ * - `run.abortable(task)` — abort is an expected outcome handled as a
+ *   {@link Result} error.
+ *
+ * ### What should Task code do with defects?
+ *
+ * Nothing. Once a defect reaches the {@link Run}, it is too late: the root Run
+ * panics, running Tasks are aborted, and the Run tree shuts down. If an
+ * operation can throw or reject for a recoverable reason, wrap that operation
+ * with {@link trySync} or {@link tryAsync} so the failure becomes a typed
+ * {@link Result} error. Let unrecoverable failures propagate as defects.
+ *
+ * ### Why does a defect panic the whole Run tree?
+ *
+ * The obvious alternative is partial recovery: only the failing subtree shuts
+ * down or restarts while the rest keeps running. Erlang/OTP made this "let it
+ * crash" model with supervisors the benchmark for fault-tolerant runtime
+ * design.
+ *
+ * Erlang can recover partially because of process isolation: each process owns
+ * its heap, so a crashed process cannot leave another process's state
+ * corrupted. JavaScript Tasks share a heap. A defect may throw after partially
+ * updating shared state, and the Run cannot prove which invariants are still
+ * valid. A subtree panic would stop the failing Task while leaving any
+ * corrupted shared state available to surviving Tasks. Locks make it worse: a
+ * defect inside a critical section may leave protected invariants half-updated.
+ * In-process restart is not a reliable recovery boundary either, because the
+ * restarted code may still share the same module state, closures, caches, or
+ * resources.
+ *
+ * JavaScript does have a boundary with Erlang-like isolation: workers. A worker
+ * has its own heap and structured-clone messaging, so corruption cannot cross
+ * the boundary, and respawning a worker starts from clean state. A defect can
+ * panic the worker's Run tree, the worker boundary can be torn down, and the
+ * supervising side decides whether to respawn — {@link retry} with a
+ * {@link Schedule} around a "spawn worker, run until exit" Task is a one-for-one
+ * supervisor. Multiple root Runs that share no mutable state are a lighter
+ * alternative, but the share-nothing guarantee is then architectural discipline
+ * rather than enforced isolation, so keep it opt-in and rare.
+ *
+ * ### Why imperative code instead of monadic effect composition?
+ *
+ * Monads give pure functional languages a way to sequence effects while keeping
+ * functions pure. JavaScript already has native effect sequencing: loops, early
+ * returns, `try`/`finally`, exceptions, and `async`/`await`.
+ *
+ * A monadic effect wrapper moves that control flow into a library DSL. The
+ * wrapper type becomes viral, and ordinary debugging, profiling, stack traces,
+ * and TypeScript narrowing have to work through the DSL instead of the
+ * language.
+ *
+ * Task follows the opposite approach: Tasks are ordinary async functions, Run
+ * owns lifetimes and scoped context, {@link Result} carries expected domain
+ * errors, and defects keep real exceptions with real stacks. Result propagation
+ * is explicit at each async boundary, so TypeScript narrows it through ordinary
+ * control flow and readers can see where an error is handled or returned.
+ *
+ * ### Are recursive Tasks stack-safe?
+ *
+ * Tasks have native JavaScript stack behavior. A deeply recursive Task can
+ * exceed the call stack when each step starts the next step synchronously.
+ * `await` alone does not prevent this: JavaScript evaluates its operand before
+ * suspending, and `run(nextTask)` starts the child Task immediately.
+ *
+ * Implement deep recursive algorithms with a loop and an explicit worklist so
+ * each iteration reuses the same stack frame:
+ *
+ * ```ts
+ * import { createRun, ok, type Task } from "@evolu/common";
+ *
+ * interface TreeNode {
+ *   readonly value: string;
+ *   readonly children: ReadonlyArray<TreeNode>;
+ * }
+ *
+ * const visitTree =
+ *   (root: TreeNode): Task<ReadonlyArray<string>> =>
+ *   () => {
+ *     const remaining = [root];
+ *     const visited: Array<string> = [];
+ *
+ *     while (remaining.length > 0) {
+ *       const node = remaining.pop();
+ *       if (!node) continue;
+ *       visited.push(node.value);
+ *       for (const child of node.children) remaining.push(child);
+ *     }
+ *
+ *     return ok(visited);
+ *   };
+ *
+ * await using run = createRun();
+ * expectOk(
+ *   await run(
+ *     visitTree({
+ *       value: "root",
+ *       children: [{ value: "child", children: [] }],
+ *     }),
+ *   ),
+ *   ["root", "child"],
+ * );
+ * ```
+ *
+ * Task favors direct native execution, `async`/`await`, and native tooling over
+ * interpreted control flow. The trade-off is no transparent stack safety or
+ * automatic scheduling fairness. Use loops or worklists for deep algorithms,
+ * periodically await {@link yieldNow} for cooperative scheduling, and move
+ * CPU-bound work to a worker.
+ *
+ * ### Should a Task be called directly?
+ *
+ * Only inside Task internals that explicitly require same-Run execution. A
+ * direct call, `task(run)`, uses the current Run instead of creating a child
+ * Run, so it bypasses child lifetime tracking, scheduling metadata, and child
+ * disposal boundaries. Application code should use `run(task)`.
+ *
+ * ### Where are fork and join?
+ *
+ * Calling `run(task)` is fork: it starts a child Task and returns a
+ * {@link Fiber}. Awaiting or returning that Fiber is join: it makes the child
+ * Result or rejection part of the parent Task control flow.
+ *
+ * ### What runtime features does Task require?
+ *
+ * Task uses modern JavaScript APIs such as `Promise.withResolvers`,
+ * `AbortSignal.throwIfAborted`, `Symbol.dispose`, `Symbol.asyncDispose`,
+ * `DisposableStack`, and `AsyncDisposableStack`. Evolu provides polyfills for
+ * supported runtimes that need them: call `installPolyfills` from
+ * `@evolu/common/polyfills`, or from the platform package such as
+ * `@evolu/react-native/polyfills`. The `using` and `await using` syntax is
+ * emitted by TypeScript; the polyfills provide the runtime resource-management
+ * globals.
+ *
  * @module
  */
 import { emptyArray, isNonEmptyArray, mapArray, } from "./Array.js";
@@ -74,7 +716,7 @@ import { emptySet } from "./Set.js";
 import { createTime, PositiveMillis, testCreateTime, } from "./Time.js";
 import { assertType, createId, maxPositiveInt, NonNegativeInt, object, onePositiveInt, PositiveInt, record, String, typed, Unknown, UnknownResult, } from "./Type.js";
 /**
- * Typed object explaining why a {@link Run} was aborted.
+ * Runtime Type for structured data explaining why a {@link Run} was aborted.
  *
  * A reason has a `type` discriminant and optional structured data, so abort
  * causes can carry typed domain data. Well-known reasons are
@@ -86,11 +728,11 @@ import { assertType, createId, maxPositiveInt, NonNegativeInt, object, onePositi
 export const AbortReason = /*#__PURE__*/ object({ type: String }, 
 /*#__PURE__*/ record(String, Unknown));
 /**
- * Typed object representing structured-concurrency abort control flow.
+ * Runtime Type for structured-concurrency abort control flow.
  *
- * AbortError is thrown to stop Task execution when a Run observes an abort
- * request. AbortableFiber catches AbortError and returns it as a {@link Result}
- * error, so abort can be handled as an ordinary Task outcome.
+ * AbortError is thrown to stop {@link Task} execution when a {@link Run} observes
+ * an abort request. {@link AbortableFiber} catches AbortError and returns it as
+ * a {@link Result} error, so abort can be handled as an ordinary Task outcome.
  *
  * The reason explains why the Run was aborted. It can be an explicit abort
  * reason, {@link runDisposedAbortReason} for normal Run cleanup, or
@@ -124,9 +766,9 @@ export const createAbortError = (reason) => ({
 /**
  * Shared abort reason used for ordinary {@link Run} cleanup.
  *
- * Disposal requests abort so child Tasks stop while the Run waits for them to
- * settle. This reason distinguishes that cleanup path from explicit abort and
- * {@link PanicAbortReason}.
+ * Disposal requests abort so child {@link Task}s stop while the Run waits for
+ * them to settle. This reason distinguishes that cleanup path from explicit
+ * abort and {@link PanicAbortReason}.
  *
  * @group Run
  */
@@ -146,7 +788,7 @@ export const explicitAbortReason = {
 /**
  * Shared abort reason for tests that need a non-production abort reason.
  *
- * @group Run
+ * @group Testing
  */
 export const testAbortReason = {
     type: "TestAbortReason",
@@ -154,7 +796,7 @@ export const testAbortReason = {
 /**
  * Shared {@link AbortError} for tests, created from {@link testAbortReason}.
  *
- * @group Run
+ * @group Testing
  */
 export const testAbortError = /*#__PURE__*/ createAbortError(testAbortReason);
 /**
@@ -203,6 +845,28 @@ export const createRunDefaultDeps = () => {
 /**
  * Creates a root {@link DisposableRun}.
  *
+ * Use at composition roots such as app, server, worker, or test entry points.
+ * The common factory is platform-agnostic; platform adapters can wrap it to add
+ * global error handling or shutdown integration.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { createRun, ok, type Task } from "@evolu/common";
+ *
+ * interface ConfigDep {
+ *   readonly config: { readonly apiUrl: string };
+ * }
+ *
+ * const loadApiUrl: Task<string, never, ConfigDep> = (run) =>
+ *   ok(run.deps.config.apiUrl);
+ *
+ * await using run = createRun({
+ *   config: { apiUrl: "https://api.example.com" },
+ * });
+ * expectOk(await run(loadApiUrl), "https://api.example.com");
+ * ```
+ *
  * @group Run
  */
 export const createRun = (deps) => createRunInternal({
@@ -685,10 +1349,11 @@ const mapInput = (input, fn) => Array.isArray(input)
  * callbacks. Resolve with `ok(value)` or `err(error)`, or reject with a defect,
  * to complete the Task. Settlement is one-shot: the first `resolve` or `reject`
  * wins, and later settlement calls are ignored, matching Promise semantics.
- * When `reject` wins settlement, the defect panics the Run tree and is observed
- * at Fiber boundaries as {@link AbortError} with {@link PanicAbortReason}.
- * Rejecting AbortError is reserved for Task abort control flow: direct
- * `run(task)` rejects with it, and `run.abortable(task)` returns it as an Err.
+ * When `reject` wins settlement, the defect panics the {@link Run} tree and is
+ * observed at {@link Fiber} boundaries as {@link AbortError} with
+ * {@link PanicAbortReason}. Rejecting AbortError is reserved for Task abort
+ * control flow: direct `run(task)` rejects with it, and `run.abortable(task)`
+ * returns it as an {@link Err}.
  *
  * This helper is a callback bridge. If `reject` forwards an Error created in a
  * separate async chain, V8 cannot reconstruct the caller's zero-cost async
@@ -703,10 +1368,10 @@ const mapInput = (input, fn) => Array.isArray(input)
  * Optionally return a synchronous cleanup callback. It runs when the Task Run
  * signal aborts, including normal completion and explicit abort. The callback
  * must not throw. Cleanup defects panic the root Run; if the callback Task
- * already settled, its Fiber keeps the original Result while the root still
- * reports the panic. Cleanup must be synchronous; returned promises are not
- * awaited. For async cleanup, prefer {@link acquireUseRelease}, `await using`
- * with {@link AsyncDisposableStack}, or a Task that owns the resource
+ * already settled, its Fiber keeps the original {@link Result} while the root
+ * still reports the panic. Cleanup must be synchronous; returned promises are
+ * not awaited. For async cleanup, prefer {@link acquireUseRelease}, `await
+ * using` with {@link AsyncDisposableStack}, or a Task that owns the resource
  * explicitly.
  *
  * If setup can throw after acquiring any resource, use a local
@@ -756,7 +1421,16 @@ export const callback = (fn) => (run) => {
 /**
  * Pauses execution for a specified {@link PositiveDuration}.
  *
- * Aborting the Task clears the scheduled timeout.
+ * Aborting the {@link Task} clears the scheduled timeout.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { createRun, sleep } from "@evolu/common";
+ *
+ * await using run = createRun();
+ * expectOk(await run(sleep("1ms")), undefined);
+ * ```
  *
  * @group Timing
  */
@@ -764,19 +1438,6 @@ export const sleep = (duration) => callback(({ run: { deps }, resolve }) => {
     const id = deps.time.setTimeout(() => resolve(ok()), duration);
     return () => deps.time.clearTimeout(id);
 });
-/**
- * Typed error returned by {@link timeout} when a Task exceeds its duration.
- *
- * @group Timing
- */
-export const TimeoutError = 
-/*#__PURE__*/ typed("TimeoutError");
-/**
- * The {@link TimeoutError} instance returned by {@link timeout}.
- *
- * @group Timing
- */
-export const timeoutError = { type: "TimeoutError" };
 /**
  * Limits how long a {@link Task} may run.
  *
@@ -815,23 +1476,37 @@ export const timeout = (task, duration) => race([
     },
 ]);
 /**
- * Retries a Task according to a {@link Schedule}.
+ * Runtime Type for the error returned by {@link timeout} when a {@link Task}
+ * exceeds its duration.
+ *
+ * @group Timing
+ */
+export const TimeoutError = 
+/*#__PURE__*/ typed("TimeoutError");
+/**
+ * The {@link TimeoutError} instance returned by {@link timeout}.
+ *
+ * @group Timing
+ */
+export const timeoutError = { type: "TimeoutError" };
+/**
+ * Retries a {@link Task} according to a {@link Schedule}.
  *
  * Use `retry` for failure recovery: it repeats after {@link Err} and wraps the
  * final domain error. Use {@link repeat} for success-driven loops: it repeats
- * after {@link Ok} and returns the Task's natural Result.
+ * after {@link Ok} and returns the Task's natural {@link Result}.
  *
  * {@link AbortError} passes through unchanged when returned as a Result error,
- * such as from {@link daemon}. Abort from `run(task)` remains Fiber control
- * flow. Other errors are domain errors: retrying continues while the schedule
- * yields another delay and {@link RetryOptions.shouldRetry} returns `true`. When
- * retrying stops, `retry` returns {@link RetryError} with the final domain error
- * as `lastError`.
+ * such as from {@link daemon}. Abort from `run(task)` remains {@link Fiber}
+ * control flow. Other errors are domain errors: retrying continues while the
+ * schedule yields another delay and {@link RetryOptions.shouldRetry} returns
+ * `true`. When retrying stops, `retry` returns {@link RetryError} with the final
+ * domain error as `lastError`.
  *
  * AbortError recognition is structural. Domain errors, especially values parsed
  * from untrusted input, must not use the reserved AbortError shape.
  *
- * ### Example
+ * ### Retrying failures
  *
  * ```ts
  * import {
@@ -842,51 +1517,58 @@ export const timeout = (task, duration) => race([
  *   type Result,
  *   type RetryTaskError,
  *   type Task,
+ *   type Typed,
  * } from "@evolu/common";
  *
- * await using run = createRun();
- *
- * interface FetchDataError {
- *   readonly type: "FetchDataError";
- * }
+ * const fetchData: Task<string, ServiceUnavailableError> = () =>
+ *   err({ type: "ServiceUnavailable" });
  *
- * const fetchData: Task<string, FetchDataError> = () =>
- *   err({ type: "FetchDataError" });
+ * interface ServiceUnavailableError extends Typed<"ServiceUnavailable"> {}
  *
  * const fetchWithRetry = retry(fetchData, recurs(2));
  *
+ * await using run = createRun();
  * const result = await run(fetchWithRetry);
  * expectTypeOf(result).toEqualTypeOf<
- *   Result<string, RetryTaskError<FetchDataError>>
+ *   Result<string, RetryTaskError<ServiceUnavailableError>>
  * >();
  * expectErr(result, {
  *   type: "RetryError",
  *   attempts: 3,
- *   lastError: { type: "FetchDataError" },
+ *   lastError: { type: "ServiceUnavailable" },
  * });
  * ```
  *
- * ### Example
+ * ### Filtering retries
  *
  * ```ts
- * import { createRun, err, recurs, retry, type Task } from "@evolu/common";
+ * import {
+ *   createRun,
+ *   err,
+ *   recurs,
+ *   retry,
+ *   type Task,
+ *   type Typed,
+ * } from "@evolu/common";
  *
- * interface FetchDataError {
- *   readonly type: "RecoverableError" | "FatalError";
- * }
+ * const fetchData: Task<
+ *   string,
+ *   TemporaryFailureError | PermanentFailureError
+ * > = () => err({ type: "PermanentFailure" });
+ *
+ * interface TemporaryFailureError extends Typed<"TemporaryFailure"> {}
  *
- * const fetchData: Task<string, FetchDataError> = () =>
- *   err({ type: "FatalError" });
+ * interface PermanentFailureError extends Typed<"PermanentFailure"> {}
  *
  * const fetchWithRetry = retry(fetchData, recurs(5), {
- *   shouldRetry: (error) => error.type !== "FatalError",
+ *   shouldRetry: (error) => error.type !== "PermanentFailure",
  * });
  *
  * await using run = createRun();
  * expectErr(await run(fetchWithRetry), {
  *   type: "RetryError",
  *   attempts: 1,
- *   lastError: { type: "FatalError" },
+ *   lastError: { type: "PermanentFailure" },
  * });
  * ```
  *
@@ -920,13 +1602,14 @@ export const retry = (task, schedule, { shouldRetry = constTrue, onRetry, } = {}
     }
 };
 /**
- * Repeats a Task according to a {@link Schedule}.
+ * Repeats a {@link Task} according to a {@link Schedule}.
  *
  * Runs the Task once, then repeats while the Task returns {@link Ok}, the
  * schedule yields another delay, and {@link RepeatOptions.shouldRepeat} returns
- * `true`. When repeating stops, `repeat` returns the last successful Result. If
- * the Task returns {@link Err}, including {@link Done} from a {@link NextTask},
- * `repeat` returns that error without scheduling another attempt.
+ * `true`. When repeating stops, `repeat` returns the last successful
+ * {@link Result}. If the Task returns {@link Err}, including {@link Done} from a
+ * {@link NextTask}, `repeat` returns that error without scheduling another
+ * attempt.
  *
  * Use `repeat` for success-driven loops such as polling or consuming a
  * NextTask: it repeats after Ok and returns the Task's natural Result. Use
@@ -935,7 +1618,7 @@ export const retry = (task, schedule, { shouldRetry = constTrue, onRetry, } = {}
  *
  * With `take(n)`, the Task runs n+1 times: the initial attempt plus n repeats.
  *
- * ### Example
+ * ### Repeating successes
  *
  * ```ts
  * import { createRun, ok, recurs, repeat, type Task } from "@evolu/common";
@@ -953,7 +1636,7 @@ export const retry = (task, schedule, { shouldRetry = constTrue, onRetry, } = {}
  * expect(attempts).toBe(4);
  * ```
  *
- * ### Example
+ * ### Stopping with Done
  *
  * ```ts
  * import {
@@ -966,8 +1649,6 @@ export const retry = (task, schedule, { shouldRetry = constTrue, onRetry, } = {}
  *   type NextTask,
  * } from "@evolu/common";
  *
- * await using run = createRun();
- *
  * interface Item {
  *   readonly id: string;
  * }
@@ -979,6 +1660,7 @@ export const retry = (task, schedule, { shouldRetry = constTrue, onRetry, } = {}
  *   return item ? ok(item) : err(done());
  * };
  *
+ * await using run = createRun();
  * const result = await run(repeat(processQueue, spaced("1ms")));
  * expectErr(result, done());
  * expect(queue).toEqual([]);
@@ -1006,22 +1688,22 @@ export const repeat = (task, schedule, { shouldRepeat = constTrue, onRepeat } =
     }
 };
 /**
- * Runs Tasks until one returns {@link Ok} or all return {@link Err}.
+ * Runs {@link Task}s until one returns {@link Ok} or all return {@link Err}.
  *
- * Use {@link race} to return the first settled Result instead, whether Ok or
- * {@link Err}.
+ * Use {@link race} to return the first settled {@link Result} instead, whether Ok
+ * or {@link Err}.
  *
- * Returns the first {@link Ok} Result. Losing Tasks are aborted. If no Task
- * returns Ok, returns the last Err by input order, regardless of completion
- * order. Other Err results are discarded; use {@link allSettled} when you need
- * every error.
+ * Returns the first {@link Ok} Result. Queued Tasks are not started, and other
+ * running Tasks are aborted. If no Task returns Ok, returns the last Err by
+ * input order, regardless of completion order. Other Err results are discarded;
+ * use {@link allSettled} when you need every error.
  *
  * Sequential by default; pass a `concurrency` option to run more than one Task
  * at a time.
  *
  * Similar to
  * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/any | Promise.any},
- * but races Tasks, returns Result values, and aborts losers.
+ * but runs Tasks, returns Result values, and stops after the first Ok.
  *
  * ### Example
  *
@@ -1033,10 +1715,14 @@ export const repeat = (task, schedule, { shouldRepeat = constTrue, onRepeat } =
  *   ok,
  *   type Result,
  *   type Task,
+ *   type Typed,
  * } from "@evolu/common";
  *
- * const unavailable: Task<string, "Unavailable"> = () =>
- *   err("Unavailable");
+ * const unavailable: Task<string, ServiceUnavailableError> = () =>
+ *   err({ type: "ServiceUnavailable" });
+ *
+ * interface ServiceUnavailableError extends Typed<"ServiceUnavailable"> {}
+ *
  * let fallbackStarted = false;
  * const fallback: Task<string> = () => {
  *   fallbackStarted = true;
@@ -1046,7 +1732,9 @@ export const repeat = (task, schedule, { shouldRepeat = constTrue, onRepeat } =
  * await using run = createRun();
  * const result = await run(any([unavailable, fallback]));
  *
- * expectTypeOf(result).toEqualTypeOf<Result<string, "Unavailable">>();
+ * expectTypeOf(result).toEqualTypeOf<
+ *   Result<string, ServiceUnavailableError>
+ * >();
  * expectOk(result, "fallback");
  * expect(fallbackStarted).toBe(true);
  * ```
@@ -1074,7 +1762,7 @@ export const any = (tasks, options) => async (run) => {
     return lastErr;
 };
 /**
- * Runs Tasks until the first Task settles.
+ * Runs {@link Task}s until the first Task settles.
  *
  * Returns the first Task {@link Result} to settle, whether {@link Ok} or
  * {@link Err}.
@@ -1095,7 +1783,7 @@ export const any = (tasks, options) => async (run) => {
  * arrays whose emptiness is only known at runtime, guard with
  * {@link isNonEmptyArray}:
  *
- * ### Example
+ * ### Runtime arrays
  *
  * ```ts
  * import {
@@ -1114,7 +1802,7 @@ export const any = (tasks, options) => async (run) => {
  * }
  * ```
  *
- * ### Example
+ * ### First settlement
  *
  * ```ts
  * import {
@@ -1157,12 +1845,12 @@ export const race = (tasks) => async (run) => {
     return firstResult;
 };
 /**
- * Runs Tasks until `count` Tasks return {@link Ok} or all Tasks settle.
+ * Runs {@link Task}s until `count` Tasks return {@link Ok} or all Tasks settle.
  *
  * Returns {@link Ok} with Ok values in settlement order, not input order.
- * {@link Err} Results are ignored. When `count` Ok values have settled,
- * remaining Tasks are aborted. If fewer than `count` Tasks return Ok, returns
- * the Ok values that did settle.
+ * {@link Err} {@link Result}s are ignored. When `count` Ok values have settled,
+ * queued Tasks are not started and remaining running Tasks are aborted. If
+ * fewer than `count` Tasks return Ok, returns the Ok values that did settle.
  *
  * Sequential by default; pass a `concurrency` option to run more than one Task
  * at a time. The count uses {@link Int1To100OrPositiveInt}: pass `1` to `100` as
@@ -1178,17 +1866,23 @@ export const race = (tasks) => async (run) => {
  *   ok,
  *   sleep,
  *   type Task,
+ *   type Typed,
  * } from "@evolu/common";
  *
  * let slowCompleted = false;
- * const slow: Task<string, "Failed"> = async (run) => {
+ * const slow: Task<string> = async (run) => {
  *   await run.ok(sleep("10ms"));
  *   slowCompleted = true;
  *   return ok("slow");
  * };
+ * const unavailable: Task<never, ServiceUnavailableError> = () =>
+ *   err({ type: "ServiceUnavailable" });
+ *
+ * interface ServiceUnavailableError extends Typed<"ServiceUnavailable"> {}
+ *
  * const tasks = [
  *   slow,
- *   () => err("Failed" as const),
+ *   unavailable,
  *   () => ok("fast-1"),
  *   () => ok("fast-2"),
  * ] as const;
@@ -1213,11 +1907,12 @@ export const firstN = (tasks, count, options) => async (run) => {
     return ok(values);
 };
 /**
- * Runs Tasks until `count` Tasks settle or all Tasks settle.
+ * Runs {@link Task}s until `count` Tasks settle or all Tasks settle.
  *
  * Returns {@link Ok} with Task {@link Result}s in settlement order, not input
- * order. When `count` Results have settled, remaining Tasks are aborted. If
- * fewer than `count` Tasks settle, returns the Results that did settle.
+ * order. When `count` Results have settled, queued Tasks are not started and
+ * remaining running Tasks are aborted. If fewer than `count` Tasks settle,
+ * returns the Results that did settle.
  *
  * Sequential by default; pass a `concurrency` option to run more than one Task
  * at a time. The count uses {@link Int1To100OrPositiveInt}: pass `1` to `100` as
@@ -1233,25 +1928,27 @@ export const firstN = (tasks, count, options) => async (run) => {
  *   ok,
  *   sleep,
  *   type Task,
+ *   type Typed,
  * } from "@evolu/common";
  *
  * let slowCompleted = false;
- * const slow: Task<string, "Failed"> = async (run) => {
+ * const slow: Task<string> = async (run) => {
  *   await run.ok(sleep("10ms"));
  *   slowCompleted = true;
  *   return ok("slow");
  * };
- * const tasks = [
- *   slow,
- *   () => err("Failed" as const),
- *   () => ok("fast"),
- * ] as const;
+ * const unavailable: Task<never, ServiceUnavailableError> = () =>
+ *   err({ type: "ServiceUnavailable" });
+ *
+ * interface ServiceUnavailableError extends Typed<"ServiceUnavailable"> {}
+ *
+ * const tasks = [slow, unavailable, () => ok("fast")] as const;
  * await using run = createRun();
  *
  * // Err and Ok both count, and Results use settlement order.
  * const result = await run(firstNSettled(tasks, 2, { concurrency: 3 }));
  * expectOk(result, [
- *   { ok: false, error: "Failed" },
+ *   { ok: false, error: { type: "ServiceUnavailable" } },
  *   { ok: true, value: "fast" },
  * ]);
  * expect(slowCompleted).toBe(false);
@@ -1269,26 +1966,27 @@ export const firstNSettled = (tasks, count, options) => async (run) => {
     return ok(results);
 };
 /**
- * Runs Tasks under a concurrency limit and calls `onResult` for each Task
- * {@link Result} as it settles.
+ * Runs {@link Task}s under a concurrency limit and calls `onResult` for each
+ * Task {@link Result} as it settles.
  *
- * `onResult` receives the Result and the original input index; call order is
- * settlement order, not input order. Returning `continue` lets queued Tasks
- * start when capacity is available. Returning `stop` prevents queued Tasks from
- * starting and aborts already-running Tasks through structured Run disposal —
- * `each` still waits for them to settle before returning.
+ * `onResult` receives the {@link Result} and the original input index; call
+ * order is settlement order, not input order. Returning `continue` lets queued
+ * Tasks start when capacity is available. Returning `stop` prevents queued
+ * Tasks from starting and aborts already-running Tasks through structured
+ * {@link Run} disposal — `each` still waits for them to settle before
+ * returning.
  *
  * `each` is the scheduling primitive under the collection helpers. Each one is
  * a small `onResult` policy:
  *
- * | Helper                | Policy                                |
- * | --------------------- | ------------------------------------- |
- * | {@link all}           | Collect values, stop on the first Err |
- * | {@link allSettled}    | Collect every Result, never stop      |
- * | {@link any}           | Stop on the first Ok                  |
- * | {@link race}          | Stop on the first settled Result      |
- * | {@link firstN}        | Stop after n Ok values                |
- * | {@link firstNSettled} | Stop after n Results                  |
+ * | Helper                | Policy                                        |
+ * | --------------------- | --------------------------------------------- |
+ * | {@link all}           | Collect values, stop on the first {@link Err} |
+ * | {@link allSettled}    | Collect every Result, never stop              |
+ * | {@link any}           | Stop on the first {@link Ok}                  |
+ * | {@link race}          | Stop on the first settled Result              |
+ * | {@link firstN}        | Stop after n Ok values                        |
+ * | {@link firstNSettled} | Stop after n Results                          |
  *
  * Use `each` directly to build a collection policy the helpers don't cover. For
  * example, keep the first successful value together with its original input
@@ -1304,6 +2002,7 @@ export const firstNSettled = (tasks, count, options) => async (run) => {
  *   ok,
  *   sleep,
  *   type Task,
+ *   type Typed,
  * } from "@evolu/common";
  *
  * let slowCompleted = false;
@@ -1312,11 +2011,12 @@ export const firstNSettled = (tasks, count, options) => async (run) => {
  *   slowCompleted = true;
  *   return ok("slow");
  * };
- * const tasks = [
- *   slow,
- *   () => err("Unavailable" as const),
- *   () => ok("fast"),
- * ] as const;
+ * const unavailable: Task<never, ServiceUnavailableError> = () =>
+ *   err({ type: "ServiceUnavailable" });
+ *
+ * interface ServiceUnavailableError extends Typed<"ServiceUnavailable"> {}
+ *
+ * const tasks = [slow, unavailable, () => ok("fast")] as const;
  * let first: readonly [string, number] | undefined;
  * await using run = createRun();
  * const result = await run(
@@ -1350,7 +2050,7 @@ export const firstNSettled = (tasks, count, options) => async (run) => {
  * building on `each` preserves diagnostics that a hand-rolled scheduling loop
  * typically loses.
  *
- * @group Concurrency
+ * @group Collection
  */
 export const each = (tasks, onResult, options = {}) => async (run) => {
     const env_1 = { stack: [], error: void 0, hasError: false };
@@ -1445,9 +2145,9 @@ export const prioritized = (priority, task) => withTaskMeta({ priority })(task);
  * Yields execution to the host scheduler.
  *
  * Uses native `scheduler.yield()` when available, `setImmediate` when
- * available, and `setTimeout` elsewhere. Because this is a Task, `await
- * run(yieldNow)` is an explicit abortable checkpoint and is visible in Run
- * monitoring.
+ * available, and `setTimeout` elsewhere. Because this is a {@link Task}, `await
+ * run(yieldNow)` is an explicit abortable checkpoint and is visible in
+ * {@link Run} monitoring.
  *
  * For example, call it periodically in a long-running synchronous loop to let
  * the host process rendering, input, and other scheduled work.
@@ -1519,12 +2219,13 @@ export const yieldNow = async (run) => {
  * interface ServerDep {
  *   readonly port: number;
  * }
+ *
  * interface Server extends AsyncDisposable {}
  *
  * const serverStarted = Promise.withResolvers<void>();
  * let serverStopped = false;
- * const startServer: Task<Server, never, ServerDep> = ({ deps }) => {
- *   expect(deps.port).toBe(3000);
+ * const startServer: Task<Server, never, ServerDep> = (run) => {
+ *   expect(run.deps.port).toBe(3000);
  *   serverStarted.resolve();
  *   return ok({
  *     [Symbol.asyncDispose]: async () => {
@@ -1588,7 +2289,7 @@ export const waitForAbort = async (run) => {
  * Do not wrap a Task that keeps using a resource the caller may release after
  * this wrapper returns, unless the Task reliably observes abort before using
  * that resource. The daemon Task can continue after the caller stops waiting.
- * Later domain `Err` results from the daemon Task are discarded after the
+ * Later domain {@link Err} results from the daemon Task are discarded after the
  * caller stops waiting. Defects from the daemon Task remain visible to the root
  * Run: if it later throws or rejects, the root Run still panics and reports the
  * defect.
@@ -1598,10 +2299,10 @@ export const waitForAbort = async (run) => {
  * to settle, keeping cleanup and late defects inside the caller's lifetime. A
  * Task that ignores abort can keep them waiting.
  *
- * `run.abortable(task)` returns an owned child Fiber and requests abort through
- * that Fiber; `daemon(task)` starts a daemon child and stops waiting when the
- * current Run aborts. {@link unabortable} masks abort for a Task that must
- * finish once started; daemon lets a Task outlive the caller.
+ * `run.abortable(task)` returns an owned child {@link Fiber} and requests abort
+ * through that Fiber; `daemon(task)` starts a daemon child and stops waiting
+ * when the current Run aborts. {@link unabortable} masks abort for a Task that
+ * must finish once started; daemon lets a Task outlive the caller.
  *
  * Because the Task starts with {@link Run.daemon}, a recorded abort request
  * returns AbortError before the Task starts — including a request masked by
@@ -1648,15 +2349,10 @@ export const waitForAbort = async (run) => {
  * import { createRun, ok, type Result, type Task } from "@evolu/common";
  *
  * type ResultValue = string;
- * interface MyError {
- *   readonly type: "MyError";
- * }
- * const createPromiseReturningResult = (): Promise<
- *   Result<ResultValue, MyError>
- * > => Promise.resolve(ok("value"));
+ * const createPromiseReturningResult = (): Promise<Result<ResultValue>> =>
+ *   Promise.resolve(ok("value"));
  *
- * const task: Task<ResultValue, MyError> = () =>
- *   createPromiseReturningResult();
+ * const task: Task<ResultValue> = () => createPromiseReturningResult();
  *
  * await using run = createRun();
  * expectOk(await run(task), "value");
@@ -1669,12 +2365,9 @@ export const waitForAbort = async (run) => {
  * import { ok, type Result, type Task } from "@evolu/common";
  *
  * type ResultValue = string;
- * interface MyError {
- *   readonly type: "MyError";
- * }
  * let promiseStarted = false;
  * const createPromiseReturningResult = (): Promise<
- *   Result<ResultValue, MyError>
+ *   Result<ResultValue>
  * > => {
  *   promiseStarted = true;
  *   return Promise.resolve(ok("value"));
@@ -1682,10 +2375,10 @@ export const waitForAbort = async (run) => {
  *
  * // Wrong: the Promise starts now, before a Run starts the Task.
  * const promise = createPromiseReturningResult();
- * const task: Task<ResultValue, MyError> = () => promise;
+ * const task: Task<ResultValue> = () => promise;
  *
  * expect(promiseStarted).toBe(true);
- * expectTypeOf(task).toEqualTypeOf<Task<ResultValue, MyError>>();
+ * expectTypeOf(task).toEqualTypeOf<Task<ResultValue>>();
  * ```
  *
  * @group Lifetime
@@ -1723,8 +2416,8 @@ export const daemon = (task) => async (run) => {
  * Abort requests are masked while the Task runs, so `run.signal.aborted`
  * remains false inside the Task. This does not force the Task to start after an
  * abort request has already reached its Run; unabortable means the Task is not
- * interrupted once it has started. Disposing the enclosing Run still waits for
- * the Task to settle.
+ * interrupted once it has started. Disposing the enclosing {@link Run} still
+ * waits for the Task to settle.
  *
  * Apply at most one abort behavior helper to a Task: do not wrap the same Task
  * with both unabortable and restore, or apply either helper more than once.
@@ -1736,10 +2429,10 @@ export const daemon = (task) => async (run) => {
  *
  * const commitStarted = Promise.withResolvers<void>();
  * const finishCommit = Promise.withResolvers<void>();
- * const commit: Task<string> = unabortable(async ({ signal }) => {
+ * const commit: Task<string> = unabortable(async (run) => {
  *   commitStarted.resolve();
  *   await finishCommit.promise;
- *   expect(signal.aborted).toBe(false);
+ *   expect(run.signal.aborted).toBe(false);
  *   return ok("committed");
  * });
  *
@@ -1758,8 +2451,8 @@ export const unabortable = /*#__PURE__*/ withTaskMeta({
     abortBehavior: "unabortable",
 });
 /**
- * Like {@link unabortable}, but provides `restore` for child Tasks that should
- * run with the previous abort mask.
+ * Like {@link unabortable}, but provides `restore` for child {@link Task}s that
+ * should run with the previous abort mask.
  *
  * Use this for acquire/use/release flows where acquire and release must finish
  * once started, while use should remain abortable. Child Tasks inherit the mask
@@ -1787,8 +2480,6 @@ export const unabortable = /*#__PURE__*/ withTaskMeta({
  *   type Task,
  * } from "@evolu/common";
  *
- * await using run = createRun();
- *
  * interface Resource {
  *   readonly id: string;
  * }
@@ -1805,13 +2496,14 @@ export const unabortable = /*#__PURE__*/ withTaskMeta({
  * let released = false;
  * const release =
  *   (_resource: Resource): Task<void> =>
- *   ({ signal }) => {
+ *   (run) => {
  *     // Release inherits the mask even after abort was requested.
- *     expect(signal.aborted).toBe(false);
+ *     expect(run.signal.aborted).toBe(false);
  *     released = true;
  *     return ok();
  *   };
  *
+ * await using run = createRun();
  * const fiber = run.abortable(
  *   unabortableMask((restore) => async (run) => {
  *     // Acquire with abort masked.
@@ -1880,6 +2572,7 @@ export const unabortableMask = (fn) => unabortable((run) => {
  *   err,
  *   ok,
  *   type Task,
+ *   type Typed,
  * } from "@evolu/common";
  *
  * interface Connection {
@@ -1890,9 +2583,14 @@ export const unabortableMask = (fn) => unabortable((run) => {
  * const openConnection: Task<Connection> = () =>
  *   ok({ user: "Ada", isAvailable: false });
  * const loadUser =
- *   (connection: Connection): Task<string, "Unavailable"> =>
+ *   (connection: Connection): Task<string, UserUnavailableError> =>
  *   () =>
- *     connection.isAvailable ? ok(connection.user) : err("Unavailable");
+ *     connection.isAvailable
+ *       ? ok(connection.user)
+ *       : err({ type: "UserUnavailable" });
+ *
+ * interface UserUnavailableError extends Typed<"UserUnavailable"> {}
+ *
  * let connectionClosed = false;
  * const closeConnection =
  *   (_connection: Connection): Task<void> =>
@@ -1908,12 +2606,12 @@ export const unabortableMask = (fn) => unabortable((run) => {
  * );
  *
  * await using run = createRun();
- * expectErr(await run(queryUser), "Unavailable");
+ * expectErr(await run(queryUser), { type: "UserUnavailable" });
  * // Release still runs when use returns a domain error.
  * expect(connectionClosed).toBe(true);
  * ```
  *
- * @group Abortability
+ * @group Lifetime
  */
 export const acquireUseRelease = (acquire, use, release) => unabortableMask((restore) => async (run) => {
     const resourceResult = await run(acquire);
@@ -1930,6 +2628,48 @@ export const acquireUseRelease = (acquire, use, release) => unabortableMask((res
 /**
  * Creates a {@link Deferred}.
  *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   createDeferred,
+ *   createRun,
+ *   ok,
+ *   type Result,
+ * } from "@evolu/common";
+ *
+ * await using run = createRun();
+ * const deferred = createDeferred<string>();
+ *
+ * const fiber = run(deferred.task);
+ * expect(deferred.resolve(ok("ready"))).toBe(true);
+ *
+ * const result = await fiber;
+ * expectTypeOf(result).toEqualTypeOf<Result<string>>();
+ * expectOk(result, "ready");
+ *
+ * // A Deferred is one-shot: later resolutions are ignored, and future
+ * // waiters receive the original Result.
+ * expect(deferred.resolve(ok("late"))).toBe(false);
+ * expectOk(await run(deferred.task), "ready");
+ * ```
+ *
+ * ### Aborting a waiter
+ *
+ * ```ts
+ * import { AbortError, createDeferred, createRun } from "@evolu/common";
+ *
+ * await using run = createRun();
+ * const deferred = createDeferred<string>();
+ *
+ * const fiber = run.abortable(deferred.task);
+ * fiber.abort({ type: "NoLongerNeeded" });
+ *
+ * const result = await fiber;
+ * assert(!result.ok);
+ * expect(AbortError.is(result.error)).toBe(true);
+ * ```
+ *
  * @group Concurrency primitives
  */
 export const createDeferred = () => {
@@ -1960,6 +2700,34 @@ export const createDeferred = () => {
 /**
  * Creates a {@link Gate}.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { createGate, createRun, ok, type Task } from "@evolu/common";
+ *
+ * await using run = createRun();
+ * const networkGate = createGate();
+ *
+ * const uploadedItems: Array<string> = [];
+ * const syncOnce =
+ *   (item: string): Task<void> =>
+ *   async (run) => {
+ *     await run.ok(networkGate.wait);
+ *     uploadedItems.push(item);
+ *     return ok();
+ *   };
+ *
+ * const first = run(syncOnce("first"));
+ * const second = run(syncOnce("second"));
+ * expect(uploadedItems).toEqual([]);
+ *
+ * networkGate.open();
+ * expectOk(await first, undefined);
+ * expectOk(await second, undefined);
+ * expect(uploadedItems).toEqual(["first", "second"]);
+ * expect(networkGate.isOpen()).toBe(true);
+ * ```
+ *
  * @group Concurrency primitives
  */
 export const createGate = ({ isOpen = false, } = {}) => {
@@ -1997,6 +2765,45 @@ export const createGate = ({ isOpen = false, } = {}) => {
 /**
  * Creates a {@link Semaphore}.
  *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   createRun,
+ *   createSemaphore,
+ *   getOk,
+ *   ok,
+ *   sleep,
+ *   type Task,
+ * } from "@evolu/common";
+ *
+ * await using run = createRun();
+ *
+ * const semaphore = createSemaphore(2);
+ * let activeSaves = 0;
+ * let maxActiveSaves = 0;
+ *
+ * const saveUser =
+ *   (id: string): Task<string> =>
+ *   async (run) => {
+ *     activeSaves += 1;
+ *     maxActiveSaves = Math.max(maxActiveSaves, activeSaves);
+ *     await run.ok(sleep("10ms"));
+ *     activeSaves -= 1;
+ *     return ok(`saved:${id}`);
+ *   };
+ *
+ * const results = await Promise.all([
+ *   run(semaphore.withPermit(saveUser("1"))),
+ *   run(semaphore.withPermit(saveUser("2"))),
+ *   run(semaphore.withPermit(saveUser("3"))),
+ * ]);
+ *
+ * const savedUsers = results.map(getOk);
+ * expect(savedUsers).toEqual(["saved:1", "saved:2", "saved:3"]);
+ * expect(maxActiveSaves).toBe(2);
+ * ```
+ *
  * @group Concurrency primitives
  */
 export const createSemaphore = (initialPermits, { policy = "fifo", } = {}) => {
@@ -2112,6 +2919,37 @@ export const createSemaphore = (initialPermits, { policy = "fifo", } = {}) => {
 /**
  * Creates a {@link Mutex}.
  *
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   createMutex,
+ *   createRun,
+ *   ok,
+ *   sleep,
+ *   type Task,
+ * } from "@evolu/common";
+ *
+ * const mutex = createMutex();
+ * let balance = 0;
+ * const deposit = (amount: number): Task<void> =>
+ *   mutex.withLock(async (run) => {
+ *     const currentBalance = balance;
+ *     await run.ok(sleep("1ms"));
+ *     balance = currentBalance + amount;
+ *     return ok();
+ *   });
+ *
+ * await using run = createRun();
+ * const [first, second] = await Promise.all([
+ *   run(deposit(2)),
+ *   run(deposit(3)),
+ * ]);
+ * expectOk(first, undefined);
+ * expectOk(second, undefined);
+ * expect(balance).toBe(5);
+ * ```
+ *
  * @group Concurrency primitives
  */
 export const createMutex = () => {
@@ -2163,6 +3001,19 @@ export function createMutexByKey({ lookup = identity, } = {}) {
 /**
  * Creates a {@link MutexRef}.
  *
+ * ### Example
+ *
+ * ```ts
+ * import { createMutexRef, createRun, ok } from "@evolu/common";
+ *
+ * const counter = createMutexRef(0);
+ * const increment = counter.updateAndGet((value) => () => ok(value + 1));
+ *
+ * await using run = createRun();
+ * expectOk(await run(increment), 1);
+ * expectOk(await run(counter.get), 1);
+ * ```
+ *
  * @group Concurrency primitives
  */
 export const createMutexRef = (initialValue) => {
@@ -2209,7 +3060,7 @@ export const createMutexRef = (initialValue) => {
         snapshot: mutex.snapshot,
     };
 };
-// TODO: Add Run observability after Task migration.
+// TODO: Expand Run observability.
 // - Structured logging with levels, inherited log annotations, JSON output,
 //   filtering, and pluggable log sinks.
 // - Tracing spans with names, timing, parent-child relationships, attributes,