@evolu/common 8.4.0 → 8.6.0

package/dist/src/Task.d.ts

@@ -1,41 +1,39 @@
 /**
- * ## 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,
@@ -78,8 +76,8 @@
  * });
  *
  * 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
@@ -122,6 +120,8 @@
  *
  * ```ts
  * import {
+ *   assertOk,
+ *   assertType,
  *   createRun,
  *   err,
  *   ok,
@@ -180,13 +180,14 @@
  *
  * 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" },
  * });
@@ -201,10 +202,11 @@
  *
  * {@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,
@@ -225,8 +227,9 @@
  *     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>
  * >();
  * ```
  *
@@ -235,7 +238,15 @@
  * 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();
  *
@@ -258,8 +269,8 @@
  *
  * // 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
@@ -291,7 +302,7 @@
  * 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;
@@ -316,10 +327,10 @@
  * 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",
  * );
@@ -370,7 +381,15 @@
  * `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;
@@ -384,8 +403,9 @@
  * const openSocket: Task<Socket, ConnectionFailedError> = () =>
  *   ok({
  *     send: (message) => message,
- *     [Symbol.asyncDispose]: async () => {
+ *     [Symbol.asyncDispose]: () => {
  *       socketDisposed = true;
+ *       return Promise.resolve();
  *     },
  *   });
  *
@@ -417,16 +437,16 @@
  *
  * 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
  *
@@ -439,7 +459,7 @@
  *
  * 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
@@ -457,7 +477,7 @@
  * 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.
@@ -517,10 +537,10 @@
  * ### 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?
  *
@@ -578,7 +598,7 @@
  * 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;
@@ -602,7 +622,7 @@
  *   };
  *
  * await using run = createRun();
- * expectOk(
+ * assertOk(
  *   await run(
  *     visitTree({
  *       value: "root",
@@ -619,13 +639,6 @@
  * 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
@@ -662,13 +675,89 @@ import { type Millis, type PositiveDuration, type TimeDep, type TestTimeDep } fr
 import { type InferType, NonNegativeInt, PositiveInt, String, Unknown, UnknownResult, type Id, type ObjectType, type RecordType, type Typed, type TypedType } from "./Type.ts";
 import type { Awaitable, ParameterIntersection, Predicate } from "./Types.ts";
 /**
- * An operation run by {@link Run} that returns a {@link Result} synchronously or
- * asynchronously and declares its dependencies through `D`.
- *
- * Its return type is {@link Awaitable}.
+ * A function passed to {@link Run} that returns an {@link Awaitable}
+ * {@link Result} and declares its dependencies through `D`.
  *
  * See the {@link @evolu/common!Task | Task overview}.
  *
+ * ### Example
+ *
+ * A Task that can't fail with a domain error:
+ *
+ * ```ts
+ * import {
+ *   assertEqual,
+ *   assertOk,
+ *   createRun,
+ *   ok,
+ *   type Task,
+ * } from "@evolu/common";
+ *
+ * const greet: Task<string> = () => ok("Hello!");
+ * const main: Task<string> = (run) => run(greet);
+ *
+ * await using run = createRun();
+ * assertOk(await run(main), "Hello!");
+ *
+ * // Without domain errors, `run.ok` returns the Ok value.
+ * assertEqual(await run.ok(main), "Hello!");
+ * ```
+ *
+ * A Task that can fail with a domain error:
+ *
+ * ```ts
+ * import {
+ *   assertErr,
+ *   createRun,
+ *   err,
+ *   type Task,
+ *   type Typed,
+ * } from "@evolu/common";
+ *
+ * const findUser =
+ *   (id: string): Task<string, UserNotFoundError> =>
+ *   () =>
+ *     err({ type: "UserNotFound", id });
+ *
+ * interface UserNotFoundError extends Typed<"UserNotFound"> {
+ *   readonly id: string;
+ * }
+ *
+ * await using run = createRun();
+ * assertErr(await run(findUser("user-1")), {
+ *   type: "UserNotFound",
+ *   id: "user-1",
+ * });
+ * ```
+ *
+ * A Task with dependencies:
+ *
+ * ```ts
+ * import { assertOk, createRun, ok, type Task } from "@evolu/common";
+ *
+ * interface Config {
+ *   readonly greeting: string;
+ * }
+ *
+ * interface ConfigDep {
+ *   readonly config: Config;
+ * }
+ *
+ * const greet: Task<string, never, ConfigDep> = (run) =>
+ *   ok(`${run.deps.config.greeting}!`);
+ *
+ * const config: Config = { greeting: "Hello" };
+ * await using run = createRun({ config });
+ * assertOk(await run(greet), "Hello!");
+ * ```
+ *
+ * Start Tasks with `run(task)`, as shown above.
+ *
+ * A Task can also be called directly as `task(run)`, but this is rarely needed.
+ * The call executes the Task inline in the current Run, as if its body were
+ * part of the parent Task, so it does not create a child Run. This is mainly
+ * useful for Task composition helpers.
+ *
  * @group Core
  */
 export type Task<T, E = never, D = unknown> = (run: Run<D>) => Awaitable<Result<T, E>>;
