@evolu/common 8.4.0 → 8.6.0

package/dist/src/Task.js

@@ -51,43 +51,41 @@ 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.
+ * Structured concurrency organizes running tasks into a tree. Every child
+ * belongs to a parent, a parent waits for its children before it completes, and
+ * abort propagates from parents to descendants. Races and fail-fast control
+ * flow abort siblings that are no longer needed.
  *
  * 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
+ * discipline: someone must remember the `finally` that aborts started tasks and
+ * the await that waits for cleanup. Evolu makes both structural: `run(task)`
+ * registers every child before it starts, and the parent {@link Run} settles
  * only after child cleanup finishes.
  *
- * Evolu models structured concurrency with ordinary JavaScript:
+ * Evolu implements structured concurrency with:
  *
- * - A {@link Task} describes an asynchronous operation and its dependencies.
+ * - A {@link Task} is a function passed to Run that returns an {@link Awaitable}
+ *   {@link Result} and declares 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.
+ * Together, these APIs provide abort, cleanup, defect handling, dependency
+ * injection, monitoring, and resource management.
  *
- * 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.
+ * Tasks return a {@link Result} containing either success or a domain error.
+ * 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 {
+ *   assertOk,
+ *   assertType,
  *   createRun,
  *   err,
  *   ok,
@@ -130,8 +128,8 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * });
  *
  * const result = await run(getUser(user.id));
