@evolu/common 7.4.0 → 8.0.0-next.0

package/dist/src/Task.js

@@ -1,466 +1,1606 @@
-import { isNonEmptyArray, shiftArray } from "./Array.js";
-import { err, ok } from "./Result.js";
-import { durationToNonNegativeInt } from "./Time.js";
-import { NonNegativeInt, PositiveInt } from "./Type.js";
-/** Narrower check to detect AbortError objects at runtime. */
-const isAbortError = (error) => typeof error === "object" &&
-    error !== null &&
-    error.type === "AbortError";
-// For React Native
-if (typeof AbortSignal.any !== "function") {
-    AbortSignal.any = function (signals) {
-        const controller = new AbortController();
-        const onAbort = (event) => {
-            controller.abort(event.target.reason);
-            cleanup();
-        };
-        const cleanup = () => {
-            for (const s of signals)
-                s.removeEventListener("abort", onAbort);
-        };
-        for (const s of signals) {
-            if (s.aborted) {
-                controller.abort(s.reason);
-                return controller.signal;
+/**
+ * JavaScript-native structured concurrency.
+ *
+ * @module
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
             }
-            s.addEventListener("abort", onAbort);
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
         }
-        return controller.signal;
+        return next();
     };
-}
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { arrayFrom, emptyArray, isNonEmptyArray, mapArray, } from "./Array.js";
+import { assert } from "./Assert.js";
+import { createConsole } from "./Console.js";
+import { createRandomBytes } from "./Crypto.js";
+import { eqArrayStrict } from "./Eq.js";
+import { identity, lazyTrue, lazyVoid } from "./Function.js";
+import { createLookupMap } from "./Lookup.js";
+import { decrement, increment } from "./Number.js";
+import { createRecord, emptyRecord, isFunction, isIterable, mapObject, } from "./Object.js";
+import { createRandom } from "./Random.js";
+import { createRef } from "./Ref.js";
+import { err, getOrThrow, ok, tryAsync } from "./Result.js";
+import { addToSet, deleteFromSet, emptySet } from "./Set.js";
+import { createTime, durationToMillis, Millis } from "./Time.js";
+import { brand, createId, Id, maxPositiveInt, NonNegativeInt, object, onePositiveInt, PositiveInt, typed, union, Unknown, UnknownResult, zeroNonNegativeInt, } from "./Type.js";
+import {} from "./Types.js";
 /**
- * Combines user signal from context with an internal signal.
+ * Error returned when a {@link Task} is aborted via
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal | AbortSignal}.
+ *
+ * This is structured-concurrency control flow, not a domain error. It plays a
+ * role similar to an interrupt: in most code, propagate it unchanged or ignore
+ * it when cleanup is already handled by the runtime.
+ *
+ * The `reason` field is `unknown` by design — use typed errors for business
+ * logic. If you need to inspect the reason, use type guards like
+ * `RaceLostError.is(reason)`.
+ *
+ * When a piece of logic must continue once started, wrap it with
+ * {@link unabortable}. That prevents ordinary mid-flight interruption, but it
+ * does not erase {@link AbortError} from the type because the Task can still be
+ * rejected before it starts, for example on an already-stopped {@link Run}. In
+ * those cases, abort usually indicates a lifecycle bug, so use
+ * `assertNotAborted` if you want to fail fast.
+ *
+ * @group Core Types
+ */
+export const AbortError = /*#__PURE__*/ typed("AbortError", {
+    reason: Unknown,
+});
+/**
+ * Abort mask depth for a {@link Run} or {@link Fiber}.
+ *
+ * - `0` — abortable (default)
+ * - `>= 1` — inside {@link unabortable}, abort requests are ignored
+ *
+ * The mask tracks nested unabortable regions. When abort is requested, the
+ * signal only propagates if `mask === 0`.
+ *
+ * - {@link unabortable} increments the mask — Task becomes protected
+ * - {@link unabortableMask} provides `restore` to restore the previous mask
+ * - Tasks inherit their parent's mask by default
+ *
+ * This enables nested resource lifecycle patterns where each level can have its
+ * own abortable section while outer acquisitions remain protected.
+ *
+ * UI/debugging tools can use this to visually distinguish protected Tasks
+ * (e.g., different icon or color) and explain why abort requests are ignored.
  *
- * If the context has a signal, combines both signals using AbortSignal.any().
- * Otherwise, returns just the internal signal.
+ * @group Abort masking
  */
-const combineSignal = (context, internalSignal) => context?.signal
-    ? AbortSignal.any([context.signal, internalSignal])
-    : internalSignal;
+export const AbortMask = /*#__PURE__*/ brand("AbortMask", NonNegativeInt);
 /**
- * Converts async function returning {@link Result} to a {@link Task}.
+ * {@link RunSnapshot} state Type.
+ *
+ * @group Monitoring
+ */
+export const RunSnapshotState = /*#__PURE__*/ union(
+/*#__PURE__*/ typed("Running"), 
+/*#__PURE__*/ typed("Disposing"), 
+/*#__PURE__*/ typed("Settled", {
+    result: UnknownResult,
+    outcome: UnknownResult,
+}));
+/**
+ * The event-specific payload of a {@link RunEvent}.
+ *
+ * @group Monitoring
+ */
+export const RunEventData = /*#__PURE__*/ union(
+/*#__PURE__*/ typed("ChildAdded", { childId: Id }), 
+/*#__PURE__*/ typed("ChildRemoved", { childId: Id }), 
+/*#__PURE__*/ typed("StateChanged", { state: RunSnapshotState }));
+/**
+ * Events emitted by a {@link Run} for monitoring and debugging.
+ *
+ * Events bubble up through parent runs, enabling centralized monitoring at the
+ * root. Use with {@link Run.onEvent} to track Run lifecycle.
+ *
+ * @group Monitoring
+ */
+export const RunEvent = /*#__PURE__*/ object({
+    id: Id,
+    timestamp: Millis,
+    data: RunEventData,
+});
+// TODO:
+// Partial<TracerConfigDep> & // TODO:
+// Partial<TracerDep>; // TODO:
+const runDeps = {
+    console: createConsole(),
+    randomBytes: createRandomBytes(),
+    random: createRandom(),
+    time: createTime(),
+};
+/**
+ * Creates root {@link Run}.
+ *
+ * The root Run is also the daemon Run: it stays running until disposed. Child
+ * Runs created by `run(task)` are disposed by their parent once they settle.
+ *
+ * Call once per entry point (main thread, worker, etc.) and dispose on
+ * shutdown. All Tasks run as descendants of this root Run.
+ *
+ * This common {@link createRun} is platform-agnostic. At application entry
+ * points, prefer the platform adapter when one exists. `@evolu/web` adds
+ * browser `error` and `unhandledrejection` handlers, `@evolu/nodejs` adds
+ * Node.js `uncaughtException`, `unhandledRejection`, and graceful shutdown
+ * handling, and `@evolu/react-native` adds React Native global error handling.
+ *
+ * {@link RunDeps} provides default dependencies:
+ *
+ * - {@link Time}
+ * - {@link Console}
+ * - {@link Random}
+ * - {@link RandomBytes}
  *
  * ### Example
  *
  * ```ts
- * interface FetchError {
- *   readonly type: "FetchError";
- *   readonly error: unknown;
+ * // App entry point
+ * await using run = createRun();
+ *
+ * const result = await run(fetchData);
+ * ```
+ *
+ * ### Example with custom dependencies
+ *
+ * ```ts
+ * // Define dependency interfaces
+ * interface Config {
+ *   readonly apiUrl: string;
+ * }
+ *
+ * interface ConfigDep {
+ *   readonly config: Config;
  * }
  *
- * // Task version of fetch with proper error handling and cancellation support.
- * const fetch = (url: string) =>
- *   toTask((context) =>
- *     tryAsync(
- *       () => globalThis.fetch(url, { signal: context?.signal ?? null }),
- *       (error): FetchError => ({ type: "FetchError", error }),
- *     ),
- *   );
- *
- * // `satisfies` shows the expected type signature.
- * fetch satisfies (url: string) => Task<Response, FetchError>;
- *
- * const result1 = await fetch("https://api.example.com/data")();
- * result1 satisfies Result<Response, FetchError>;
- *
- * // With AbortController
- * const controller = new AbortController();
- * const result2 = await fetch("https://api.example.com/data")(controller);
- * result2 satisfies Result<Response, FetchError | AbortError>;
+ * // Task declares its dependencies via the D type parameter
+ * const fetchUser =
+ *   (id: string): Task<User, FetchError, ConfigDep> =>
+ *   async (run) => {
+ *     const { config } = run.deps;
+ *     const response = await fetch(`${config.apiUrl}/users/${id}`);
+ *     // ...
+ *   };
+ *
+ * // Composition root: create a Run with custom deps
+ * type AppDeps = RunDeps & ConfigDep;
+ *
+ * const appDeps: AppDeps = {
+ *   ...testCreateDeps(), // or spread individual deps
+ *   config: { apiUrl: "https://api.example.com" },
+ * };
+ *
+ * await using run = createRun(appDeps);
+ *
+ * // Run type is inferred from the deps argument
+ * const result = await run(fetchUser("123"));
+ *
+ * // TypeScript catches missing deps at compile time:
+ * // await using run2 = createRun(); // Run<RunDeps>
+ * // run2(fetchUser("123")); // Error: Property 'config' is missing
  * ```
+ *
+ * @group Creating Run
  */
-export const toTask = (fn) => 
-// Note: Not using async to avoid Promise wrapper overhead in fast path
-((context) => {
-    const signal = context?.signal;
-    // Fast path when no signal – return promise directly
-    if (!signal) {
-        // Preserve future context fields (e.g., tracing) even without a signal
-        return fn(context);
+export const createRun = (deps) => {
+    const mergedDeps = { ...runDeps, ...deps };
+    return createRunInternal(createRef(mergedDeps))();
+};
+const createRunInternal = (depsRef) => (parent, daemon, abortBehavior, concurrencyBehavior) => {
+    const parentMask = parent?.abortMask ?? isAbortable;
+    let abortMask;
+    switch (abortBehavior) {
+        case undefined:
+            abortMask = parentMask;
+            break;
+        case "unabortable":
+            abortMask = increment(parentMask);
+            break;
+        default:
+            assert(abortBehavior <= parentMask, "restore used outside its unabortableMask");
+            abortMask = abortBehavior;
     }
-    if (signal.aborted) {
-        return Promise.resolve(err({ type: "AbortError", reason: signal.reason }));
+    const requestController = new AbortController();
+    const signalController = new AbortController();
+    let state = running;
+    let result;
+    let outcome;
+    let children = emptySet;
+    const requestAbort = (reason) => {
+        const abortError = reason;
+        if (abortMask === isAbortable)
+            signalController.abort(abortError);
+        requestController.abort(abortError);
+    };
+    if (parent) {
+        subscribeToAbort(parent.requestSignal, () => requestAbort(parent.requestSignal.reason), { signal: requestController.signal });
     }
-    // Use Promise.withResolvers for clean abort handling and cleanup
-    const { promise: abortPromise, resolve: resolveAbort } = Promise.withResolvers();
-    const handleAbort = () => {
-        resolveAbort(err({ type: "AbortError", reason: signal.reason }));
+    const emitEvent = (data) => {
+        const deps = depsRef.get();
+        if (!deps.runConfig?.eventsEnabled.get())
+            return;
+        const e = { id: self.id, timestamp: deps.time.now(), data };
+        for (let node = self; node; node = node.parent) {
+            node.onEvent?.(e);
+        }
     };
-    signal.addEventListener("abort", handleAbort, { once: true });
-    // No finally: we expect no throws in normal flow; Result path removes listener.
-    // Unexpected throws indicate a bug and are allowed to crash (no recovery here).
-    return Promise.race([
-        abortPromise,
-        fn(context).then((result) => {
-            signal.removeEventListener("abort", handleAbort);
-            return result;
-        }),
-    ]);
-});
-// For React Native
-if (typeof AbortSignal.timeout !== "function") {
-    AbortSignal.timeout = function (ms) {
-        const controller = new AbortController();
-        const id = setTimeout(() => {
-            controller.abort();
-        }, ms);
-        // clear timeout if aborted early
-        controller.signal.addEventListener("abort", () => {
-            clearTimeout(id);
+    const run = (task) => {
+        const childRun = createRunInternal(depsRef)(self, daemon ?? self, getAbortBehavior(task), getConcurrencyBehavior(task));
+        if (state !== running) {
+            childRun.requestAbort(runStoppedAbortError);
+            task = () => err(runStoppedAbortError);
+        }
+        else if (signalController.signal.aborted &&
+            childRun.abortMask === isAbortable) {
+            childRun.requestAbort(signalController.signal.reason);
+            task = () => err(signalController.signal.reason);
+        }
+        const childFiber = Object.assign(Promise.try(task, childRun)
+            .then(childRun.handleTaskFulfilled)
+            .finally(childRun.handleTaskSettled)
+            .finally(childRun[Symbol.asyncDispose])
+            .finally(() => {
+            children = deleteFromSet(children, childFiber);
+            emitEvent({ type: "ChildRemoved", childId: childRun.id });
+        }), {
+            run: childRun,
+            abort: (reason) => {
+                childRun.requestAbort(createAbortError(reason));
+            },
+            getState: () => childRun.getState(),
+            [Symbol.dispose]: () => {
+                childFiber.abort();
+            },
         });
-        return controller.signal;
+        children = addToSet(children, childFiber);
+        emitEvent({ type: "ChildAdded", childId: childRun.id });
+        return childFiber;
     };
+    const self = run;
+    {
+        const run = self;
+        const id = createId(depsRef.get());
+        let snapshot = null;
+        let disposingPromise = null;
+        run.orThrow = async (task) => getOrThrow(await self(task));
+        run.id = id;
+        run.parent = parent ?? null;
+        run.signal = signalController.signal;
+        run.abortMask = abortMask;
+        run.onAbort = (callback) => {
+            if (abortMask !== isAbortable)
+                return;
+            subscribeToAbort(signalController.signal, () => callback(signalController.signal.reason.reason), { once: true, signal: requestController.signal });
+        };
+        run.getState = () => state;
+        run.getChildren = () => children;
+        run.snapshot = () => {
+            const childSnapshots = Array.from(children).map((fiber) => fiber.run.snapshot());
+            if (snapshot?.state !== state ||
+                !eqArrayStrict(snapshot.children, childSnapshots)) {
+                snapshot = {
+                    id,
+                    state: state,
+                    children: childSnapshots,
+                    abortMask,
+                };
+            }
+            return snapshot;
+        };
+        run.daemon = daemon ?? self;
+        run.create = () => run.daemon(createDeferred().task).run;
+        Object.defineProperty(run, "deps", { get: depsRef.get });
+        run.concurrency =
+            concurrencyBehavior ?? parent?.concurrency ?? defaultConcurrency;
+        run.addDeps = (newDeps) => {
+            depsRef.modify((currentDeps) => {
+                const duplicate = Object.keys(newDeps).find((k) => k in currentDeps);
+                assert(!duplicate, `Dependency '${duplicate}' already added. ` +
+                    `This assert ensures dependencies are created once. ` +
+                    `Automatic deduplication would mask bugs.`);
+                return [undefined, { ...currentDeps, ...newDeps }];
+            });
+            return self;
+        };
+        run[Symbol.asyncDispose] = () => {
+            if (disposingPromise)
+                return disposingPromise;
+            state = { type: "Disposing" };
+            emitEvent({ type: "StateChanged", state });
+            requestAbort(runStoppedAbortError);
+            disposingPromise = Promise.allSettled((run.ownTaskSettled
+                ? [run.ownTaskSettled.promise, ...children]
+                : children))
+                .then(lazyVoid)
+                .finally(() => {
+                /**
+                 * Root and daemon Runs have no own Task, so
+                 * `run.handleTaskFulfilled` never populates their terminal values.
+                 * In that case disposal publishes `ok()` for both `result` and
+                 * `outcome`. Task-backed Runs normally reach this point with both
+                 * values already set.
+                 */
+                [result, outcome] = [result ?? ok(), outcome ?? ok()];
+                state = { type: "Settled", result, outcome };
+                emitEvent({ type: "StateChanged", state });
+            });
+            return disposingPromise;
+        };
+        // Internal
+        run.ownTaskSettled = parent ? Promise.withResolvers() : null;
+        run.requestAbort = requestAbort;
+        run.requestSignal = requestController.signal;
+        run.handleTaskFulfilled = (taskOutcome) => {
+            const taskResult = run.signal.aborted
+                ? err(run.signal.reason)
+                : taskOutcome;
+            result = taskResult;
+            outcome = taskOutcome;
+            return taskResult;
+        };
+        run.handleTaskSettled = () => {
+            run.ownTaskSettled?.resolve();
+        };
+    }
+    return self;
+};
+const running = { type: "Running" };
+/**
+ * Abort reason indicating a {@link Run} can no longer start new Tasks.
+ *
+ * Covers both disposing and settled Runs.
+ *
+ * @group Creating Run
+ */
+export const RunStoppedError = /*#__PURE__*/ typed("RunStoppedError");
+/**
+ * Shared {@link RunStoppedError} instance used as the default
+ * {@link AbortError.reason} when a Task is started on a non-running {@link Run}.
+ *
+ * @group Creating Run
+ */
+export const runStoppedError = {
+    type: "RunStoppedError",
+};
+const createAbortError = (reason) => ({
+    type: "AbortError",
+    reason,
+});
+const subscribeToAbort = (signal, handler, options) => {
+    if (signal.aborted)
+        handler();
+    else
+        signal.addEventListener("abort", handler, options);
+};
+const runStoppedAbortError = createAbortError(runStoppedError);
+const isAbortable = AbortMask.orThrow(0);
+const abortBehaviorSymbol = Symbol("evolu.Task.abortBehavior");
+const getAbortBehavior = (task) => task[abortBehaviorSymbol];
+const abortBehavior = (behavior) => (task) => Object.assign((run) => run(task), {
+    [abortBehaviorSymbol]: behavior,
+});
+/**
+ * Makes a {@link Task} unabortable.
+ *
+ * Once started, an unabortable Task always completes — abort requests are
+ * ignored and `signal.aborted` remains `false`.
+ *
+ * If the parent {@link Run} is already disposing or settled, `run(task)`
+ * short-circuits before task execution and returns `err(AbortError)` with
+ * {@link runStoppedError} as reason. So `unabortable` means “do not interrupt
+ * this Task once it has started”, not “remove AbortError from its type”.
+ *
+ * When that pre-start abort would be a programmer error, assert it explicitly
+ * with `assertNotAborted` after awaiting the result.
+ *
+ * ### Example
+ *
+ * ```ts
+ * await using run = createRun();
+ *
+ * const events: Array<string> = [];
+ * const canComplete = Promise.withResolvers<void>();
+ * let signalAbortedInAnalytics = true;
+ *
+ * // Simulate async analytics API (abortable by default)
+ * const sendToAnalytics =
+ *   (event: number): Task<void, never> =>
+ *   async ({ signal }) => {
+ *     await canComplete.promise;
+ *     signalAbortedInAnalytics = signal.aborted;
+ *     events.push(`sent ${event}`);
+ *     return ok();
+ *   };
+ *
+ * // Important events must be sent even if the user navigates away
+ * const trackImportantEvent = (event: number) =>
+ *   unabortable(sendToAnalytics(event));
+ *
+ * // User clicks, we start tracking (Task runs until first await)
+ * const fiber = run(trackImportantEvent(123));
+ *
+ * // User navigates away (abort requested while task is running)
+ * fiber.abort();
+ * canComplete.resolve();
+ *
+ * const result = await fiber;
+ *
+ * expect(signalAbortedInAnalytics).toBe(false);
+ * // Analytics was sent despite abort
+ * expect(events).toEqual(["sent 123"]);
+ * expect(result).toEqual(ok());
+ * ```
+ *
+ * @group Abort masking
+ */
+// TODO: Clear AbortError from unabortable task results.
+export const unabortable = /*#__PURE__*/ abortBehavior("unabortable");
+/**
+ * Like {@link unabortable}, but provides `restore` to restore abortability for
+ * specific tasks.
+ *
+ * Tasks inherit abort masking from their parent. This means:
+ *
+ * - Tasks run inside `unabortableMask` are unabortable by default
+ * - Tasks wrapped with `restore()` restore the previous abortability
+ *
+ * @group Abort masking
+ */
+export const unabortableMask = (fn) => unabortable((run) => fn(abortBehavior(AbortMask.orThrow(decrement(run.abortMask))))(run));
+const defaultConcurrency = 1;
+const concurrencyBehaviorSymbol = Symbol("evolu.Task.concurrencyBehavior");
+const getConcurrencyBehavior = (task) => task[concurrencyBehaviorSymbol];
+export function concurrently(concurrencyOrTask, taskOrFallback) {
+    const isTask = isFunction(concurrencyOrTask);
+    const task = isTask ? concurrencyOrTask : taskOrFallback;
+    return Object.assign((run) => run(task), {
+        [concurrencyBehaviorSymbol]: isTask ? maxPositiveInt : concurrencyOrTask,
+    });
 }
 /**
- * Creates a {@link Task} that waits for the specified duration.
+ * Yields execution to allow other work to proceed.
+ *
+ * Long-running JavaScript blocks the main thread. In browsers, this makes the
+ * UI unresponsive (user interactions, animations). In Node.js, it prevents I/O
+ * callbacks, timers, and other requests from being handled. Inserting yield
+ * points lets the runtime process high-priority work between chunks of code.
+ *
+ * Uses `scheduler.yield()` in browsers for optimal main thread scheduling,
+ * falls back to `setImmediate` in Node.js, or `setTimeout` elsewhere.
  *
  * ### Example
  *
  * ```ts
- * const result1 = await wait("10ms")();
- * result1 satisfies Result<void, never>;
+ * const processLargeArray: Task<void, never> = async (run) => {
+ *   const { time } = run.deps;
+ *   let lastYield = time.now();
+ *
+ *   for (const item of largeArray) {
+ *     processItem(item);
+ *
+ *     // Yield periodically to keep UI responsive
+ *     if (time.now() - lastYield > msLongTask) {
+ *       const r = await run(yieldNow);
+ *       if (!r.ok) return r;
+ *       lastYield = time.now();
+ *     }
+ *   }
  *
- * // With AbortController
- * const controller = new AbortController();
- * const result2 = await wait("10ms")(controller);
- * result2 satisfies Result<void, AbortError>;
+ *   return ok();
+ * };
  * ```
+ *
+ * Recursive tasks also benefit from periodic yields — without them, deep
+ * recursion overflows the call stack:
+ *
+ * ```ts
+ * const processRecursive =
+ *   (count: number, index: number, sum: number): Task<number> =>
+ *   async (run) => {
+ *     if (index >= count) return ok(sum);
+ *
+ *     // Yield periodically to break synchronous call chains.
+ *     if (index > 0 && index % 1000 === 0) {
+ *       const y = await run(yieldNow);
+ *       if (!y.ok) return y;
+ *     }
+ *
+ *     // Direct tail-call: no fiber overhead, stack-safe thanks to yieldNow.
+ *     return await processRecursive(count, index + 1, sum + index)(run);
+ *   };
+ * ```
+ *
+ * @group Composition
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/Scheduler/yield
+ * @see https://web.dev/articles/optimize-long-tasks
  */
-export const wait = (duration) => toTask((context) => new Promise((resolve) => {
-    const ms = durationToNonNegativeInt(duration);
-    const timeoutSignal = AbortSignal.timeout(ms);
-    const signal = combineSignal(context, timeoutSignal);
-    // Listen for abort - either from timeout completion or external abort
-    signal.addEventListener("abort", () => {
-        resolve(ok());
-    }, { once: true });
-}));
+export const yieldNow = () => tryAsync(() => yieldImpl(), // TODO: yieldImpl(run.signal)
+(reason) => createAbortError(reason));
+const scheduler = globalThis.scheduler;
+const yieldImpl = typeof scheduler?.yield === "function"
+    ? () => scheduler.yield()
+    : typeof setImmediate !== "undefined"
+        ? () => new Promise((resolve) => setImmediate(resolve))
+        : () => new Promise((r) => setTimeout(r, 0)); // Safari
 /**
- * Adds timeout behavior to a {@link Task}.
+ * Creates a {@link Task} from a callback-based API.
+ *
+ * Use this to wrap callback-style APIs (event listeners, Node.js callbacks,
+ * etc.) into Tasks with proper abort handling.
+ *
+ * Optionally return a teardown function that runs on abort.
  *
  * ### Example
  *
  * ```ts
- * interface FetchError {
- *   readonly type: "FetchError";
- *   readonly error: unknown;
- * }
+ * // The sleep helper is implemented using callback:
+ * const sleep = (duration: Duration): Task<void> =>
+ *   callback(({ ok, deps: { time } }) => {
+ *     const id = time.setTimeout(ok, durationToMillis(duration));
+ *     return () => time.clearTimeout(id);
+ *   });
  *
- * // Task version of fetch with proper error handling and cancellation support.
- * const fetch = (url: string) =>
- *   toTask((context) =>
- *     tryAsync(
- *       () => globalThis.fetch(url, { signal: context?.signal ?? null }),
- *       (error): FetchError => ({ type: "FetchError", error }),
- *     ),
- *   );
+ * // Wrap an event listener — use signal directly
+ * const waitForClick = (element: HTMLElement): Task<MouseEvent> =>
+ *   callback(({ ok, signal }) => {
+ *     element.addEventListener("click", ok, { once: true, signal });
+ *   });
  *
- * // `satisfies` shows the expected type signature.
- * fetch satisfies (url: string) => Task<Response, FetchError>;
+ * // Wrap Node.js callback API
+ * const readFile = (path: string): Task<string, NodeJS.ErrnoException> =>
+ *   callback(({ ok, err }) => {
+ *     fs.readFile(path, "utf8", (error, data) => {
+ *       if (error) err(error);
+ *       else ok(data);
+ *     });
+ *   });
+ * ```
  *
- * const fetchWithTimeout = (url: string) => timeout("2m", fetch(url));
+ * @group Composition
+ */
+export const callback = (callback) => (run) => new Promise((resolve) => {
+    const teardown = callback({
+        ok: (value) => resolve(ok(value)),
+        err: (error) => resolve(err(error)),
+        signal: run.signal,
+        deps: run.deps,
+    });
+    run.onAbort((reason) => {
+        if (teardown)
+            teardown();
+        resolve(err(createAbortError(reason)));
+    });
+});
+/**
+ * Pauses execution for a specified duration.
  *
- * const result1 = await fetchWithTimeout("https://api.example.com/data")();
- * result1 satisfies Result<Response, FetchError | TimeoutError>;
+ * ### Example
  *
- * // With AbortController
- * const controller = new AbortController();
- * const result2 = await fetchWithTimeout("https://api.example.com/data")(
- *   controller,
- * );
- * result2 satisfies Result<
- *   Response,
- *   FetchError | TimeoutError | AbortError
- * >;
+ * ```ts
+ * const task: Task<void> = async (run) => {
+ *   console.log("Starting...");
+ *   await run(sleep("1s"));
+ *   console.log("Done after 1 second");
+ *   return ok();
+ * };
  * ```
+ *
+ * @group Composition
  */
-export const timeout = (duration, task) => toTask(async (context) => {
-    const timeoutMs = durationToNonNegativeInt(duration);
-    const timeoutSignal = AbortSignal.timeout(timeoutMs);
-    const signal = combineSignal(context, timeoutSignal);
-    const result = await task({ signal });
-    if (timeoutSignal.aborted) {
-        return err({ type: "TimeoutError", timeoutMs });
-    }
-    return result;
+export const sleep = (duration) => callback(({ ok, deps: { time } }) => {
+    const id = time.setTimeout(ok, durationToMillis(duration));
+    return () => time.clearTimeout(id);
 });
 /**
- * Adds retry logic with exponential backoff and jitter to a {@link Task}.
+ * Returns a {@link Task} that completes first.
+ *
+ * Like
+ * {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race | Promise.race},
+ * the first Task to complete (whether success or failure) wins. All other Tasks
+ * are aborted. Use {@link any} if you need the first Task to succeed instead.
+ *
+ * Requires a non-empty array — racing zero Tasks has no meaningful result
+ * (there's no "first to complete" without participants). This is enforced at
+ * compile time for non-empty tuple types. For other arrays, guard with
+ * {@link isNonEmptyArray}:
+ *
+ * ```ts
+ * if (isNonEmptyArray(tasks)) {
+ *   await run(race(tasks));
+ * }
+ * ```
+ *
+ * ### Example
+ *
+ * ```ts
+ * const fast: Task<string> = () => ok("fast");
+ * const slow: Task<string> = async (run) => {
+ *   await run(sleep("10ms"));
+ *   return ok("slow");
+ * };
+ *
+ * // First wins, others are aborted.
+ * const result = await run(race([fast, slow])); // ok("fast")
+ * ```
+ *
+ * Always runs with unlimited concurrency — a sequential race makes no sense
+ * since the first Task would always "win".
+ *
+ * @group Composition
+ */
+export const race = (tasks, { abortReason = raceLostError, } = {}) => concurrently(pool(tasks, { stopOn: "first", collect: false, abortReason }));
+/**
+ * Abort reason for tasks that lose a {@link race}.
+ *
+ * @group Composition
+ */
+export const RaceLostError = /*#__PURE__*/ typed("RaceLostError");
+/**
+ * {@link RaceLostError} used as abort reason in {@link race}.
+ *
+ * @group Composition
+ */
+export const raceLostError = { type: "RaceLostError" };
+/**
+ * Wraps a {@link Task} with a time limit.
+ *
+ * Returns {@link TimeoutError} if the Task doesn't complete within the specified
+ * duration. The original Task is aborted when the timeout fires.
  *
  * ### Example
  *
  * ```ts
- * interface FetchError {
- *   readonly type: "FetchError";
- *   readonly error: unknown;
+ * const fetchWithTimeout = timeout(fetchData, "5s");
+ *
+ * const result = await run(fetchWithTimeout);
+ * if (!result.ok && result.error.type === "TimeoutError") {
+ *   console.log("Request timed out");
  * }
+ * ```
  *
- * // Task version of fetch with proper error handling and cancellation support.
- * const fetch = (url: string) =>
- *   toTask((context) =>
- *     tryAsync(
- *       () => globalThis.fetch(url, { signal: context?.signal ?? null }),
- *       (error): FetchError => ({ type: "FetchError", error }),
- *     ),
- *   );
+ * @group Composition
+ */
+export const timeout = (task, duration, { abortReason = timeoutError, } = {}) => race([
+    task,
+    async (run) => {
+        await run(sleep(duration));
+        return err(timeoutError);
+    },
+], { abortReason });
+/**
+ * Typed error returned by {@link timeout} when a task exceeds its time limit.
  *
- * // `satisfies` shows the expected type signature.
- * fetch satisfies (url: string) => Task<Response, FetchError>;
+ * @group Composition
+ */
+export const TimeoutError = /*#__PURE__*/ typed("TimeoutError");
+/**
+ * {@link TimeoutError} used as abort reason in {@link timeout}.
  *
- * const fetchWithRetry = (url: string) =>
- *   retry({ retries: PositiveInt.orThrow(3) }, fetch(url));
+ * @group Composition
+ */
+export const timeoutError = { type: "TimeoutError" };
+/**
+ * Wraps a {@link Task} with retry logic.
+ *
+ * Retries the Task according to the {@link Schedule}'s rules. Use
+ * {@link RetryOptions.retryable} to filter which errors should trigger retries.
+ *
+ * All non-abort errors are wrapped in {@link RetryError}:
+ *
+ * - Task succeeds → `ok(value)`
+ * - Task returns {@link AbortError} → `err(AbortError)` — passed through, no
+ *   retry, no wrapping
+ * - Task returns any other error → retry until schedule exhausted or `retryable`
+ *   returns false → `err(RetryError)` with `cause` = the last error
+ *
+ * The `RetryError` is informative: "I tried N times, here's why I finally gave
+ * up" — and `cause` contains the actual underlying error.
  *
- * const result1 = await fetchWithRetry("https://api.example.com/data")();
- * result1 satisfies Result<Response, FetchError | RetryError<FetchError>>;
+ * ### Example
+ *
+ * ```ts
+ * import {
+ *   exponential,
+ *   jitter,
+ *   maxDelay,
+ *   retry,
+ *   take,
+ * } from "@evolu/common";
+ *
+ * const fetchWithRetry = retry(
+ *   fetchData,
+ *   // A jittered, capped, limited exponential backoff.
+ *   jitter(1)(maxDelay("20s")(take(2)(exponential("100ms")))),
+ * );
+ *
+ * const result = await run(fetchWithRetry);
+ * if (!result.ok) {
+ *   if (AbortError.is(result.error)) {
+ *     // Was aborted externally
+ *   } else {
+ *     // RetryError — failed after retrying
+ *     console.log(`Failed after ${result.error.attempts} attempts`);
+ *     console.log(`Last error:`, result.error.cause);
+ *   }
+ * }
+ * ```
+ *
+ * The schedule receives the error as input, enabling error-aware strategies
+ * like stopping on fatal errors:
  *
- * // With AbortController
- * const controller = new AbortController();
- * const result2 = await fetchWithRetry("https://api.example.com/data")(
- *   controller,
+ * ```ts
+ * import { whileScheduleInput } from "@evolu/common";
+ *
+ * // Don't retry fatal errors
+ * const smartRetry = retry(
+ *   fetchData,
+ *   whileScheduleInput((e: FetchError) => e.type !== "FatalError")(
+ *     take(5)(spaced("1s")),
+ *   ),
  * );
- * result2 satisfies Result<
- *   Response,
- *   FetchError | RetryError<FetchError> | AbortError
- * >;
  * ```
+ *
+ * @group Composition
+ * @see {@link RetryOptions}
  */
-export const retry = ({ retries, initialDelay = "1s", maxDelay = "30s", factor = 2, jitter = 0.5, retryable = (error) => !isAbortError(error), onRetry, }, task) => toTask(async (context) => {
-    const initialDelayMs = durationToNonNegativeInt(initialDelay);
-    const maxDelayMs = durationToNonNegativeInt(maxDelay);
-    const maxRetries = PositiveInt.orThrow(retries);
-    let attempt = 0;
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-    while (true) {
-        const result = await task(context);
-        if (result.ok) {
-            return result;
+export const retry = (task, schedule, { retryable = lazyTrue, onRetry, } = {}) => async (run) => {
+    const step = schedule(run.deps);
+    let attempt = onePositiveInt;
+    let error;
+    for (;;) {
+        if (error !== undefined) {
+            const scheduleResult = step(error);
+            if (!scheduleResult.ok) {
+                return err({
+                    type: "RetryError",
+                    cause: error,
+                    attempts: PositiveInt.orThrow(decrement(attempt)),
+                });
+            }
+            const [output, delay] = scheduleResult.value;
+            onRetry?.({
+                error,
+                attempt: PositiveInt.orThrow(decrement(attempt)),
+                output,
+                delay,
+            });
+            if (delay > 0) {
+                const sleepResult = await run(sleep(delay));
+                if (!sleepResult.ok)
+                    return sleepResult;
+            }
         }
-        // Never retry on AbortError; propagate it directly
-        if (isAbortError(result.error)) {
+        const result = await run(task);
+        if (result.ok)
+            return result;
+        if (AbortError.is(result.error))
             return err(result.error);
-        }
-        attempt += 1;
-        if (attempt > maxRetries || !retryable(result.error)) {
+        error = result.error;
+        if (!retryable(error)) {
             return err({
                 type: "RetryError",
-                cause: result.error,
+                cause: error,
                 attempts: attempt,
             });
         }
-        // Calculate delay with exponential backoff
-        const exponentialDelay = initialDelayMs * Math.pow(factor, attempt - 1);
-        const cappedDelay = Math.min(exponentialDelay, maxDelayMs);
-        // Apply jitter to prevent thundering herd problem
-        const randomFactor = 1 - jitter + Math.random() * jitter * 2;
-        const delay = Math.floor(cappedDelay * randomFactor);
-        if (onRetry) {
-            onRetry(result.error, attempt, delay);
-        }
-        // Wait before retry
-        {
-            const result = await wait(NonNegativeInt.orThrow(delay))(context);
-            if (!result.ok) {
-                // If delay was aborted, return AbortError (will be handled by toTask)
-                return result;
-            }
+        attempt = PositiveInt.orThrow(increment(attempt));
+    }
+};
+/**
+ * Repeats a {@link Task} according to a {@link Schedule}.
+ *
+ * Runs the Task, then checks the schedule to determine if it should repeat. The
+ * schedule controls how many repetitions occur and the delay between them.
+ * Continues until the schedule returns `Err(Done<void>)` or the Task fails.
+ *
+ * With `take(n)`, the task runs n+1 times (initial run plus n repetitions).
+ *
+ * Also works with {@link NextTask} — when the Task returns `Err(Done<D>)`,
+ * repeat stops and propagates the done signal.
+ *
+ * ### Example
+ *
+ * ```ts
+ * import { fixed, take } from "@evolu/common/schedule";
+ * import { repeat } from "@evolu/common";
+ *
+ * // Heartbeat every 30 seconds (runs forever until aborted)
+ * const heartbeat = repeat(sendHeartbeat, fixed("30s"));
+ *
+ * // Poll 4 times total (initial + 3 repetitions), 1 second apart
+ * const poll = repeat(checkStatus, take(3)(fixed("1s")));
+ *
+ * // Process queue items until empty (NextTask pattern)
+ * const processQueue: NextTask<Item, ProcessError, void> = async (run) => {
+ *   const item = queue.dequeue();
+ *   if (!item) return err(done()); // Queue empty, stop
+ *   await process(item);
+ *   return ok(item);
+ * };
+ *
+ * const result = await run(repeat(processQueue, fixed("100ms")));
+ * if (!result.ok && result.error.type === "Done") {
+ *   console.log("Queue exhausted");
+ * }
+ * ```
+ *
+ * @group Composition
+ */
+export const repeat = (task, schedule, { repeatable = lazyTrue, onRepeat, } = {}) => async (run) => {
+    const step = schedule(run.deps);
+    let lastResult;
+    let attempt = onePositiveInt;
+    for (;;) {
+        const result = await run(task);
+        if (!result.ok)
+            return result;
+        lastResult = result;
+        if (!repeatable(result.value))
+            return lastResult;
+        const next = step(result.value);
+        if (!next.ok)
+            break;
+        const [output, delay] = next.value;
+        onRepeat?.({
+            value: result.value,
+            attempt,
+            output,
+            delay,
+        });
+        attempt = PositiveInt.orThrow(increment(attempt));
+        if (delay > 0) {
+            const sleepResult = await run(sleep(delay));
+            if (!sleepResult.ok)
+                return sleepResult;
         }
     }
-});
+    return lastResult;
+};
 /**
- * Creates a semaphore that limits concurrent async Tasks to the specified
- * count.
+ * Creates a {@link Deferred}.
  *
- * A semaphore controls access to a resource by maintaining a count of available
- * permits. Tasks acquire a permit before executing and release it when
- * complete.
+ * @group Concurrency primitives
+ */
+export const createDeferred = () => {
+    let resolved = null;
+    const resolvers = new Set();
+    const resolve = (result) => {
+        if (resolved !== null)
+            return false;
+        resolved = result;
+        for (const resolver of resolvers)
+            resolver(result);
+        resolvers.clear();
+        return true;
+    };
+    return {
+        task: (run) => {
+            if (resolved !== null)
+                return resolved;
+            return new Promise((resolvePromise) => {
+                const resolve = (result) => {
+                    resolvers.delete(resolve);
+                    resolvePromise(result);
+                };
+                resolvers.add(resolve);
+                run.onAbort((reason) => {
+                    resolve(err(createAbortError(reason)));
+                });
+            });
+        },
+        resolve,
+        [Symbol.dispose]: () => {
+            resolve(err(deferredDisposedError));
+        },
+    };
+};
+/**
+ * Abort reason used when a {@link Deferred} is disposed.
  *
- * For mutual exclusion (exactly one Task at a time), consider using
- * {@link createMutex} instead.
+ * @group Concurrency primitives
+ */
+export const DeferredDisposedError = /*#__PURE__*/ typed("DeferredDisposedError");
+/**
+ * {@link DeferredDisposedError} used as abort reason in {@link createDeferred}.
+ *
+ * @group Concurrency primitives
+ */
+export const deferredDisposedError = {
+    type: "DeferredDisposedError",
+};
+/**
+ * Creates a {@link Gate} that starts closed.
+ *
+ * Useful for "stop/go" logic where multiple Tasks need to wait for a state
+ * change.
  *
  * ### Example
  *
  * ```ts
- * // Allow maximum 3 concurrent Tasks
- * const semaphore = createSemaphore(PositiveInt.orThrow(3));
+ * const networkGate = createGate();
  *
- * let currentConcurrent = 0;
- * const events: Array<string> = [];
+ * // Pause processing when offline
+ * const onOffline = () => networkGate.close();
  *
- * const fetchData = (id: number) =>
- *   toTask<number, never>(async (context) => {
- *     currentConcurrent++;
- *     events.push(`start ${id} (concurrent: ${currentConcurrent})`);
+ * // Resume processing when online
+ * const onOnline = () => networkGate.open();
  *
- *     await wait("10ms")(context);
+ * const syncLoop = async (run) => {
+ *   while (true) {
+ *     // Blocks here whenever the gate is closed
+ *     await run(networkGate.wait);
+ *     await run(uploadNextItem);
+ *   }
+ * };
+ * ```
  *
- *     currentConcurrent--;
- *     events.push(`end ${id} (concurrent: ${currentConcurrent})`);
- *     return ok(id * 10);
- *   });
+ * @group Concurrency primitives
+ */
+export const createGate = () => {
+    let isOpen = false;
+    let disposed = false;
+    let deferred = createDeferred();
+    return {
+        wait: (run) => {
+            if (disposed)
+                return err(deferredDisposedError);
+            if (isOpen)
+                return ok();
+            return run(deferred.task);
+        },
+        open: () => {
+            if (disposed || isOpen)
+                return;
+            isOpen = true;
+            deferred.resolve(ok());
+        },
+        close: () => {
+            if (disposed || !isOpen)
+                return;
+            isOpen = false;
+            deferred = createDeferred();
+        },
+        isOpen: () => isOpen,
+        [Symbol.dispose]: () => {
+            if (disposed)
+                return;
+            disposed = true;
+            deferred[Symbol.dispose]();
+        },
+    };
+};
+/**
+ * Creates a {@link Semaphore} that limits concurrent {@link Task}s.
+ *
+ * ### Example
+ *
+ * ```ts
+ * await using run = createRun();
+ *
+ * const semaphore = createSemaphore(PositiveInt.orThrow(2));
  *
- * // These will execute with at most 3 running concurrently
- * const results = await Promise.all([
- *   semaphore.withPermit(fetchData(1))(),
- *   semaphore.withPermit(fetchData(2))(),
- *   semaphore.withPermit(fetchData(3))(),
- *   semaphore.withPermit(fetchData(4))(), // waits for one above to complete
- *   semaphore.withPermit(fetchData(5))(), // waits for permit
+ * const fetchUser =
+ *   (id: string): Task<string> =>
+ *   async (run) => {
+ *     const { console } = run.deps;
+ *     console.log("[demo]", "start", id);
+ *     const slept = await run(sleep("10ms"));
+ *     if (!slept.ok) return slept;
+ *     console.log("[demo]", "end", id);
+ *     return ok(`user:${id}`);
+ *   };
+ *
+ * const fetchWithPermit = (id: string) =>
+ *   semaphore.withPermit(fetchUser(id));
+ *
+ * await Promise.all([
+ *   run(fetchWithPermit("1")),
+ *   run(fetchWithPermit("2")),
+ *   run(fetchWithPermit("3")),
  * ]);
  *
- * expect(results.map(getOrThrow)).toEqual([10, 20, 30, 40, 50]);
- * expect(events).toMatchInlineSnapshot(`
- *   [
- *     "start 1 (concurrent: 1)",
- *     "start 2 (concurrent: 2)",
- *     "start 3 (concurrent: 3)",
- *     "end 1 (concurrent: 2)",
- *     "start 4 (concurrent: 3)",
- *     "end 2 (concurrent: 2)",
- *     "start 5 (concurrent: 3)",
- *     "end 3 (concurrent: 2)",
- *     "end 4 (concurrent: 1)",
- *     "end 5 (concurrent: 0)",
- *   ]
- * `);
+ * // [demo] start 1
+ * // [demo] start 2
+ * // [demo] end 1
+ * // [demo] start 3
+ * // [demo] end 2
+ * // [demo] end 3
  * ```
+ *
+ * @group Concurrency primitives
  */
-export const createSemaphore = (maxConcurrent) => {
-    let isDisposed = false;
-    let availablePermits = maxConcurrent;
-    const waitingQueue = [];
-    const semaphoreController = new AbortController();
-    const acquire = () => {
-        if (availablePermits > 0) {
-            availablePermits--;
-            return Promise.resolve();
+export const createSemaphore = (permits) => {
+    const fibers = new Set();
+    const waiters = [];
+    let taken = zeroNonNegativeInt;
+    let disposed = false;
+    const withPermits = (requestedPermits) => (task) => async (run) => {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const requested = PositiveInt.orThrow(requestedPermits);
+            assert(requested <= permits, "Requested permits must not exceed semaphore capacity.");
+            if (disposed)
+                return err(semaphoreDisposedAbortError);
+            if (waiters.length > 0 || taken + requested > permits) {
+                const waiter = Promise.withResolvers();
+                const waiting = {
+                    permits: requested,
+                    resolve: waiter.resolve,
+                };
+                waiters.push(waiting);
+                run.onAbort((reason) => {
+                    const i = waiters.indexOf(waiting);
+                    if (i >= 0)
+                        waiters.splice(i, 1);
+                    waiter.resolve(err(createAbortError(reason)));
+                });
+                const permit = await waiter.promise;
+                if (!permit.ok)
+                    return permit;
+            }
+            else {
+                taken = NonNegativeInt.orThrow(taken + requested);
+            }
+            let fiber = null;
+            const _ = __addDisposableResource(env_1, {
+                [Symbol.dispose]: () => {
+                    if (fiber)
+                        fibers.delete(fiber);
+                    taken = NonNegativeInt.orThrow(taken - requested);
+                    while (waiters.length > 0) {
+                        const waiter = waiters[0];
+                        if (taken + waiter.permits > permits)
+                            break;
+                        waiters.shift();
+                        taken = NonNegativeInt.orThrow(taken + waiter.permits);
+                        waiter.resolve(ok());
+                    }
+                },
+            }, false);
+            fiber = run(task);
+            fibers.add(fiber);
+            return await fiber;
         }
-        return new Promise((resolve) => {
-            waitingQueue.push(resolve);
-        });
-    };
-    const release = () => {
-        if (isNonEmptyArray(waitingQueue)) {
-            shiftArray(waitingQueue)();
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
         }
-        else {
-            availablePermits++;
+        finally {
+            __disposeResources(env_1);
         }
     };
     return {
-        withPermit: (task) => toTask(async (context) => {
-            await acquire();
-            // Check if semaphore was disposed while waiting
-            if (isDisposed) {
-                return err({
-                    type: "AbortError",
-                    reason: "Semaphore disposed",
-                });
-            }
-            const signal = combineSignal(context, semaphoreController.signal);
-            const result = await task({ signal });
-            release();
-            return result;
+        withPermits,
+        withPermit: (task) => withPermits(1)(task),
+        snapshot: () => ({
+            permits,
+            taken,
+            waiting: NonNegativeInt.orThrow(waiters.length),
+            available: NonNegativeInt.orThrow(permits - taken),
+            isIdle: taken === 0 && waiters.length === 0,
+            disposed,
         }),
         [Symbol.dispose]: () => {
-            if (isDisposed)
-                return;
-            isDisposed = true;
-            // Cancel all running and waiting tasks
-            semaphoreController.abort("Semaphore disposed");
-            // Release all waiting tasks so they can continue and check isDisposed
-            while (isNonEmptyArray(waitingQueue)) {
-                shiftArray(waitingQueue)();
+            const env_2 = { stack: [], error: void 0, hasError: false };
+            try {
+                if (disposed)
+                    return;
+                disposed = true;
+                const stack = __addDisposableResource(env_2, new DisposableStack(), false);
+                for (const fiber of fibers) {
+                    stack.adopt(fiber, (fiber) => {
+                        fiber.abort(semaphoreDisposedError);
+                    });
+                }
+                for (const waiter of waiters) {
+                    waiter.resolve(err(semaphoreDisposedAbortError));
+                }
+                waiters.length = 0;
+            }
+            catch (e_2) {
+                env_2.error = e_2;
+                env_2.hasError = true;
+            }
+            finally {
+                __disposeResources(env_2);
             }
         },
     };
 };
 /**
- * Creates a new mutex for ensuring mutual exclusion.
+ * Abort reason used when a {@link Semaphore} is disposed.
  *
- * A mutex is a {@link createSemaphore} with exactly one permit, ensuring that
- * only one Task can execute at a time.
+ * @group Concurrency primitives
+ */
+export const SemaphoreDisposedError = /*#__PURE__*/ typed("SemaphoreDisposedError");
+/**
+ * {@link SemaphoreDisposedError} used as abort reason in {@link createSemaphore}.
  *
- * ### Example
+ * @group Concurrency primitives
+ */
+export const semaphoreDisposedError = {
+    type: "SemaphoreDisposedError",
+};
+const semaphoreDisposedAbortError = createAbortError(semaphoreDisposedError);
+export function createSemaphoreByKey(permits, { lookup = identity } = {}) {
+    const semaphoresByKey = createLookupMap({
+        lookup,
+    });
+    let disposed = false;
+    const withPermits = (key, requestedPermits) => (task) => async (run) => {
+        const env_3 = { stack: [], error: void 0, hasError: false };
+        try {
+            if (disposed)
+                return err(semaphoreDisposedAbortError);
+            let semaphore = semaphoresByKey.get(key);
+            if (!semaphore) {
+                semaphore = createSemaphore(permits);
+                semaphoresByKey.set(key, semaphore);
+            }
+            const _ = __addDisposableResource(env_3, {
+                [Symbol.dispose]: () => {
+                    const snapshot = semaphore.snapshot();
+                    if (snapshot.isIdle) {
+                        semaphoresByKey.delete(key);
+                        semaphore[Symbol.dispose]();
+                    }
+                },
+            }, false);
+            return await run(semaphore.withPermits(requestedPermits)(task));
+        }
+        catch (e_3) {
+            env_3.error = e_3;
+            env_3.hasError = true;
+        }
+        finally {
+            __disposeResources(env_3);
+        }
+    };
+    return {
+        withPermit: (key, task) => withPermits(key, 1)(task),
+        withPermits,
+        snapshot: (key) => semaphoresByKey.get(key)?.snapshot() ?? null,
+        [Symbol.dispose]: () => {
+            const env_4 = { stack: [], error: void 0, hasError: false };
+            try {
+                if (disposed)
+                    return;
+                disposed = true;
+                const stack = __addDisposableResource(env_4, new DisposableStack(), false);
+                for (const semaphore of semaphoresByKey.values()) {
+                    stack.use(semaphore);
+                }
+                semaphoresByKey.clear();
+            }
+            catch (e_4) {
+                env_4.error = e_4;
+                env_4.hasError = true;
+            }
+            finally {
+                __disposeResources(env_4);
+            }
+        },
+    };
+}
+/**
+ * Creates a {@link Mutex}.
  *
- * ```ts
- * const mutex = createMutex();
- *
- * const updateTask = (id: number) =>
- *   toTask((context) =>
- *     tryAsync(
- *       () => updateSharedResource(id, context),
- *       (error): UpdateError => ({ type: "UpdateError", error }),
- *     ),
- *   );
- *
- * // These Tasks will execute one at a time
- * const results = await Promise.all([
- *   mutex.withLock(updateTask(1))(),
- *   mutex.withLock(updateTask(2))(),
- *   mutex.withLock(updateTask(3))(),
- * ]);
- * ```
+ * @group Concurrency primitives
  */
 export const createMutex = () => {
-    const mutex = createSemaphore(PositiveInt.orThrow(1));
+    const semaphore = createSemaphore(onePositiveInt);
+    return {
+        withLock: semaphore.withPermit,
+        snapshot: semaphore.snapshot,
+        [Symbol.dispose]: semaphore[Symbol.dispose],
+    };
+};
+export function createMutexByKey({ lookup = identity, } = {}) {
+    const semaphoreByKey = createSemaphoreByKey(onePositiveInt, {
+        lookup,
+    });
+    return {
+        withLock: (key, task) => semaphoreByKey.withPermit(key, task),
+        snapshot: semaphoreByKey.snapshot,
+        [Symbol.dispose]: semaphoreByKey[Symbol.dispose],
+    };
+}
+/**
+ * Creates a {@link MutexRef} with the given initial immutable value.
+ *
+ * @group Concurrency primitives
+ */
+export const createMutexRef = (initialValue) => {
+    const ref = createRef(initialValue);
+    const mutex = createMutex();
     return {
-        withLock: mutex.withPermit,
+        get: mutex.withLock(() => ok(ref.get())),
+        set: (value) => mutex.withLock(() => {
+            ref.set(value);
+            return ok();
+        }),
+        getAndSet: (value) => mutex.withLock(() => ok(ref.getAndSet(value))),
+        setAndGet: (value) => mutex.withLock(() => ok(ref.setAndGet(value))),
+        update: (updater) => mutex.withLock(async (run) => {
+            const nextValue = await run(updater(ref.get()));
+            if (!nextValue.ok)
+                return nextValue;
+            ref.set(nextValue.value);
+            return ok();
+        }),
+        getAndUpdate: (updater) => mutex.withLock(async (run) => {
+            const previousValue = ref.get();
+            const nextValue = await run(updater(previousValue));
+            if (!nextValue.ok)
+                return nextValue;
+            ref.set(nextValue.value);
+            return ok(previousValue);
+        }),
+        updateAndGet: (updater) => mutex.withLock(async (run) => {
+            const currentValue = ref.get();
+            const nextValue = await run(updater(currentValue));
+            if (!nextValue.ok)
+                return nextValue;
+            ref.set(nextValue.value);
+            return ok(nextValue.value);
+        }),
+        modify: (modifier) => mutex.withLock(async (run) => {
+            const nextValue = await run(modifier(ref.get()));
+            if (!nextValue.ok)
+                return nextValue;
+            const [result, updatedValue] = nextValue.value;
+            ref.set(updatedValue);
+            return ok(result);
+        }),
         [Symbol.dispose]: mutex[Symbol.dispose],
     };
 };
 /**
- * Schedule a task to run after all interactions (animations, gestures,
- * navigation) have completed.
+ * Creates an in-process {@link LeaderLock}.
  *
- * This uses `requestIdleCallback` when available, otherwise falls back to
- * `setTimeout(0)` for cross-platform compatibility.
+ * Uses one {@link Mutex} per {@link Name}. Suitable for runtimes without a
+ * cross-process lock manager (for example in-memory worker tests or React
+ * Native).
  *
- * ### Example
+ * @group Concurrency primitives
+ */
+export const createInMemoryLeaderLock = () => {
+    const mutexByName = createMutexByKey();
+    return {
+        lock: (name) => async (run) => {
+            const leaseRun = run.create();
+            const released = createDeferred();
+            const acquired = createDeferred();
+            void leaseRun(mutexByName.withLock(name, async (run) => {
+                acquired.resolve(ok());
+                await run(released.task);
+                return ok();
+            }));
+            const acquiredResult = await run(acquired.task);
+            if (!acquiredResult.ok) {
+                assert(AbortError.is(acquiredResult.error), "Leader lock acquisition deferred must not be disposed.");
+                void leaseRun[Symbol.asyncDispose]();
+                return err(acquiredResult.error);
+            }
+            return ok({
+                [Symbol.asyncDispose]: leaseRun[Symbol.asyncDispose],
+            });
+        },
+    };
+};
+export function all(input, options) {
+    return collect("all", input, options);
+}
+/**
+ * Abort reason used by {@link all} when aborting remaining tasks.
  *
- * ```ts
- * const processDataTask: Task<void, ProcessError> = toTask(async () => {
- *   // Heavy processing work
- *   return ok();
- * });
+ * Used when a Task fails and other Tasks need to be aborted.
  *
- * // Schedule the task to run when idle
- * void requestIdleTask(processDataTask)();
- * ```
+ * @group Composition
+ */
+export const AllAbortError = /*#__PURE__*/ typed("AllAbortError");
+/**
+ * {@link AllAbortError} used as abort reason in {@link all}.
+ *
+ * @group Composition
+ */
+export const allAbortError = { type: "AllAbortError" };
+export function allSettled(input, options) {
+    return collect("allSettled", input, options);
+}
+/**
+ * Abort reason used by {@link allSettled} when aborted externally.
+ *
+ * @group Composition
  */
-export const requestIdleTask = (task) => toTask(async (context) => new Promise((resolve) => {
-    idleCallback(() => {
-        void task(context).then(resolve);
+export const AllSettledAbortError = /*#__PURE__*/ typed("AllSettledAbortError");
+/**
+ * {@link AllSettledAbortError} used as abort reason in {@link allSettled}.
+ *
+ * @group Composition
+ */
+export const allSettledAbortError = {
+    type: "AllSettledAbortError",
+};
+export function map(items, fn, { abortReason = mapAbortError, ...options } = {}) {
+    const mapped = mapInput(items, fn);
+    return all(mapped, {
+        ...options,
+        abortReason,
     });
-}));
-const idleCallback = typeof globalThis.requestIdleCallback === "function"
-    ? globalThis.requestIdleCallback
-    : (callback) => setTimeout(callback, 0);
+}
+/**
+ * Abort reason used by {@link map} when aborting remaining tasks.
+ *
+ * @group Composition
+ */
+export const MapAbortError = /*#__PURE__*/ typed("MapAbortError");
+/**
+ * {@link MapAbortError} used as abort reason in {@link map}.
+ *
+ * @group Composition
+ */
+export const mapAbortError = {
+    type: "MapAbortError",
+};
+export function mapSettled(items, task, options) {
+    const mapped = mapInput(items, task);
+    return allSettled(mapped, options);
+}
+export function any(tasks, options) {
+    const { allFailed = "input" } = options ?? {};
+    return pool(tasks, {
+        stopOn: "success",
+        collect: false,
+        abortReason: anyAbortError,
+        allFailed,
+    });
+}
+/**
+ * Abort reason used by {@link any} when aborting remaining tasks.
+ *
+ * @group Composition
+ */
+export const AnyAbortError = /*#__PURE__*/ typed("AnyAbortError");
+/**
+ * {@link AnyAbortError} used as abort reason in {@link any}.
+ *
+ * @group Composition
+ */
+export const anyAbortError = { type: "AnyAbortError" };
+/** Shared implementation for {@link all} and {@link allSettled}. */
+const collect = (type, input, { collect = true, abortReason = type === "all" ? allAbortError : allSettledAbortError, } = {}) => {
+    const stopOn = type === "all" ? "error" : null;
+    if (isIterable(input)) {
+        const array = arrayFrom(input);
+        if (!isNonEmptyArray(array))
+            return () => ok(collect ? emptyArray : undefined);
+        return pool(array, {
+            stopOn,
+            collect,
+            abortReason,
+        });
+    }
+    const keys = [];
+    const taskArray = [];
+    for (const key in input) {
+        keys.push(key);
+        taskArray.push(input[key]);
+    }
+    if (keys.length === 0)
+        return () => ok(collect ? emptyRecord : undefined);
+    return async (run) => {
+        const result = await run(pool(taskArray, { stopOn, collect, abortReason }));
+        if (!result.ok)
+            return result;
+        if (!collect)
+            return ok();
+        const record = createRecord();
+        for (let i = 0; i < keys.length; i++) {
+            record[keys[i]] = result.value[i];
+        }
+        return ok(record);
+    };
+};
+const mapInput = (input, fn) => isIterable(input) ? mapArray(arrayFrom(input), fn) : mapObject(input, fn);
+function pool(tasksIterable, { stopOn = null, collect, abortReason, allFailed, }) {
+    const tasks = arrayFrom(tasksIterable);
+    const { length } = tasks;
+    if (length === 0)
+        return () => ok(emptyArray);
+    return async (run) => {
+        const env_5 = { stack: [], error: void 0, hasError: false };
+        try {
+            const results = collect ? new Array(length) : null;
+            const aborted = Promise.withResolvers();
+            const stopSignal = stopOn ? Promise.withResolvers() : null;
+            let index = 0;
+            let stopped = null;
+            let lastResult = null;
+            let lastIndexResult = null;
+            const worker = async (run) => {
+                while (index < length && (stopOn ? !stopped : true)) {
+                    const i = index++;
+                    const result = (await run(tasks[i]));
+                    lastResult = result;
+                    if (i === length - 1)
+                        lastIndexResult = result;
+                    if (!stopOn) {
+                        if (results)
+                            results[i] = result;
+                        continue;
+                    }
+                    const stop = stopOn === "first" ||
+                        (stopOn === "error" && !result.ok) ||
+                        (stopOn === "success" && result.ok);
+                    if (!stop) {
+                        if (results)
+                            results[i] = result.value;
+                        continue;
+                    }
+                    if (!stopped) {
+                        stopped = result;
+                        abortWorkers(!result.ok && AbortError.is(result.error)
+                            ? result.error.reason
+                            : abortReason);
+                        stopSignal?.resolve();
+                    }
+                    break;
+                }
+                return ok();
+            };
+            let workersAborted = false;
+            const abortWorkers = (reason) => {
+                if (workersAborted)
+                    return;
+                workersAborted = true;
+                for (const worker of workers)
+                    worker.abort(reason);
+            };
+            const workerCount = Math.min(run.concurrency, length);
+            const workers = arrayFrom(workerCount, () => run.daemon(worker));
+            const _ = __addDisposableResource(env_5, new DisposableStack(), false);
+            _.defer(() => {
+                abortWorkers(abortReason);
+            });
+            run.onAbort((reason) => {
+                abortWorkers(reason);
+                aborted.resolve();
+            });
+            const waitFor = [Promise.all(workers), aborted.promise];
+            if (stopSignal)
+                waitFor.push(stopSignal.promise);
+            await Promise.race(waitFor);
+            if (run.signal.aborted) {
+                return err(run.signal.reason);
+            }
+            if (!stopOn)
+                return results ? ok(results) : ok();
+            if (stopped)
+                return stopped;
+            if (results)
+                return ok(results);
+            // For all/allSettled/map/mapSettled with collect: false (no allFailed handler)
+            if (!allFailed)
+                return ok();
+            return allFailed === "completion" ? lastResult : lastIndexResult;
+        }
+        catch (e_5) {
+            env_5.error = e_5;
+            env_5.hasError = true;
+        }
+        finally {
+            __disposeResources(env_5);
+        }
+    };
+}
+/**
+ * Error returned when a {@link fetch} {@link Task} fails.
+ *
+ * @group Composition
+ */
+export const FetchError = /*#__PURE__*/ typed("FetchError", { error: Unknown });
 /**
- * Type guard to check if a {@link MaybeAsync} value is async (a promise).
+ * Creates a {@link Task} that wraps the native
+ * {@link https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API | Fetch API}.
  *
- * This function narrows the type of a {@link MaybeAsync} value, allowing you to
- * conditionally `await` only when necessary.
+ * Handles cross-browser abort behavior — WebKit throws a `DOMException` with
+ * message "Fetch is aborted" instead of propagating `signal.reason`. This
+ * helper normalizes the behavior to always return {@link AbortError}.
  *
  * ### Example
  *
  * ```ts
- * const getData = (id: string): MaybeAsync<Data> => {
- *   const cached = cache.get(id);
- *   if (cached) return cached; // Sync path
- *   return fetchData(id); // Async path
- * };
+ * await using run = createRun();
+ *
+ * const result = await run(fetch("https://api.example.com/users"));
  *
- * const result = getData(id);
- * const data = isAsync(result) ? await result : result;
- * // No microtask overhead when cached!
+ * if (!result.ok) {
+ *   // Handle FetchError or AbortError
+ * }
+ *
+ * // Compose with timeout and retry
+ * const fetchWithRetry = (url: string) =>
+ *   retry(timeout(fetch(url), "10s"), retryStrategyAws);
  * ```
+ *
+ * @group Composition
  */
-export const isAsync = (value) => 
-// eslint-disable-next-line @typescript-eslint/no-unsafe-member-access
-typeof value?.then === "function";
-// TODO: Add tracing support
-// - Extend TaskContext with optional tracing field
-// - Add traced(name, task) helper that wraps Task execution
-// - Collect span data (name, timing, parent-child relationships, status)
-// - Support OpenTelemetry export format with proper traceId/spanId generation
-// - Automatic parent-child span relationships through context propagation
+export const fetch = (input, init) => ({ signal }) => tryAsync(() => globalThis.fetch(input, { ...init, signal }), (error) => {
+    if (AbortError.is(error))
+        return error;
+    // WebKit throws DOMException with message "Fetch is aborted" instead of
+    // propagating signal.reason. Detect this and create AbortError.
+    if (signal.aborted &&
+        error instanceof Error &&
+        error.message === "Fetch is aborted") {
+        return createAbortError(signal.reason);
+    }
+    return { type: "FetchError", error };
+});
+// TODO: Prioritized Task Scheduling API integration
+// https://developer.mozilla.org/en-US/docs/Web/API/Prioritized_Task_Scheduling_API
+//
+// - `run(task, { priority })` - Fiber-level priority via TaskController
+//   (extends AbortController), so the fiber's signal gets priority and all
+//   nested work inherits it.
+// - `fiber.setPriority(priority)` - Dynamic priority changes mid-flight via
+//   TaskController.setPriority().
+//
+// Note: scheduler.yield() inherits priority from enclosing postTask, so
+// yieldNow doesn't need a priority argument — just run the fiber at priority.
+//
+// Safari doesn't support it yet, Node.js probably never will (use setImmediate).
+// For Safari, scheduler-polyfill can be used.
+// https://www.npmjs.com/package/scheduler-polyfill
+// TODO: Do we really need specialized aborts?