@@ -794,7 +883,13 @@ export interface Run<D = unknown> {
      * ### Example
      *
      * ```ts
-     * import { createRun, ok, type Task } from "@evolu/common";
+     * import {
+     *   assertSame,
+     *   assertOk,
+     *   createRun,
+     *   ok,
+     *   type Task,
+     * } from "@evolu/common";
      *
      * interface Db {
      *   readonly name: string;
@@ -807,16 +902,23 @@ export interface Run<D = unknown> {
      * const db: Db = { name: "main" };
      * const loadUser: Task<string> = () => ok("Ada");
      * const saveUser: Task<void, never, DbDep> = (run) => {
-     *   expect(run.deps.db).toBe(db);
+     *   assertSame(run.deps.db, db);
      *   return ok();
      * };
      *
      * await using run = createRun({ db });
      * const userResult = await run(loadUser);
      * const savedResult = await run(saveUser);
-     * expectOk(userResult, "Ada");
-     * expectOk(savedResult, undefined);
+     * assertOk(userResult, "Ada");
+     * assertOk(savedResult, undefined);
      * ```
+     *
+     * Start Tasks with `run(task)`, as shown above.
+     *
+     * A Task can also be called directly as `task(run)`, but this is rarely
+     * needed. The call executes the Task inline in the current Run, as if its
+     * body were part of the parent Task, so it does not create a child Run. This
+     * is mainly useful for Task composition helpers.
      */
     <T, E>(task: Task<T, E, D>): Fiber<T, E, D>;
     /**
@@ -837,7 +939,13 @@ export interface Run<D = unknown> {
      * ### Example
      *
      * ```ts
-     * import { createRun, ok, type Task, type Typed } from "@evolu/common";
+     * import {
+     *   assertEqual,
+     *   createRun,
+     *   ok,
+     *   type Task,
+     *   type Typed,
+     * } from "@evolu/common";
      *
      * const loadConfig: Task<string, ConfigInvalidError> = () =>
      *   ok("config");
@@ -845,7 +953,7 @@ export interface Run<D = unknown> {
      * interface ConfigInvalidError extends Typed<"ConfigInvalid"> {}
      *
      * await using run = createRun();
-     * expect(await run.orThrow(loadConfig)).toBe("config");
+     * assertEqual(await run.orThrow(loadConfig), "config");
      * ```
      */
     readonly orThrow: {
@@ -861,7 +969,13 @@ export interface Run<D = unknown> {
      * ### Example
      *
      * ```ts
-     * import { createRun, ok, type Task } from "@evolu/common";
+     * import {
+     *   assertEqual,
+     *   assertTrue,
+     *   createRun,
+     *   ok,
+     *   type Task,
+     * } from "@evolu/common";
      *
      * interface Resource extends AsyncDisposable {
      *   readonly value: string;
@@ -871,17 +985,18 @@ export interface Run<D = unknown> {
      * const openResource: Task<Resource> = () =>
      *   ok({
      *     value: "resource",
-     *     [Symbol.asyncDispose]: async () => {
+     *     [Symbol.asyncDispose]: () => {
      *       disposed = true;
+     *       return Promise.resolve();
      *     },
      *   });
      *
      * await using run = createRun();
      * {
      *   await using resource = await run.ok(openResource);
-     *   expect(resource.value).toBe("resource");
+     *   assertEqual(resource.value, "resource");
      * }
-     * expect(disposed).toBe(true);
+     * assertTrue(disposed);
      * ```
      */
     readonly ok: {
@@ -906,6 +1021,9 @@ export interface Run<D = unknown> {
      *
      * ```ts
      * import {
+     *   assertFalse,
+     *   assertType,
+     *   assertTrue,
      *   AbortError,
      *   createRun,
      *   ok,
@@ -926,13 +1044,11 @@ export interface Run<D = unknown> {
      *
      * await using run = createRun();
      * const fiber = run.abortable(loadUser, { db });
-     * expectTypeOf(fiber).toEqualTypeOf<
-     *   AbortableFiber<string, never, DbDep>
-     * >();
+     * assertType<AbortableFiber<string, never, DbDep>, typeof fiber>();
      * fiber.abort();
      * const userResult = await fiber;
-     * assert(!userResult.ok);
-     * expect(AbortError.is(userResult.error)).toBe(true);
+     * assertFalse(userResult.ok);
+     * assertTrue(AbortError.is(userResult.error));
      * ```
      */
     readonly abortable: {
@@ -968,35 +1084,45 @@ export interface Run<D = unknown> {
      * ### Abort masks
      *
      * ```ts
-     * import { createRun, ok, unabortable, type Task } from "@evolu/common";
+     * import {
+     *   assertEqual,
+     *   assertOk,
+     *   assertTrue,
+     *   createRun,
+     *   ok,
+     *   unabortable,
+     *   type Task,
+     * } from "@evolu/common";
      *
      * const syncUsers: Task<string> = () => ok("synced");
      * const syncParent = unabortable(async (run) => {
-     *   expect(run.snapshot().abortMask).toBe(1);
+     *   assertEqual(run.snapshot().abortMask, 1);
      *
      *   // Plain daemon — the caller's mask does not follow it, so abort
      *   // requests are observed.
      *   const fiber = run.daemon(syncUsers);
-     *   expect(fiber.run.snapshot().abortMask).toBe(0);
+     *   assertEqual(fiber.run.snapshot().abortMask, 0);
      *
      *   // Explicitly masked daemon — finishes once started.
      *   const maskedFiber = run.daemon(unabortable(syncUsers));
-     *   expect(maskedFiber.run.snapshot().abortMask).toBe(1);
+     *   assertEqual(maskedFiber.run.snapshot().abortMask, 1);
      *   const firstResult = await fiber;
      *   const secondResult = await maskedFiber;
-     *   assert(firstResult.ok);
-     *   assert(secondResult.ok);
+     *   assertTrue(firstResult.ok);
+     *   assertTrue(secondResult.ok);
      *   return ok([firstResult.value, secondResult.value] as const);
      * });
      *
      * await using run = createRun();
-     * expectOk(await run(syncParent), ["synced", "synced"]);
+     * assertOk(await run(syncParent), ["synced", "synced"]);
      * ```
      *
      * ### Aborting a daemon
      *
      * ```ts
      * import {
+     *   assertFalse,
+     *   assertTrue,
      *   AbortError,
      *   createRun,
      *   ok,
@@ -1018,14 +1144,21 @@ export interface Run<D = unknown> {
      * const fiber = run.daemon(syncUsers, { db });
      * fiber.abort();
      * const syncResult = await fiber;
-     * assert(!syncResult.ok);
-     * expect(AbortError.is(syncResult.error)).toBe(true);
+     * assertFalse(syncResult.ok);
+     * assertTrue(AbortError.is(syncResult.error));
      * ```
      *
      * ### Disposing a daemon
      *
      * ```ts
-     * import { createRun, ok, waitForAbort, type Task } from "@evolu/common";
+     * import {
+     *   assertOk,
+     *   assertTrue,
+     *   createRun,
+     *   ok,
+     *   waitForAbort,
+     *   type Task,
+     * } from "@evolu/common";
      *
      * let syncStopped = false;
      * const syncUsers: Task<never> = async (run) => {
@@ -1040,9 +1173,9 @@ export interface Run<D = unknown> {
      * {
      *   // Async disposal requests abort and waits for the daemon to stop.
      *   await using _syncFiber = run.daemon(syncUsers);
-     *   expectOk(await run(loadUser), "Ada");
+     *   assertOk(await run(loadUser), "Ada");
      * }
-     * expect(syncStopped).toBe(true);
+     * assertTrue(syncStopped);
      * ```
      */
     readonly daemon: {
@@ -1053,8 +1186,8 @@ export interface Run<D = unknown> {
      * Creates a {@link DisposableRun} attached to the root {@link Run} with this
      * Run's deps.
      *
-     * Use it when you need a Run that can be reused across multiple operations.
-     * For a single long-lived {@link Task}, use {@link Run.daemon}.
+     * Use it to give multiple related Tasks a shared lifetime. For a single
+     * long-lived {@link Task}, use {@link Run.daemon}.
      *
      * Use deps to replace the created Run's custom deps. Default deps
      * ({@link RunDefaultDeps}) are inherited unless explicitly replaced with
@@ -1068,7 +1201,13 @@ export interface Run<D = unknown> {
      * ### Example
      *
      * ```ts
-     * import { createRun, ok, type Task } from "@evolu/common";
+     * import {
+     *   assertEqual,
+     *   assertOk,
+     *   createRun,
+     *   ok,
+     *   type Task,
+     * } from "@evolu/common";
      *
      * interface DbDep {
      *   readonly db: { readonly users: Array<string> };
@@ -1086,9 +1225,9 @@ export interface Run<D = unknown> {
      * await using createdRun = run.create({ db });
      * const userResult = await createdRun(loadUser);
      * const savedResult = await createdRun(saveUser);
-     * expectOk(userResult, "Ada");
-     * expectOk(savedResult, undefined);
-     * expect(db.users).toEqual(["Ada", "Grace"]);
+     * assertOk(userResult, "Ada");
+     * assertOk(savedResult, undefined);
+     * assertEqual(db.users, ["Ada", "Grace"]);
      * ```
      */
     readonly create: {
@@ -1139,20 +1278,27 @@ export interface Run<D = unknown> {
      * ### Example
      *
      * ```ts
-     * import { AbortError, createRun, ok, sleep } from "@evolu/common";
+     * import {
+     *   assertFalse,
+     *   assertTrue,
+     *   AbortError,
+     *   createRun,
+     *   ok,
+     *   sleep,
+     * } from "@evolu/common";
      *
      * let socketClosed = false;
      * const openSocket = () => ({
      *   close: () => {
      *     socketClosed = true;
      *   },
-     *   read: async () => "message",
+     *   read: () => Promise.resolve("message"),
      * });
      *
      * await using run = createRun();
      * const fiber = run.abortable(async (run) => {
      *   const socket = openSocket();
-     *   using closeOnAbort = run.onAbort(() => {
+     *   using _closeOnAbort = run.onAbort(() => {
      *     socket.close();
      *   });
      *
@@ -1162,9 +1308,9 @@ export interface Run<D = unknown> {
      * });
      * fiber.abort();
      * const result = await fiber;
-     * assert(!result.ok);
-     * expect(AbortError.is(result.error)).toBe(true);
-     * expect(socketClosed).toBe(true);
+     * assertFalse(result.ok);
+     * assertTrue(AbortError.is(result.error));
+     * assertTrue(socketClosed);
      * ```
      */
     readonly onAbort: (callback: (abortError: AbortError) => void) => Disposable | null;
@@ -1229,7 +1375,7 @@ export interface DisposableRun<D = unknown> extends Run<D>, Disposable, AsyncDis
      * ### Example
      *
      * ```ts
-     * import { createRun } from "@evolu/common";
+     * import { assertFalse, assertTrue, createRun } from "@evolu/common";
      *
      * let connectionClosed = false;
      * {
@@ -1238,9 +1384,9 @@ export interface DisposableRun<D = unknown> extends Run<D>, Disposable, AsyncDis
      *     connectionClosed = true;
      *   });
      *
-     *   expect(connectionClosed).toBe(false);
+     *   assertFalse(connectionClosed);
      * }
-     * expect(connectionClosed).toBe(true);
+     * assertTrue(connectionClosed);
      * ```
      */
     readonly defer: (finalizer: () => Awaitable<void>) => void;
@@ -1304,7 +1450,15 @@ export interface DisposableRun<D = unknown> extends Run<D>, Disposable, AsyncDis
  * ### Example
  *
  * ```ts
- * import { createRun, ok, type Fiber, type Task } from "@evolu/common";
+ * import {
+ *   assertEqual,
+ *   assertOk,
+ *   assertType,
+ *   createRun,
+ *   ok,
+ *   type Fiber,
+ *   type Task,
+ * } from "@evolu/common";
  *
  * await using run = createRun();
  *
@@ -1314,9 +1468,9 @@ export interface DisposableRun<D = unknown> extends Run<D>, Disposable, AsyncDis
  * const userResult = await fiber;
  * const snapshot = fiber.run.snapshot();
  *
- * expectTypeOf(fiber).toEqualTypeOf<Fiber<string, never>>();
- * expectOk(userResult, "Ada");
- * expect(snapshot.id).toBe(fiber.run.id);
+ * assertType<Fiber<string, never>, typeof fiber>();
+ * assertOk(userResult, "Ada");
+ * assertEqual(snapshot.id, fiber.run.id);
  * ```
  *
  * @group Core
@@ -1366,6 +1520,9 @@ export type InferFiberDeps<TFiber extends AnyFiber> = TFiber extends Fiber<any,
  *
  * ```ts
  * import {
+ *   assertFalse,
+ *   assertType,
+ *   assertTrue,
  *   AbortError,
  *   createRun,
  *   ok,
@@ -1382,11 +1539,11 @@ export type InferFiberDeps<TFiber extends AnyFiber> = TFiber extends Fiber<any,
  * };
  *
  * const fiber = run.abortable<string, never>(fetchData);
- * expectTypeOf(fiber).toEqualTypeOf<AbortableFiber<string, never>>();
+ * assertType<AbortableFiber<string, never>, typeof fiber>();
  * fiber.abort();
  * const result = await fiber;
- * assert(!result.ok);
- * expect(AbortError.is(result.error)).toBe(true);
+ * assertFalse(result.ok);
+ * assertTrue(AbortError.is(result.error));
  * ```
  *
  * @group Core
@@ -1759,7 +1916,7 @@ export interface CreateRun {
  * ### 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 };
@@ -1771,7 +1928,7 @@ export interface CreateRun {
  * 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
@@ -1852,12 +2009,12 @@ export declare const testCreateDeps: (options?: {
  * ### Example
  *
  * ```ts
- * import { ok, testCreateRun, type Task } from "@evolu/common";
+ * import { assertOk, ok, testCreateRun, type Task } from "@evolu/common";
  *
  * const readTime: Task<number> = (run) => ok(run.deps.time.now());
  *
  * await using run = testCreateRun();
- * expectOk(await run(readTime), 0);
+ * assertOk(await run(readTime), 0);
  * ```
  *
  * @group Testing
@@ -1869,7 +2026,7 @@ export declare function testCreateRun(deps?: TestRunDefaultDeps): DisposableRun<
  * ### Example
  *
  * ```ts
- * import { ok, testCreateRun, type Task } from "@evolu/common";
+ * import { assertOk, ok, testCreateRun, type Task } from "@evolu/common";
  *
  * interface FeatureDep {
  *   readonly feature: { readonly enabled: boolean };
@@ -1879,7 +2036,7 @@ export declare function testCreateRun(deps?: TestRunDefaultDeps): DisposableRun<
  *   ok(run.deps.feature.enabled);
  *
  * await using run = testCreateRun({ feature: { enabled: true } });
- * expectOk(await run(isFeatureEnabled), true);
+ * assertOk(await run(isFeatureEnabled), true);
  * ```
  */
 export declare function testCreateRun<D extends object>(deps: RunCustomDeps<D>): DisposableRun<TestRunDefaultDeps & D>;
@@ -1906,7 +2063,7 @@ export type InferTaskRecordDeps<TTasks extends TaskRecord> = InferTasksDeps<Read
  * Options shared by {@link Task} collection helpers.
  *
  * `concurrency` controls how many Tasks run at once. It defaults to `1`. For
- * CPU-bound Tasks backed by workers or parallel native operations, a platform
+ * CPU-bound Tasks backed by workers or native parallelism, a platform
  * `availableParallelism()` result is often a good limit. For network or
  * database Tasks, choose a limit based on the transport, server, connection
  * pool, and rate limits.
@@ -1967,6 +2124,9 @@ export type InferTasksOk<TTasks> = {
  *
  * ```ts
  * import {
+ *   assertErr,
+ *   assertEqual,
+ *   assertType,
  *   all,
  *   createRun,
  *   err,
@@ -1997,14 +2157,12 @@ export type InferTasksOk<TTasks> = {
  *     collect: false,
  *   }),
  * );
- * expectTypeOf(saveResult).toEqualTypeOf<
- *   Result<void, SaveUserFailedError>
- * >();
- * expectErr(saveResult, {
+ * assertType<Result<void, SaveUserFailedError>, typeof saveResult>();
+ * assertErr(saveResult, {
  *   type: "SaveUserFailed",
  *   userId: "missing",
  * });
- * expect(savedUserIds).toEqual(["user-1"]);
+ * assertEqual(savedUserIds, ["user-1"]);
  * ```
  *
  * @group Collection
@@ -2019,6 +2177,8 @@ export declare function all<const TTasks extends TaskRecord>(tasks: TTasks, opti
  *
  * ```ts
  * import {
+ *   assertOk,
+ *   assertType,
  *   all,
  *   createRun,
  *   ok,
@@ -2040,10 +2200,11 @@ export declare function all<const TTasks extends TaskRecord>(tasks: TTasks, opti
  *
  * await using run = createRun();
  * const dashboard = await run(all([fetchUser, fetchPosts]));
- * expectTypeOf(dashboard).toEqualTypeOf<
- *   Result<readonly [User, ReadonlyArray<Post>]>
+ * assertType<
+ *   Result<readonly [User, ReadonlyArray<Post>]>,
+ *   typeof dashboard
  * >();
- * expectOk(dashboard, [{ id: "user-1" }, [{ id: "post-1" }]]);
+ * assertOk(dashboard, [{ id: "user-1" }, [{ id: "post-1" }]]);
  * ```
  */
 export declare function all<const TTasks extends ReadonlyArray<AnyTask>>(tasks: TTasks, options?: TaskCollectionOptions): Task<InferTasksOk<TTasks>, InferTaskErr<TTasks[number]>, InferTasksDeps<TTasks>>;
@@ -2054,6 +2215,8 @@ export declare function all<const TTasks extends ReadonlyArray<AnyTask>>(tasks:
  *
  * ```ts
  * import {
+ *   assertOk,
+ *   assertType,
  *   all,
  *   createRun,
  *   ok,
@@ -2076,10 +2239,11 @@ export declare function all<const TTasks extends ReadonlyArray<AnyTask>>(tasks:
  * await using run = createRun();
  * const result = await run(all({ user: fetchUser, posts: fetchPosts }));
  *
- * expectTypeOf(result).toEqualTypeOf<
- *   Result<{ readonly user: User; readonly posts: ReadonlyArray<Post> }>
+ * assertType<
+ *   Result<{ readonly user: User; readonly posts: ReadonlyArray<Post> }>,
+ *   typeof result
  * >();
- * expectOk(result, {
+ * assertOk(result, {
  *   user: { id: "user-1" },
  *   posts: [{ id: "post-1" }],
  * });
@@ -2098,6 +2262,9 @@ export declare function all<const TValues extends Readonly<Record<string, unknow
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertOk,
+ *   assertType,
  *   all,
  *   createRun,
  *   ok,
@@ -2122,12 +2289,12 @@ export declare function all<const TValues extends Readonly<Record<string, unknow
  * });
  *
  * // Mapping is eager: it happens before the returned Task starts.
- * expect(indexes).toEqual([0, 1]);
+ * assertEqual(indexes, [0, 1]);
  *
  * await using run = createRun();
  * const result = await run(loadUsers);
- * expectTypeOf(result).toEqualTypeOf<Result<readonly [User, User]>>();
- * expectOk(result, [{ id: "user-1" }, { id: "user-2" }]);
+ * assertType<Result<readonly [User, User]>, typeof result>();
+ * assertOk(result, [{ id: "user-1" }, { id: "user-2" }]);
  * ```
  */
 export declare function all<const TValues extends ReadonlyArray<unknown>, TTask extends AnyTask>(values: TValues, fn: (value: TValues[number], index: number) => TTask, options?: TaskCollectionOptions): Task<{
@@ -2140,6 +2307,9 @@ export declare function all<const TValues extends ReadonlyArray<unknown>, TTask
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertOk,
+ *   assertType,
  *   all,
  *   createRun,
  *   ok,
@@ -2167,14 +2337,15 @@ export declare function all<const TValues extends ReadonlyArray<unknown>, TTask
  * });
  *
  * // Mapping is eager: it happens before the returned Task starts.
- * expect(roles).toEqual(["admin", "reviewer"]);
+ * assertEqual(roles, ["admin", "reviewer"]);
  *
  * await using run = createRun();
  * const result = await run(loadUsersByRole);
- * expectTypeOf(result).toEqualTypeOf<
- *   Result<{ readonly admin: User; readonly reviewer: User }>
+ * assertType<
+ *   Result<{ readonly admin: User; readonly reviewer: User }>,
+ *   typeof result
  * >();
- * expectOk(result, {
+ * assertOk(result, {
  *   admin: { id: "user-1" },
  *   reviewer: { id: "user-2" },
  * });
@@ -2217,6 +2388,9 @@ export type InferTasksSettled<TTasks> = {
  *
  * ```ts
  * import {
+ *   assertOk,
+ *   assertType,
+ *   assertTrue,
  *   allSettled,
  *   createRun,
  *   err,
@@ -2239,20 +2413,21 @@ export type InferTasksSettled<TTasks> = {
  *
  * await using run = createRun();
  * const results = await run(allSettled([loadProfile, loadActivity]));
- * expectTypeOf(results).toEqualTypeOf<
+ * assertType<
  *   Result<
  *     readonly [
  *       Result<string, ProfileNotFoundError>,
  *       Result<ReadonlyArray<string>>,
  *     ]
- *   >
+ *   >,
+ *   typeof results
  * >();
- * expectOk(results, [
+ * assertOk(results, [
  *   { ok: false, error: { type: "ProfileNotFound" } },
  *   { ok: true, value: ["signed-in"] },
  * ]);
  * // Unlike all, a later Task still runs after an Err.
- * expect(activityLoaded).toBe(true);
+ * assertTrue(activityLoaded);
  * ```
  *
  * @group Collection
@@ -2265,6 +2440,8 @@ export declare function allSettled<const TTasks extends ReadonlyArray<AnyTask>>(
  *
  * ```ts
  * import {
+ *   assertOk,
+ *   assertType,
  *   allSettled,
  *   createRun,
  *   err,
@@ -2289,13 +2466,14 @@ export declare function allSettled<const TTasks extends ReadonlyArray<AnyTask>>(
  *   allSettled({ user: fetchUser, profile: fetchProfile }),
  * );
  *
- * expectTypeOf(results).toEqualTypeOf<
+ * assertType<
  *   Result<{
  *     readonly user: Result<User>;
  *     readonly profile: Result<string, ProfileNotFoundError>;
- *   }>
+ *   }>,
+ *   typeof results
  * >();
- * expectOk(results, {
+ * assertOk(results, {
  *   user: { ok: true, value: { id: "user-1" } },
  *   profile: { ok: false, error: { type: "ProfileNotFound" } },
  * });
@@ -2309,6 +2487,9 @@ export declare function allSettled<const TTasks extends TaskRecord>(tasks: TTask
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertOk,
+ *   assertType,
  *   allSettled,
  *   createRun,
  *   err,
@@ -2337,19 +2518,20 @@ export declare function allSettled<const TTasks extends TaskRecord>(tasks: TTask
  * });
  *
  * // Mapping is eager: it happens before the returned Task starts.
- * expect(indexes).toEqual([0, 1]);
+ * assertEqual(indexes, [0, 1]);
  *
  * await using run = createRun();
  * const results = await run(loadUsers);
- * expectTypeOf(results).toEqualTypeOf<
+ * assertType<
  *   Result<
  *     readonly [
  *       Result<User, UserNotFoundError>,
  *       Result<User, UserNotFoundError>,
  *     ]
- *   >
+ *   >,
+ *   typeof results
  * >();
- * expectOk(results, [
+ * assertOk(results, [
  *   { ok: true, value: { id: "user-1" } },
  *   { ok: false, error: { type: "UserNotFound" } },
  * ]);
@@ -2365,6 +2547,9 @@ export declare function allSettled<const TValues extends ReadonlyArray<unknown>,
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertOk,
+ *   assertType,
  *   allSettled,
  *   createRun,
  *   err,
@@ -2393,17 +2578,18 @@ export declare function allSettled<const TValues extends ReadonlyArray<unknown>,
  * });
  *
  * // Mapping is eager: it happens before the returned Task starts.
- * expect(roles).toEqual(["admin", "reviewer"]);
+ * assertEqual(roles, ["admin", "reviewer"]);
  *
  * await using run = createRun();
  * const results = await run(loadUsersByRole);
- * expectTypeOf(results).toEqualTypeOf<
+ * assertType<
  *   Result<{
  *     readonly admin: Result<User, UserNotFoundError>;
  *     readonly reviewer: Result<User, UserNotFoundError>;
- *   }>
+ *   }>,
+ *   typeof results
  * >();
- * expectOk(results, {
+ * assertOk(results, {
  *   admin: { ok: true, value: { id: "user-1" } },
  *   reviewer: { ok: false, error: { type: "UserNotFound" } },
  * });
@@ -2428,7 +2614,7 @@ export declare function allSettled<const TValues extends Readonly<Record<string,
  * 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
@@ -2453,14 +2639,23 @@ export declare function allSettled<const TValues extends Readonly<Record<string,
  * ### 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))),
@@ -2468,11 +2663,11 @@ export declare function allSettled<const TValues extends Readonly<Record<string,
  *
  * 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
@@ -2490,10 +2685,10 @@ export declare const callback: <T, E = never, D = unknown>(fn: (options: {
  * ### 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
@@ -2512,6 +2707,8 @@ export declare const sleep: (duration: PositiveDuration) => Task<void>;
  *
  * ```ts
  * import {
+ *   assertErr,
+ *   assertType,
  *   createRun,
  *   timeout,
  *   timeoutError,
@@ -2523,8 +2720,8 @@ export declare const sleep: (duration: PositiveDuration) => Task<void>;
  * 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
@@ -2606,6 +2803,8 @@ export interface RetryAttempt<E, Output> extends ScheduleStep<Output> {
  *
  * ```ts
  * import {
+ *   assertErr,
+ *   assertType,
  *   createRun,
  *   err,
  *   recurs,
@@ -2625,10 +2824,11 @@ export interface RetryAttempt<E, Output> extends ScheduleStep<Output> {
  *
  * 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" },
@@ -2639,6 +2839,7 @@ export interface RetryAttempt<E, Output> extends ScheduleStep<Output> {
  *
  * ```ts
  * import {
+ *   assertErr,
  *   createRun,
  *   err,
  *   recurs,
@@ -2661,7 +2862,8 @@ export interface RetryAttempt<E, Output> extends ScheduleStep<Output> {
  * });
  *
  * await using run = createRun();
- * expectErr(await run(fetchWithRetry), {
+ * const result = await run(fetchWithRetry);
+ * assertErr(result, {
  *   type: "RetryError",
  *   attempts: 1,
  *   lastError: { type: "PermanentFailure" },
@@ -2741,7 +2943,15 @@ export interface RepeatAttempt<T, Output> extends ScheduleStep<Output> {
  * ### 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> = () => {
@@ -2752,14 +2962,16 @@ export interface RepeatAttempt<T, Output> extends ScheduleStep<Output> {
  * 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,
@@ -2782,8 +2994,8 @@ export interface RepeatAttempt<T, Output> extends ScheduleStep<Output> {
  *
  * 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
@@ -2818,6 +3030,9 @@ export type InferTasksResult<TTasks extends NonEmptyReadonlyArray<AnyTask>> = Re
  *
  * ```ts
  * import {
+ *   assertOk,
+ *   assertType,
+ *   assertTrue,
  *   any,
  *   createRun,
  *   err,
@@ -2841,11 +3056,9 @@ export type InferTasksResult<TTasks extends NonEmptyReadonlyArray<AnyTask>> = Re
  * 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
@@ -2877,6 +3090,7 @@ export declare const any: <TTasks extends NonEmptyReadonlyArray<AnyTask>>(tasks:
  *
  * ```ts
  * import {
+ *   assertOk,
  *   createRun,
  *   isNonEmptyArray,
  *   ok,
@@ -2888,7 +3102,7 @@ export declare const any: <TTasks extends NonEmptyReadonlyArray<AnyTask>>(tasks:
  * await using run = createRun();
  * if (isNonEmptyArray(tasks)) {
  *   const result = await run(race(tasks));
- *   expectOk(result, "first");
+ *   assertOk(result, "first");
  * }
  * ```
  *
@@ -2896,6 +3110,9 @@ export declare const any: <TTasks extends NonEmptyReadonlyArray<AnyTask>>(tasks:
  *
  * ```ts
  * import {
+ *   assertFalse,
+ *   assertOk,
+ *   assertType,
  *   createRun,
  *   ok,
  *   race,
@@ -2917,9 +3134,9 @@ export declare const any: <TTasks extends NonEmptyReadonlyArray<AnyTask>>(tasks:
  * // 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
@@ -2941,6 +3158,8 @@ export declare const race: <TTasks extends NonEmptyReadonlyArray<AnyTask>>(tasks
  *
  * ```ts
  * import {
+ *   assertFalse,
+ *   assertOk,
  *   createRun,
  *   err,
  *   firstN,
@@ -2971,8 +3190,8 @@ export declare const race: <TTasks extends NonEmptyReadonlyArray<AnyTask>>(tasks
  *
  * // 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
@@ -2994,6 +3213,8 @@ export declare const firstN: <TTasks extends NonEmptyReadonlyArray<AnyTask>>(tas
  *
  * ```ts
  * import {
+ *   assertFalse,
+ *   assertOk,
  *   createRun,
  *   err,
  *   firstNSettled,
@@ -3019,11 +3240,11 @@ export declare const firstN: <TTasks extends NonEmptyReadonlyArray<AnyTask>>(tas
  *
  * // 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
@@ -3079,6 +3300,9 @@ export type EachCallback<TTasks extends NonEmptyReadonlyArray<AnyTask>> = (resul
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   assertOk,
  *   createRun,
  *   each,
  *   err,
@@ -3114,9 +3338,9 @@ export type EachCallback<TTasks extends NonEmptyReadonlyArray<AnyTask>> = (resul
  *   ),
  * );
  *
- * 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
@@ -3160,13 +3384,19 @@ export type TaskPriority = "user-blocking" | "user-visible" | "background";
  * ### 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
@@ -3186,7 +3416,13 @@ export declare const prioritized: <T, E, D = unknown>(priority: TaskPriority, ta
  * ### 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> =>
@@ -3202,7 +3438,7 @@ export declare const prioritized: <T, E, D = unknown>(priority: TaskPriority, ta
  *   };
  *
  * await using run = createRun();
- * expectOk(await run(sumTo(1001)), 500500);
+ * assertOk(await run(sumTo(1001)), 500500);
  * ```
  *
  * @group Scheduling
@@ -3219,6 +3455,10 @@ export declare const yieldNow: Task<void>;
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   assertType,
+ *   assertTrue,
  *   AbortError,
  *   createRun,
  *   ok,
@@ -3235,23 +3475,22 @@ export declare const yieldNow: Task<void>;
  * 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 });
@@ -3259,9 +3498,9 @@ export declare const yieldNow: Task<void>;
  * 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
@@ -3277,8 +3516,8 @@ export declare const waitForAbort: Task<never>;
  * 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.
  *
@@ -3311,6 +3550,9 @@ export declare const waitForAbort: Task<never>;
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   assertTrue,
  *   createRun,
  *   daemon,
  *   ok,
@@ -3331,18 +3573,24 @@ export declare const waitForAbort: Task<never>;
  * {
  *   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>> =>
@@ -3351,14 +3599,20 @@ export declare const waitForAbort: Task<never>;
  * 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;
@@ -3373,8 +3627,8 @@ export declare const waitForAbort: Task<never>;
  * 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
@@ -3395,14 +3649,21 @@ export declare const daemon: <T, E, D = unknown>(task: Task<T, E, D>) => Task<T,
  * ### 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");
  * });
  *
@@ -3412,7 +3673,7 @@ export declare const daemon: <T, E, D = unknown>(task: Task<T, E, D>) => Task<T,
  * fiber.abort();
  * finishCommit.resolve();
  *
- * expectOk(await fiber, "committed");
+ * assertOk(await fiber, "committed");
  * ```
  *
  * @group Abortability
@@ -3428,7 +3689,7 @@ export declare const unabortable: <T, E, D>(task: Task<T, E, D>) => Task<T, E, D
  *
  * 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.
  *
@@ -3440,6 +3701,9 @@ export declare const unabortable: <T, E, D>(task: Task<T, E, D>) => Task<T, E, D
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertFalse,
+ *   assertTrue,
  *   AbortError,
  *   createRun,
  *   ok,
@@ -3456,17 +3720,17 @@ export declare const unabortable: <T, E, D>(task: Task<T, E, D>) => Task<T, E, D
  * 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();
  *   };
@@ -3490,9 +3754,9 @@ export declare const unabortable: <T, E, D>(task: Task<T, E, D>) => Task<T, E, D
  * 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
@@ -3512,13 +3776,15 @@ export declare const unabortableMask: <T, E, D = unknown>(fn: (restore: <T2, E2,
  * 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,
@@ -3558,9 +3824,9 @@ export declare const unabortableMask: <T, E, D = unknown>(fn: (restore: <T2, E2,
  * );
  *
  * 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
@@ -3594,6 +3860,10 @@ export interface Deferred<T, E = never> {
  *
  * ```ts
  * import {
+ *   assertFalse,
+ *   assertOk,
+ *   assertType,
+ *   assertTrue,
  *   createDeferred,
  *   createRun,
  *   ok,
@@ -3604,22 +3874,28 @@ export interface Deferred<T, E = never> {
  * 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>();
@@ -3628,8 +3904,8 @@ export interface Deferred<T, E = never> {
  * 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
@@ -3671,7 +3947,15 @@ export interface Gate {
  * ### 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();
@@ -3687,13 +3971,13 @@ export interface Gate {
  *
  * 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
@@ -3706,8 +3990,8 @@ export declare const createGate: ({ isOpen, }?: {
  *
  * Use {@link Semaphore.withPermit} or {@link Semaphore.withPermits} to acquire
  * permits for one Task and release them when it settles. Use
- * {@link Semaphore.take} when permits must be held across multiple operations;
- * the returned {@link SemaphorePermit} owns release and is disposable.
+ * {@link Semaphore.take} when one permit must cover several child Tasks; the
+ * returned {@link SemaphorePermit} owns release and is disposable.
  *
  * Requests are not capped by the current permit count because
  * {@link Semaphore.resize} can increase it later.
@@ -3796,8 +4080,8 @@ export interface SemaphorePermit extends Disposable {
  * semaphore does not reorder requests to maximize utilization.
  *
  * Use `"fifo"` when fairness and predictable progress matter, such as tenant
- * sync, API quota, or database operations where large requests must not be
- * starved by a stream of smaller requests.
+ * sync, API quota, or database pools where large requests must not be starved
+ * by a stream of smaller requests.
  *
  * Use `"greedy"` when permits represent a shared budget and smaller or
  * latency-sensitive requests should proceed around larger queued requests. For
@@ -3845,6 +4129,7 @@ export interface SemaphoreSnapshot {
  *
  * ```ts
  * import {
+ *   assertEqual,
  *   createRun,
  *   createSemaphore,
  *   getOk,
@@ -3876,8 +4161,8 @@ export interface SemaphoreSnapshot {
  * ]);
  *
  * 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
@@ -3911,6 +4196,8 @@ export interface Mutex {
  *
  * ```ts
  * import {
+ *   assertEqual,
+ *   assertOk,
  *   createMutex,
  *   createRun,
  *   ok,
@@ -3933,9 +4220,9 @@ export interface Mutex {
  *   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
@@ -3950,8 +4237,8 @@ export declare const createMutex: () => Mutex;
  * resources, making idle-key cleanup less predictable and making accidental key
  * retention easier.
  *
- * Use Semaphore directly when callers need to hold permits across multiple
- * operations or resize a permit pool. Use `SemaphoreByKey` when permit
+ * Use Semaphore directly when callers need to hold permits while starting
+ * several child Tasks or resize a permit pool. Use `SemaphoreByKey` when permit
  * ownership should be tied to one Task lifetime and idle keys can be forgotten
  * automatically.
  *
@@ -3981,6 +4268,8 @@ export interface CreateSemaphoreByKeyOptions<K, L = K> extends LookupOption<K, L
  *
  * ```ts
  * import {
+ *   assertOk,
+ *   assertTrue,
  *   createRun,
  *   createSemaphoreByKey,
  *   ok,
@@ -3993,11 +4282,11 @@ export interface CreateSemaphoreByKeyOptions<K, L = K> extends LookupOption<K, L
  *   downloadsByHost.withPermit(host, () => ok(`${host}/${file}`));
  *
  * await using run = createRun();
- * expectOk(
+ * assertOk(
  *   await run(download("a.example", "index.json")),
  *   "a.example/index.json",
  * );
- * expect(downloadsByHost.isIdle("a.example")).toBe(true);
+ * assertTrue(downloadsByHost.isIdle("a.example"));
  * ```
  *
  * @group Concurrency primitives
@@ -4033,6 +4322,8 @@ export interface CreateMutexByKeyOptions<K, L = K> extends LookupOption<K, L> {
  *
  * ```ts
  * import {
+ *   assertOk,
+ *   assertTrue,
  *   createMutexByKey,
  *   createRun,
  *   ok,
@@ -4049,9 +4340,9 @@ export interface CreateMutexByKeyOptions<K, L = K> extends LookupOption<K, L> {
  *   });
  *
  * await using run = createRun();
- * expectOk(await run(deposit("checking", 2)), 2);
- * expectOk(await run(deposit("checking", 3)), 5);
- * expect(accountLocks.isIdle("checking")).toBe(true);
+ * assertOk(await run(deposit("checking", 2)), 2);
+ * assertOk(await run(deposit("checking", 3)), 5);
+ * assertTrue(accountLocks.isIdle("checking"));
  * ```
  *
  * @group Concurrency primitives
@@ -4062,9 +4353,9 @@ export declare function createMutexByKey<K, L>(options: CreateMutexByKeyOptions<
 /**
  * {@link Ref} protected by a {@link Mutex}.
  *
- * `MutexRef` serializes reads, writes, and updates through an internal Mutex,
- * so every operation observes one consistent value transition at a time. When
- * an update fails or is aborted, the previous value is preserved.
+ * `MutexRef` serializes reads, writes, and updates through an internal Mutex.
+ * Reads see a stable value, while writes and updates commit one transition at a
+ * time. When an update fails or is aborted, the previous value is preserved.
  *
  * `MutexRef` is non-reentrant. Updaters and modifiers run while holding the
  * internal Mutex, so calling another method on the same MutexRef from inside
@@ -4074,8 +4365,8 @@ export declare function createMutexByKey<K, L>(options: CreateMutexByKeyOptions<
  * read-modify-write. Plain Ref cannot express that — between a sync read and a
  * later write, a concurrent transition can interleave and get lost.
  *
- * `MutexRef` operations are Tasks and incur normal {@link Run} lifecycle
- * overhead. Use {@link Ref} instead for synchronous state transitions,
+ * `MutexRef` reads, writes, and updates are Tasks and incur normal {@link Run}
+ * lifecycle overhead. Use {@link Ref} instead for synchronous state transitions,
  * especially on allocation-sensitive hot paths.
  *
  * @group Concurrency primitives
@@ -4107,14 +4398,14 @@ export interface MutexRef<T> {
  * ### 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