brass-runtime 1.14.0 → 1.16.0

package/dist/http/index.d.ts

@@ -1,188 +1,178 @@
-import { A as Async, a as AsyncWithPromise } from '../effect-DM56H743.js';
-import { Z as ZStream, C as CircuitBreakerConfig, T as Tracer } from '../stream-Oqe6WeLE.js';
-
-type RetryPolicy = {
-    maxRetries: number;
-    baseDelayMs: number;
-    maxDelayMs: number;
-    /** Optional total retry budget, including request attempts and sleeps. */
-    maxElapsedMs?: number;
-    /** Defaults to true. When true, Retry-After is honored but capped by maxDelayMs/budget. */
-    respectRetryAfter?: boolean;
-    retryOnMethods?: HttpMethod[];
-    retryOnStatus?: (status: number) => boolean;
-    retryOnError?: (e: HttpError) => boolean;
-    /** Strict engine selector for retry planning. Defaults to ts. */
-    engine?: "ts" | "wasm";
-    /** Back-compat knob: wasm=true maps to engine="wasm", wasm=false maps to engine="ts". */
-    wasm?: boolean;
-};
-
-type HttpPoolKeyResolver = "global" | "origin" | "host" | ((req: HttpRequest, url: URL) => string);
-type HttpPoolConfig = {
-    /** Max concurrent downstream calls per resolved key. */
-    readonly concurrency?: number;
-    /** Max queued waiters per key. `0` means fail fast when the pool is full. */
-    readonly maxQueue?: number;
-    /** Max time a request may wait for a pool slot before failing fast. */
-    readonly queueTimeoutMs?: number;
-    /** How to isolate pools. Default: `origin`; useful values: `global`, `host`, `origin`. */
-    readonly key?: HttpPoolKeyResolver;
-    /**
-     * Strict engine selector for permit governance. Defaults to ts.
-     * - ts: TypeScript permit pool.
-     * - wasm: require BrassWasmHttpPermitPool from wasm/pkg; never falls back.
-     */
-    readonly engine?: "ts" | "wasm";
-    /** Back-compat knob: wasm=true maps to engine="wasm", wasm=false maps to engine="ts". */
-    readonly wasm?: boolean;
-};
-type HttpPoolKeyStats = {
-    readonly key: string;
-    readonly running: number;
-    readonly queued: number;
-    readonly concurrency: number;
-    readonly maxQueue: number;
-    readonly acquired: number;
-    readonly released: number;
-    readonly rejected: number;
-    readonly queueTimeouts: number;
-    readonly abortedWhileQueued: number;
-};
-type HttpPoolStats = {
-    readonly running: number;
-    readonly queued: number;
-    readonly acquired: number;
-    readonly released: number;
-    readonly rejected: number;
-    readonly queueTimeouts: number;
-    readonly abortedWhileQueued: number;
-    readonly wasm?: unknown;
-    readonly keys: HttpPoolKeyStats[];
-};
-type HttpPoolLease = {
-    readonly key: string;
-    release: () => void;
-};
-declare function resolveHttpPoolKey(resolver: HttpPoolKeyResolver | undefined, req: HttpRequest, url: URL): string;
-declare class HttpConcurrencyPool {
-    private readonly states;
-    private readonly concurrency;
-    private readonly maxQueue;
-    private readonly queueTimeoutMs;
-    readonly keyResolver: HttpPoolKeyResolver | undefined;
-    private readonly wasm;
-    private readonly wasmWaiters;
-    private wasmTimer;
-    private nextSubjectId;
-    constructor(config?: HttpPoolConfig);
-    acquire(key: string, signal: AbortSignal): Promise<HttpPoolLease>;
-    stats(): HttpPoolStats;
-    private acquireJs;
-    private acquireWasm;
-    private getState;
-    private makeLease;
-    private drain;
-    private handleWasmGrants;
-    private handleWasmTimeouts;
-    private scheduleWasmTimeoutPump;
-    private cleanupWaiter;
-    private removeWaiter;
-    private allocateSubjectId;
+import { e as HttpClientFn, c as HttpError, b as HttpWireResponse, a as HttpRequest, d as HttpMiddleware, R as RetryPolicy, H as HttpClient, M as MakeHttpConfig, f as HttpWireResponseStream, g as HttpClientStream, h as HttpClientStats, i as AdaptiveLimiter, j as AdaptiveLimiterConfig, k as HttpMethod, l as AdaptiveLimiterPreset, m as HttpPoolConfig } from '../client-CtFmoDvM.js';
+export { n as AdaptiveAcquireOptions, o as AdaptiveBaselineStrategy, p as AdaptiveHeadroomContext, q as AdaptiveHeadroomMode, r as AdaptiveHeadroomStrategy, s as AdaptiveLease, t as AdaptiveLimiterDiagnostics, u as AdaptiveLimiterKeySnapshot, A as AdaptiveLimiterStats, v as AdaptiveQueueLoadShedding, w as AdaptiveQueueStrategy, x as AdaptiveReleaseInfo, y as HttpBody, z as HttpClientStreamFn, B as HttpConcurrencyPool, C as HttpInit, D as HttpPoolKeyResolver, E as HttpPoolKeyStats, F as HttpPoolLease, G as HttpPoolStats, L as LimitChangeEvent, P as PerRequestRetryOverride, I as ResolvedConfig, J as RetryEvent, K as RetryScheduleInput, N as adaptiveLimiterPresets, O as backoffDelayMs, Q as decorate, S as defaultRetryOnError, T as defaultRetryOnStatus, U as defaultRetryableMethods, V as makeAdaptiveLimiterConfig, W as makeHttp, X as makeHttpStream, Y as normalizeHeadersInit, Z as normalizeRetryBudget, _ as resolveConfig, $ as resolveHttpPoolKey, a0 as retryAfterMs, a1 as validateConfig, a2 as withMiddleware, a3 as withRetry, a4 as withRetryStream } from '../client-CtFmoDvM.js';
+import { A as Async, C as AsyncWithPromise, f as Runtime, h as RuntimeOptions } from '../effect-CGNl5Rqp.js';
+import { SchemaIssue, JsonSchemaLike, AnyJsonSchemaLike, InferJsonSchema } from '../schema/index.js';
+export { AnySchema, ConfigValidationError, InferObject, InferSchema, JsonValidator, JsonValidatorResult, NumberSchemaOptions, ObjectSchemaOptions, Schema, SchemaPathPart, SchemaResult, SchemaShape, SchemaValidationException, StringSchemaOptions, formatIssues, isSchema, makeSchemaIssue, parseConfig, s, schema, validateValue } from '../schema/index.js';
+import { g as CircuitBreakerConfig, h as CircuitBreakerError } from '../tracer-B5tRH9H7.js';
+import { T as Tracer, R as Resource } from '../tracing-Dt9S_6V8.js';
+import { Server } from 'node:http';
+import { AddressInfo } from 'node:net';
+import { S as Schedule } from '../schedule-Fque9Abz.js';
+import { O as Observability, p as HttpServerObservabilityOptions, Z as RuntimeHealthOptions } from '../server-C8hDXA74.js';
+import '../stream-dvSs0QS5.js';
+
+/**
+ * A fixed-size circular buffer that stores latency samples and supports
+ * efficient min and percentile computation using the nearest-rank method.
+ *
+ * The ring preserves eviction order while `sorted` keeps an exact sorted view.
+ * Recording is O(windowSize) because it removes/inserts by binary search +
+ * splice, but percentile reads are O(1) and avoid sorting on every call.
+ */
+declare class LatencyWindow {
+    private readonly buffer;
+    private readonly sorted;
+    private readonly size;
+    private head;
+    private count;
+    constructor(size: number);
+    /**
+     * Record a latency sample. Discards non-positive, NaN, and Infinity values.
+     * Evicts the oldest sample when the buffer is full.
+     */
+    record(latencyMs: number): void;
+    /**
+     * Returns the minimum latency in the current window, or undefined if empty.
+     */
+    min(): number | undefined;
+    /**
+     * Computes the percentile using the nearest-rank method.
+     * Returns undefined if fewer than 2 samples are present.
+     * @param p - Percentile value in [0, 100]
+     */
+    percentile(p: number): number | undefined;
+    /**
+     * Computes a percentile where newer samples receive exponentially higher
+     * weight. A decay of 1 is identical to `percentile`; lower values adapt
+     * faster to recent latency shifts.
+     */
+    weightedPercentile(p: number, decay: number): number | undefined;
+    /** Number of samples currently in the window. */
+    get length(): number;
+    /** Maximum capacity of the window. */
+    get capacity(): number;
+    /** Returns a copy of the current samples (oldest to newest). */
+    samples(): number[];
+    private insertSorted;
+    private removeSorted;
+    private lowerBound;
 }
 
-type HttpError = {
-    _tag: "Abort";
-} | {
-    _tag: "BadUrl";
-    message: string;
-} | {
-    _tag: "FetchError";
-    message: string;
-} | {
-    _tag: "Timeout";
-    timeoutMs: number;
-    message: string;
-    phase?: "request" | "queue" | "retry";
-} | {
-    _tag: "PoolRejected";
-    key: string;
-    limit: number;
-    message: string;
+/**
+ * Exponential Moving Average computer.
+ * Smooths latency samples using the formula: ema = α * sample + (1 - α) * previous_ema
+ */
+declare class EmaComputer {
+    private readonly alpha;
+    private current;
+    /**
+     * @param alpha - Smoothing factor in (0, 1]. Higher values weight recent samples more.
+     */
+    constructor(alpha: number);
+    /**
+     * Update the EMA with a new sample and return the new EMA value.
+     * On the first sample, the EMA is initialized to that sample.
+     */
+    update(sample: number): number;
+    /** Returns the current EMA value, or undefined if no samples have been recorded. */
+    get value(): number | undefined;
+    /** Resets the EMA state. */
+    reset(): void;
+}
+
+/**
+ * Computes the gradient as the ratio of minimum latency to current (smoothed) latency.
+ * A gradient < 1.0 indicates latency is increasing (saturation).
+ * A gradient >= 1.0 indicates latency is stable or decreasing.
+ */
+declare function computeGradient(minLatency: number, currentLatency: number): number;
+/**
+ * Computes the new concurrency limit based on the gradient.
+ *
+ * - If gradient < decreaseThreshold: decrease toward `currentLimit * gradient`
+ * - If gradient >= increaseThreshold: newLimit = currentLimit + headroom
+ * - Otherwise: hold the current limit
+ *
+ * Decreases are capped by `maxDecreaseRatio` so a single noisy latency sample
+ * cannot collapse concurrency.
+ *
+ * The result is clamped to [minBound, maxBound].
+ */
+declare function computeNewLimit(currentLimit: number, gradient: number, headroom: number, minBound: number, maxBound: number, options?: {
+    readonly decreaseThreshold?: number;
+    readonly increaseThreshold?: number;
+    readonly maxDecreaseRatio?: number;
+}): number;
+
+type ValidationError = {
+    readonly _tag: "ValidationError";
+    readonly message: string;
+    readonly body: string;
+    readonly issues: readonly SchemaIssue[];
+    readonly phase?: "request" | "response";
+    readonly schema?: string;
+};
+type JsonDecodeResult<A> = {
+    readonly success: true;
+    readonly data: A;
 } | {
-    _tag: "PoolTimeout";
-    key: string;
-    timeoutMs: number;
-    message: string;
+    readonly success: false;
+    readonly error: ValidationError;
 };
-type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
-type HttpInit = Omit<RequestInit, "method" | "body" | "headers">;
-type HttpRequest = {
-    method: HttpMethod;
-    url: string;
-    headers?: Record<string, string>;
-    body?: string;
-    init?: HttpInit;
-    /** Per-request override for `MakeHttpConfig.timeoutMs`. */
+declare function decodeJsonBody<A = unknown>(bodyText: string, validator?: JsonSchemaLike<A>, options?: {
+    readonly schemaName?: string;
+}): JsonDecodeResult<A>;
+declare function encodeJsonBodyEffect(bodyObj: unknown, validator?: JsonSchemaLike<any>, options?: {
+    readonly schemaName?: string;
+}): Async<unknown, ValidationError, string>;
+declare function decodeJsonBodyEffect<A = unknown>(bodyText: string, validator?: JsonSchemaLike<A>, options?: {
+    readonly schemaName?: string;
+}): Async<unknown, ValidationError, A>;
+declare function validatedJson<A>(client: HttpClientFn, validator: JsonSchemaLike<A>): (req: Parameters<HttpClientFn>[0]) => Async<unknown, HttpError | ValidationError, A>;
+declare function validatedJsonResponse<A>(client: HttpClientFn, validator: JsonSchemaLike<A>): (req: Parameters<HttpClientFn>[0]) => Async<unknown, HttpError | ValidationError, HttpWireResponse & {
+    readonly body: A;
+}>;
+
+type InitNoMethodBody$1 = Omit<RequestInit, "method" | "body"> & {
     timeoutMs?: number;
-    /** Optional stable key for downstream isolation. When omitted, the pool uses origin/host/global config. */
     poolKey?: string;
+    headers?: any;
 };
-type HttpWireResponse = {
-    status: number;
-    statusText: string;
-    headers: Record<string, string>;
-    bodyText: string;
-    ms: number;
+type JsonInitNoSchema$1 = InitNoMethodBody$1 & {
+    schema?: undefined;
+    schemaName?: string;
 };
-type HttpClientStats = {
-    readonly inFlight: number;
-    readonly started: number;
-    readonly succeeded: number;
-    readonly failed: number;
-    readonly aborted: number;
-    readonly timedOut: number;
-    readonly poolRejected: number;
-    readonly poolTimeouts: number;
-    readonly lastDurationMs?: number;
-    readonly pool?: HttpPoolStats;
-};
-type MakeHttpConfig = {
-    baseUrl?: string;
-    headers?: Record<string, string>;
-    /** Request budget covering pool wait + fetch + body read. Disabled when omitted. */
-    timeoutMs?: number;
-    /** Downstream pool/concurrency limiter. Disabled by default to preserve existing behavior. */
-    pool?: false | HttpPoolConfig;
+type JsonInitWithSchema<Validator extends AnyJsonSchemaLike> = InitNoMethodBody$1 & {
+    schema: Validator;
+    schemaName?: string;
 };
-type HttpWireResponseStream = {
-    status: number;
-    statusText: string;
-    headers: Record<string, string>;
-    body: ZStream<unknown, HttpError, Uint8Array>;
-    ms: number;
+type PostJsonInitNoSchema$1 = AnyInitWithHeaders & {
+    schema?: undefined;
+    schemaName?: string;
+    bodySchema?: undefined;
+    bodySchemaName?: string;
 };
-type HttpClientStreamFn = (req: HttpRequest) => Async<unknown, HttpError, HttpWireResponseStream>;
-type HttpClientStream = HttpClientStreamFn & {
-    stats: () => HttpClientStats;
+type PostJsonInitWithBodySchema<BodyValidator extends AnyJsonSchemaLike> = AnyInitWithHeaders & {
+    schema?: undefined;
+    schemaName?: string;
+    bodySchema: BodyValidator;
+    bodySchemaName?: string;
 };
-type HttpClientFn = (req: HttpRequest) => Async<unknown, HttpError, HttpWireResponse>;
-type HttpMiddleware = (next: HttpClientFn) => HttpClientFn;
-type HttpClient = HttpClientFn & {
-    with: (mw: HttpMiddleware) => HttpClient;
-    stats: () => HttpClientStats;
+type PostJsonInitWithSchema<Validator extends AnyJsonSchemaLike> = AnyInitWithHeaders & {
+    schema: Validator;
+    schemaName?: string;
+    bodySchema?: undefined;
+    bodySchemaName?: string;
 };
-declare const decorate: (run: HttpClientFn, stats?: () => HttpClientStats) => HttpClient;
-declare const withMiddleware: (mw: HttpMiddleware) => (c: HttpClient) => HttpClient;
-declare const normalizeHeadersInit: (h: any) => Record<string, string> | undefined;
-declare function makeHttpStream(cfg?: MakeHttpConfig): HttpClientStream;
-declare function makeHttp(cfg?: MakeHttpConfig): HttpClient;
-declare const withRetryStream: (p: RetryPolicy) => (next: HttpClientStream) => HttpClientStream;
-
-type InitNoMethodBody = Omit<RequestInit, "method" | "body"> & {
-    timeoutMs?: number;
-    poolKey?: string;
-    headers?: any;
+type PostJsonInitWithSchemaAndBody<Validator extends AnyJsonSchemaLike, BodyValidator extends AnyJsonSchemaLike> = AnyInitWithHeaders & {
+    schema: Validator;
+    schemaName?: string;
+    bodySchema: BodyValidator;
+    bodySchemaName?: string;
+};
+type AnyJsonInit = InitNoMethodBody$1 & {
+    schema?: AnyJsonSchemaLike;
+    schemaName?: string;
 };
 type HttpMeta = {
     request: HttpRequest;
@@ -214,9 +204,17 @@ type Dx = {
     request: (req: HttpRequest) => AsyncWithPromise<unknown, HttpError, HttpWireResponse>;
     get: (url: string, init?: AnyInitWithHeaders) => AsyncWithPromise<unknown, HttpError, HttpWireResponse>;
     post: (url: string, body?: string, init?: AnyInitWithHeaders) => AsyncWithPromise<unknown, HttpError, HttpWireResponse>;
-    getText: (url: string, init?: InitNoMethodBody) => AsyncWithPromise<unknown, HttpError, HttpResponse<string>>;
-    getJson: <A>(url: string, init?: InitNoMethodBody) => AsyncWithPromise<unknown, HttpError, HttpResponse<A>>;
-    postJson: <A>(url: string, bodyObj: unknown, init?: AnyInitWithHeaders) => AsyncWithPromise<unknown, HttpError, HttpResponse<A>>;
+    getText: (url: string, init?: InitNoMethodBody$1) => AsyncWithPromise<unknown, HttpError, HttpResponse<string>>;
+    getJson: {
+        <Validator extends AnyJsonSchemaLike>(url: string, init: JsonInitWithSchema<Validator>): AsyncWithPromise<unknown, HttpError | ValidationError, HttpResponse<InferJsonSchema<Validator>>>;
+        <A = unknown>(url: string, init?: JsonInitNoSchema$1): AsyncWithPromise<unknown, HttpError | ValidationError, HttpResponse<A>>;
+    };
+    postJson: {
+        <Validator extends AnyJsonSchemaLike, BodyValidator extends AnyJsonSchemaLike>(url: string, bodyObj: InferJsonSchema<BodyValidator>, init: PostJsonInitWithSchemaAndBody<Validator, BodyValidator>): AsyncWithPromise<unknown, HttpError | ValidationError, HttpResponse<InferJsonSchema<Validator>>>;
+        <BodyValidator extends AnyJsonSchemaLike, A = unknown>(url: string, bodyObj: InferJsonSchema<BodyValidator>, init: PostJsonInitWithBodySchema<BodyValidator>): AsyncWithPromise<unknown, HttpError | ValidationError, HttpResponse<A>>;
+        <Validator extends AnyJsonSchemaLike>(url: string, bodyObj: unknown, init: PostJsonInitWithSchema<Validator>): AsyncWithPromise<unknown, HttpError | ValidationError, HttpResponse<InferJsonSchema<Validator>>>;
+        <A = unknown>(url: string, bodyObj: unknown, init?: PostJsonInitNoSchema$1): AsyncWithPromise<unknown, HttpError | ValidationError, HttpResponse<A>>;
+    };
     with: (mw: HttpMiddleware) => Dx;
     withRetry: (p: RetryPolicy) => Dx;
     wire: HttpClient;
@@ -228,11 +226,11 @@ declare function httpClientWithMeta(cfg?: MakeHttpConfig): {
         wire: HttpWireResponse;
         meta: HttpMeta;
     }>;
-    get: (url: string, init?: InitNoMethodBody) => AsyncWithPromise<unknown, HttpError, {
+    get: (url: string, init?: InitNoMethodBody$1) => AsyncWithPromise<unknown, HttpError, {
         wire: HttpWireResponse;
         meta: HttpMeta;
     }>;
-    getText: (url: string, init?: InitNoMethodBody) => AsyncWithPromise<unknown, HttpError, {
+    getText: (url: string, init?: InitNoMethodBody$1) => AsyncWithPromise<unknown, HttpError, {
         wire: HttpWireResponse;
         response: {
             status: number;
@@ -242,37 +240,30 @@ declare function httpClientWithMeta(cfg?: MakeHttpConfig): {
         };
         meta: HttpMeta;
     }>;
-    getJson: <A>(url: string, init?: InitNoMethodBody) => AsyncWithPromise<unknown, HttpError, {
+    getJson: <A>(url: string, init?: AnyJsonInit) => AsyncWithPromise<unknown, HttpError | ValidationError, {
         wire: HttpWireResponse;
-        response: {
-            status: number;
-            statusText: string;
-            headers: Record<string, string>;
-            body: A;
-        };
+        response: HttpResponse<A>;
         meta: HttpMeta;
     }>;
-    post: (url: string, body?: string, init?: InitNoMethodBody) => AsyncWithPromise<unknown, HttpError, {
+    post: (url: string, body?: string, init?: InitNoMethodBody$1) => AsyncWithPromise<unknown, HttpError, {
         wire: HttpWireResponse;
         meta: HttpMeta;
     }>;
-    postJson: <A>(url: string, bodyObj: unknown, init?: HttpInit & {
-        headers?: Record<string, string>;
-    }) => AsyncWithPromise<unknown, HttpError, {
+    postJson: <A>(url: string, bodyObj: unknown, init?: AnyInitWithHeaders & {
+        schema?: AnyJsonSchemaLike;
+        schemaName?: string;
+        bodySchema?: AnyJsonSchemaLike;
+        bodySchemaName?: string;
+    }) => AsyncWithPromise<unknown, HttpError | ValidationError, {
         wire: HttpWireResponse;
-        response: {
-            status: number;
-            statusText: string;
-            headers: Record<string, string>;
-            body: A;
-        };
+        response: HttpResponse<A>;
         meta: HttpMeta;
     }>;
 };
 declare function httpClientStream(cfg?: MakeHttpConfig): {
     request: (req: HttpRequest) => AsyncWithPromise<unknown, HttpError, HttpWireResponseStream>;
-    getStream: (url: string, init?: InitNoMethodBody) => AsyncWithPromise<unknown, HttpError, HttpWireResponseStream>;
-    get: (url: string, init?: InitNoMethodBody) => AsyncWithPromise<unknown, HttpError, HttpWireResponseStream>;
+    getStream: (url: string, init?: InitNoMethodBody$1) => AsyncWithPromise<unknown, HttpError, HttpWireResponseStream>;
+    get: (url: string, init?: InitNoMethodBody$1) => AsyncWithPromise<unknown, HttpError, HttpWireResponseStream>;
     with: (mw: (n: HttpClientStream) => HttpClientStream) => /*elided*/ any;
     withRetry: (p: RetryPolicy) => /*elided*/ any;
     wire: HttpClientStream;
@@ -282,6 +273,10 @@ declare function httpClientStream(cfg?: MakeHttpConfig): {
 type HttpCircuitBreakerConfig = CircuitBreakerConfig & {
     /** Key resolver for per-origin circuit breakers. Default: per-origin. */
     perOrigin?: boolean;
+    /** Optional limiter to notify when this breaker is already/opened. Defaults to `next.adaptiveLimiter` when available. */
+    adaptiveLimiter?: Pick<AdaptiveLimiter, "keyResolver" | "markCircuitOpen">;
+    /** Optional resolver when the limiter key differs from the request URL origin/global fallback. */
+    adaptiveLimiterKey?: (req: HttpRequest) => string;
 };
 /**
  * HTTP middleware that wraps requests in a circuit breaker.
@@ -294,34 +289,2109 @@ declare function withCircuitBreaker(config?: HttpCircuitBreakerConfig): HttpMidd
  */
 declare function withTracing(tracer: Tracer): HttpMiddleware;
 
-type ValidationError = {
-    _tag: "ValidationError";
-    message: string;
+type KnownHttpError = HttpError | ValidationError | CircuitBreakerError;
+type KnownHttpErrorTag = KnownHttpError["_tag"];
+type HttpErrorHandlers<R> = {
+    readonly [K in KnownHttpErrorTag]?: (error: Extract<KnownHttpError, {
+        readonly _tag: K;
+    }>) => R;
+} & {
+    readonly default?: (error: unknown) => R;
+};
+declare function isHttpError(error: unknown): error is HttpError;
+declare function isValidationError(error: unknown): error is ValidationError;
+declare function isCircuitBreakerOpen(error: unknown): error is CircuitBreakerError;
+declare function isKnownHttpError(error: unknown): error is KnownHttpError;
+declare function matchHttpError<R>(error: unknown, handlers: HttpErrorHandlers<R>): R | undefined;
+declare function formatHttpError(error: unknown): string;
+
+/**
+ * Developer-provided function that defines how to combine multiple requests
+ * into one and split the response back.
+ *
+ * @typeParam K - The item type extracted from individual requests, ensuring
+ *   type consistency between coalesce and split.
+ */
+type BatchFunction<K> = {
+    /**
+     * Combines multiple HttpRequest objects into a single batched HttpRequest.
+     * The items array corresponds 1:1 with the requests array.
+     */
+    coalesce: (requests: readonly HttpRequest[]) => HttpRequest;
+    /**
+     * Splits the batched response back into individual responses.
+     * Must return an array of the same length as the original requests array.
+     */
+    split: (response: HttpWireResponse, requests: readonly HttpRequest[]) => HttpWireResponse[];
+};
+/**
+ * Configuration for the Batch_Middleware.
+ *
+ * @typeParam K - The item type linking coalesce and split operations.
+ */
+type BatchConfig<K = unknown> = {
+    /** The batch function defining coalesce/split logic. Required. */
+    batch: BatchFunction<K>;
+    /**
+     * Time window in milliseconds to collect requests before dispatching.
+     * Valid range: [1, 5000]. Required.
+     */
+    windowMs: number;
+    /**
+     * Maximum number of requests in a single batch.
+     * When reached, the batch dispatches immediately.
+     * Valid range: [2, 10000]. Required.
+     */
+    maxBatchSize: number;
+    /**
+     * Computes the Batch_Key from a request.
+     * Requests with the same key are batched together.
+     * Return empty string to bypass batching for a request.
+     * Throwing bypasses batching for that request.
+     */
+    batchKey: (req: HttpRequest) => string;
+};
+/**
+ * Optional observer callback for batch lifecycle events.
+ */
+type BatchEventCallback = (event: {
+    type: "batch-hit" | "batch-dispatch";
+    batchKey: string;
+    batchSize?: number;
+}) => void;
+/**
+ * Creates a Batch_Middleware that collects requests by Batch_Key during
+ * a time window and dispatches them as a single batched request.
+ *
+ * @typeParam K - Inferred from the provided BatchFunction.
+ * @param config - Batch configuration.
+ * @param onEvent - Optional lifecycle event observer.
+ * @returns An HttpMiddleware conforming to (next: HttpClientFn) => HttpClientFn.
+ */
+declare function withBatch<K>(config: BatchConfig<K>, onEvent?: BatchEventCallback): HttpMiddleware;
+
+/**
+ * Status of a pre-warm probe result.
+ */
+type PrewarmResultStatus = "warmed" | "already-warm" | "failed" | "cancelled";
+/**
+ * Result of a single pre-warm probe operation.
+ */
+type PrewarmResult = {
+    /** The origin that was probed. */
+    origin: string;
+    /** Outcome of the probe operation. */
+    status: PrewarmResultStatus;
+    /** Duration of the probe in milliseconds (0 for "already-warm"). */
+    durationMs: number;
+    /** Error information if status is "failed". */
+    error?: string;
+};
+/**
+ * Event types emitted by the PrewarmManager during connection state changes.
+ */
+type PrewarmEventType = "connection-warmed" | "connection-expired" | "connection-failed" | "connection-cancelled";
+/**
+ * An event emitted by the PrewarmManager to notify observers of connection state changes.
+ */
+type PrewarmEvent = {
+    /** The type of prewarm event. */
+    type: PrewarmEventType;
+    /** The origin associated with the event. */
+    origin: string;
+    /** Timestamp (ms) when the event occurred. */
+    timestamp: number;
+    /** Duration of the probe in milliseconds, if applicable. */
+    durationMs?: number;
+    /** Error information, if applicable. */
+    error?: string;
+};
+/**
+ * Per-origin connection state in the state machine.
+ */
+type PrewarmOriginStatus = "idle" | "probing" | "warm" | "expired";
+/**
+ * State information for a single managed origin.
+ */
+type PrewarmOriginState = {
+    /** The origin string. */
+    origin: string;
+    /** Current state of the origin. */
+    status: PrewarmOriginStatus;
+    /** Timestamp of the last successful probe, if any. */
+    lastProbeAt?: number;
+    /** Timestamp until which the connection is considered warm. */
+    warmUntil?: number;
+};
+/**
+ * Snapshot of all managed origins and their current states.
+ */
+type PrewarmStatusSnapshot = {
+    /** State of each managed origin. */
+    origins: PrewarmOriginState[];
+};
+/**
+ * Configuration for creating a PrewarmManager.
+ */
+type PrewarmConfig = {
+    /** Origins to pre-warm. Each must be a valid URL origin (scheme + host + optional port). */
+    origins: string[];
+    /** Keep-alive duration in ms. Default: 55000. */
+    keepAliveDurationMs?: number;
+    /** Max concurrent in-flight probes. Default: 4. */
+    budget?: number;
+    /** Probe timeout in ms. Default: 5000. */
+    probeTimeoutMs?: number;
+    /** Auto-refresh expired connections. Default: false. */
+    autoRefresh?: boolean;
+    /** Route probes through the Wire_Client pool. Default: false. */
+    useClientPool?: boolean;
+    /** Optional Wire_Client to use when useClientPool is true. */
+    client?: HttpClientFn;
+    /** Event observer callback. */
+    onEvent?: (event: PrewarmEvent) => void;
+};
+
+/**
+ * Configuration for the prewarm layer within the lifecycle client.
+ *
+ * When provided to `makeLifecycleClient`, the lifecycle client creates and manages
+ * a PrewarmManager internally, triggering pre-warming based on the `afterResponse` hook.
+ */
+type PrewarmLifecycleConfig = {
+    /** Origins to pre-warm at client creation. */
+    origins?: string[];
+    /** Hook called after each successful response to determine origins to pre-warm. */
+    afterResponse?: (response: HttpWireResponse, request: HttpRequest) => string[];
+    /** Keep-alive duration in ms. Default: 55000. */
+    keepAliveDurationMs?: number;
+    /** Max concurrent in-flight probes. Default: 4. */
+    budget?: number;
+    /** Probe timeout in ms. Default: 5000. */
+    probeTimeoutMs?: number;
+    /** Auto-refresh expired connections. Default: false. */
+    autoRefresh?: boolean;
+    /** Route probes through the Wire_Client pool. Default: false. */
+    useClientPool?: boolean;
+    /** Event observer for prewarm events. */
+    onEvent?: (event: PrewarmEvent) => void;
+};
+/**
+ * Configuration for the deduplication layer.
+ *
+ * When enabled, the dedup layer collapses concurrent identical requests into a single
+ * in-flight Async_Effect, sharing the response across all callers with the same Cache_Key.
+ *
+ * @property {function} [dedupKey] - Custom key function that computes a dedup key from an HttpRequest.
+ *   When provided, overrides the default Cache_Key computation. Default: undefined (uses default key derivation).
+ */
+type DedupConfig$1 = {
+    /** Custom key function. When provided, overrides default Cache_Key computation. */
+    dedupKey?: (req: HttpRequest) => string;
+    /** Internal lifecycle observer. Public callers should prefer LifecycleClientConfig.onEvent. */
+    onEvent?: (event: {
+        type: "dedup-hit" | "dedup-miss" | "dedup-active";
+        cacheKey?: string;
+        active?: number;
+    }) => void;
+};
+/**
+ * Configuration for the response cache layer.
+ *
+ * Controls how responses are stored and retrieved from the in-memory LRU cache.
+ * Each cached entry is keyed by its deterministic Cache_Key.
+ *
+ * @property {number} [ttlSeconds] - Time-to-live in seconds for cached entries. Default: 60. Valid range: [1, 86400].
+ * @property {number} [maxEntries] - Maximum number of cached entries before LRU eviction. Default: 1024. Valid range: >= 1.
+ * @property {boolean} [staleWhileRevalidate] - When true, serves stale cache entries while revalidating in the background. Default: false.
+ * @property {function} [cachePolicy] - Custom cache policy function that determines cacheability and optional TTL override for a given request/response pair. Default: undefined (uses built-in policy).
+ * @property {string[]} [cacheRelevantHeaders] - Additional HTTP headers to include in Cache_Key computation beyond the defaults. Default: undefined (uses DEFAULT_CACHE_RELEVANT_HEADERS).
+ */
+type CacheConfig$1 = {
+    /** Time-to-live in seconds. Default: 60. Range: [1, 86400]. */
+    ttlSeconds?: number;
+    /** Maximum number of cached entries. Default: 1024. Minimum: 1. */
+    maxEntries?: number;
+    /** Enable stale-while-revalidate. Default: false. */
+    staleWhileRevalidate?: boolean;
+    /** Custom cache policy function. */
+    cachePolicy?: (req: HttpRequest, res: HttpWireResponse) => CachePolicyResult$1;
+    /** Additional headers to include in Cache_Key computation. */
+    cacheRelevantHeaders?: string[];
+    /** Cache-specific observer for stale revalidation failures. */
+    onEvent?: (event: {
+        type: string;
+        cacheKey?: string;
+        error?: any;
+    }) => void;
+    /** Internal lifecycle observer. Public callers should prefer LifecycleClientConfig.onEvent. */
+    onLifecycleEvent?: (event: {
+        type: "cache-hit" | "cache-miss" | "cache-eviction";
+        cacheKey?: string;
+        count?: number;
+    }) => void;
+};
+/**
+ * Result of a custom cache policy evaluation.
+ *
+ * Returned by the `cachePolicy` function in {@link CacheConfig} to control
+ * whether a response should be stored in the cache and for how long.
+ *
+ * @property {boolean} cacheable - Whether the response should be cached. Required.
+ * @property {number} [ttlSeconds] - Optional TTL override in seconds. When provided, takes precedence over the global CacheConfig ttlSeconds. Valid range: [1, 86400].
+ */
+type CachePolicyResult$1 = {
+    /** Whether the response should be cached. */
+    cacheable: boolean;
+    /** Optional TTL override in seconds. */
+    ttlSeconds?: number;
+};
+/**
+ * Configuration for the priority scheduler layer.
+ *
+ * The priority scheduler orders outgoing requests by priority level and limits
+ * concurrency to prevent overwhelming the downstream Wire_Client.
+ *
+ * @property {number} [concurrency] - Maximum concurrent requests dispatched by the priority scheduler. Default: 32. Valid range: >= 1.
+ * @property {number} [queueTimeoutMs] - Queue timeout in milliseconds for priority-queued requests. When a request waits longer than this value, it is rejected. Default: undefined (no timeout).
+ */
+type PriorityConfig$1 = {
+    /** Maximum concurrent requests dispatched by the priority scheduler. Default: 32. Valid range: >= 1. */
+    concurrency?: number;
+    /** Queue timeout in ms for priority-queued requests. Default: no timeout. */
+    queueTimeoutMs?: number;
+    /** Internal lifecycle observer. Public callers should prefer LifecycleClientConfig.onEvent. */
+    onEvent?: (event: {
+        type: "queue-enqueue" | "queue-dispatch";
+        priority: number;
+    }) => void;
+};
+/**
+ * Configuration for creating a lifecycle client.
+ *
+ * Extends MakeHttpConfig with optional lifecycle layer configurations.
+ * Each layer (dedup, cache, priority) can be configured with an options object
+ * or explicitly disabled by setting it to `false`. When omitted, the layer is disabled
+ * (zero-cost when disabled).
+ *
+ * @property {DedupConfig | false} [dedup] - Dedup layer configuration. Set to an object to enable with options, or `false` to explicitly disable. Default: undefined (disabled).
+ * @property {CacheConfig | false} [cache] - Cache layer configuration. Set to an object to enable with options, or `false` to explicitly disable. Default: undefined (disabled).
+ * @property {PriorityConfig | false} [priority] - Priority scheduler configuration. Set to an object to enable with options, or `false` to explicitly disable. Default: undefined (disabled).
+ * @property {function} [onEvent] - Optional event observer callback invoked for each {@link LifecycleEvent} during request processing. Default: undefined.
+ */
+type LifecycleClientConfig = MakeHttpConfig & {
+    /** Dedup layer config. Set to `false` to explicitly disable. Default: undefined (disabled). */
+    dedup?: DedupConfig$1 | false;
+    /** Batch layer config. Set to `false` to explicitly disable. Default: undefined (disabled). */
+    batch?: BatchConfig | false;
+    /** Cache layer config. Set to `false` to explicitly disable. Default: undefined (disabled). */
+    cache?: CacheConfig$1 | false;
+    /** Priority scheduler config. Set to `false` to explicitly disable. Default: undefined (disabled). */
+    priority?: PriorityConfig$1 | false;
+    /** Retry policy. Set to `false` to explicitly disable. Default: undefined (disabled). */
+    retry?: RetryPolicy | false;
+    /** Prewarm layer config. Set to `false` to explicitly disable. Default: undefined (disabled). */
+    prewarm?: PrewarmLifecycleConfig | false;
+    /** Adaptive concurrency limiter config. Set to `false` to explicitly disable. Default: undefined (disabled). */
+    adaptiveLimiter?: AdaptiveLimiterConfig | false;
+    /** Optional event observer for lifecycle events. */
+    onEvent?: (event: LifecycleEvent) => void;
+};
+/**
+ * The lifecycle client interface.
+ *
+ * A callable HTTP client function (Wire_Client wrapper) with additional lifecycle
+ * management methods. Supports middleware composition via `.with()`, statistics
+ * via `.stats()`, and bulk cancellation via `.cancelAll()`.
+ *
+ * @property {function} with - Apply middleware, returning a new LifecycleClient with the middleware applied.
+ * @property {function} stats - Return a frozen snapshot of {@link LifecycleStats}.
+ * @property {function} cancelAll - Cancel all in-flight and queued requests, returning an Async_Effect that resolves when cancellation is complete.
+ * @property {object} cache - Cache management methods for manual invalidation.
+ * @property {function} cache.invalidate - Invalidate a specific cache entry by its Cache_Key.
+ * @property {function} cache.clear - Clear all cache entries.
+ */
+type LifecycleClient = HttpClientFn & {
+    /** Apply middleware, returning a new LifecycleClient with the middleware applied. */
+    with: (mw: HttpMiddleware) => LifecycleClient;
+    /** Return a frozen snapshot of lifecycle statistics. */
+    stats: () => LifecycleStats;
+    /** Cancel all in-flight and queued requests. Returns an Async_Effect that resolves when complete. */
+    cancelAll: () => Async<unknown, never, void>;
+    /** Cancel active work and release owned resources such as adaptive limiter timers. */
+    shutdown: () => Async<unknown, never, void>;
+    /** Adaptive limiter owned by the underlying wire client, when enabled. */
+    adaptiveLimiter?: AdaptiveLimiter;
+    /** Cache management methods. */
+    cache: {
+        /** Invalidate a specific cache entry by Cache_Key. */
+        invalidate: (key: string) => void;
+        /** Clear all cache entries. */
+        clear: () => void;
+    };
+};
+/**
+ * Lifecycle event types emitted during request processing.
+ *
+ * Each value represents a distinct point in the lifecycle pipeline:
+ * - `"request-start"` — Emitted when a request enters the lifecycle pipeline.
+ * - `"request-end"` — Emitted when a request completes (success or failure).
+ * - `"cache-hit"` — Emitted when a response is served from the cache.
+ * - `"cache-miss"` — Emitted when a request misses the cache and proceeds to the Wire_Client.
+ * - `"dedup-hit"` — Emitted when a request is collapsed into an existing in-flight Async_Effect.
+ * - `"dedup-miss"` — Emitted when a request initiates a new in-flight Async_Effect (no existing match).
+ * - `"queue-enqueue"` — Emitted when a request is enqueued in the priority scheduler.
+ * - `"queue-dispatch"` — Emitted when a queued request is dispatched to the Wire_Client.
+ * - `"retry"` — Emitted when the retry middleware schedules another attempt.
+ */
+type LifecycleEventType = "request-start" | "request-end" | "cache-hit" | "cache-miss" | "dedup-hit" | "dedup-miss" | "queue-enqueue" | "queue-dispatch" | "retry" | "batch-hit" | "batch-dispatch" | "limit-change";
+/**
+ * A lifecycle event emitted to the onEvent observer.
+ *
+ * Provides observability into the lifecycle pipeline by reporting events
+ * as they occur during request processing.
+ *
+ * @property {LifecycleEventType} type - The type of lifecycle event. Required.
+ * @property {number} timestamp - Timestamp in milliseconds (from `Date.now()`) when the event occurred. Required.
+ * @property {string} [cacheKey] - The Cache_Key associated with the event, if applicable (present for cache and dedup events).
+ * @property {number} [priority] - Priority level associated with the event, if applicable (present for queue events). Valid range: 0-9.
+ * @property {number} [attempt] - Zero-based retry attempt, if applicable.
+ * @property {number} [delayMs] - Retry delay in milliseconds, if applicable.
+ * @property {number} [status] - HTTP status that triggered retry, if applicable.
+ * @property {string} [errorTag] - HttpError tag that triggered retry, if applicable.
+ */
+type LifecycleEvent = {
+    /** The type of lifecycle event. */
+    type: LifecycleEventType;
+    /** Timestamp (ms) when the event occurred. */
+    timestamp: number;
+    /** Cache_Key associated with the event, if applicable. */
+    cacheKey?: string;
+    /** Priority level associated with the event, if applicable. Valid range: 0-9. */
+    priority?: number;
+    /** Batch_Key associated with the event, if applicable. Present for batch events. */
+    batchKey?: string;
+    /** Number of requests in the batch, if applicable. Present for batch-dispatch events. */
+    batchSize?: number;
+    /** Zero-based retry attempt, if applicable. */
+    attempt?: number;
+    /** Retry delay in milliseconds, if applicable. */
+    delayMs?: number;
+    /** HTTP status that triggered retry, if applicable. */
+    status?: number;
+    /** HttpError tag that triggered retry, if applicable. */
+    errorTag?: string;
+    /** Previous concurrency limit, present for limit-change events. */
+    previousLimit?: number;
+    /** New concurrency limit, present for limit-change events. */
+    newLimit?: number;
+    /** Gradient value, present for limit-change events. */
+    gradient?: number;
+    /** Smoothed latency value, present for limit-change events. */
+    smoothedLatency?: number;
+};
+/**
+ * Lifecycle statistics snapshot.
+ *
+ * All counters start at zero and increase monotonically. Returned as a frozen
+ * object by {@link LifecycleClient.stats}.
+ *
+ * @property {number} cacheHits - Number of cache hits (responses served from cache). Default: 0.
+ * @property {number} cacheMisses - Number of cache misses (requests forwarded to Wire_Client). Default: 0.
+ * @property {number} cacheEvictions - Number of cache evictions triggered by LRU policy. Default: 0.
+ * @property {number} dedupHits - Number of dedup hits (requests collapsed into an existing in-flight Async_Effect). Default: 0.
+ * @property {number} dedupActive - Number of currently active dedup groups (in-flight unique Cache_Keys). Default: 0.
+ * @property {number} queueDepth - Current depth of the priority queue (requests waiting to be dispatched). Default: 0.
+ * @property {number} requestsStarted - Total number of requests that entered the lifecycle pipeline. Default: 0.
+ * @property {number} requestsCompleted - Total number of requests that completed successfully. Default: 0.
+ * @property {number} requestsFailed - Total number of requests that failed with an error. Default: 0.
+ * @property {number} retries - Total number of retry attempts scheduled. Default: 0.
+ * @property {HttpClientStats} wire - Underlying Wire_Client statistics snapshot.
+ */
+type LifecycleStats = {
+    /** Number of cache hits. */
+    cacheHits: number;
+    /** Number of cache misses. */
+    cacheMisses: number;
+    /** Number of cache evictions (LRU). */
+    cacheEvictions: number;
+    /** Number of dedup hits (requests collapsed into existing in-flight Async_Effect). */
+    dedupHits: number;
+    /** Number of currently active dedup groups. */
+    dedupActive: number;
+    /** Current depth of the priority queue. */
+    queueDepth: number;
+    /** Total number of requests started. */
+    requestsStarted: number;
+    /** Total number of requests completed successfully. */
+    requestsCompleted: number;
+    /** Total number of requests that failed. */
+    requestsFailed: number;
+    /** Total number of retry attempts scheduled. */
+    retries: number;
+    /** Total number of batch dispatches. */
+    batchDispatches: number;
+    /** Total number of individual requests that were coalesced into batches. */
+    batchedRequests: number;
+    /** Underlying Wire_Client stats. */
+    wire: HttpClientStats;
+};
+/**
+ * Per-request lifecycle options that can be passed alongside a request.
+ *
+ * Allows fine-grained control over lifecycle behavior on a per-request basis,
+ * overriding the client-level configuration for individual requests.
+ *
+ * @property {number} [priority] - Priority level for this request. Valid range: 0-9 (0 = highest priority). Default: 5.
+ * @property {string} [dedupKey] - Custom dedup key override for this request. When provided, overrides the computed Cache_Key for dedup purposes. Default: undefined.
+ * @property {boolean} [noCache] - When true, bypasses the cache layer for this request (neither reads from nor writes to cache). Default: false.
+ * @property {boolean} [noDedup] - When true, bypasses the dedup layer for this request (always creates a new in-flight Async_Effect). Default: false.
+ */
+type LifecycleRequestOptions = {
+    /** Priority level 0-9 (0 = highest). Default: 5. Valid range: 0-9. */
+    priority?: number;
+    /** Custom dedup key override for this request. */
+    dedupKey?: string;
+    /** Skip cache for this request. Default: false. */
+    noCache?: boolean;
+    /** Skip dedup for this request. Default: false. */
+    noDedup?: boolean;
+};
+
+/**
+ * Creates a lifecycle-aware HTTP client that composes deduplication, caching,
+ * and priority scheduling layers on top of the Wire_Client.
+ *
+ * When no layers are configured, the client delegates directly to the underlying
+ * Wire_Client with zero additional overhead (zero-cost when disabled). Each layer
+ * is independently optional and can be set to `false` to explicitly disable.
+ *
+ * Layer composition order (outermost to innermost):
+ * - User middleware (applied via `.with()`)
+ * - Dedup layer (if enabled)
+ * - Cache layer (if enabled)
+ * - Priority layer (if enabled)
+ * - Wire_Client (`makeHttp`)
+ *
+ * @param config - Lifecycle client configuration extending `MakeHttpConfig` with optional layer settings.
+ *   - `config.baseUrl` — Base URL prepended to relative request paths.
+ *   - `config.headers` — Default headers merged into every request.
+ *   - `config.timeoutMs` — Request budget in milliseconds covering pool wait + fetch + body read.
+ *   - `config.dedup` — Deduplication layer config or `false` to disable.
+ *     - `config.dedup.dedupKey` — Custom key function overriding default key computation.
+ *   - `config.cache` — Response cache layer config or `false` to disable.
+ *     - `config.cache.ttlSeconds` — Time-to-live in seconds; integer between 1 and 86400 (default: 60).
+ *     - `config.cache.maxEntries` — Maximum cached entries; integer >= 1 (default: 1024).
+ *     - `config.cache.staleWhileRevalidate` — Enable stale-while-revalidate (default: false).
+ *     - `config.cache.cachePolicy` — Custom cache policy function.
+ *     - `config.cache.cacheRelevantHeaders` — Additional headers included in Cache_Key computation.
+ *   - `config.priority` — Priority scheduler layer config or `false` to disable.
+ *     - `config.priority.concurrency` — Maximum concurrent dispatched requests; integer >= 1 (default: 32).
+ *     - `config.priority.queueTimeoutMs` — Queue timeout in milliseconds for priority-queued requests.
+ *   - `config.onEvent` — Optional observer callback invoked on each lifecycle event.
+ *
+ * @returns A {@link LifecycleClient} instance that is callable as an `HttpClientFn` and exposes
+ *   `.with()` for middleware composition, `.stats()` for observability, `.cancelAll()` for
+ *   bulk cancellation, and `.cache` for cache management.
+ *
+ * @example
+ * ```typescript
+ * import { makeLifecycleClient } from "./index";
+ * import type { LifecycleClientConfig } from "./index";
+ *
+ * const config: LifecycleClientConfig = {
+ *   baseUrl: "https://api.example.com",
+ *   cache: { ttlSeconds: 120, maxEntries: 512 },
+ *   priority: { concurrency: 8 },
+ *   dedup: {},
+ * };
+ *
+ * const client = makeLifecycleClient(config);
+ *
+ * // Execute a GET request through all lifecycle layers
+ * const response = client({ method: "GET", url: "/users" });
+ * ```
+ */
+declare function makeLifecycleClient(config?: LifecycleClientConfig): LifecycleClient;
+/**
+ * Canonical production HTTP client factory.
+ *
+ * Alias of {@link makeLifecycleClient}; kept as the recommended public name
+ * for callers that want the stable wire -> priority -> retry -> cache -> dedup
+ * lifecycle pipeline without importing lower-level building blocks.
+ *
+ * @param config - Lifecycle client configuration with optional wire, retry, cache, dedup, and priority settings.
+ * @returns A lifecycle-aware HTTP client with stats, cache controls, middleware composition, and `cancelAll`.
+ */
+declare function makeHttpClient(config?: LifecycleClientConfig): LifecycleClient;
+
+/**
+ * Components of a parsed Cache_Key, representing the individual parts
+ * that make up a deterministic cache key string.
+ *
+ * @property method - The HTTP method (uppercase), e.g. "GET", "POST"
+ * @property resolvedUrl - The fully resolved URL including base URL resolution
+ * @property headers - Cache-relevant headers as key-value pairs (lowercase keys)
+ * @property body - The request body string, or empty string if no body was present
+ */
+type CacheKeyComponents = {
+    method: string;
+    resolvedUrl: string;
+    headers: Record<string, string>;
     body: string;
-    schema?: string;
 };
-type JsonValidator<A> = (data: unknown) => {
-    success: true;
-    data: A;
-} | {
-    success: false;
-    error: string;
+/**
+ * Null character (`\u0000`) used as a separator between Cache_Key components.
+ *
+ * This non-printable character is chosen because it cannot appear in valid HTTP
+ * method names, URLs, or header values, ensuring unambiguous key parsing via
+ * `parseCacheKey`.
+ */
+declare const SEPARATOR = "\0";
+/**
+ * Default set of HTTP headers included in Cache_Key computation.
+ *
+ * Value: `["accept", "authorization", "content-type"]`
+ *
+ * These headers are always factored into the cache key to ensure that requests
+ * with different content negotiation, authentication, or body encoding are
+ * cached separately. Additional headers can be included via the `extraHeaders`
+ * parameter of `computeCacheKey` or the `cacheRelevantHeaders` option in `CacheConfig`.
+ */
+declare const DEFAULT_CACHE_RELEVANT_HEADERS: string[];
+/**
+ * Computes a deterministic Cache_Key string from an HTTP request.
+ *
+ * The key is composed of: method (uppercase), resolved URL, sorted filtered headers,
+ * and body — concatenated with null character separators. The resulting string
+ * uniquely identifies a cacheable request and can be round-tripped via `parseCacheKey`.
+ *
+ * @param req - The HTTP request to compute a Cache_Key for
+ * @param baseUrl - Base URL for resolving relative request URLs
+ * @param extraHeaders - Additional header names to include in the Cache_Key beyond
+ *   the defaults in `DEFAULT_CACHE_RELEVANT_HEADERS`
+ * @returns A deterministic Cache_Key string suitable for use as a cache lookup key
+ *
+ * @example
+ * ```typescript
+ * import { computeCacheKey } from "./cacheKey";
+ *
+ * const key = computeCacheKey(
+ *   { method: "GET", url: "/users", headers: { accept: "application/json" } },
+ *   "https://api.example.com"
+ * );
+ * // key is a deterministic string encoding method, URL, headers, and body
+ * ```
+ */
+declare function computeCacheKey(req: HttpRequest, baseUrl: string, extraHeaders?: string[]): string;
+/**
+ * Parses a Cache_Key string back into its component parts.
+ *
+ * Splits on the null character separator and reconstructs the `CacheKeyComponents` object.
+ * The body may contain separator characters, so all parts after the third separator
+ * are joined back together as the body. This enables round-trip fidelity with
+ * `computeCacheKey`.
+ *
+ * @param key - A Cache_Key string produced by `computeCacheKey`
+ * @returns The parsed `CacheKeyComponents` with method, resolvedUrl, headers, and body
+ *
+ * @example
+ * ```typescript
+ * import { computeCacheKey, parseCacheKey } from "./cacheKey";
+ *
+ * const key = computeCacheKey(
+ *   { method: "POST", url: "/data", headers: { "content-type": "application/json" }, body: '{"id":1}' },
+ *   "https://api.example.com"
+ * );
+ * const parts = parseCacheKey(key);
+ * // parts.method === "POST"
+ * // parts.resolvedUrl === "https://api.example.com/data"
+ * // parts.headers === { "content-type": "application/json" }
+ * // parts.body === '{"id":1}'
+ * ```
+ */
+declare function parseCacheKey(key: string): CacheKeyComponents;
+
+/**
+ * Event object passed to the `withLogging` middleware's logger callback on each
+ * request lifecycle phase (request, response, or error).
+ *
+ * @property phase - The lifecycle phase that triggered this event: `"request"` before
+ *   the request is sent, `"response"` on success, or `"error"` on failure.
+ * @property req - The original HttpRequest being executed.
+ * @property res - The HttpWireResponse received from the server. Present only when
+ *   `phase` is `"response"`.
+ * @property error - The HttpError that occurred. Present only when `phase` is `"error"`.
+ * @property durationMs - Elapsed time in milliseconds since the request was initiated.
+ *   Present only when `phase` is `"response"` or `"error"`.
+ */
+type LogEvent = {
+    phase: "request" | "response" | "error";
+    req: HttpRequest;
+    res?: HttpWireResponse;
+    error?: HttpError;
+    durationMs?: number;
 };
 /**
- * Creates a validated JSON getter that checks the response body against a schema.
+ * Creates a middleware that injects a Bearer token into the Authorization header.
+ * The token is obtained asynchronously via the provided `tokenProvider` Async_Effect.
+ * If the token provider fails, the error propagates to the caller unchanged.
  *
- * Usage:
- * ```ts
- * const getUser = validatedJson<User>(client, (data) => {
- *   if (typeof data === "object" && data !== null && "id" in data) {
- *     return { success: true, data: data as User };
- *   }
- *   return { success: false, error: "Invalid user shape" };
- * });
+ * @param tokenProvider - A function returning an Async_Effect that resolves to the
+ *   Bearer token string. Called on every request to support token rotation.
+ * @returns An HttpMiddleware that prepends `Authorization: Bearer <token>` to outgoing requests.
+ *
+ * @example
+ * ```typescript
+ * import { makeLifecycleClient, withAuth } from "./index";
+ * import { asyncSucceed } from "../../core/types/asyncEffect";
+ *
+ * const client = makeLifecycleClient({ baseUrl: "https://api.example.com" })
+ *   .with(withAuth(() => asyncSucceed("my-secret-token")));
  *
- * const user = await run(getUser({ method: "GET", url: "/users/1" }));
+ * // All requests now include Authorization: Bearer my-secret-token
+ * const result = client({ method: "GET", url: "/users" });
  * ```
  */
-declare function validatedJson<A>(client: HttpClientFn, validator: JsonValidator<A>): (req: Parameters<HttpClientFn>[0]) => Async<unknown, HttpError | ValidationError, A>;
+declare function withAuth(tokenProvider: () => Async<unknown, HttpError, string>): HttpMiddleware;
+/**
+ * Creates a middleware that logs request, response, and error events through a
+ * user-supplied logger callback. The logger is invoked synchronously at each phase;
+ * if it throws, the error is swallowed to avoid disrupting the request pipeline.
+ *
+ * @param logger - A synchronous callback invoked with a {@link LogEvent} for each
+ *   lifecycle phase (`"request"`, `"response"`, `"error"`). Exceptions thrown by
+ *   the logger are silently caught.
+ * @returns An HttpMiddleware that instruments requests with logging side-effects.
+ *
+ * @example
+ * ```typescript
+ * import { makeLifecycleClient, withLogging } from "./index";
+ * import type { LogEvent } from "./index";
+ *
+ * const client = makeLifecycleClient({ baseUrl: "https://api.example.com" })
+ *   .with(withLogging((event: LogEvent) => {
+ *     console.log(`[${event.phase}] ${event.req.method} ${event.req.url} ${event.durationMs ?? ""}ms`);
+ *   }));
+ *
+ * const result = client({ method: "GET", url: "/health" });
+ * ```
+ */
+declare function withLogging(logger: (event: LogEvent) => void): HttpMiddleware;
+/**
+ * Creates a middleware that transforms HTTP responses after retrieval. The
+ * transformation is applied to both cached and network responses. Cached
+ * responses are stored in their original (untransformed) form, so the transform
+ * runs on every access.
+ *
+ * If the transform function throws, the error is propagated as a `FetchError`.
+ *
+ * @param fn - A synchronous function that receives the response and the original
+ *   request, and returns a modified HttpWireResponse. Must not return `undefined`.
+ * @returns An HttpMiddleware that applies the transform to every successful response.
+ *
+ * @example
+ * ```typescript
+ * import { makeLifecycleClient, withResponseTransform } from "./index";
+ *
+ * const client = makeLifecycleClient({ baseUrl: "https://api.example.com" })
+ *   .with(withResponseTransform((res, req) => ({
+ *     ...res,
+ *     headers: { ...res.headers, "x-request-url": req.url },
+ *   })));
+ *
+ * // Responses now include the x-request-url header
+ * const result = client({ method: "GET", url: "/data" });
+ * ```
+ */
+declare function withResponseTransform(fn: (res: HttpWireResponse, req: HttpRequest) => HttpWireResponse): HttpMiddleware;
+
+/**
+ * Configuration for the LRU cache.
+ *
+ * @property maxEntries - Maximum number of entries the cache can hold.
+ *   Must be >= 1. Values less than 1 are clamped to 1. Fractional values are floored.
+ *   Default: 1024.
+ * @property onEvict - Optional callback invoked when entries are evicted from the cache.
+ *   Receives the number of entries evicted in that operation (currently always 1).
+ *
+ * @example
+ * ```typescript
+ * import { LRUCache } from "./lruCache";
+ *
+ * const cache = new LRUCache<string>({ maxEntries: 100, onEvict: (n) => console.log(`Evicted ${n}`) });
+ * ```
+ */
+type LRUCacheConfig = {
+    /** Maximum number of entries. Must be >= 1. Default: 1024. */
+    maxEntries?: number;
+    /** Optional callback invoked with the number of entries evicted on each eviction. */
+    onEvict?: (count: number) => void;
+};
+/**
+ * A generic LRU (Least Recently Used) cache with per-entry TTL support.
+ *
+ * Uses a doubly-linked list combined with a Map for O(1) get, set, and eviction
+ * operations. The head of the list is the most recently used entry; the tail is
+ * the least recently used.
+ *
+ * When the cache exceeds `maxEntries`, the least recently used entry is evicted.
+ * Expired entries are lazily removed on access (get).
+ *
+ * @example
+ * ```typescript
+ * import { LRUCache } from "./lruCache";
+ *
+ * const cache = new LRUCache<string>({ maxEntries: 256 });
+ * cache.set("user:1", "Alice", 60_000); // TTL of 60 seconds
+ * const value = cache.get("user:1");    // "Alice" (moves to head)
+ * cache.delete("user:1");               // true
+ * ```
+ */
+declare class LRUCache<V> {
+    private readonly map;
+    private head;
+    private tail;
+    private readonly maxEntries;
+    private readonly onEvict;
+    /**
+     * Creates a new LRU cache instance.
+     *
+     * @param config - Cache configuration options.
+     * @param config.maxEntries - Maximum number of entries. Must be >= 1. Default: 1024.
+     * @param config.onEvict - Optional eviction callback.
+     *
+     * @example
+     * ```typescript
+     * import { LRUCache } from "./lruCache";
+     *
+     * const cache = new LRUCache<number>({ maxEntries: 50 });
+     * ```
+     */
+    constructor(config?: LRUCacheConfig);
+    /**
+     * Returns the number of entries currently in the cache.
+     *
+     * @returns The current entry count.
+     *
+     * @example
+     * ```typescript
+     * import { LRUCache } from "./lruCache";
+     *
+     * const cache = new LRUCache<string>();
+     * cache.set("a", "1", 10_000);
+     * console.log(cache.size); // 1
+     * ```
+     */
+    get size(): number;
+    /**
+     * Retrieves a value by key.
+     *
+     * Returns `undefined` if the key is not found or the entry has expired.
+     * On a hit (non-expired), the entry is moved to the head (most recently used).
+     * Expired entries are lazily removed on access.
+     *
+     * @param key - The cache key to look up.
+     * @returns The cached value, or `undefined` if not found or expired.
+     *
+     * @example
+     * ```typescript
+     * import { LRUCache } from "./lruCache";
+     *
+     * const cache = new LRUCache<string>();
+     * cache.set("greeting", "hello", 30_000);
+     * const val = cache.get("greeting"); // "hello"
+     * const miss = cache.get("unknown"); // undefined
+     * ```
+     */
+    get(key: string): V | undefined;
+    /**
+     * Inserts or updates an entry in the cache.
+     *
+     * If the key already exists, the value and TTL are updated and the entry is
+     * moved to the head. If inserting a new entry causes the cache to exceed
+     * `maxEntries` (must be >= 1), the least recently used entry is evicted.
+     *
+     * @param key - The cache key.
+     * @param value - The value to store.
+     * @param ttlMs - Time-to-live in milliseconds. The entry expires after this duration.
+     *
+     * @example
+     * ```typescript
+     * import { LRUCache } from "./lruCache";
+     *
+     * const cache = new LRUCache<string>({ maxEntries: 2 });
+     * cache.set("a", "alpha", 60_000);
+     * cache.set("b", "beta", 60_000);
+     * cache.set("c", "gamma", 60_000); // evicts "a" (LRU)
+     * ```
+     */
+    set(key: string, value: V, ttlMs: number): void;
+    /**
+     * Removes an entry by key.
+     *
+     * @param key - The cache key to remove.
+     * @returns `true` if the entry was found and removed, `false` otherwise.
+     *
+     * @example
+     * ```typescript
+     * import { LRUCache } from "./lruCache";
+     *
+     * const cache = new LRUCache<string>();
+     * cache.set("x", "value", 10_000);
+     * cache.delete("x"); // true
+     * cache.delete("x"); // false (already removed)
+     * ```
+     */
+    delete(key: string): boolean;
+    /**
+     * Removes all entries from the cache, resetting it to an empty state.
+     *
+     * @example
+     * ```typescript
+     * import { LRUCache } from "./lruCache";
+     *
+     * const cache = new LRUCache<string>();
+     * cache.set("a", "1", 10_000);
+     * cache.clear();
+     * console.log(cache.size); // 0
+     * ```
+     */
+    clear(): void;
+    /** Adds a node to the head of the list (most recently used position). */
+    private addToHead;
+    /** Removes a node from its current position in the list. */
+    private removeNode;
+    /** Moves an existing node to the head of the list. */
+    private moveToHead;
+    /** Evicts the tail node (least recently used) and notifies via callback. */
+    private evictTail;
+}
+
+/**
+ * Clamps a priority value to the valid range [0, 9].
+ *
+ * - Truncates toward zero (removes fractional part)
+ * - Clamps the result to the integer range 0 through 9
+ * - Returns a default of 5 for `undefined`, `NaN`, or non-finite values
+ *
+ * @param value - The priority value to clamp. Must be an integer from 0 to 9.
+ *   Values outside this range are clamped. Undefined or non-finite values default to 5.
+ * @returns An integer in the range [0, 9] representing the clamped priority.
+ *
+ * @example
+ * ```typescript
+ * import { clampPriority } from "./priorityQueue";
+ *
+ * clampPriority(3);         // 3
+ * clampPriority(15);        // 9 (clamped to max)
+ * clampPriority(-2);        // 0 (clamped to min)
+ * clampPriority(undefined); // 5 (default)
+ * clampPriority(2.7);       // 2 (truncated)
+ * ```
+ */
+declare function clampPriority(value: number | undefined): number;
+/**
+ * An entry stored in the priority queue.
+ *
+ * @property priority - Priority level from 0 to 9, where 0 is the highest priority.
+ *   Clamped on enqueue via `clampPriority`.
+ * @property arrivalOrder - Monotonic counter used for FIFO tiebreak within the same
+ *   priority level. Lower values are dispatched first.
+ * @property value - The stored value associated with this entry.
+ * @property cancelled - When `true`, the entry is logically removed (lazy deletion).
+ *   Cancelled entries are skipped during dequeue and peek operations.
+ */
+type PriorityQueueEntry<T> = {
+    /** Priority level 0-9 (0 = highest priority). Clamped on enqueue. */
+    priority: number;
+    /** Monotonic counter for FIFO tiebreak within the same priority level. */
+    arrivalOrder: number;
+    /** The stored value. */
+    value: T;
+    /** When true, the entry is logically removed (lazy deletion). */
+    cancelled: boolean;
+};
+/**
+ * A generic binary min-heap priority queue.
+ *
+ * Entries are ordered by priority ascending (lower value = higher priority),
+ * with FIFO tiebreak via a monotonic arrivalOrder counter. Priority values
+ * are integers from 0 to 9, where 0 is the highest priority.
+ *
+ * Supports lazy removal: entries can be marked as cancelled and are
+ * skipped during dequeue and peek operations.
+ *
+ * @example
+ * ```typescript
+ * import { PriorityQueue } from "./priorityQueue";
+ *
+ * const queue = new PriorityQueue<string>();
+ * queue.enqueue("low", 9);
+ * queue.enqueue("high", 0);
+ * const entry = queue.dequeue(); // { value: "high", priority: 0, ... }
+ * ```
+ */
+declare class PriorityQueue<T> {
+    private heap;
+    private counter;
+    /**
+     * Returns the number of entries in the queue (including cancelled entries).
+     *
+     * @returns The total number of entries in the internal heap.
+     *
+     * @example
+     * ```typescript
+     * import { PriorityQueue } from "./priorityQueue";
+     *
+     * const queue = new PriorityQueue<string>();
+     * queue.enqueue("task", 5);
+     * console.log(queue.size); // 1
+     * ```
+     */
+    get size(): number;
+    /** Returns the number of entries that have not been cancelled. */
+    get activeSize(): number;
+    /**
+     * Adds a value to the queue with the given priority.
+     *
+     * Priority is clamped to the valid range [0, 9] via `clampPriority`.
+     * Returns the created entry, which can be used for later cancellation
+     * by setting `entry.cancelled = true`.
+     *
+     * @param value - The value to enqueue.
+     * @param priority - Priority level, integer from 0 (highest) to 9 (lowest).
+     *   Clamped to [0, 9]. Defaults to 5 if undefined.
+     * @returns The created queue entry.
+     *
+     * @example
+     * ```typescript
+     * import { PriorityQueue } from "./priorityQueue";
+     *
+     * const queue = new PriorityQueue<string>();
+     * const entry = queue.enqueue("urgent-task", 0);
+     * entry.cancelled = true; // cancel later if needed
+     * ```
+     */
+    enqueue(value: T, priority?: number): PriorityQueueEntry<T>;
+    /**
+     * Removes and returns the highest-priority non-cancelled entry.
+     *
+     * Skips (and discards) any cancelled entries at the top of the heap.
+     * Returns `undefined` if the queue is empty or all entries are cancelled.
+     *
+     * @returns The highest-priority non-cancelled entry, or `undefined` if none available.
+     *
+     * @example
+     * ```typescript
+     * import { PriorityQueue } from "./priorityQueue";
+     *
+     * const queue = new PriorityQueue<string>();
+     * queue.enqueue("first", 1);
+     * queue.enqueue("second", 2);
+     * const entry = queue.dequeue(); // { value: "first", priority: 1, ... }
+     * ```
+     */
+    dequeue(): PriorityQueueEntry<T> | undefined;
+    /**
+     * Returns the highest-priority non-cancelled entry without removing it.
+     *
+     * Discards cancelled entries at the top of the heap as a side effect.
+     * Returns `undefined` if the queue is empty or all entries are cancelled.
+     *
+     * @returns The highest-priority non-cancelled entry, or `undefined` if none available.
+     *
+     * @example
+     * ```typescript
+     * import { PriorityQueue } from "./priorityQueue";
+     *
+     * const queue = new PriorityQueue<string>();
+     * queue.enqueue("task", 3);
+     * const top = queue.peek(); // { value: "task", priority: 3, ... }
+     * console.log(queue.size);  // 1 (not removed)
+     * ```
+     */
+    peek(): PriorityQueueEntry<T> | undefined;
+    /**
+     * Marks all entries matching the predicate as cancelled (lazy removal).
+     *
+     * Cancelled entries are skipped on subsequent dequeue/peek calls.
+     * This does not immediately remove entries from the heap; they are
+     * discarded lazily when encountered at the top during dequeue or peek.
+     *
+     * @param predicate - A function that returns `true` for entries to cancel.
+     * @returns The number of entries marked as cancelled.
+     *
+     * @example
+     * ```typescript
+     * import { PriorityQueue } from "./priorityQueue";
+     *
+     * const queue = new PriorityQueue<string>();
+     * queue.enqueue("a", 1);
+     * queue.enqueue("b", 2);
+     * const removed = queue.remove((e) => e.value === "a"); // 1
+     * ```
+     */
+    remove(predicate: (entry: PriorityQueueEntry<T>) => boolean): number;
+    /** Removes the top element from the heap and restores heap property. */
+    private removeTop;
+    /** Moves an element up the heap until the heap property is restored. */
+    private bubbleUp;
+    /** Moves an element down the heap until the heap property is restored. */
+    private sinkDown;
+}
+
+/**
+ * Tracks lifecycle statistics for the HTTP Lifecycle Client.
+ *
+ * All counters start at zero and increase monotonically. The tracker also
+ * provides event emission for observability, wrapping the user-supplied
+ * `onEvent` callback in a try-catch so that callback errors never disrupt
+ * request processing.
+ *
+ * Use the `snapshot()` method to obtain a frozen point-in-time view of all
+ * statistics, including wire-level stats from the underlying HTTP client.
+ *
+ * @example
+ * ```typescript
+ * import { LifecycleStatsTracker } from "./stats";
+ *
+ * const tracker = new LifecycleStatsTracker({
+ *   onEvent: (event) => console.log(event.type),
+ *   wireStats: () => ({ requestCount: 0, errorCount: 0 }),
+ * });
+ * tracker.cacheHit();
+ * const stats = tracker.snapshot();
+ * console.log(stats.cacheHits); // 1
+ * ```
+ */
+declare class LifecycleStatsTracker {
+    private _cacheHits;
+    private _cacheMisses;
+    private _cacheEvictions;
+    private _dedupHits;
+    private _dedupActive;
+    private _queueDepth;
+    private _requestsStarted;
+    private _requestsCompleted;
+    private _requestsFailed;
+    private _retries;
+    private _batchDispatches;
+    private _batchedRequests;
+    private readonly _onEvent;
+    private readonly _wireStats;
+    /**
+     * Creates a new lifecycle stats tracker.
+     *
+     * @param opts - Configuration options for the tracker.
+     * @param opts.onEvent - Optional callback invoked on each lifecycle event.
+     *   Errors thrown by this callback are silently discarded.
+     * @param opts.wireStats - A function returning the current wire-level HTTP client stats.
+     *
+     * @example
+     * ```typescript
+     * import { LifecycleStatsTracker } from "./stats";
+     *
+     * const tracker = new LifecycleStatsTracker({
+     *   wireStats: () => ({ requestCount: 0, errorCount: 0 }),
+     * });
+     * ```
+     */
+    constructor(opts: {
+        onEvent?: (event: LifecycleEvent) => void;
+        wireStats: () => HttpClientStats;
+    });
+    /**
+     * Records a cache hit. Increments the cache hit counter by 1.
+     *
+     * @example
+     * ```typescript
+     * import { LifecycleStatsTracker } from "./stats";
+     *
+     * const tracker = new LifecycleStatsTracker({ wireStats: () => ({ requestCount: 0, errorCount: 0 }) });
+     * tracker.cacheHit();
+     * ```
+     */
+    cacheHit(): void;
+    /**
+     * Records a cache miss. Increments the cache miss counter by 1.
+     *
+     * @example
+     * ```typescript
+     * import { LifecycleStatsTracker } from "./stats";
+     *
+     * const tracker = new LifecycleStatsTracker({ wireStats: () => ({ requestCount: 0, errorCount: 0 }) });
+     * tracker.cacheMiss();
+     * ```
+     */
+    cacheMiss(): void;
+    /**
+     * Records a cache eviction. Increments the cache eviction counter by 1.
+     *
+     * @example
+     * ```typescript
+     * import { LifecycleStatsTracker } from "./stats";
+     *
+     * const tracker = new LifecycleStatsTracker({ wireStats: () => ({ requestCount: 0, errorCount: 0 }) });
+     * tracker.cacheEviction();
+     * ```
+     */
+    cacheEviction(): void;
+    /**
+     * Records a dedup hit (a request that joined an in-flight duplicate).
+     * Increments the dedup hit counter by 1.
+     *
+     * @example
+     * ```typescript
+     * import { LifecycleStatsTracker } from "./stats";
+     *
+     * const tracker = new LifecycleStatsTracker({ wireStats: () => ({ requestCount: 0, errorCount: 0 }) });
+     * tracker.dedupHit();
+     * ```
+     */
+    dedupHit(): void;
+    /**
+     * Sets the current number of active dedup groups.
+     *
+     * @param n - The current count of active dedup groups. Must be >= 0.
+     *
+     * @example
+     * ```typescript
+     * import { LifecycleStatsTracker } from "./stats";
+     *
+     * const tracker = new LifecycleStatsTracker({ wireStats: () => ({ requestCount: 0, errorCount: 0 }) });
+     * tracker.setDedupActive(3);
+     * ```
+     */
+    setDedupActive(n: number): void;
+    /**
+     * Sets the current priority queue depth.
+     *
+     * @param n - The current number of entries in the priority queue. Must be >= 0.
+     *
+     * @example
+     * ```typescript
+     * import { LifecycleStatsTracker } from "./stats";
+     *
+     * const tracker = new LifecycleStatsTracker({ wireStats: () => ({ requestCount: 0, errorCount: 0 }) });
+     * tracker.setQueueDepth(5);
+     * ```
+     */
+    setQueueDepth(n: number): void;
+    /**
+     * Records that a request has started. Increments the requests started counter by 1.
+     *
+     * @example
+     * ```typescript
+     * import { LifecycleStatsTracker } from "./stats";
+     *
+     * const tracker = new LifecycleStatsTracker({ wireStats: () => ({ requestCount: 0, errorCount: 0 }) });
+     * tracker.requestStarted();
+     * ```
+     */
+    requestStarted(): void;
+    /**
+     * Records that a request has completed successfully.
+     * Increments the requests completed counter by 1.
+     *
+     * @example
+     * ```typescript
+     * import { LifecycleStatsTracker } from "./stats";
+     *
+     * const tracker = new LifecycleStatsTracker({ wireStats: () => ({ requestCount: 0, errorCount: 0 }) });
+     * tracker.requestCompleted();
+     * ```
+     */
+    requestCompleted(): void;
+    /**
+     * Records that a request has failed.
+     * Increments the requests failed counter by 1.
+     *
+     * @example
+     * ```typescript
+     * import { LifecycleStatsTracker } from "./stats";
+     *
+     * const tracker = new LifecycleStatsTracker({ wireStats: () => ({ requestCount: 0, errorCount: 0 }) });
+     * tracker.requestFailed();
+     * ```
+     */
+    requestFailed(): void;
+    retry(): void;
+    /**
+     * Records a batch dispatch. Increments the batch dispatches counter by 1.
+     */
+    batchDispatch(): void;
+    /**
+     * Records requests that were coalesced into a batch.
+     * @param count - The number of individual requests in the batch.
+     */
+    batchedRequests(count: number): void;
+    /**
+     * Emits a lifecycle event to the registered `onEvent` callback.
+     *
+     * The callback is wrapped in a try-catch so that any exception thrown by
+     * the callback is silently discarded and request processing continues
+     * unaffected. If no `onEvent` callback was provided, this is a no-op.
+     *
+     * @param type - The lifecycle event type to emit (e.g., `"cache-hit"`, `"request-start"`).
+     * @param extra - Optional additional event data.
+     *
+     * @example
+     * ```typescript
+     * import { LifecycleStatsTracker } from "./stats";
+     *
+     * const tracker = new LifecycleStatsTracker({
+     *   onEvent: (event) => console.log(event.type, event.timestamp),
+     *   wireStats: () => ({ requestCount: 0, errorCount: 0 }),
+     * });
+     * tracker.emit("cache-hit", { cacheKey: "GET|/api/users" });
+     * ```
+     */
+    emit(type: LifecycleEventType, extra?: {
+        cacheKey?: string;
+        priority?: number;
+        batchKey?: string;
+        batchSize?: number;
+        attempt?: number;
+        delayMs?: number;
+        status?: number;
+        errorTag?: string;
+    }): void;
+    /**
+     * Returns a frozen snapshot of all lifecycle statistics including wire stats.
+     *
+     * The returned object is frozen (immutable) and represents a point-in-time
+     * view of all counters and gauges.
+     *
+     * @returns A frozen `LifecycleStats` object containing all current statistics.
+     *
+     * @example
+     * ```typescript
+     * import { LifecycleStatsTracker } from "./stats";
+     *
+     * const tracker = new LifecycleStatsTracker({
+     *   wireStats: () => ({ requestCount: 10, errorCount: 1 }),
+     * });
+     * tracker.cacheHit();
+     * tracker.cacheHit();
+     * const stats = tracker.snapshot();
+     * console.log(stats.cacheHits); // 2
+     * ```
+     */
+    snapshot(): LifecycleStats;
+}
+
+/**
+ * Configuration for the deduplication middleware.
+ */
+type DedupConfig = {
+    /** Custom key function. When provided, overrides default key computation. */
+    dedupKey?: (req: HttpRequest) => string;
+    /** Optional lifecycle observer for dedup hits/misses. */
+    onEvent?: (event: {
+        type: "dedup-hit" | "dedup-miss" | "dedup-active";
+        cacheKey?: string;
+        active?: number;
+    }) => void;
+};
+/**
+ * Creates a deduplication middleware that collapses identical in-flight requests
+ * into a single network call.
+ *
+ * For safe HTTP methods (GET, HEAD, OPTIONS), concurrent requests with the same
+ * dedup key share a single underlying network call. All callers receive the same
+ * response or error.
+ *
+ * Non-safe methods (POST, PUT, PATCH, DELETE) pass through without deduplication.
+ *
+ * Supports ref-counted cancellation: when a caller cancels, the refCount is decremented.
+ * When refCount reaches 0, the underlying request is aborted via AbortController.
+ *
+ * @param config - Optional dedup configuration. Provide a `dedupKey` function to override
+ *   the default Cache_Key computation. Return an empty string from `dedupKey` to bypass
+ *   deduplication for a specific request.
+ * @returns An HttpMiddleware that wraps the next Wire_Client with deduplication logic.
+ *   Concurrent safe-method requests sharing the same key resolve to a single network call.
+ *
+ * @example
+ * ```typescript
+ * import { withDedup } from "./dedup";
+ *
+ * // Basic usage with default key computation
+ * const dedupMiddleware = withDedup();
+ *
+ * // With custom key function
+ * const customDedup = withDedup({
+ *   dedupKey: (req) => `${req.method}:${req.url}`,
+ * });
+ * ```
+ */
+declare function withDedup(config?: DedupConfig): HttpMiddleware;
+
+/**
+ * Result of a custom cache policy function.
+ */
+type CachePolicyResult = {
+    cacheable: boolean;
+    ttlSeconds?: number;
+};
+/**
+ * Configuration for the response cache middleware.
+ */
+type CacheConfig = {
+    /** Time-to-live in seconds. Default: 60. Range: [1, 86400]. */
+    ttlSeconds?: number;
+    /** Maximum number of cached entries. Default: 1024. Minimum: 1. */
+    maxEntries?: number;
+    /** Enable stale-while-revalidate. Default: false. */
+    staleWhileRevalidate?: boolean;
+    /** Custom cache policy function. */
+    cachePolicy?: (req: HttpRequest, res: HttpWireResponse) => CachePolicyResult;
+    /** Additional headers to include in cache key computation. */
+    cacheRelevantHeaders?: string[];
+    /** Base URL needed for cache key computation. */
+    baseUrl?: string;
+    /** Optional event callback for structured cache failure events. */
+    onEvent?: (event: {
+        type: string;
+        cacheKey?: string;
+        error?: any;
+    }) => void;
+    /** Optional internal lifecycle callback for hit/miss/eviction stats. */
+    onLifecycleEvent?: (event: {
+        type: "cache-hit" | "cache-miss" | "cache-eviction";
+        cacheKey?: string;
+        count?: number;
+    }) => void;
+};
+/**
+ * Creates a response cache middleware that stores and serves previously fetched
+ * responses based on configurable cache policies.
+ *
+ * Features:
+ * - LRU eviction when maxEntries is exceeded
+ * - Per-entry TTL with configurable default
+ * - Stale-while-revalidate support
+ * - Custom cache policy function for cacheability and TTL override
+ * - Only caches safe methods (GET, HEAD, OPTIONS) by default
+ * - Exposes `invalidate(key)` and `clear()` for manual cache control
+ *
+ * @param config - Optional cache configuration object.
+ *   - `ttlSeconds`: Time-to-live per entry in seconds, clamped to [1, 86400]. Default: 60.
+ *   - `maxEntries`: Maximum cached entries, minimum 1. Default: 1024.
+ *   - `staleWhileRevalidate`: When true, serves stale entries while refreshing in background. Default: false.
+ *   - `cachePolicy`: Custom function to determine cacheability and per-entry TTL override.
+ *   - `cacheRelevantHeaders`: Additional headers included in Cache_Key computation.
+ *   - `baseUrl`: Base URL for Cache_Key computation.
+ *   - `onEvent`: Callback for structured cache events (e.g., revalidation failures).
+ * @returns An object containing:
+ *   - `middleware`: An HttpMiddleware that wraps the next Wire_Client with caching logic.
+ *   - `invalidate(key)`: Removes a specific entry from the cache by its Cache_Key.
+ *   - `clear()`: Removes all entries from the cache.
+ *
+ * @example
+ * ```typescript
+ * import { withCache } from "./responseCache";
+ *
+ * // Basic usage with defaults (60s TTL, 1024 max entries)
+ * const { middleware, invalidate, clear } = withCache();
+ *
+ * // Custom TTL and max entries
+ * const cache = withCache({
+ *   ttlSeconds: 300,
+ *   maxEntries: 512,
+ *   staleWhileRevalidate: true,
+ * });
+ *
+ * // Manually invalidate a cached entry
+ * cache.invalidate("GET|https://api.example.com/users");
+ * ```
+ */
+declare function withCache(config?: CacheConfig): {
+    middleware: HttpMiddleware;
+    invalidate: (key: string) => void;
+    clear: () => void;
+};
+
+/**
+ * Configuration for the priority scheduler middleware.
+ */
+type PriorityConfig = {
+    /** Maximum concurrent requests dispatched to the wire client. Default: 32. */
+    concurrency?: number;
+    /** Queue timeout in ms for priority-queued requests. Default: no timeout. */
+    queueTimeoutMs?: number;
+    /** Optional lifecycle observer for queue events. */
+    onEvent?: (event: {
+        type: "queue-enqueue" | "queue-dispatch";
+        priority: number;
+    }) => void;
+};
+/**
+ * Creates a priority scheduler middleware that reorders queued requests
+ * by priority before dispatching them to the downstream wire client.
+ *
+ * When the concurrency limit is not reached, requests are dispatched immediately.
+ * When at capacity, requests are held in a priority queue (lower numeric priority = higher urgency)
+ * and dispatched in priority order as slots become available.
+ *
+ * Supports:
+ * - Priority extraction from request options (default 5, clamped to 0-9)
+ * - Queue timeout via `queueTimeoutMs` config (produces PoolTimeout error)
+ * - Cancellation: removes from queue on abort signal
+ * - Stats tracking via `queueDepth` getter
+ *
+ * @param config - Optional priority scheduler configuration.
+ *   - `concurrency`: Maximum concurrent requests dispatched to the Wire_Client.
+ *     Must be a positive integer (>= 1). Default: 32.
+ *   - `queueTimeoutMs`: Maximum time in milliseconds a request may wait in the queue
+ *     before receiving a PoolTimeout error. Must be a positive integer (>= 1) or undefined
+ *     for no timeout. Default: undefined (no timeout).
+ * @returns An HttpMiddleware (with an additional `queueDepth()` method) that wraps the
+ *   next Wire_Client with priority-based scheduling. Requests carry a priority level
+ *   (integer from 0 to 9, where 0 is highest urgency). Default priority is 5.
+ *
+ * @example
+ * ```typescript
+ * import { withPriority } from "./priorityScheduler";
+ *
+ * // Basic usage with default concurrency (32)
+ * const priorityMiddleware = withPriority();
+ *
+ * // Limit concurrency and set queue timeout
+ * const scheduler = withPriority({
+ *   concurrency: 4,
+ *   queueTimeoutMs: 5000,
+ * });
+ *
+ * // Check current queue depth
+ * const depth = scheduler.queueDepth();
+ * ```
+ */
+declare function withPriority(config?: PriorityConfig): HttpMiddleware & {
+    queueDepth: () => number;
+};
+
+/**
+ * Supported content encoding algorithms.
+ */
+type SupportedEncoding = "gzip" | "br" | "deflate";
+/**
+ * All supported encodings in default preference order (Brotli first).
+ */
+declare const SUPPORTED_ENCODINGS: readonly SupportedEncoding[];
+/**
+ * Configuration for the compression middleware.
+ */
+type CompressionConfig = {
+    /**
+     * Enabled encodings in preference order.
+     * Default: ["br", "gzip", "deflate"]
+     */
+    encodings?: SupportedEncoding[];
+};
+type RequestCompressionConfig = {
+    /**
+     * Encoding to apply to outbound request bodies.
+     * Default: "gzip".
+     */
+    encoding?: SupportedEncoding;
+    /**
+     * Minimum uncompressed body size in bytes before compression is attempted.
+     * Default: 1024.
+     */
+    minBytes?: number;
+    /**
+     * HTTP methods eligible for request compression.
+     * Default: ["POST", "PUT", "PATCH"].
+     */
+    methods?: readonly string[];
+};
+/**
+ * Frozen snapshot of compression statistics.
+ */
+type CompressionStats = {
+    /** Responses decompressed per encoding type */
+    readonly decompressed: Readonly<Record<SupportedEncoding, number>>;
+    /** Total compressed bytes received */
+    readonly compressedBytes: number;
+    /** Total decompressed bytes produced */
+    readonly decompressedBytes: number;
+    /** Responses that bypassed decompression */
+    readonly passthroughCount: number;
+    /** Decompression errors encountered */
+    readonly errorCount: number;
+    /** Unsupported encoding warnings */
+    readonly unsupportedEncodingCount: number;
+};
+type RequestCompressionStats = {
+    readonly compressedCount: number;
+    readonly skippedCount: number;
+    readonly errorCount: number;
+    readonly originalBytes: number;
+    readonly compressedBytes: number;
+};
+/**
+ * Result of a decompression attempt.
+ */
+type DecompressResult = {
+    ok: true;
+    data: Buffer;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Abstraction over zlib / noop decompression.
+ */
+interface Decompressor {
+    readonly isPassthrough: boolean;
+    decompress(data: Buffer | Uint8Array, encoding: SupportedEncoding): DecompressResult;
+}
+/**
+ * Result of makeCompressionMiddleware — the middleware plus a stats accessor.
+ */
+type CompressionMiddlewareResult = {
+    middleware: HttpMiddleware;
+    stats: () => CompressionStats;
+};
+type RequestCompressionMiddlewareResult = {
+    middleware: HttpMiddleware;
+    stats: () => RequestCompressionStats;
+};
+
+/**
+ * Creates the compression middleware with optional configuration.
+ *
+ * The middleware:
+ * 1. Injects Accept-Encoding header on outgoing requests (if missing)
+ * 2. Decompresses response bodies based on Content-Encoding header
+ * 3. Tracks compression statistics
+ */
+declare function makeCompressionMiddleware(config?: CompressionConfig): CompressionMiddlewareResult;
+declare const makeResponseCompressionMiddleware: typeof makeCompressionMiddleware;
+declare function makeRequestCompressionMiddleware(config?: RequestCompressionConfig): RequestCompressionMiddlewareResult;
+
+type RequestBatchingEvent = {
+    type: "batch-enqueue";
+    key: string;
+    size: number;
+    request: HttpRequest;
+} | {
+    type: "batch-flush";
+    key: string;
+    size: number;
+    reason: "size" | "timer" | "manual";
+} | {
+    type: "batch-cancel";
+    key: string;
+    remaining: number;
+} | {
+    type: "batch-error";
+    key: string;
+    size: number;
+    error: HttpError;
+};
+type RequestBatchingConfig = {
+    /**
+     * Groups requests into independent batches. Return undefined/null/empty string
+     * to bypass batching for a request.
+     *
+     * Default: `${method}:${url}`.
+     */
+    key?: (req: HttpRequest) => string | undefined | null;
+    /** Extra predicate for per-request opt-in/out. Default: batch all keyed requests. */
+    shouldBatch?: (req: HttpRequest) => boolean;
+    /** Maximum requests per batch. Default: 16. */
+    maxBatchSize?: number;
+    /** Maximum time to wait before flushing a non-full batch. Default: 5ms. */
+    maxWaitMs?: number;
+    /** Builds the actual wire request sent to the batch endpoint. */
+    encode: (requests: readonly HttpRequest[]) => HttpRequest;
+    /**
+     * Splits the batch endpoint response back into one response per original
+     * request. The returned array must have the same length and order.
+     */
+    decode: (response: HttpWireResponse, requests: readonly HttpRequest[]) => readonly HttpWireResponse[];
+    /** Optional observability hook. Exceptions are swallowed. */
+    onEvent?: (event: RequestBatchingEvent) => void;
+};
+declare function withRequestBatching(config: RequestBatchingConfig): HttpMiddleware;
+
+/**
+ * The PrewarmManager interface for managing connection pre-warming.
+ */
+type PrewarmManager = {
+    /** Warm a single origin. Skips if already warm. */
+    warm: (origin: string) => Promise<PrewarmResult>;
+    /** Warm all configured origins. Skips already-warm origins. */
+    warmAll: () => Promise<PrewarmResult[]>;
+    /** Check if an origin has an active warm connection. */
+    isWarm: (origin: string) => boolean;
+    /** Cancel in-flight probe for a specific origin. */
+    cancel: (origin: string) => void;
+    /** Cancel all in-flight and queued probes. */
+    cancelAll: () => void;
+    /** Get a snapshot of all managed origins and their states. */
+    status: () => PrewarmStatusSnapshot;
+    /** Dispose the manager: cancel all, stop timers, release resources. */
+    dispose: () => void;
+};
+/**
+ * Creates a PrewarmManager that proactively establishes TCP+TLS connections
+ * to known origins using lightweight HEAD probe requests.
+ *
+ * @param config - Configuration for the prewarm manager.
+ * @returns A PrewarmManager instance.
+ * @throws Error if fetch/AbortController is unavailable or origins are invalid.
+ */
+declare function makePrewarmManager(config: PrewarmConfig): PrewarmManager;
+
+/**
+ * Validates and normalizes an origin string.
+ *
+ * A valid origin is: scheme + host + optional port (e.g., "https://api.example.com" or "http://localhost:3000").
+ * Trailing slashes are stripped. Paths, query strings, and fragments are rejected.
+ *
+ * @param origin - The origin string to validate.
+ * @returns The normalized origin string.
+ * @throws Error if the origin is invalid.
+ */
+declare function validateOrigin(origin: string): string;
+
+/**
+ * Detects the current runtime platform.
+ *
+ * @returns "browser" if running in a browser environment, "node" otherwise.
+ */
+declare function detectPlatform(): "browser" | "node";
+/**
+ * Validates that the global `fetch` API is available.
+ *
+ * @throws Error if `fetch` or `AbortController` is not available.
+ */
+declare function validateFetchAvailable(): void;
+
+/**
+ * Outcome of a probe request.
+ */
+type ProbeOutcome = {
+    /** Whether the probe succeeded (connection established). */
+    ok: boolean;
+    /** Duration of the probe in milliseconds. */
+    durationMs: number;
+    /** Error message if the probe failed. */
+    error?: string;
+};
+/**
+ * Options for executing a probe request.
+ */
+type ProbeOptions = {
+    /** Probe timeout in milliseconds. */
+    timeoutMs: number;
+    /** AbortSignal for external cancellation. */
+    signal: AbortSignal;
+    /** Runtime platform. */
+    platform: "browser" | "node";
+    /** Optional Wire_Client to route through (when useClientPool is true). */
+    client?: HttpClientFn;
+};
+/**
+ * Executes a HEAD probe request to the root path of the given origin.
+ *
+ * The probe is a lightweight HEAD request to `${origin}/` designed to trigger
+ * TCP+TLS connection establishment in the platform's connection pool.
+ *
+ * @param origin - The validated origin to probe (e.g., "https://api.example.com").
+ * @param options - Probe configuration options.
+ * @returns A ProbeOutcome indicating success or failure.
+ */
+declare function executeProbe(origin: string, options: ProbeOptions): Promise<ProbeOutcome>;
+
+/**
+ * Interface for the connection state map.
+ */
+type ConnectionStateMap = {
+    /** Mark an origin as warm with the current timestamp. */
+    markWarm: (origin: string, now?: number) => void;
+    /** Mark an origin as expired. */
+    markExpired: (origin: string) => void;
+    /** Mark an origin as idle (reset state). */
+    markIdle: (origin: string) => void;
+    /** Mark an origin as probing. */
+    markProbing: (origin: string) => void;
+    /** Check if an origin is currently warm (not expired). */
+    isWarm: (origin: string, now?: number) => boolean;
+    /** Get the current state of an origin. */
+    getState: (origin: string) => PrewarmOriginState | undefined;
+    /** Get a snapshot of all managed origins. */
+    snapshot: () => PrewarmStatusSnapshot;
+};
+/**
+ * Creates a connection state map for tracking per-origin warm/expired/idle states.
+ *
+ * @param origins - Array of origin strings to manage.
+ * @param keepAliveDurationMs - Duration in ms after which a warm connection expires.
+ * @returns A ConnectionStateMap instance.
+ */
+declare function makeConnectionStateMap(origins: string[], keepAliveDurationMs: number): ConnectionStateMap;
+
+/**
+ * A lightweight counting semaphore that limits concurrent in-flight operations.
+ */
+type BudgetSemaphore = {
+    /** Acquire a slot. Resolves with a release handle when a slot is available. */
+    acquire: () => Promise<{
+        release: () => void;
+    }>;
+    /** Try to acquire a slot synchronously. Returns undefined if no slot is available. */
+    tryAcquire: () => {
+        release: () => void;
+    } | undefined;
+    /** Number of currently available slots. */
+    available: () => number;
+    /** Number of waiters currently queued. */
+    queued: () => number;
+};
+/**
+ * Creates a budget semaphore with the given capacity.
+ *
+ * @param capacity - Maximum number of concurrent slots. Must be >= 1.
+ * @returns A BudgetSemaphore instance.
+ */
+declare function makeBudgetSemaphore(capacity: number): BudgetSemaphore;
+
+type ConnectionPrewarmAttempt = {
+    url: string;
+    origin: string;
+    ok: boolean;
+    status?: number;
+    ms: number;
+    error?: HttpError;
+};
+type ConnectionPrewarmResult = {
+    attempted: number;
+    warmed: number;
+    failed: number;
+    skipped: number;
+    attempts: readonly ConnectionPrewarmAttempt[];
+};
+type ConnectionPrewarmEvent = {
+    type: "prewarm-start";
+    url: string;
+    origin: string;
+} | {
+    type: "prewarm-success";
+    url: string;
+    origin: string;
+    status: number;
+    ms: number;
+} | {
+    type: "prewarm-failure";
+    url: string;
+    origin: string;
+    error: HttpError;
+    ms: number;
+};
+type ConnectionPrewarmConfig = {
+    baseUrl?: string;
+    urls?: readonly string[];
+    origins?: readonly string[];
+    path?: string;
+    method?: Extract<HttpMethod, "HEAD" | "GET" | "OPTIONS">;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    failFast?: boolean;
+    fetchImpl?: typeof fetch;
+    onEvent?: (event: ConnectionPrewarmEvent) => void;
+};
+type ConnectionPrewarmingMiddlewareConfig = ConnectionPrewarmConfig & {
+    once?: boolean;
+    shouldPrewarm?: (req: HttpRequest) => boolean;
+    target?: (req: HttpRequest) => string | undefined | null;
+};
+declare function prewarmConnections(config?: ConnectionPrewarmConfig): Async<unknown, HttpError, ConnectionPrewarmResult>;
+declare const prewarmHttpConnections: typeof prewarmConnections;
+declare function withConnectionPrewarming(config?: ConnectionPrewarmingMiddlewareConfig): HttpMiddleware;
+
+type InitNoMethodBody = Omit<RequestInit, "method" | "body"> & {
+    timeoutMs?: number;
+    poolKey?: string;
+    headers?: unknown;
+};
+type InitWithHeaders = {
+    headers?: unknown;
+    timeoutMs?: number;
+    poolKey?: string;
+} & Record<string, unknown>;
+type HttpJsonInit<Validator extends AnyJsonSchemaLike> = InitNoMethodBody & {
+    readonly schema: Validator;
+    readonly schemaName?: string;
+};
+type HttpPostJsonInit<Validator extends AnyJsonSchemaLike> = InitWithHeaders & {
+    readonly schema: Validator;
+    readonly schemaName?: string;
+    readonly bodySchema?: undefined;
+    readonly bodySchemaName?: string;
+};
+type HttpPostJsonSchemaBodyInit<Validator extends AnyJsonSchemaLike, BodyValidator extends AnyJsonSchemaLike> = InitWithHeaders & {
+    readonly schema: Validator;
+    readonly schemaName?: string;
+    readonly bodySchema: BodyValidator;
+    readonly bodySchemaName?: string;
+};
+type HttpPostJsonBodyInit<BodyValidator extends AnyJsonSchemaLike> = InitWithHeaders & {
+    readonly schema?: undefined;
+    readonly schemaName?: string;
+    readonly bodySchema: BodyValidator;
+    readonly bodySchemaName?: string;
+};
+type JsonInitNoSchema = InitNoMethodBody & {
+    readonly schema?: undefined;
+    readonly schemaName?: string;
+};
+type PostJsonInitNoSchema = InitWithHeaders & {
+    readonly schema?: undefined;
+    readonly schemaName?: string;
+    readonly bodySchema?: undefined;
+    readonly bodySchemaName?: string;
+};
+type DefaultGetJson = {
+    <Validator extends AnyJsonSchemaLike>(url: string, init: HttpJsonInit<Validator>): AsyncWithPromise<unknown, HttpError | ValidationError, HttpResponse<InferJsonSchema<Validator>>>;
+    <A = unknown>(url: string, init?: JsonInitNoSchema): AsyncWithPromise<unknown, HttpError | ValidationError, HttpResponse<A>>;
+};
+type DefaultPostJson = {
+    <Validator extends AnyJsonSchemaLike, BodyValidator extends AnyJsonSchemaLike>(url: string, bodyObj: InferJsonSchema<BodyValidator>, init: HttpPostJsonSchemaBodyInit<Validator, BodyValidator>): AsyncWithPromise<unknown, HttpError | ValidationError, HttpResponse<InferJsonSchema<Validator>>>;
+    <BodyValidator extends AnyJsonSchemaLike, A = unknown>(url: string, bodyObj: InferJsonSchema<BodyValidator>, init: HttpPostJsonBodyInit<BodyValidator>): AsyncWithPromise<unknown, HttpError | ValidationError, HttpResponse<A>>;
+    <Validator extends AnyJsonSchemaLike>(url: string, bodyObj: unknown, init: HttpPostJsonInit<Validator>): AsyncWithPromise<unknown, HttpError | ValidationError, HttpResponse<InferJsonSchema<Validator>>>;
+    <A = unknown>(url: string, bodyObj: unknown, init?: PostJsonInitNoSchema): AsyncWithPromise<unknown, HttpError | ValidationError, HttpResponse<A>>;
+};
+type DefaultHttpClientPreset = "minimal" | "balanced" | "default";
+type DefaultHttpClientFeatures = {
+    readonly dedup: boolean;
+    readonly batch: boolean;
+    readonly cache: boolean;
+    readonly priority: boolean;
+    readonly retry: boolean;
+    readonly prewarm: boolean;
+    readonly adaptiveLimiter: boolean;
+    readonly compression: boolean;
+    readonly middleware: number;
+};
+type DefaultHttpClientConfig = LifecycleClientConfig & {
+    /**
+     * Preset used as the baseline before caller overrides are applied.
+     * - minimal: wire client + timeout only.
+     * - balanced: retry, priority, dedup, adaptive limiter, response compression.
+     * - default: balanced + short safe-method response cache.
+     */
+    readonly preset?: DefaultHttpClientPreset;
+    /** Response decompression. Enabled by balanced/default presets; set false to disable. */
+    readonly compression?: CompressionConfig | false;
+    /** Extra middleware applied outermost after the preset stack, e.g. withHttpObservability(obs). */
+    readonly middleware?: readonly HttpMiddleware[];
+};
+type DefaultHttpClient = {
+    readonly request: (req: HttpRequest) => AsyncWithPromise<unknown, HttpError, HttpWireResponse>;
+    readonly get: (url: string, init?: InitNoMethodBody) => AsyncWithPromise<unknown, HttpError, HttpWireResponse>;
+    readonly post: (url: string, body?: string, init?: InitWithHeaders) => AsyncWithPromise<unknown, HttpError, HttpWireResponse>;
+    readonly getText: (url: string, init?: InitNoMethodBody) => AsyncWithPromise<unknown, HttpError, HttpResponse<string>>;
+    readonly getJson: DefaultGetJson;
+    readonly postJson: DefaultPostJson;
+    readonly with: (mw: HttpMiddleware) => DefaultHttpClient;
+    readonly wire: LifecycleClient;
+    readonly stats: () => LifecycleStats;
+    readonly cache: LifecycleClient["cache"];
+    readonly cancelAll: LifecycleClient["cancelAll"];
+    readonly shutdown: LifecycleClient["shutdown"];
+    readonly preset: DefaultHttpClientPreset;
+    readonly features: DefaultHttpClientFeatures;
+    readonly compression?: {
+        readonly stats: () => CompressionStats;
+    };
+};
+declare const defaultHttpClientPreset: DefaultHttpClientPreset;
+/**
+ * Creates the recommended default HTTP client.
+ *
+ * The returned client has the easy JSON/text helpers from `httpClient`, but its
+ * wire path is the full lifecycle stack: priority, retry, cache, batch, dedup,
+ * adaptive concurrency, optional prewarm, compression, stats, and cancelAll.
+ */
+declare function makeDefaultHttpClient(config?: DefaultHttpClientConfig): DefaultHttpClient;
+
+type HttpClientBuilder = {
+    readonly config: () => DefaultHttpClientConfig;
+    readonly baseUrl: (baseUrl: string) => HttpClientBuilder;
+    readonly header: (name: string, value: string) => HttpClientBuilder;
+    readonly headers: (headers: Record<string, string>) => HttpClientBuilder;
+    readonly timeoutMs: (timeoutMs: number) => HttpClientBuilder;
+    readonly timeout: (timeoutMs: number) => HttpClientBuilder;
+    readonly preset: (preset: DefaultHttpClientPreset) => HttpClientBuilder;
+    readonly minimal: () => HttpClientBuilder;
+    readonly balanced: () => HttpClientBuilder;
+    readonly defaultPreset: () => HttpClientBuilder;
+    readonly dedup: (config?: DedupConfig$1 | false) => HttpClientBuilder;
+    readonly noDedup: () => HttpClientBuilder;
+    readonly batch: (config: BatchConfig | false) => HttpClientBuilder;
+    readonly noBatch: () => HttpClientBuilder;
+    readonly cache: (config?: CacheConfig$1 | false) => HttpClientBuilder;
+    readonly noCache: () => HttpClientBuilder;
+    readonly priority: (config?: PriorityConfig$1 | false) => HttpClientBuilder;
+    readonly noPriority: () => HttpClientBuilder;
+    readonly retry: (config?: RetryPolicy | false) => HttpClientBuilder;
+    readonly noRetry: () => HttpClientBuilder;
+    readonly prewarm: (config?: PrewarmLifecycleConfig | false) => HttpClientBuilder;
+    readonly noPrewarm: () => HttpClientBuilder;
+    readonly adaptiveLimiter: (config?: AdaptiveLimiterConfig | false) => HttpClientBuilder;
+    readonly adaptiveLimiterPreset: (preset: AdaptiveLimiterPreset, overrides?: AdaptiveLimiterConfig) => HttpClientBuilder;
+    readonly conservativeLimiter: (overrides?: AdaptiveLimiterConfig) => HttpClientBuilder;
+    readonly balancedLimiter: (overrides?: AdaptiveLimiterConfig) => HttpClientBuilder;
+    readonly aggressiveLimiter: (overrides?: AdaptiveLimiterConfig) => HttpClientBuilder;
+    readonly noAdaptiveLimiter: () => HttpClientBuilder;
+    readonly pool: (config?: HttpPoolConfig | false) => HttpClientBuilder;
+    readonly noPool: () => HttpClientBuilder;
+    readonly compression: (config?: CompressionConfig | false) => HttpClientBuilder;
+    readonly noCompression: () => HttpClientBuilder;
+    readonly middleware: (mw: HttpMiddleware) => HttpClientBuilder;
+    readonly use: (mw: HttpMiddleware) => HttpClientBuilder;
+    readonly configure: (config: DefaultHttpClientConfig) => HttpClientBuilder;
+    readonly build: () => DefaultHttpClient;
+    readonly buildWire: () => LifecycleClient;
+};
+declare function httpClientBuilder(config?: DefaultHttpClientConfig): HttpClientBuilder;
+declare const makeHttpClientBuilder: typeof httpClientBuilder;
+declare const httpBuilder: typeof httpClientBuilder;
+
+type HttpServerMethod = HttpMethod | "ALL";
+type HttpServerHeaders = Record<string, string>;
+type HttpServerQuery = Record<string, string | readonly string[]>;
+type HttpServerParams = Record<string, string>;
+type HttpServerBody = string | Uint8Array | ArrayBuffer | unknown;
+type HttpServerRequest = {
+    readonly method: string;
+    readonly url: string;
+    readonly path: string;
+    readonly target: string;
+    readonly headers: HttpServerHeaders;
+    readonly query: HttpServerQuery;
+    readonly params: HttpServerParams;
+    readonly bodyText: string;
+    readonly raw?: unknown;
+};
+type HttpServerContext<Params = HttpServerParams, Query = HttpServerQuery, Body = unknown> = Omit<HttpServerRequest, "params" | "query"> & {
+    readonly route: string;
+    readonly params: Params;
+    readonly query: Query;
+    readonly body: Body;
+};
+type HttpServerResponse<Body = unknown> = {
+    readonly status?: number;
+    readonly headers?: HttpServerHeaders;
+    readonly body?: Body;
+};
+type HttpServerHandler<R = unknown, E = unknown, Params = HttpServerParams, Query = HttpServerQuery, Body = unknown, ResponseBody = unknown> = (ctx: HttpServerContext<Params, Query, Body>) => Async<R, E, HttpServerResponse<ResponseBody>>;
+type HttpServerMiddleware = (next: HttpServerHandler<any, any, any, any, any, any>) => HttpServerHandler<any, any, any, any, any, any>;
+type HttpRouteSchemas<ParamsSchema extends AnyJsonSchemaLike | undefined = undefined, QuerySchema extends AnyJsonSchemaLike | undefined = undefined, BodySchema extends AnyJsonSchemaLike | undefined = undefined, ResponseSchema extends AnyJsonSchemaLike | undefined = undefined> = {
+    readonly params?: ParamsSchema;
+    readonly paramsSchemaName?: string;
+    readonly query?: QuerySchema;
+    readonly querySchemaName?: string;
+    readonly body?: BodySchema;
+    readonly bodySchemaName?: string;
+    readonly response?: ResponseSchema;
+    readonly responseSchemaName?: string;
+};
+type HttpRouteOptions<ParamsSchema extends AnyJsonSchemaLike | undefined = undefined, QuerySchema extends AnyJsonSchemaLike | undefined = undefined, BodySchema extends AnyJsonSchemaLike | undefined = undefined, ResponseSchema extends AnyJsonSchemaLike | undefined = undefined> = HttpRouteSchemas<ParamsSchema, QuerySchema, BodySchema, ResponseSchema> & {
+    readonly middleware?: readonly HttpServerMiddleware[];
+};
+type HttpRuntimeHealthRouteOptions = RuntimeHealthOptions & {
+    readonly path?: string;
+};
+type InferServerPart<Schema, Fallback> = Schema extends AnyJsonSchemaLike ? InferJsonSchema<Schema> : Fallback;
+type RoutePathParamNames<Path extends string> = Path extends `${string}:${infer Param}/${infer Rest}` ? StripRouteParamModifier<Param> | RoutePathParamNames<`/${Rest}`> : Path extends `${string}:${infer Param}` ? StripRouteParamModifier<Param> : never;
+type RoutePathParams<Path extends string> = [
+    RoutePathParamNames<Path>
+] extends [never] ? {} : {
+    readonly [Key in RoutePathParamNames<Path>]: string;
+};
+type StripRouteParamModifier<Param extends string> = Param extends `${infer Name}?` ? Name : Param extends `${infer Name}+` ? Name : Param extends `${infer Name}*` ? Name : Param;
+type HttpServerRoute<R = unknown, E = unknown, Path extends string = string, ParamsSchema extends AnyJsonSchemaLike | undefined = AnyJsonSchemaLike | undefined, QuerySchema extends AnyJsonSchemaLike | undefined = AnyJsonSchemaLike | undefined, BodySchema extends AnyJsonSchemaLike | undefined = AnyJsonSchemaLike | undefined, ResponseSchema extends AnyJsonSchemaLike | undefined = AnyJsonSchemaLike | undefined> = {
+    readonly method: HttpServerMethod;
+    readonly path: Path;
+    readonly options: HttpRouteOptions<ParamsSchema, QuerySchema, BodySchema, ResponseSchema>;
+    readonly handler: HttpServerHandler<R, E, InferServerPart<ParamsSchema, RoutePathParams<Path>>, InferServerPart<QuerySchema, HttpServerQuery>, InferServerPart<BodySchema, unknown>, InferServerPart<ResponseSchema, unknown>>;
+    readonly match: (path: string) => HttpServerParams | undefined;
+};
+type HttpRouterOptions = {
+    readonly middleware?: readonly HttpServerMiddleware[];
+    readonly includeErrorDetails?: boolean;
+};
+type HttpRouteMatch = {
+    readonly _tag: "Match";
+    readonly route: HttpServerRoute<any, any, any, any, any, any, any>;
+    readonly params: HttpServerParams;
+} | {
+    readonly _tag: "MethodNotAllowed";
+    readonly route: HttpServerRoute<any, any, any, any, any, any, any>;
+    readonly allowed: readonly HttpServerMethod[];
+} | {
+    readonly _tag: "NotFound";
+};
+type HttpRouter = {
+    readonly routes: readonly HttpServerRoute<any, any, any, any, any, any, any>[];
+    readonly match: (method: string, path: string) => HttpRouteMatch;
+    readonly handle: (request: HttpServerRequest, match?: HttpRouteMatch) => Async<unknown, never, HttpServerResponse>;
+    readonly listen: <R extends object = {}>(options?: Omit<NodeHttpServerOptions<R>, "router">) => Resource<unknown, NodeHttpServerError, NodeHttpServerHandle>;
+};
+type NodeHttpServerError = {
+    readonly _tag: "ListenError";
+    readonly error: unknown;
+    readonly message: string;
+} | {
+    readonly _tag: "ServerClosed";
+    readonly message: string;
+};
+type NodeHttpServerHandle = {
+    readonly server: Server;
+    readonly router: HttpRouter;
+    readonly address: () => AddressInfo | string | null;
+    readonly url: () => string | undefined;
+    readonly close: () => Promise<void>;
+};
+type NodeHttpServerOptions<R extends object = {}> = {
+    readonly router: HttpRouter | readonly HttpServerRoute<any, any, any, any, any, any, any>[];
+    readonly host?: string;
+    readonly port?: number;
+    readonly env?: R;
+    readonly runtime?: Runtime<R>;
+    readonly runtimeOptions?: Omit<RuntimeOptions<R>, "env" | "hooks">;
+    readonly observability?: Observability;
+    readonly observabilityOptions?: HttpServerObservabilityOptions<HttpServerResponse>;
+    readonly maxBodyBytes?: number;
+    readonly gracefulShutdownMs?: number;
+    readonly shutdownPollSchedule?: Schedule<NodeHttpServerShutdownState, unknown>;
+    readonly onError?: (error: unknown) => void;
+};
+type NodeHttpServerShutdownState = {
+    readonly listening: boolean;
+    readonly elapsedMs: number;
+};
+declare function route<Path extends string, ParamsSchema extends AnyJsonSchemaLike | undefined = undefined, QuerySchema extends AnyJsonSchemaLike | undefined = undefined, BodySchema extends AnyJsonSchemaLike | undefined = undefined, ResponseSchema extends AnyJsonSchemaLike | undefined = undefined, R = unknown, E = unknown>(method: HttpServerMethod, path: Path, options: HttpRouteOptions<ParamsSchema, QuerySchema, BodySchema, ResponseSchema>, handler: HttpServerHandler<R, E, InferServerPart<ParamsSchema, RoutePathParams<Path>>, InferServerPart<QuerySchema, HttpServerQuery>, InferServerPart<BodySchema, unknown>, InferServerPart<ResponseSchema, unknown>>): HttpServerRoute<R, E, Path, ParamsSchema, QuerySchema, BodySchema, ResponseSchema>;
+declare function route<Path extends string, R = unknown, E = unknown>(method: HttpServerMethod, path: Path, handler: HttpServerHandler<R, E, RoutePathParams<Path>>): HttpServerRoute<R, E, Path, undefined, undefined, undefined, undefined>;
+declare const httpRoute: typeof route;
+declare function makeHttpRouter(routes: readonly HttpServerRoute<any, any, any, any, any, any, any>[], options?: HttpRouterOptions): HttpRouter;
+declare function json<Body>(body: Body, init?: Omit<HttpServerResponse<Body>, "body">): HttpServerResponse<Body>;
+declare function text(body: string, init?: Omit<HttpServerResponse<string>, "body">): HttpServerResponse<string>;
+declare function empty(status?: number, headers?: HttpServerHeaders): HttpServerResponse<void>;
+declare function makeRuntimeHealthRoute(options?: HttpRuntimeHealthRouteOptions): HttpServerRoute<unknown, never, string, undefined, undefined, undefined, undefined>;
+declare function makeRuntimeReadinessRoute(options?: HttpRuntimeHealthRouteOptions): HttpServerRoute<unknown, never, string, undefined, undefined, undefined, undefined>;
+declare const runtimeHealthRoute: typeof makeRuntimeHealthRoute;
+declare const runtimeReadinessRoute: typeof makeRuntimeReadinessRoute;
+declare function withResponseHeader(name: string, value: string): HttpServerMiddleware;
+declare function makeNodeHttpServer<R extends object = {}>(options: NodeHttpServerOptions<R>): Async<unknown, NodeHttpServerError, NodeHttpServerHandle>;
+declare function nodeHttpServerResource<R extends object = {}>(options: NodeHttpServerOptions<R>): Resource<unknown, NodeHttpServerError, NodeHttpServerHandle>;
+declare const makeNodeHttpServerResource: typeof nodeHttpServerResource;
+declare const makeHttpServerResource: typeof nodeHttpServerResource;
 
-export { type Dx, type HttpCircuitBreakerConfig, type HttpClient, type HttpClientFn, type HttpClientStats, type HttpClientStream, type HttpClientStreamFn, HttpConcurrencyPool, type HttpError, type HttpInit, type HttpMeta, type HttpMethod, type HttpMiddleware, type HttpPoolConfig, type HttpPoolKeyResolver, type HttpPoolKeyStats, type HttpPoolLease, type HttpPoolStats, type HttpRequest, type HttpResponse, type HttpResponseWithMeta, type HttpWireResponse, type HttpWireResponseStream, type HttpWireWithMeta, type JsonValidator, type MakeHttpConfig, type ValidationError, decorate, httpClient, httpClientStream, httpClientWithMeta, makeHttp, makeHttpStream, normalizeHeadersInit, resolveHttpPoolKey, validatedJson, withCircuitBreaker, withMiddleware, withRetryStream, withTracing };
+export { AdaptiveLimiter, AdaptiveLimiterConfig, AdaptiveLimiterPreset, AnyJsonSchemaLike, type BatchConfig, type BatchFunction, type BudgetSemaphore, type CacheConfig$1 as CacheConfig, type CacheKeyComponents, type CachePolicyResult$1 as CachePolicyResult, type CompressionConfig, type CompressionMiddlewareResult, type CompressionStats, type ConnectionPrewarmAttempt, type ConnectionPrewarmConfig, type ConnectionPrewarmEvent, type ConnectionPrewarmResult, type ConnectionPrewarmingMiddlewareConfig, type ConnectionStateMap, DEFAULT_CACHE_RELEVANT_HEADERS, type DecompressResult, type Decompressor, type DedupConfig$1 as DedupConfig, type DefaultGetJson, type DefaultHttpClient, type DefaultHttpClientConfig, type DefaultHttpClientFeatures, type DefaultHttpClientPreset, type DefaultPostJson, type Dx, EmaComputer, type HttpCircuitBreakerConfig, HttpClient, type HttpClientBuilder, HttpClientFn, HttpClientStats, HttpClientStream, HttpError, type HttpErrorHandlers, type HttpJsonInit, type HttpMeta, HttpMethod, HttpMiddleware, HttpPoolConfig, type HttpPostJsonBodyInit, type HttpPostJsonInit, type HttpPostJsonSchemaBodyInit, HttpRequest, type HttpResponse, type HttpResponseWithMeta, type HttpRouteMatch, type HttpRouteOptions, type HttpRouteSchemas, type HttpRouter, type HttpRouterOptions, type HttpRuntimeHealthRouteOptions, type HttpServerBody, type HttpServerContext, type HttpServerHandler, type HttpServerHeaders, type HttpServerMethod, type HttpServerMiddleware, type HttpServerParams, type HttpServerQuery, type HttpServerRequest, type HttpServerResponse, type HttpServerRoute, HttpWireResponse, HttpWireResponseStream, type HttpWireWithMeta, InferJsonSchema, type InferServerPart, type JsonDecodeResult, JsonSchemaLike, type KnownHttpError, type KnownHttpErrorTag, LRUCache, type LRUCacheConfig, LatencyWindow, type LifecycleClient, type LifecycleClientConfig, type LifecycleEvent, type LifecycleEventType, type LifecycleRequestOptions, type LifecycleStats, LifecycleStatsTracker, type LogEvent, MakeHttpConfig, type NodeHttpServerError, type NodeHttpServerHandle, type NodeHttpServerOptions, type NodeHttpServerShutdownState, type PrewarmConfig, type PrewarmEvent, type PrewarmEventType, type PrewarmLifecycleConfig, type PrewarmManager, type PrewarmOriginState, type PrewarmOriginStatus, type PrewarmResult, type PrewarmResultStatus, type PrewarmStatusSnapshot, type PriorityConfig$1 as PriorityConfig, PriorityQueue, type PriorityQueueEntry, type ProbeOutcome, type RequestBatchingConfig, type RequestBatchingEvent, type RequestCompressionConfig, type RequestCompressionMiddlewareResult, type RequestCompressionStats, RetryPolicy, type RoutePathParamNames, type RoutePathParams, SEPARATOR, SUPPORTED_ENCODINGS, SchemaIssue, type SupportedEncoding, type ValidationError, clampPriority, computeCacheKey, computeGradient, computeNewLimit, decodeJsonBody, decodeJsonBodyEffect, defaultHttpClientPreset, detectPlatform, empty, encodeJsonBodyEffect, executeProbe, formatHttpError, httpBuilder, httpClient, httpClientBuilder, httpClientStream, httpClientWithMeta, httpRoute, isCircuitBreakerOpen, isHttpError, isKnownHttpError, isValidationError, json, makeBudgetSemaphore, makeCompressionMiddleware, makeConnectionStateMap, makeDefaultHttpClient, makeHttpClient, makeHttpClientBuilder, makeHttpRouter, makeHttpServerResource, makeLifecycleClient, makeNodeHttpServer, makeNodeHttpServerResource, makePrewarmManager, makeRequestCompressionMiddleware, makeResponseCompressionMiddleware, makeRuntimeHealthRoute, makeRuntimeReadinessRoute, matchHttpError, nodeHttpServerResource, parseCacheKey, prewarmConnections, prewarmHttpConnections, route, runtimeHealthRoute, runtimeReadinessRoute, text, validateFetchAvailable, validateOrigin, validatedJson, validatedJsonResponse, withAuth, withBatch, withCache, withCircuitBreaker, withConnectionPrewarming, withDedup, withLogging, withPriority, withRequestBatching, withResponseHeader, withResponseTransform, withTracing };