- * expectTypeOf(result).toEqualTypeOf<Result<User, UserNotFoundError>>();
- * expectOk(result, user);
+ * assertType<Result<User, UserNotFoundError>, typeof result>();
+ * assertOk(result, user);
  * ```
  *
  * In composition roots, prefer the lifecycle API from the matching Evolu
@@ -174,6 +172,8 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *
  * ```ts
  * import {
+ *   assertOk,
+ *   assertType,
  *   createRun,
  *   err,
  *   ok,
@@ -232,13 +232,14 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *
  * await using run = createRun();
  * const result = await run(getUserWithProfile("user-1"));
- * expectTypeOf(result).toEqualTypeOf<
+ * assertType<
  *   Result<
  *     { readonly user: User; readonly profile: Profile },
  *     UserNotFoundError | ProfileNotFoundError
- *   >
+ *   >,
+ *   typeof result
  * >();
- * expectOk(result, {
+ * assertOk(result, {
  *   user: { id: "user-1", profileId: "profile-1" },
  *   profile: { id: "profile-1" },
  * });
@@ -253,10 +254,11 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *
  * {@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:
+ * each attempt and retry recoverable domain errors:
  *
  * ```ts
  * import {
+ *   assertType,
  *   exponential,
  *   fetch,
  *   jitter,
@@ -277,8 +279,9 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *     jitter("100%")(maxDelay("20s")(take(2)(exponential("100ms")))),
  *   );
  *
- * expectTypeOf(fetchWithRetry).returns.toEqualTypeOf<
- *   Task<string, RetryTaskError<FetchError | TimeoutError>>
+ * assertType<
+ *   Task<string, RetryTaskError<FetchError | TimeoutError>>,
+ *   ReturnType<typeof fetchWithRetry>
  * >();
  * ```
  *
@@ -287,7 +290,15 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * Run composed Tasks with a `concurrency` option and {@link all}:
  *
  * ```ts
- * import { all, createRun, ok, sleep, type Task } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertOk,
+ *   all,
+ *   createRun,
+ *   ok,
+ *   sleep,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * await using run = createRun();
  *
@@ -310,8 +321,8 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *
  * // At most 2 concurrent requests.
  * const result = await run(all(urls, fetchUrl, { concurrency: 2 }));
- * expectOk(result, urls);
- * expect(maxActiveRequests).toBe(2);
+ * assertOk(result, urls);
+ * assertEqual(maxActiveRequests, 2);
  * ```
  *
  * Task helpers compose Tasks; concurrency primitives are stateful objects that
@@ -343,7 +354,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * resources, or services shared by all code running inside a Run.
  *
  * ```ts
- * import { createRun, ok, type Task } from "@evolu/common";
+ * import { assertOk, createRun, ok, type Task } from "@evolu/common";
  *
  * interface GreetingFormatter {
  *   readonly format: (name: string) => string;
@@ -368,10 +379,10 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * await using run = createRun({ greetingFormatter: formal });
  *
  * // Root dependencies are inherited.
- * expectOk(await run(greet("Ada")), "Hello, Ada");
+ * assertOk(await run(greet("Ada")), "Hello, Ada");
  *
  * // Child-specific dependencies replace the root's custom dependencies.
- * expectOk(
+ * assertOk(
  *   await run(greet("Ada"), { greetingFormatter: casual }),
  *   "Hi, Ada",
  * );
@@ -422,7 +433,15 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * `undefined` should represent valid absence, not failure.
  *
  * ```ts
- * import { createRun, ok, type Task, type Typed } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   assertTrue,
+ *   createRun,
+ *   ok,
+ *   type Task,
+ *   type Typed,
+ * } from "@evolu/common";
  *
  * interface Socket extends AsyncDisposable {
  *   readonly send: (message: string) => string;
@@ -436,8 +455,9 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * const openSocket: Task<Socket, ConnectionFailedError> = () =>
  *   ok({
  *     send: (message) => message,
- *     [Symbol.asyncDispose]: async () => {
+ *     [Symbol.asyncDispose]: () => {
  *       socketDisposed = true;
+ *       return Promise.resolve();
  *     },
  *   });
  *
@@ -469,16 +489,16 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *
  * await using run = createRun();
  * const result = await run(createConnection);
- * assert(result.ok);
- * expect(socketDisposed).toBe(false);
- * expect(result.value.send("hello")).toBe("hello");
+ * assertTrue(result.ok);
+ * assertFalse(socketDisposed);
+ * assertEqual(result.value.send("hello"), "hello");
  * await result.value[Symbol.asyncDispose]();
- * expect(socketDisposed).toBe(true);
+ * assertTrue(socketDisposed);
  * ```
  *
- * 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.
+ * Use {@link Run.ok} with `await using` when a Task whose error type is `never`
+ * returns a disposable value. Use {@link acquireUseRelease} when acquisition and
+ * release are separate steps rather than a disposable value.
  *
  * ## Awaitable
  *
@@ -491,7 +511,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *
  * 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 plain async function when it 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
@@ -509,7 +529,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * 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
+ * Large CPU-bound computations, 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.
@@ -569,10 +589,10 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * ### 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.
+ * panics, running Tasks are aborted, and the Run tree shuts down. Use
+ * {@link trySync} or {@link tryAsync} to turn recoverable exceptions and Promise
+ * rejections into typed {@link Result} errors. Let unrecoverable failures
+ * propagate as defects.
  *
  * ### Why does a defect panic the whole Run tree?
  *
@@ -630,7 +650,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * each iteration reuses the same stack frame:
  *
  * ```ts
- * import { createRun, ok, type Task } from "@evolu/common";
+ * import { assertOk, createRun, ok, type Task } from "@evolu/common";
  *
  * interface TreeNode {
  *   readonly value: string;
@@ -654,7 +674,7 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  *   };
  *
  * await using run = createRun();
- * expectOk(
+ * assertOk(
  *   await run(
  *     visitTree({
  *       value: "root",
@@ -671,13 +691,6 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
  * 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
@@ -852,7 +865,7 @@ export const createRunDefaultDeps = () => {
  * ### Example
  *
  * ```ts
- * import { createRun, ok, type Task } from "@evolu/common";
+ * import { assertOk, createRun, ok, type Task } from "@evolu/common";
  *
  * interface ConfigDep {
  *   readonly config: { readonly apiUrl: string };
@@ -864,7 +877,7 @@ export const createRunDefaultDeps = () => {
  * await using run = createRun({
  *   config: { apiUrl: "https://api.example.com" },
  * });
- * expectOk(await run(loadApiUrl), "https://api.example.com");
+ * assertOk(await run(loadApiUrl), "https://api.example.com");
  * ```
  *
  * @group Run
@@ -1128,7 +1141,6 @@ const createRunInternal = (deps, parent, rootRun, taskMeta) => {
                 if (taskMeta?.priority && scheduler?.postTask) {
                     result = await scheduler.postTask(() => {
                         startSignal.throwIfAborted();
-                        // eslint-disable-next-line evolu/no-direct-task-call -- The executor invokes the Task with its child Run.
                         return task(taskRun);
                     }, {
                         priority: taskMeta.priority,
@@ -1137,7 +1149,6 @@ const createRunInternal = (deps, parent, rootRun, taskMeta) => {
                 }
                 else {
                     startSignal.throwIfAborted();
-                    // eslint-disable-next-line evolu/no-direct-task-call -- The executor invokes the Task with its child Run.
                     result = await task(taskRun);
                 }
                 // Full Result validation is dev-only; production checks only the
@@ -1286,7 +1297,6 @@ const withTaskMeta = (meta) => (task) => {
     const taskInternal = task;
     assert(meta.abortBehavior === undefined ||
         taskInternal[taskMetaSymbol]?.abortBehavior === undefined, "abort behavior helpers cannot wrap the same Task");
-    // eslint-disable-next-line evolu/no-direct-task-call -- Preserve the wrapped Task's child Run.
     const wrapped = (run) => task(run);
     const taskMeta = taskInternal[taskMetaSymbol];
     wrapped[taskMetaSymbol] = taskMeta ? { ...taskMeta, ...meta } : meta;
@@ -1358,7 +1368,7 @@ const mapInput = (input, fn) => Array.isArray(input)
  * 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
  * stack through this bridge. Prefer native promise APIs and `await` when the
- * wrapped operation already has a promise-shaped API.
+ * wrapped API already returns a Promise.
  *
  * One-shot settlement applies only to `resolve` and `reject`. A synchronous
  * throw from the setup function is a defect that panics the Run tree even after
@@ -1383,14 +1393,23 @@ const mapInput = (input, fn) => Array.isArray(input)
  * ### Example
  *
  * ```ts
- * import { callback, createRun, ok, type Task } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertOk,
+ *   callback,
+ *   createRun,
+ *   ok,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * const listeners = new Set<(message: string) => void>();
  * const subscribe = (
  *   listener: (message: string) => void,
  * ): (() => void) => {
  *   listeners.add(listener);
- *   return () => listeners.delete(listener);
+ *   return () => {
+ *     listeners.delete(listener);
+ *   };
  * };
  * const nextMessage: Task<string> = callback(({ resolve }) =>
  *   subscribe((message) => resolve(ok(message))),
@@ -1398,11 +1417,11 @@ const mapInput = (input, fn) => Array.isArray(input)
  *
  * await using run = createRun();
  * const fiber = run(nextMessage);
- * expect(listeners.size).toBe(1);
+ * assertEqual(listeners.size, 1);
  * for (const listener of listeners) listener("ready");
- * expectOk(await fiber, "ready");
+ * assertOk(await fiber, "ready");
  * // The callback cleanup unsubscribes after settlement.
- * expect(listeners.size).toBe(0);
+ * assertEqual(listeners.size, 0);
  * ```
  *
  * @group Interop
@@ -1426,10 +1445,10 @@ export const callback = (fn) => (run) => {
  * ### Example
  *
  * ```ts
- * import { createRun, sleep } from "@evolu/common";
+ * import { assertOk, createRun, sleep } from "@evolu/common";
  *
  * await using run = createRun();
- * expectOk(await run(sleep("1ms")), undefined);
+ * assertOk(await run(sleep("1ms")), undefined);
  * ```
  *
  * @group Timing
@@ -1451,6 +1470,8 @@ export const sleep = (duration) => callback(({ run: { deps }, resolve }) => {
  *
  * ```ts
  * import {
+ *   assertErr,
+ *   assertType,
  *   createRun,
  *   timeout,
  *   timeoutError,
@@ -1462,8 +1483,8 @@ export const sleep = (duration) => callback(({ run: { deps }, resolve }) => {
  * await using run = createRun();
  *
  * const result = await run(timeout(waitForAbort, "1ms"));
- * expectTypeOf(result).toEqualTypeOf<Result<never, TimeoutError>>();
- * expectErr(result, timeoutError);
+ * assertType<Result<never, TimeoutError>, typeof result>();
+ * assertErr(result, timeoutError);
  * ```
  *
  * @group Timing
@@ -1510,6 +1531,8 @@ export const timeoutError = { type: "TimeoutError" };
  *
  * ```ts
  * import {
+ *   assertErr,
+ *   assertType,
  *   createRun,
  *   err,
  *   recurs,
@@ -1529,10 +1552,11 @@ export const timeoutError = { type: "TimeoutError" };
  *
  * await using run = createRun();
  * const result = await run(fetchWithRetry);
- * expectTypeOf(result).toEqualTypeOf<
- *   Result<string, RetryTaskError<ServiceUnavailableError>>
+ * assertType<
+ *   Result<string, RetryTaskError<ServiceUnavailableError>>,
+ *   typeof result
  * >();
- * expectErr(result, {
+ * assertErr(result, {
  *   type: "RetryError",
  *   attempts: 3,
  *   lastError: { type: "ServiceUnavailable" },
@@ -1543,6 +1567,7 @@ export const timeoutError = { type: "TimeoutError" };
  *
  * ```ts
  * import {
+ *   assertErr,
  *   createRun,
  *   err,
  *   recurs,
@@ -1565,7 +1590,8 @@ export const timeoutError = { type: "TimeoutError" };
  * });
  *
  * await using run = createRun();
- * expectErr(await run(fetchWithRetry), {
+ * const result = await run(fetchWithRetry);
+ * assertErr(result, {
  *   type: "RetryError",
  *   attempts: 1,
  *   lastError: { type: "PermanentFailure" },
@@ -1621,7 +1647,15 @@ export const retry = (task, schedule, { shouldRetry = constTrue, onRetry, } = {}
  * ### Repeating successes
  *
  * ```ts
- * import { createRun, ok, recurs, repeat, type Task } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertOk,
+ *   createRun,
+ *   ok,
+ *   recurs,
+ *   repeat,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * let attempts = 0;
  * const checkStatus: Task<string> = () => {
@@ -1632,14 +1666,16 @@ export const retry = (task, schedule, { shouldRetry = constTrue, onRetry, } = {}
  * const poll = repeat(checkStatus, recurs(3));
  *
  * await using run = createRun();
- * expectOk(await run(poll), "pending");
- * expect(attempts).toBe(4);
+ * assertOk(await run(poll), "pending");
+ * assertEqual(attempts, 4);
  * ```
  *
  * ### Stopping with Done
  *
  * ```ts
  * import {
+ *   assertErr,
+ *   assertEqual,
  *   createRun,
  *   done,
  *   err,
@@ -1662,8 +1698,8 @@ export const retry = (task, schedule, { shouldRetry = constTrue, onRetry, } = {}
  *
  * await using run = createRun();
  * const result = await run(repeat(processQueue, spaced("1ms")));
- * expectErr(result, done());
- * expect(queue).toEqual([]);
+ * assertErr(result, done());
+ * assertEqual(queue, []);
  * ```
  *
  * @group Repetition
@@ -1709,6 +1745,9 @@ export const repeat = (task, schedule, { shouldRepeat = constTrue, onRepeat } =
  *
  * ```ts
  * import {
+ *   assertOk,
+ *   assertType,
+ *   assertTrue,
  *   any,
  *   createRun,
  *   err,
@@ -1732,11 +1771,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, ServiceUnavailableError>
- * >();
- * expectOk(result, "fallback");
- * expect(fallbackStarted).toBe(true);
+ * assertType<Result<string, ServiceUnavailableError>, typeof result>();
+ * assertOk(result, "fallback");
+ * assertTrue(fallbackStarted);
  * ```
  *
  * @group Racing
@@ -1787,6 +1824,7 @@ export const any = (tasks, options) => async (run) => {
  *
  * ```ts
  * import {
+ *   assertOk,
  *   createRun,
  *   isNonEmptyArray,
  *   ok,
@@ -1798,7 +1836,7 @@ export const any = (tasks, options) => async (run) => {
  * await using run = createRun();
  * if (isNonEmptyArray(tasks)) {
  *   const result = await run(race(tasks));
- *   expectOk(result, "first");
+ *   assertOk(result, "first");
  * }
  * ```
  *
@@ -1806,6 +1844,9 @@ export const any = (tasks, options) => async (run) => {
  *
  * ```ts
  * import {
+ *   assertFalse,
+ *   assertOk,
+ *   assertType,
  *   createRun,
  *   ok,
  *   race,
@@ -1827,9 +1868,9 @@ export const any = (tasks, options) => async (run) => {
  * // Input order does not matter: the first settled Result wins, and the
  * // still-running loser is aborted.
  * const result = await run(race([slow, fast]));
- * expectTypeOf(result).toEqualTypeOf<Result<string>>();
- * expectOk(result, "fast");
- * expect(slowCompleted).toBe(false);
+ * assertType<Result<string>, typeof result>();
+ * assertOk(result, "fast");
+ * assertFalse(slowCompleted);
  * ```
  *
  * @group Racing
@@ -1860,6 +1901,8 @@ export const race = (tasks) => async (run) => {
  *
  * ```ts
  * import {
+ *   assertFalse,
+ *   assertOk,
  *   createRun,
  *   err,
  *   firstN,
@@ -1890,8 +1933,8 @@ export const race = (tasks) => async (run) => {
  *
  * // Errs do not count. After two Ok values settle, the slow Task is aborted.
  * const result = await run(firstN(tasks, 2, { concurrency: 4 }));
- * expectOk(result, ["fast-1", "fast-2"]);
- * expect(slowCompleted).toBe(false);
+ * assertOk(result, ["fast-1", "fast-2"]);
+ * assertFalse(slowCompleted);
  * ```
  *
  * @group Racing
@@ -1922,6 +1965,8 @@ export const firstN = (tasks, count, options) => async (run) => {
  *
  * ```ts
  * import {
+ *   assertFalse,
+ *   assertOk,
  *   createRun,
  *   err,
  *   firstNSettled,
@@ -1947,11 +1992,11 @@ export const firstN = (tasks, count, options) => async (run) => {
  *
  * // Err and Ok both count, and Results use settlement order.
  * const result = await run(firstNSettled(tasks, 2, { concurrency: 3 }));
- * expectOk(result, [
+ * assertOk(result, [
  *   { ok: false, error: { type: "ServiceUnavailable" } },
  *   { ok: true, value: "fast" },
  * ]);
- * expect(slowCompleted).toBe(false);
+ * assertFalse(slowCompleted);
  * ```
  *
  * @group Racing
@@ -1996,6 +2041,9 @@ export const firstNSettled = (tasks, count, options) => async (run) => {
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   assertOk,
  *   createRun,
  *   each,
  *   err,
@@ -2031,9 +2079,9 @@ export const firstNSettled = (tasks, count, options) => async (run) => {
  *   ),
  * );
  *
- * expectOk(result, undefined);
- * expect(first).toEqual(["fast", 2]);
- * expect(slowCompleted).toBe(false);
+ * assertOk(result, undefined);
+ * assertEqual(first, ["fast", 2]);
+ * assertFalse(slowCompleted);
  * ```
  *
  * `onResult` is a synchronous scheduling decision, not a place to do work. It
@@ -2078,7 +2126,7 @@ export const each = (tasks, onResult, options = {}) => async (run) => {
                     const index = nextIndex;
                     nextIndex += 1;
                     const result = await run(tasks[index]);
-                    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- stopped can flip across the await via sibling workers
+                    // stopped can flip across the await via sibling workers.
                     if (stopped)
                         break;
                     run.signal.throwIfAborted();
@@ -2097,6 +2145,7 @@ export const each = (tasks, onResult, options = {}) => async (run) => {
             active -= 1;
             if (active === 0)
                 wake.resolve();
+            // oxlint-disable-next-line typescript/return-await -- StackTrace.test.ts measures this direct await edge in the worker topology.
             return await parked;
         };
         await Promise.race([
@@ -2129,13 +2178,19 @@ export const each = (tasks, onResult, options = {}) => async (run) => {
  * ### Example
  *
  * ```ts
- * import { createRun, ok, prioritized, type Task } from "@evolu/common";
+ * import {
+ *   assertOk,
+ *   createRun,
+ *   ok,
+ *   prioritized,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * const rebuildSearchIndex: Task<string> = () => ok("indexed");
  * const backgroundIndexing = prioritized("background", rebuildSearchIndex);
  *
  * await using run = createRun();
- * expectOk(await run(backgroundIndexing), "indexed");
+ * assertOk(await run(backgroundIndexing), "indexed");
  * ```
  *
  * @group Scheduling
@@ -2155,7 +2210,13 @@ export const prioritized = (priority, task) => withTaskMeta({ priority })(task);
  * ### Example
  *
  * ```ts
- * import { createRun, ok, yieldNow, type Task } from "@evolu/common";
+ * import {
+ *   assertOk,
+ *   createRun,
+ *   ok,
+ *   yieldNow,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * const sumTo =
  *   (count: number): Task<number> =>
@@ -2171,7 +2232,7 @@ export const prioritized = (priority, task) => withTaskMeta({ priority })(task);
  *   };
  *
  * await using run = createRun();
- * expectOk(await run(sumTo(1001)), 500500);
+ * assertOk(await run(sumTo(1001)), 500500);
  * ```
  *
  * @group Scheduling
@@ -2197,7 +2258,6 @@ export const yieldNow = async (run) => {
     run.signal.throwIfAborted();
     return ok();
 };
-// Abortability
 /**
  * Waits until the current {@link Run} aborts, then rejects with its
  * {@link AbortError}.
@@ -2209,6 +2269,10 @@ export const yieldNow = async (run) => {
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   assertType,
+ *   assertTrue,
  *   AbortError,
  *   createRun,
  *   ok,
@@ -2225,23 +2289,22 @@ export const yieldNow = async (run) => {
  * const serverStarted = Promise.withResolvers<void>();
  * let serverStopped = false;
  * const startServer: Task<Server, never, ServerDep> = (run) => {
- *   expect(run.deps.port).toBe(3000);
+ *   assertEqual(run.deps.port, 3000);
  *   serverStarted.resolve();
  *   return ok({
- *     [Symbol.asyncDispose]: async () => {
+ *     [Symbol.asyncDispose]: () => {
  *       serverStopped = true;
+ *       return Promise.resolve();
  *     },
  *   });
  * };
  *
  * const serve = (): Task<never, never, ServerDep> => async (run) => {
- *   await using server = await run.ok(startServer);
+ *   await using _ = await run.ok(startServer);
  *   return await run(waitForAbort);
  * };
  *
- * expectTypeOf(serve).returns.toEqualTypeOf<
- *   Task<never, never, ServerDep>
- * >();
+ * assertType<Task<never, never, ServerDep>, ReturnType<typeof serve>>();
  *
  * await using run = createRun();
  * const fiber = run.abortable(serve(), { port: 3000 });
@@ -2249,9 +2312,9 @@ export const yieldNow = async (run) => {
  * fiber.abort();
  *
  * const result = await fiber;
- * assert(!result.ok);
- * expect(AbortError.is(result.error)).toBe(true);
- * expect(serverStopped).toBe(true);
+ * assertFalse(result.ok);
+ * assertTrue(AbortError.is(result.error));
+ * assertTrue(serverStopped);
  * ```
  *
  * @group Abortability
@@ -2281,8 +2344,8 @@ export const waitForAbort = async (run) => {
  * execution. The daemon Task continues under root Run ownership until it
  * settles, observes abort, or the root Run is disposed.
  *
- * This is not a replacement for direct {@link AbortSignal} support in operations
- * that can observe abort, such as {@link fetch}, timers that accept a signal, or
+ * This is not a replacement for direct {@link AbortSignal} support in APIs that
+ * can observe abort, such as {@link fetch}, timers that accept a signal, or
  * callback APIs that accept a signal. Use it as an escape hatch for Tasks that
  * ignore abort when an abort request must stop waiting immediately.
  *
@@ -2315,6 +2378,9 @@ export const waitForAbort = async (run) => {
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   assertTrue,
  *   createRun,
  *   daemon,
  *   ok,
@@ -2335,18 +2401,24 @@ export const waitForAbort = async (run) => {
  * {
  *   await using run = createRun();
  *   const result = await run(timeout(daemon(taskNotUsingAbort), "1ms"));
- *   assert(!result.ok);
- *   expect(result.error.type).toBe("TimeoutError");
- *   expect(finished).toBe(false);
+ *   assertFalse(result.ok);
+ *   assertEqual(result.error.type, "TimeoutError");
+ *   assertFalse(finished);
  *   finishTask();
  * }
- * expect(finished).toBe(true);
+ * assertTrue(finished);
  * ```
  *
- * Promise-producing operations should start inside the Task, not before it.
+ * Promise-returning functions should be called inside the Task, not before it.
  *
  * ```ts
- * import { createRun, ok, type Result, type Task } from "@evolu/common";
+ * import {
+ *   assertOk,
+ *   createRun,
+ *   ok,
+ *   type Result,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * type ResultValue = string;
  * const createPromiseReturningResult = (): Promise<Result<ResultValue>> =>
@@ -2355,14 +2427,20 @@ export const waitForAbort = async (run) => {
  * const task: Task<ResultValue> = () => createPromiseReturningResult();
  *
  * await using run = createRun();
- * expectOk(await run(task), "value");
+ * assertOk(await run(task), "value");
  * ```
  *
  * Do not reuse an already-running Promise. It started outside the Task, so the
  * Run cannot own its lifetime or request abort before it begins.
  *
  * ```ts
- * import { ok, type Result, type Task } from "@evolu/common";
+ * import {
+ *   assertType,
+ *   assertTrue,
+ *   ok,
+ *   type Result,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * type ResultValue = string;
  * let promiseStarted = false;
@@ -2377,8 +2455,8 @@ export const waitForAbort = async (run) => {
  * const promise = createPromiseReturningResult();
  * const task: Task<ResultValue> = () => promise;
  *
- * expect(promiseStarted).toBe(true);
- * expectTypeOf(task).toEqualTypeOf<Task<ResultValue>>();
+ * assertTrue(promiseStarted);
+ * assertType<Task<ResultValue>, typeof task>();
  * ```
  *
  * @group Lifetime
@@ -2425,14 +2503,21 @@ export const daemon = (task) => async (run) => {
  * ### Example
  *
  * ```ts
- * import { createRun, ok, unabortable, type Task } from "@evolu/common";
+ * import {
+ *   assertFalse,
+ *   assertOk,
+ *   createRun,
+ *   ok,
+ *   unabortable,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * const commitStarted = Promise.withResolvers<void>();
  * const finishCommit = Promise.withResolvers<void>();
  * const commit: Task<string> = unabortable(async (run) => {
  *   commitStarted.resolve();
  *   await finishCommit.promise;
- *   expect(run.signal.aborted).toBe(false);
+ *   assertFalse(run.signal.aborted);
  *   return ok("committed");
  * });
  *
@@ -2442,7 +2527,7 @@ export const daemon = (task) => async (run) => {
  * fiber.abort();
  * finishCommit.resolve();
  *
- * expectOk(await fiber, "committed");
+ * assertOk(await fiber, "committed");
  * ```
  *
  * @group Abortability
@@ -2460,7 +2545,7 @@ export const unabortable = /*#__PURE__*/ withTaskMeta({
  *
  * An abort request before the mask Task starts prevents entering the mask. Once
  * the body starts, plain child Tasks inherit the mask, so acquire and release
- * can run after abort. Put release operations directly in the original mask's
+ * can run after abort. Start release Tasks directly in the original mask's
  * `finally`; do not wrap release in a nested `unabortableMask`, which is a new
  * critical-section entry and may not start after abort.
  *
@@ -2472,6 +2557,9 @@ export const unabortable = /*#__PURE__*/ withTaskMeta({
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   assertTrue,
  *   AbortError,
  *   createRun,
  *   ok,
@@ -2488,17 +2576,17 @@ export const unabortable = /*#__PURE__*/ withTaskMeta({
  * const operationStarted = Promise.withResolvers<void>();
  * const operate =
  *   (resource: Resource): Task<never> =>
- *   async (run) => {
- *     expect(resource.id).toBe("resource-1");
+ *   (run) => {
+ *     assertEqual(resource.id, "resource-1");
  *     operationStarted.resolve();
- *     return await run(waitForAbort);
+ *     return run(waitForAbort);
  *   };
  * let released = false;
  * const release =
  *   (_resource: Resource): Task<void> =>
  *   (run) => {
  *     // Release inherits the mask even after abort was requested.
- *     expect(run.signal.aborted).toBe(false);
+ *     assertFalse(run.signal.aborted);
  *     released = true;
  *     return ok();
  *   };
@@ -2522,9 +2610,9 @@ export const unabortable = /*#__PURE__*/ withTaskMeta({
  * await operationStarted.promise;
  * fiber.abort();
  * const result = await fiber;
- * assert(!result.ok);
- * expect(AbortError.is(result.error)).toBe(true);
- * expect(released).toBe(true);
+ * assertFalse(result.ok);
+ * assertTrue(AbortError.is(result.error));
+ * assertTrue(released);
  * ```
  *
  * @group Abortability
@@ -2534,7 +2622,7 @@ export const unabortableMask = (fn) => unabortable((run) => {
     // Only verifies the Run is masked. A direct call inside an already masked
     // Run passes undetected; direct calls bypass Run semantics by design.
     assert(runInternal.abortMask > abortableMask, "unabortableMask requires a masked Run; use run(task), not a direct call");
-    const restoreToken = Symbol();
+    const restoreToken = Symbol("restore");
     // The token is local to this Task Run; descendant Runs inherit the token
     // set so helpers can receive restore while the mask Task is alive.
     // Each set is bounded by its Run lifetime and is intentionally not pruned.
@@ -2560,13 +2648,15 @@ export const unabortableMask = (fn) => unabortable((run) => {
  * Prefer native `using`, `await using`, or {@link AsyncDisposableStack} for
  * owned values that implement {@link Disposable} or {@link AsyncDisposable}. Use
  * `acquireUseRelease` when acquisition must be balanced with a separate release
- * operation, such as unlocking, returning a pooled value, releasing a lease, or
+ * step, such as unlocking, returning a pooled value, releasing a lease, or
  * logging out of a session.
  *
  * ### Example
  *
  * ```ts
  * import {
+ *   assertErr,
+ *   assertTrue,
  *   acquireUseRelease,
  *   createRun,
  *   err,
@@ -2606,9 +2696,9 @@ export const unabortableMask = (fn) => unabortable((run) => {
  * );
  *
  * await using run = createRun();
- * expectErr(await run(queryUser), { type: "UserUnavailable" });
+ * assertErr(await run(queryUser), { type: "UserUnavailable" });
  * // Release still runs when use returns a domain error.
- * expect(connectionClosed).toBe(true);
+ * assertTrue(connectionClosed);
  * ```
  *
  * @group Lifetime
@@ -2618,7 +2708,7 @@ export const acquireUseRelease = (acquire, use, release) => unabortableMask((res
     if (!resourceResult.ok)
         return resourceResult;
     try {
-        // eslint-disable-next-line react-hooks/rules-of-hooks -- `use` is an acquireUseRelease callback, not a React Hook.
+        // oxlint-disable-next-line react/rules-of-hooks -- `use` is an acquireUseRelease callback, not a React Hook.
         return await run(restore(use(resourceResult.value)));
     }
     finally {
@@ -2632,6 +2722,10 @@ export const acquireUseRelease = (acquire, use, release) => unabortableMask((res
  *
  * ```ts
  * import {
+ *   assertFalse,
+ *   assertOk,
+ *   assertType,
+ *   assertTrue,
  *   createDeferred,
  *   createRun,
  *   ok,
@@ -2642,22 +2736,28 @@ export const acquireUseRelease = (acquire, use, release) => unabortableMask((res
  * const deferred = createDeferred<string>();
  *
  * const fiber = run(deferred.task);
- * expect(deferred.resolve(ok("ready"))).toBe(true);
+ * assertTrue(deferred.resolve(ok("ready")));
  *
  * const result = await fiber;
- * expectTypeOf(result).toEqualTypeOf<Result<string>>();
- * expectOk(result, "ready");
+ * assertType<Result<string>, typeof result>();
+ * assertOk(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");
+ * assertFalse(deferred.resolve(ok("late")));
+ * assertOk(await run(deferred.task), "ready");
  * ```
  *
  * ### Aborting a waiter
  *
  * ```ts
- * import { AbortError, createDeferred, createRun } from "@evolu/common";
+ * import {
+ *   assertFalse,
+ *   assertTrue,
+ *   AbortError,
+ *   createDeferred,
+ *   createRun,
+ * } from "@evolu/common";
  *
  * await using run = createRun();
  * const deferred = createDeferred<string>();
@@ -2666,8 +2766,8 @@ export const acquireUseRelease = (acquire, use, release) => unabortableMask((res
  * fiber.abort({ type: "NoLongerNeeded" });
  *
  * const result = await fiber;
- * assert(!result.ok);
- * expect(AbortError.is(result.error)).toBe(true);
+ * assertFalse(result.ok);
+ * assertTrue(AbortError.is(result.error));
  * ```
  *
  * @group Concurrency primitives
@@ -2703,7 +2803,15 @@ export const createDeferred = () => {
  * ### Example
  *
  * ```ts
- * import { createGate, createRun, ok, type Task } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertOk,
+ *   assertTrue,
+ *   createGate,
+ *   createRun,
+ *   ok,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * await using run = createRun();
  * const networkGate = createGate();
@@ -2719,13 +2827,13 @@ export const createDeferred = () => {
  *
  * const first = run(syncOnce("first"));
  * const second = run(syncOnce("second"));
- * expect(uploadedItems).toEqual([]);
+ * assertEqual(uploadedItems, []);
  *
  * networkGate.open();
- * expectOk(await first, undefined);
- * expectOk(await second, undefined);
- * expect(uploadedItems).toEqual(["first", "second"]);
- * expect(networkGate.isOpen()).toBe(true);
+ * assertOk(await first, undefined);
+ * assertOk(await second, undefined);
+ * assertEqual(uploadedItems, ["first", "second"]);
+ * assertTrue(networkGate.isOpen());
  * ```
  *
  * @group Concurrency primitives
@@ -2736,7 +2844,6 @@ export const createGate = ({ isOpen = false, } = {}) => {
         deferred.resolve(ok());
     return {
         // Direct same-Run delegation is intentional so wait observes the current deferred.
-        // eslint-disable-next-line evolu/no-direct-task-call
         wait: (run) => deferred.task(run),
         open: () => {
             if (isOpen)
@@ -2769,6 +2876,7 @@ export const createGate = ({ isOpen = false, } = {}) => {
  *
  * ```ts
  * import {
+ *   assertEqual,
  *   createRun,
  *   createSemaphore,
  *   getOk,
@@ -2800,8 +2908,8 @@ export const createGate = ({ isOpen = false, } = {}) => {
  * ]);
  *
  * const savedUsers = results.map(getOk);
- * expect(savedUsers).toEqual(["saved:1", "saved:2", "saved:3"]);
- * expect(maxActiveSaves).toBe(2);
+ * assertEqual(savedUsers, ["saved:1", "saved:2", "saved:3"]);
+ * assertEqual(maxActiveSaves, 2);
  * ```
  *
  * @group Concurrency primitives
@@ -2923,6 +3031,8 @@ export const createSemaphore = (initialPermits, { policy = "fifo", } = {}) => {
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertOk,
  *   createMutex,
  *   createRun,
  *   ok,
@@ -2945,9 +3055,9 @@ export const createSemaphore = (initialPermits, { policy = "fifo", } = {}) => {
  *   run(deposit(2)),
  *   run(deposit(3)),
  * ]);
- * expectOk(first, undefined);
- * expectOk(second, undefined);
- * expect(balance).toBe(5);
+ * assertOk(first, undefined);
+ * assertOk(second, undefined);
+ * assertEqual(balance, 5);
  * ```
  *
  * @group Concurrency primitives
@@ -3004,14 +3114,14 @@ export function createMutexByKey({ lookup = identity, } = {}) {
  * ### Example
  *
  * ```ts
- * import { createMutexRef, createRun, ok } from "@evolu/common";
+ * import { assertOk, 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);
+ * assertOk(await run(increment), 1);
+ * assertOk(await run(counter.get), 1);
  * ```
  *
  * @group Concurrency primitives
@@ -3065,7 +3175,7 @@ export const createMutexRef = (initialValue) => {
 //   filtering, and pluggable log sinks.
 // - Tracing spans with names, timing, parent-child relationships, attributes,
 //   error status, and helpers for annotating the current or child spans.
-// - Metrics for counters, gauges, histograms, and operation durations.
+// - Metrics for counters, gauges, histograms, and Task execution durations.
 // - Resource metadata for service name, service version, deployment
 //   environment, and user-provided attributes.
 // - Exporters for production telemetry backends, including OTLP-compatible
@@ -3078,5 +3188,5 @@ export const createMutexRef = (initialValue) => {
 // - Run labels and structured annotations for rendering useful snapshot trees
 //   instead of anonymous ids.
 // - Snapshot and trace views should preserve ownership boundaries, so reusable
-//   resources and long-lived operations appear as labeled subtrees instead of
-//   unrelated child operations.
+//   resources and long-lived Runs appear as labeled subtrees instead of
+//   unrelated child Runs.