brass-runtime 1.13.8 → 1.15.0

package/dist/core/index.d.ts

@@ -0,0 +1,673 @@
+import { A as Async, E as Exit, aa as Runtime } from '../effect-CMOQKX8y.js';
+export { n as AbortablePromiseFinish, o as AbortablePromiseLabelStats, p as AbortablePromiseOptions, q as AbortablePromiseOutcome, r as AbortablePromiseStats, t as AsyncWithPromise, C as CancelToken, v as Canceler, w as Cause, b as Fiber, c as FiberId, d as FiberStatus, _ as Interrupted, a1 as None, a2 as NoopHooks, O as Option, R as RuntimeFiber, ad as RuntimeOptions, S as Scope, ak as ScopeId, al as Some, Z as ZIO, aq as abortablePromiseStats, ar as acquireRelease, as as async, at as asyncCatchAll, au as asyncFail, av as asyncFlatMap, aw as asyncFold, ax as asyncInterruptible, ay as asyncMap, az as asyncMapError, aA as asyncSucceed, aB as asyncSync, aC as asyncTotal, aD as catchAll, aE as end, aG as fail, aH as flatMap, aI as fork, aJ as fromPromiseAbortable, aK as getBenchmarkBudget, aL as getCurrentFiber, aP as linkAbortController, aR as makeCancelToken, aS as map, aT as mapAsync, aU as mapError, aV as mapTryAsync, aW as none, aX as orElseOptional, aY as resetAbortablePromiseStats, a_ as runtimeForCaller, b1 as setBenchmarkBudget, b2 as some, b3 as succeed, b4 as sync, b5 as toPromise, b6 as toPromiseByCaller, b7 as unit, b8 as unsafeGetCurrentRuntime, b9 as unsafeRunAsync, ba as unsafeRunFoldWithEnv, bb as withAsyncPromise, bc as withCurrentFiber, bd as withScope, be as withScopeAsync } from '../effect-CMOQKX8y.js';
+export { C as CircuitBreaker, a as CircuitBreakerConfig, b as CircuitBreakerError, c as CircuitBreakerState, d as CircuitBreakerStats, S as Span, e as SpanContext, f as SpanEvent, g as SpanStatus, T as Tracer, h as TracerConfig, m as makeCircuitBreaker, i as makeTracer } from '../tracing-DNT9jEbr.js';
+
+type TimeoutError = {
+    readonly _tag: "TimeoutError";
+    readonly ms: number;
+};
+/**
+ * Suspends the fiber for `ms` milliseconds. Cancellable via fiber interruption.
+ */
+declare function sleep(ms: number): Async<unknown, never, void>;
+/**
+ * Runs `effect` with a timeout of `ms` milliseconds.
+ * - If the effect completes before the timeout, returns its result.
+ * - If the timeout fires first, the effect is cancelled and a TimeoutError is returned.
+ *
+ * Works with ANY effect type (Async, FlatMap, Fold, etc.) by forking
+ * the effect into a child fiber and interrupting it on timeout.
+ */
+declare function timeout<R, E, A>(effect: Async<R, E, A>, ms: number): Async<R, E | TimeoutError, A>;
+type RetryPolicy = {
+    /** Maximum number of retry attempts (0 = no retries, just the initial attempt) */
+    readonly maxRetries: number;
+    /** Base delay in ms for exponential backoff */
+    readonly baseDelayMs: number;
+    /** Maximum delay cap in ms */
+    readonly maxDelayMs: number;
+    /** Total time budget in ms (optional). Retries stop if elapsed time exceeds this. */
+    readonly maxElapsedMs?: number;
+    /** Custom predicate: should this error trigger a retry? Default: always retry. */
+    readonly shouldRetry?: (error: unknown, attempt: number) => boolean;
+    /** Jitter strategy. Default: "full" (random 0..delay). "none" = no jitter. */
+    readonly jitter?: "full" | "none";
+};
+type RetryState = {
+    readonly attempt: number;
+    readonly elapsedMs: number;
+    readonly lastError: unknown;
+};
+/**
+ * Retries an effect according to the given policy.
+ * Uses exponential backoff with full jitter by default.
+ *
+ * ```ts
+ * const result = retry(
+ *   fetchData(),
+ *   { maxRetries: 3, baseDelayMs: 100, maxDelayMs: 5000 }
+ * );
+ * ```
+ */
+declare function retry<R, E, A>(effect: Async<R, E, A>, policy: RetryPolicy): Async<R, E, A>;
+/**
+ * Retry with a simple count (no backoff, immediate retry).
+ * Useful for flaky operations that just need a few attempts.
+ */
+declare function retryN<R, E, A>(effect: Async<R, E, A>, n: number): Async<R, E, A>;
+/**
+ * Retry with exponential backoff and full jitter.
+ * Convenience wrapper with sensible defaults.
+ */
+declare function retryWithBackoff<R, E, A>(effect: Async<R, E, A>, opts?: {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    maxElapsedMs?: number;
+    shouldRetry?: (error: unknown, attempt: number) => boolean;
+}): Async<R, E, A>;
+
+/**
+ * Acquires a resource, uses it, and guarantees release regardless of outcome.
+ *
+ * - `acquire` runs uninterruptibly (once started, it completes)
+ * - `use` runs with the acquired resource
+ * - `release` runs after `use` completes (success, failure, or interruption)
+ *
+ * ```ts
+ * const result = bracket(
+ *   openConnection(),                    // acquire
+ *   (conn) => queryDatabase(conn),       // use
+ *   (conn, exit) => conn.close()         // release (always runs)
+ * );
+ * ```
+ */
+declare function bracket<R, E, A, B>(acquire: Async<R, E, A>, use: (resource: A) => Async<R, E, B>, release: (resource: A, exit: Exit<E, B>) => Async<R, any, void>): Async<R, E, B>;
+/**
+ * Runs `effect` and then runs `finalizer` regardless of the outcome.
+ * The finalizer receives the exit value for inspection.
+ *
+ * ```ts
+ * const result = ensuring(
+ *   doWork(),
+ *   (exit) => logCompletion(exit)
+ * );
+ * ```
+ */
+declare function ensuring<R, E, A>(effect: Async<R, E, A>, finalizer: (exit: Exit<E, A>) => Async<R, any, void>): Async<R, E, A>;
+/**
+ * A Managed resource describes how to acquire and release a resource.
+ * It can be used multiple times — each `use` call acquires a fresh instance.
+ *
+ * ```ts
+ * const dbPool = managed(
+ *   createPool({ max: 10 }),
+ *   (pool) => pool.close()
+ * );
+ *
+ * // Use it:
+ * const result = useManaged(dbPool, (pool) => pool.query("SELECT 1"));
+ * ```
+ */
+type Managed<R, E, A> = {
+    readonly _tag: "Managed";
+    readonly acquire: Async<R, E, A>;
+    readonly release: (resource: A, exit: Exit<any, any>) => Async<R, any, void>;
+};
+/**
+ * Creates a Managed resource descriptor.
+ */
+declare function managed<R, E, A>(acquire: Async<R, E, A>, release: (resource: A, exit?: Exit<any, any>) => Async<R, any, void>): Managed<R, E, A>;
+/**
+ * Uses a Managed resource: acquires, runs the body, and releases.
+ */
+declare function useManaged<R, E, A, B>(m: Managed<R, E, A>, body: (resource: A) => Async<R, E, B>): Async<R, E, B>;
+/**
+ * Combines multiple Managed resources. All are acquired in order,
+ * and released in reverse order (LIFO).
+ *
+ * ```ts
+ * const resources = managedAll([dbPool, cacheConn, fileHandle]);
+ * const result = useManaged(resources, ([db, cache, file]) => ...);
+ * ```
+ */
+declare function managedAll<R, E, Resources extends readonly any[]>(manageds: {
+    [K in keyof Resources]: Managed<R, E, Resources[K]>;
+}): Managed<R, E, Resources>;
+
+type Semaphore = {
+    /** Current number of available permits. */
+    readonly available: () => number;
+    /** Total number of permits (capacity). */
+    readonly capacity: number;
+    /** Number of effects waiting for a permit. */
+    readonly waiting: () => number;
+    /** Acquire a permit, run the effect, and release the permit. */
+    readonly withPermit: <R, E, A>(effect: Async<R, E, A>) => Async<R, E, A>;
+    /** Acquire a permit (manual). Must call release() when done. */
+    readonly acquire: () => Async<unknown, never, void>;
+    /** Release a permit (manual). */
+    readonly release: () => void;
+};
+type SemaphoreStats = {
+    readonly capacity: number;
+    readonly available: number;
+    readonly waiting: number;
+    readonly acquired: number;
+    readonly released: number;
+};
+/**
+ * Creates a counting semaphore with `n` permits.
+ *
+ * ```ts
+ * const sem = makeSemaphore(5); // max 5 concurrent
+ *
+ * // Automatic acquire/release:
+ * const result = await run(sem.withPermit(fetchData()));
+ *
+ * // Manual acquire/release:
+ * await run(sem.acquire());
+ * try { ... } finally { sem.release(); }
+ * ```
+ */
+declare function makeSemaphore(n: number): Semaphore;
+
+type Ref<A> = {
+    /** Get the current value. */
+    readonly get: () => Async<unknown, never, A>;
+    /** Set a new value. */
+    readonly set: (value: A) => Async<unknown, never, void>;
+    /** Modify the value with a function and return the new value. */
+    readonly update: (f: (current: A) => A) => Async<unknown, never, A>;
+    /** Modify the value and return a derived result. */
+    readonly modify: <B>(f: (current: A) => [B, A]) => Async<unknown, never, B>;
+    /** Get the current value synchronously (for non-effect contexts). */
+    readonly unsafeGet: () => A;
+};
+/**
+ * Creates a mutable reference with an initial value.
+ *
+ * ```ts
+ * const counter = makeRef(0);
+ *
+ * // In effects:
+ * await run(counter.update(n => n + 1));
+ * const value = await run(counter.get());
+ *
+ * // Synchronous access (outside effects):
+ * counter.unsafeGet();
+ * ```
+ */
+declare function makeRef<A>(initial: A): Ref<A>;
+/**
+ * Creates a derived Ref that applies a lens to a parent Ref.
+ *
+ * ```ts
+ * const state = makeRef({ count: 0, name: "test" });
+ * const countRef = derivedRef(state, s => s.count, (s, c) => ({ ...s, count: c }));
+ * ```
+ */
+declare function derivedRef<A, B>(parent: Ref<A>, get: (a: A) => B, set: (a: A, b: B) => A): Ref<B>;
+
+type ScheduleDecision = {
+    readonly continue: boolean;
+    readonly delayMs: number;
+};
+/**
+ * A Schedule<I, O> takes an input I (typically the error or output of an effect)
+ * and decides whether to continue and with what delay.
+ */
+type Schedule<I, O> = {
+    readonly _tag: "Schedule";
+    /** Initial state */
+    readonly initial: () => any;
+    /** Given current state and input, produce a decision and next state */
+    readonly step: (state: any, input: I) => [ScheduleDecision, any, O];
+};
+/** Retry/repeat up to N times with no delay. */
+declare function recurs(n: number): Schedule<unknown, number>;
+/** Fixed delay between each retry/repeat. */
+declare function fixed(delayMs: number): Schedule<unknown, number>;
+/** Exponential backoff: delay doubles each time, capped at maxDelayMs. */
+declare function exponential(baseMs: number, maxMs?: number): Schedule<unknown, number>;
+/** Exponential backoff with full jitter (random in [0, delay]). */
+declare function jittered(baseMs: number, maxMs?: number): Schedule<unknown, number>;
+/** Stop after a total elapsed time. */
+declare function elapsed(maxMs: number): Schedule<unknown, number>;
+/** Only continue while a predicate holds on the input. */
+declare function whileInput<I>(pred: (input: I) => boolean): Schedule<I, I>;
+/** Limit a schedule to N repetitions. */
+declare function take<I, O>(schedule: Schedule<I, O>, n: number): Schedule<I, O>;
+/** Compose two schedules: use the first, then switch to the second. */
+declare function andThen<I, O1, O2>(first: Schedule<I, O1>, second: Schedule<I, O2>): Schedule<I, O1 | O2>;
+/** Run both schedules and continue while BOTH say continue. Use max delay. */
+declare function intersect<I, O1, O2>(left: Schedule<I, O1>, right: Schedule<I, O2>): Schedule<I, [O1, O2]>;
+/** Run both schedules and continue while EITHER says continue. Use min delay. */
+declare function union<I, O1, O2>(left: Schedule<I, O1>, right: Schedule<I, O2>): Schedule<I, [O1, O2]>;
+/**
+ * Retry an effect according to a schedule.
+ * The schedule receives the error as input on each failure.
+ */
+declare function retryWithSchedule<R, E, A, O>(effect: Async<R, E, A>, schedule: Schedule<E, O>): Async<R, E, A>;
+/**
+ * Repeat an effect according to a schedule.
+ * The schedule receives the success value as input on each iteration.
+ * Returns the last successful value.
+ */
+declare function repeatWithSchedule<R, E, A, O>(effect: Async<R, E, A>, schedule: Schedule<A, O>): Async<R, E, A>;
+
+type ShutdownConfig = {
+    /** Max time to wait for in-flight work to complete. Default: 30000ms */
+    readonly timeoutMs?: number;
+    /** Called when shutdown starts. */
+    readonly onStart?: () => void;
+    /** Called when shutdown completes. */
+    readonly onComplete?: (stats: ShutdownStats) => void;
+    /** Called if shutdown times out. */
+    readonly onTimeout?: (stats: ShutdownStats) => void;
+};
+type ShutdownStats = {
+    readonly startedAt: number;
+    readonly completedAt: number;
+    readonly elapsedMs: number;
+    readonly timedOut: boolean;
+};
+/**
+ * Performs a graceful shutdown of the runtime.
+ *
+ * 1. Signals the scheduler to stop accepting new work
+ * 2. Waits for in-flight fibers to complete (up to timeoutMs)
+ * 3. Calls the runtime's shutdown hook
+ * 4. Reports stats
+ *
+ * ```ts
+ * await gracefulShutdown(runtime, {
+ *   timeoutMs: 5000,
+ *   onStart: () => console.log("Shutting down..."),
+ *   onComplete: (stats) => console.log(`Done in ${stats.elapsedMs}ms`),
+ * });
+ * ```
+ */
+declare function gracefulShutdown<R>(runtime: Runtime<R>, config?: ShutdownConfig): Promise<ShutdownStats>;
+/**
+ * Registers process signal handlers for graceful shutdown.
+ * Handles SIGTERM and SIGINT (Ctrl+C).
+ *
+ * ```ts
+ * registerShutdownHooks(runtime, {
+ *   timeoutMs: 10000,
+ *   onComplete: () => process.exit(0),
+ *   onTimeout: () => process.exit(1),
+ * });
+ * ```
+ */
+declare function registerShutdownHooks<R>(runtime: Runtime<R>, config?: ShutdownConfig): () => void;
+
+type TestRuntimeOptions = {
+    /** If true, effects run synchronously where possible. Default: true */
+    readonly synchronous?: boolean;
+};
+/**
+ * Creates a test runtime that provides controlled execution.
+ *
+ * ```ts
+ * const { runtime, run, runExit } = makeTestRuntime();
+ *
+ * const result = await run(myEffect);
+ * const exit = await runExit(myEffect); // get full Exit (success or failure)
+ * ```
+ */
+declare function makeTestRuntime<R = {}>(env?: R, options?: TestRuntimeOptions): {
+    runtime: Runtime<R>;
+    run: <E, A>(effect: Async<R, E, A>) => Promise<A>;
+    runExit: <E, A>(effect: Async<R, E, A>) => Promise<Exit<E, A>>;
+};
+/**
+ * Asserts that an effect succeeds with a specific value.
+ *
+ * ```ts
+ * await assertSucceeds(myEffect, 42);
+ * ```
+ */
+declare function assertSucceeds<R, E, A>(effect: Async<R, E, A>, expected: A, runtime?: Runtime<R>): Promise<void>;
+/**
+ * Asserts that an effect fails with a specific error.
+ *
+ * ```ts
+ * await assertFails(myEffect, "not found");
+ * ```
+ */
+declare function assertFails<R, E, A>(effect: Async<R, E, A>, expectedError: E, runtime?: Runtime<R>): Promise<void>;
+/**
+ * Asserts that an effect fails with an error matching a predicate.
+ *
+ * ```ts
+ * await assertFailsWith(myEffect, (e) => e._tag === "NotFound");
+ * ```
+ */
+declare function assertFailsWith<R, E, A>(effect: Async<R, E, A>, predicate: (error: E) => boolean, runtime?: Runtime<R>): Promise<void>;
+/**
+ * Asserts that an effect completes within a time limit.
+ *
+ * ```ts
+ * await assertCompletesWithin(myEffect, 100); // must finish in 100ms
+ * ```
+ */
+declare function assertCompletesWithin<R, E, A>(effect: Async<R, E, A>, maxMs: number, runtime?: Runtime<R>): Promise<A>;
+/**
+ * Creates an effect that fails on the first N calls, then succeeds.
+ * Useful for testing retry logic.
+ *
+ * ```ts
+ * const flaky = flakyEffect(3, "success!", "temporary error");
+ * // Fails 3 times, then returns "success!"
+ * ```
+ */
+declare function flakyEffect<E, A>(failCount: number, successValue: A, errorValue: E): Async<unknown, E, A>;
+/**
+ * Creates an effect that takes a specific amount of time to complete.
+ * Useful for testing timeouts and concurrency.
+ *
+ * ```ts
+ * const slow = delayedEffect(100, "done"); // completes after 100ms
+ * ```
+ */
+declare function delayedEffect<A>(ms: number, value: A): Async<unknown, never, A>;
+/**
+ * Creates an effect that never completes (hangs forever).
+ * Useful for testing timeouts and interruption.
+ */
+declare function neverEffect<A = never>(): Async<unknown, never, A>;
+
+/**
+ * A Layer describes how to build a service.
+ *
+ * - RIn: dependencies required to build this service
+ * - E: possible failure during construction
+ * - ROut: the service produced
+ */
+type Layer<RIn, E, ROut> = {
+    readonly _tag: "Layer";
+    readonly build: (deps: RIn) => Async<unknown, E, {
+        service: ROut;
+        release: () => Async<unknown, never, void>;
+    }>;
+};
+/**
+ * Creates a Layer from an acquire/release pair.
+ *
+ * ```ts
+ * const DbLayer = layer(
+ *   () => createPool({ max: 10 }),
+ *   (pool) => pool.close()
+ * );
+ * ```
+ */
+declare function layer<ROut, E = never>(acquire: () => Async<unknown, E, ROut>, release?: (service: ROut) => Async<unknown, never, void>): Layer<unknown, E, ROut>;
+/**
+ * Creates a Layer that depends on another service.
+ *
+ * ```ts
+ * const RepoLayer = layerFrom<DbPool>()(
+ *   (pool) => createRepo(pool),
+ *   (repo) => repo.close()
+ * );
+ * ```
+ */
+declare function layerFrom<RIn>(): <ROut, E = never>(acquire: (deps: RIn) => Async<unknown, E, ROut>, release?: (service: ROut) => Async<unknown, never, void>) => Layer<RIn, E, ROut>;
+/**
+ * Creates a Layer from a pure value (no lifecycle).
+ *
+ * ```ts
+ * const ConfigLayer = layerSucceed({ port: 3000, host: "localhost" });
+ * ```
+ */
+declare function layerSucceed<ROut>(value: ROut): Layer<unknown, never, ROut>;
+/**
+ * Creates a Layer that always fails.
+ */
+declare function layerFail<E>(error: E): Layer<unknown, E, never>;
+/**
+ * Compose two layers: the output of `from` feeds into `to`.
+ *
+ * ```ts
+ * const AppLayer = compose(DbLayer, RepoLayer);
+ * // DbLayer produces DbPool → RepoLayer consumes DbPool → produces Repo
+ * ```
+ */
+declare function compose<R1, E1, Mid, E2, ROut>(from: Layer<R1, E1, Mid>, to: Layer<Mid, E2, ROut>): Layer<R1, E1 | E2, ROut>;
+/**
+ * Merge two independent layers into one that produces both services.
+ *
+ * ```ts
+ * const AppLayer = merge(DbLayer, CacheLayer);
+ * // Produces { db: DbPool, cache: CacheClient }
+ * ```
+ */
+declare function merge<R1, E1, A, R2, E2, B>(left: Layer<R1, E1, A>, right: Layer<R2, E2, B>): Layer<R1 & R2, E1 | E2, A & B>;
+/**
+ * Map the output of a layer.
+ */
+declare function mapLayer<RIn, E, A, B>(l: Layer<RIn, E, A>, f: (a: A) => B): Layer<RIn, E, B>;
+/**
+ * Builds a layer, runs an effect with the produced service, and releases.
+ *
+ * ```ts
+ * const result = await run(
+ *   provideLayer(AppLayer, (services) => services.db.query("SELECT 1"))
+ * );
+ * ```
+ */
+declare function provideLayer<RIn, E, ROut, E2, A>(l: Layer<RIn, E, ROut>, use: (service: ROut) => Async<unknown, E2, A>, deps?: RIn): Async<unknown, E | E2, A>;
+
+type WorkerPoolConfig = {
+    /** Number of worker threads. Default: number of CPUs - 1 */
+    readonly size?: number;
+    /** Max queued tasks. Tasks beyond this are rejected. Default: 1000 */
+    readonly maxQueue?: number;
+    /** Task timeout in ms. Default: 30000 */
+    readonly taskTimeoutMs?: number;
+};
+type WorkerPoolError = {
+    readonly _tag: "WorkerPoolFull";
+    readonly queued: number;
+} | {
+    readonly _tag: "WorkerTaskTimeout";
+    readonly ms: number;
+} | {
+    readonly _tag: "WorkerTaskError";
+    readonly message: string;
+} | {
+    readonly _tag: "WorkerPoolClosed";
+};
+type WorkerPool = {
+    /** Execute a function in a worker thread. */
+    readonly execute: <A>(fn: () => A) => Async<unknown, WorkerPoolError, A>;
+    /** Execute a serializable task (function source + args). */
+    readonly run: <A>(taskSource: string, args?: any[]) => Async<unknown, WorkerPoolError, A>;
+    /** Current pool stats. */
+    readonly stats: () => WorkerPoolStats;
+    /** Shutdown the pool (terminate all workers). */
+    readonly shutdown: () => Promise<void>;
+};
+type WorkerPoolStats = {
+    readonly size: number;
+    readonly busy: number;
+    readonly idle: number;
+    readonly queued: number;
+    readonly completed: number;
+    readonly failed: number;
+    readonly timedOut: number;
+};
+/**
+ * Creates a worker pool for CPU-intensive tasks.
+ *
+ * NOTE: This is a simplified implementation that uses setTimeout to simulate
+ * async execution. For real worker_threads support, the pool would need to
+ * spawn actual Worker instances. This provides the API contract and can be
+ * upgraded to real threads when needed.
+ *
+ * ```ts
+ * const pool = makeWorkerPool({ size: 4 });
+ *
+ * const result = await run(pool.execute(() => heavyComputation()));
+ *
+ * await pool.shutdown();
+ * ```
+ */
+declare function makeWorkerPool(config?: WorkerPoolConfig): WorkerPool;
+
+type MetricType = "counter" | "gauge" | "histogram";
+type MetricValue = {
+    readonly name: string;
+    readonly type: MetricType;
+    readonly value: number;
+    readonly labels: Record<string, string>;
+    readonly timestamp: number;
+};
+type HistogramBuckets = {
+    readonly boundaries: readonly number[];
+    counts: number[];
+    sum: number;
+    count: number;
+    min: number;
+    max: number;
+};
+type MetricsRegistry = {
+    /** Create or get a counter. */
+    readonly counter: (name: string, labels?: Record<string, string>) => Counter;
+    /** Create or get a gauge. */
+    readonly gauge: (name: string, labels?: Record<string, string>) => Gauge;
+    /** Create or get a histogram. */
+    readonly histogram: (name: string, boundaries?: number[], labels?: Record<string, string>) => Histogram;
+    /** Get all current metric values. */
+    readonly snapshot: () => MetricSnapshot;
+    /** Reset all metrics. */
+    readonly reset: () => void;
+};
+type Counter = {
+    readonly increment: (n?: number) => void;
+    readonly value: () => number;
+};
+type Gauge = {
+    readonly set: (value: number) => void;
+    readonly increment: (n?: number) => void;
+    readonly decrement: (n?: number) => void;
+    readonly value: () => number;
+};
+type Histogram = {
+    readonly observe: (value: number) => void;
+    readonly buckets: () => HistogramBuckets;
+    readonly percentile: (p: number) => number;
+};
+type MetricSnapshot = {
+    readonly counters: Array<{
+        name: string;
+        labels: Record<string, string>;
+        value: number;
+    }>;
+    readonly gauges: Array<{
+        name: string;
+        labels: Record<string, string>;
+        value: number;
+    }>;
+    readonly histograms: Array<{
+        name: string;
+        labels: Record<string, string>;
+        buckets: HistogramBuckets;
+    }>;
+};
+/**
+ * Creates a metrics registry.
+ *
+ * ```ts
+ * const metrics = makeMetrics();
+ *
+ * const requestCount = metrics.counter("http_requests_total", { method: "GET" });
+ * requestCount.increment();
+ *
+ * const latency = metrics.histogram("http_request_duration_ms");
+ * latency.observe(42.5);
+ *
+ * const activeConns = metrics.gauge("active_connections");
+ * activeConns.set(10);
+ *
+ * console.log(metrics.snapshot());
+ * ```
+ */
+declare function makeMetrics(): MetricsRegistry;
+
+/**
+ * Base type for tagged errors. All errors should extend this pattern:
+ *
+ * ```ts
+ * type NetworkError = { _tag: "NetworkError"; url: string; status: number };
+ * type TimeoutError = { _tag: "TimeoutError"; ms: number };
+ * type AppError = NetworkError | TimeoutError;
+ * ```
+ */
+type TaggedError = {
+    readonly _tag: string;
+};
+/**
+ * Catches a specific error by its `_tag` field and handles it.
+ * Other errors pass through unchanged.
+ *
+ * ```ts
+ * const result = catchTag(effect, "NetworkError", (e) => fallbackValue);
+ * // e is narrowed to NetworkError
+ * ```
+ */
+declare function catchTag<R, E extends TaggedError, A, Tag extends E["_tag"], B>(effect: Async<R, E, A>, tag: Tag, handler: (error: Extract<E, {
+    _tag: Tag;
+}>) => Async<R, Exclude<E, {
+    _tag: Tag;
+}>, A | B>): Async<R, Exclude<E, {
+    _tag: Tag;
+}>, A | B>;
+/**
+ * Catches multiple error tags with a single handler map.
+ *
+ * ```ts
+ * const result = catchTags(effect, {
+ *   NetworkError: (e) => asyncSucceed(defaultValue),
+ *   TimeoutError: (e) => retry(effect),
+ * });
+ * ```
+ */
+declare function catchTags<R, E extends TaggedError, A, Handlers extends Partial<{
+    [K in E["_tag"]]: (error: Extract<E, {
+        _tag: K;
+    }>) => Async<R, any, any>;
+}>>(effect: Async<R, E, A>, handlers: Handlers): Async<R, Exclude<E, {
+    _tag: keyof Handlers & string;
+}>, A>;
+/**
+ * Maps the error channel of an effect.
+ *
+ * ```ts
+ * const result = mapError(effect, (e) => ({ _tag: "Wrapped", cause: e }));
+ * ```
+ */
+declare function mapError<R, E, E2, A>(effect: Async<R, E, A>, f: (error: E) => E2): Async<R, E2, A>;
+/**
+ * Wraps any error with a tag, making it part of a discriminated union.
+ *
+ * ```ts
+ * const typed = tagError(fetchData(), "NetworkError", (e) => ({ url, cause: e }));
+ * // Error type becomes { _tag: "NetworkError"; url: string; cause: unknown }
+ * ```
+ */
+declare function tagError<R, E, A, Tag extends string, Fields extends Record<string, unknown>>(effect: Async<R, E, A>, tag: Tag, enrich?: (error: E) => Fields): Async<R, {
+    _tag: Tag;
+} & Fields, A>;
+/**
+ * If the effect fails, run the fallback instead.
+ *
+ * ```ts
+ * const result = orElse(primary(), () => fallback());
+ * ```
+ */
+declare function orElse<R, E, A, R2, E2, B>(effect: Async<R, E, A>, fallback: (error: E) => Async<R2, E2, B>): Async<R & R2, E2, A | B>;
+
+export { Async, type Counter, Exit, type Gauge, type Histogram, type HistogramBuckets, type Layer, type Managed as ManagedResource, type MetricSnapshot, type MetricType, type MetricValue, type MetricsRegistry, type Ref, type RetryPolicy, type RetryState, Runtime, type Schedule, type ScheduleDecision, type Semaphore, type SemaphoreStats, type ShutdownConfig, type ShutdownStats, type TaggedError, type TestRuntimeOptions, type TimeoutError, type WorkerPool, type WorkerPoolConfig, type WorkerPoolError, type WorkerPoolStats, andThen as andThenSchedule, assertCompletesWithin, assertFails, assertFailsWith, assertSucceeds, bracket, catchTag, catchTags, compose as composeLayer, delayedEffect, derivedRef, elapsed, ensuring, exponential, fixed, flakyEffect, gracefulShutdown, intersect, jittered, layer, layerFail, layerFrom, layerSucceed, makeMetrics, makeRef, makeSemaphore, makeTestRuntime, makeWorkerPool, managed, managedAll, mapError as mapErrorTyped, mapLayer, merge as mergeLayer, neverEffect, orElse, provideLayer, recurs, registerShutdownHooks, repeatWithSchedule, retry, retryN, retryWithBackoff, retryWithSchedule, sleep, tagError, take as takeSchedule, timeout, union, useManaged, whileInput };