@cntryl/fitz 0.0.2 → 0.0.3

package/dist/index.mjs

@@ -531,11 +531,18 @@ function retryableKey(error) {
 	if (error.domainCode === void 0) return null;
 	return `${prefix}_${error.domainCode}`;
 }
+function isTransientQueueCommitFailure(error) {
+	if (!error.code.startsWith("QUEUE_")) return false;
+	const message = error.message.toLowerCase();
+	if (!message.includes("failed to commit transaction:")) return false;
+	return message.includes("writestall(") || message.includes("memory budget exceeded") || message.includes("lease heartbeat reports unhealthy") || message.includes("refusing writes");
+}
 function isRetryable(error) {
 	if (!(error instanceof FitzError)) return false;
 	if (error instanceof TimeoutError || error instanceof TransportError) return true;
 	const key = retryableKey(error);
-	return key !== null && retryableErrorCodes.has(key);
+	if (key !== null && retryableErrorCodes.has(key)) return true;
+	return isTransientQueueCommitFailure(error);
 }
 /**
 * Error types for Fitz client
@@ -974,7 +981,7 @@ function createMultiplexer(observability = {}) {
 		const span = tracer?.startSpan("fitz.request", attributes);
 		let spanEnded = false;
 		if (signal?.aborted) {
-			const error = abortError$1();
+			const error = abortError$2();
 			span?.recordException(error);
 			span?.end();
 			meter?.counter("fitz.request.failed", 1, {
@@ -1048,7 +1055,7 @@ function createMultiplexer(observability = {}) {
 		heapifyUp(requestEntry.timeoutIndex);
 		if (signal) {
 			onAbort = () => {
-				failRequest(abortError$1());
+				failRequest(abortError$2());
 			};
 			signal.addEventListener("abort", onAbort, { once: true });
 		}
@@ -1068,7 +1075,7 @@ function createMultiplexer(observability = {}) {
 			return deferred.promise;
 		}, (err) => {
 			if (!finalize()) {
-				if (signal?.aborted) throw abortError$1();
+				if (signal?.aborted) throw abortError$2();
 				throw err;
 			}
 			unregisterRequest(messageType, requestEntry);
@@ -1081,7 +1088,7 @@ function createMultiplexer(observability = {}) {
 				span?.end();
 				spanEnded = true;
 			}
-			if (signal?.aborted) throw abortError$1();
+			if (signal?.aborted) throw abortError$2();
 			throw err;
 		});
 	};
@@ -1193,7 +1200,7 @@ function createMultiplexer(observability = {}) {
 const Multiplexer = function(observability = {}) {
 	return createMultiplexer(observability);
 };
-function abortError$1() {
+function abortError$2() {
 	const error = /* @__PURE__ */ new Error("The operation was aborted");
 	error.name = "AbortError";
 	return error;
@@ -1237,8 +1244,64 @@ function readU32BE(payload, offset) {
 	return (payload[offset] << 24 | payload[offset + 1] << 16 | payload[offset + 2] << 8 | payload[offset + 3]) >>> 0;
 }
 //#endregion
+//#region src/client/resilience.ts
+const resilienceMetaSymbol = Symbol("fitz.resilience.meta");
+function attachResilienceMeta(error, meta) {
+	if (error && (typeof error === "object" || typeof error === "function")) Object.defineProperty(error, resilienceMetaSymbol, {
+		value: meta,
+		configurable: true,
+		enumerable: false,
+		writable: true
+	});
+	return error;
+}
+function getResilienceMeta(error) {
+	if (!error || typeof error !== "object" && typeof error !== "function") return;
+	return error[resilienceMetaSymbol];
+}
+function classifyFailureKind(error) {
+	if (error instanceof TimeoutError) return "timeout";
+	if (error instanceof TransportError) return "transport";
+	if (error instanceof ConnectionError) return "connection";
+	if (error instanceof FitzError) return "domain";
+	return "other";
+}
+function isTransientRetryError(error) {
+	return error instanceof TimeoutError || error instanceof TransportError || error instanceof ConnectionError || isRetryable(error);
+}
+function shouldRetryOperation(retryClass, error) {
+	switch (retryClass) {
+		case "wait_only": return false;
+		case "replayable_read": return isTransientRetryError(error);
+		case "confirmed_negative_retry": {
+			const meta = getResilienceMeta(error);
+			return meta?.explicitNegative === true && meta.boundary === "post-send" && isRetryable(error);
+		}
+		default: return false;
+	}
+}
+//#endregion
 //#region src/client/connection.ts
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+const sleepWithAbort = async (ms, signal) => {
+	if (signal?.aborted) throw abortError$1();
+	if (ms <= 0) return;
+	await new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			cleanup();
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			cleanup();
+			reject(abortError$1());
+		};
+		const cleanup = () => {
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+};
 function createAsyncHandlerDispatcher(maxConcurrency, timeoutMs, onError) {
 	let activeCount = 0;
 	let closed = false;
@@ -1306,7 +1369,7 @@ function createRequestGate(maxConcurrency, maxQueueSize) {
 	let closed = false;
 	const queue = [];
 	const acquire = async (signal) => {
-		if (signal?.aborted) throw abortError();
+		if (signal?.aborted) throw abortError$1();
 		if (closed) throw connectionClosedError();
 		return await new Promise((resolve, reject) => {
 			const grant = () => {
@@ -1329,7 +1392,7 @@ function createRequestGate(maxConcurrency, maxQueueSize) {
 			waiter.onAbort = () => {
 				removeWaiter(waiter);
 				cleanup();
-				reject(abortError());
+				reject(abortError$1());
 			};
 			if (signal) signal.addEventListener("abort", waiter.onAbort, { once: true });
 			if (activeCount < maxConcurrency) {
@@ -1378,7 +1441,7 @@ function createRequestGate(maxConcurrency, maxQueueSize) {
 		close
 	};
 }
-function abortError() {
+function abortError$1() {
 	const error = /* @__PURE__ */ new Error("The operation was aborted");
 	error.name = "AbortError";
 	return error;
@@ -1386,12 +1449,37 @@ function abortError() {
 function connectionClosedError() {
 	return new ConnectionError("Connection closed", { state: "CLOSED" });
 }
-function throwIfAborted(signal) {
-	if (signal?.aborted) throw abortError();
+function throwIfAborted$1(signal) {
+	if (signal?.aborted) throw abortError$1();
 }
 function isAbortError$1(error) {
 	return error instanceof Error && error.name === "AbortError";
 }
+const waitForSharedPromise$1 = async (promise, signal) => {
+	if (!signal) return promise;
+	if (signal.aborted) throw abortError$1();
+	return await new Promise((resolve, reject) => {
+		let settled = false;
+		const cleanup = () => {
+			signal.removeEventListener("abort", onAbort);
+		};
+		const settle = (callback) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			callback();
+		};
+		const onAbort = () => {
+			settle(() => reject(abortError$1()));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then((value) => {
+			settle(() => resolve(value));
+		}, (error) => {
+			settle(() => reject(error));
+		});
+	});
+};
 function createConnection(transportFactory, tokenProvider, options = {}) {
 	const timeout = options.timeout ?? 3e4;
 	const authSettleDelayMs = options.authSettleDelayMs ?? 100;
@@ -1399,6 +1487,10 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 	const reconnectMaxAttempts = options.reconnect?.maxAttempts ?? Infinity;
 	const reconnectBackoffMs = options.reconnect?.backoffMs ?? 250;
 	const reconnectMaxBackoffMs = options.reconnect?.maxBackoffMs ?? 5e3;
+	const retryEnabled = options.retry?.enabled ?? true;
+	const retryMaxAttempts = options.retry?.maxAttempts ?? 3;
+	const retryBackoffMs = options.retry?.backoffMs ?? 100;
+	const retryMaxBackoffMs = options.retry?.maxBackoffMs ?? 1e3;
 	const maxInFlightRequests = options.maxInFlightRequests ?? 256;
 	const maxRequestQueueSize = options.maxRequestQueueSize ?? 1024;
 	const observability = options.observability;
@@ -1412,10 +1504,18 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 	let receiveLoop = null;
 	let receiveLoopAbort = false;
 	let closeRequested = false;
+	let permanentlyClosed = false;
+	let connectPromise = null;
 	let reconnectPromise = null;
+	let reconnectRestoreActive = false;
 	let authOutcome = null;
 	let authRejected = false;
+	let hasEstablishedSession = false;
+	let reconnectExhausted = false;
+	let readyWaiterCount = 0;
+	const closeAbortController = new AbortController();
 	const connectionScope = createScope("connection");
+	const readyListeners = /* @__PURE__ */ new Set();
 	const log = (level, event, fields) => {
 		observability?.logger?.log(level, event, fields);
 	};
@@ -1446,6 +1546,8 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 	};
 	const handlePossibleTransportFailure = (error) => {
 		if (closeRequested) return;
+		if (state !== "AUTHENTICATED") return;
+		if (getResilienceMeta(error)?.boundary === "pre-send") return;
 		if (error instanceof TransportError || error instanceof ConnectionError || error instanceof AuthenticationError) handleConnectionLoss(error);
 	};
 	const multiplexer = new Multiplexer({
@@ -1456,17 +1558,34 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 		log("warn", "fitz.connection.handler_failed", { error: describeError(error) });
 	});
 	const connect = async (options = {}) => {
-		closeRequested = false;
+		if (permanentlyClosed || closeRequested) throw connectionClosedError();
+		throwIfAborted$1(options.signal);
+		if (state === "AUTHENTICATED") return;
+		if (connectPromise) {
+			await waitForSharedPromise$1(connectPromise, options.signal);
+			return;
+		}
+		if (reconnectPromise || state === "CONNECTING" || state === "CONNECTED" || state === "AUTHENTICATING" || state === "RECONNECTING" || state === "DISCONNECTED" && canWaitForReconnect()) {
+			await waitForReady(options.signal, timeout);
+			return;
+		}
 		authRejected = false;
-		await openAndAuthenticate(false, options.signal);
+		reconnectExhausted = false;
+		const sharedConnectPromise = openAndAuthenticate(false, options.signal).finally(() => {
+			if (connectPromise === sharedConnectPromise) connectPromise = null;
+		});
+		connectPromise = sharedConnectPromise;
+		await sharedConnectPromise;
 	};
 	const close = async () => {
 		if (state === "CLOSED" && !transport) {
 			await connectionScope.dispose();
 			return;
 		}
+		permanentlyClosed = true;
 		closeRequested = true;
 		receiveLoopAbort = true;
+		closeAbortController.abort();
 		asyncHandlerDispatcher.close();
 		const scopeDisposePromise = connectionScope.dispose();
 		setState("CLOSED");
@@ -1487,15 +1606,34 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 		await asyncHandlerDispatcher.drain();
 		await scopeDisposePromise;
 	};
-	const request = async (messageType, requestPayload, signal) => {
+	const waitForRequestReady = async (signal, allowReconnectRestore = false) => {
+		if (allowReconnectRestore && reconnectRestoreActive && state === "AUTHENTICATING" && !closeRequested && !authRejected && transport) return;
+		const releaseReadyWaitSlot = acquireReadyWaitSlot();
+		try {
+			await waitForReady(signal, timeout);
+		} finally {
+			releaseReadyWaitSlot?.();
+		}
 		ensureAuthenticated();
+	};
+	const requestInternal = async (messageType, requestPayload, signal, allowReconnectRestore = false) => {
+		let sendStarted = false;
+		await waitForRequestReady(signal, allowReconnectRestore);
 		const releaseRequestSlot = await requestGate.acquire(signal);
 		const startedAt = Date.now();
 		try {
 			const activeTransport = ensureTransport();
 			const frame = FrameCodec.encodeFrame(messageType, requestPayload);
-			return await multiplexer.request(messageType, frame, (data) => sendSerialized(activeTransport, data), timeout, signal);
+			return await multiplexer.request(messageType, frame, (data) => {
+				sendStarted = true;
+				return sendSerialized(activeTransport, data);
+			}, timeout, signal);
 		} catch (error) {
+			attachResilienceMeta(error, {
+				boundary: sendStarted ? "post-send" : "pre-send",
+				failureKind: classifyFailureKind(error),
+				explicitNegative: false
+			});
 			log("error", "fitz.connection.request_failed", {
 				operation: "request",
 				state,
@@ -1510,13 +1648,34 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 			releaseRequestSlot();
 		}
 	};
-	const send = async (messageType, requestPayload) => {
+	const request = async (messageType, requestPayload, signal) => {
+		return await requestInternal(messageType, requestPayload, signal);
+	};
+	const requestDuringReconnectRestore = async (messageType, requestPayload, signal) => {
+		return await requestInternal(messageType, requestPayload, signal, true);
+	};
+	const send = async (messageType, requestPayload, signal) => {
+		let sendStarted = false;
+		const releaseReadyWaitSlot = acquireReadyWaitSlot();
+		try {
+			await waitForReady(signal, timeout);
+		} finally {
+			releaseReadyWaitSlot?.();
+		}
 		ensureAuthenticated();
-		const releaseRequestSlot = await requestGate.acquire();
+		const releaseRequestSlot = await requestGate.acquire(signal);
 		const startedAt = Date.now();
 		try {
-			await sendSerialized(ensureTransport(), FrameCodec.encodeFrame(messageType, requestPayload));
+			const activeTransport = ensureTransport();
+			const frame = FrameCodec.encodeFrame(messageType, requestPayload);
+			sendStarted = true;
+			await sendSerialized(activeTransport, frame);
 		} catch (error) {
+			attachResilienceMeta(error, {
+				boundary: sendStarted ? "post-send" : "pre-send",
+				failureKind: classifyFailureKind(error),
+				explicitNegative: false
+			});
 			log("error", "fitz.connection.send_failed", {
 				operation: "send",
 				state,
@@ -1531,8 +1690,8 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 			releaseRequestSlot();
 		}
 	};
-	const sendFireAndForget = async (messageType, requestPayload) => {
-		await send(messageType, requestPayload);
+	const sendFireAndForget = async (messageType, requestPayload, signal) => {
+		await send(messageType, requestPayload, signal);
 	};
 	const registerNotificationHandler = (messageType, handler) => {
 		multiplexer.registerNotificationHandler(messageType, handler);
@@ -1560,8 +1719,138 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 	const getState = () => state;
 	const isConnected = () => state === "AUTHENTICATED";
 	const getUrl = () => ensureTransport().getUrl();
+	const canWaitForReconnect = () => {
+		return reconnectEnabled && hasEstablishedSession && !reconnectExhausted && !authRejected;
+	};
+	const readyFailure = () => {
+		if (state === "AUTHENTICATED") return null;
+		if (closeRequested || state === "CLOSED") return connectionClosedError();
+		if (authRejected) return new AuthenticationError("Authentication rejected", { state });
+		if (state === "CONNECTING" || state === "CONNECTED" || state === "AUTHENTICATING" || state === "RECONNECTING") return null;
+		if (state === "DISCONNECTED" && canWaitForReconnect()) return null;
+		return new ConnectionError(`Cannot use connection while state is ${state}`, { state });
+	};
+	const notifyReadyListeners = () => {
+		for (const listener of readyListeners) listener();
+	};
+	const acquireReadyWaitSlot = () => {
+		const failure = readyFailure();
+		if (state === "AUTHENTICATED" || failure) return null;
+		if (readyWaiterCount >= maxRequestQueueSize) throw new RequestQueueFullError();
+		readyWaiterCount += 1;
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			readyWaiterCount = Math.max(readyWaiterCount - 1, 0);
+		};
+	};
+	const waitForReady = async (signal, waitTimeoutMs = timeout) => {
+		throwIfAborted$1(signal);
+		const immediateFailure = readyFailure();
+		if (!immediateFailure) {
+			if (state === "AUTHENTICATED") return;
+		} else throw immediateFailure;
+		await new Promise((resolve, reject) => {
+			let settled = false;
+			let timeoutId = null;
+			const cleanup = () => {
+				readyListeners.delete(onStateChange);
+				if (timeoutId) clearTimeout(timeoutId);
+				signal?.removeEventListener("abort", onAbort);
+			};
+			const settle = (cb) => {
+				if (settled) return;
+				settled = true;
+				cleanup();
+				cb();
+			};
+			const onAbort = () => {
+				settle(() => reject(abortError$1()));
+			};
+			const onStateChange = () => {
+				const failure = readyFailure();
+				if (state === "AUTHENTICATED") {
+					settle(resolve);
+					return;
+				}
+				if (failure) settle(() => reject(failure));
+			};
+			readyListeners.add(onStateChange);
+			signal?.addEventListener("abort", onAbort, { once: true });
+			timeoutId = setTimeout(() => {
+				settle(() => reject(new ConnectionError("Timed out waiting for connection to become ready", { state })));
+			}, waitTimeoutMs);
+			onStateChange();
+		});
+	};
+	const waitUntilReady = async (signal, waitTimeoutMs = timeout) => {
+		await waitForReady(signal, waitTimeoutMs);
+	};
+	const shouldWaitForReconnect = () => {
+		return reconnectPromise !== null || state === "RECONNECTING" || state === "DISCONNECTED" && canWaitForReconnect();
+	};
+	const getRetryDelayMs = (baseDelayMs) => {
+		const jitter = Math.floor(Math.random() * baseDelayMs * .5);
+		return Math.min(Math.max(baseDelayMs + jitter, 1), retryMaxBackoffMs);
+	};
+	const recordRetry = (operation, attempt, delayMs, error) => {
+		const meta = getResilienceMeta(error);
+		log("warn", "fitz.request.retry", {
+			domain: operation.domain,
+			operation: operation.operation,
+			attempt,
+			delayMs,
+			boundary: meta?.boundary ?? "unknown",
+			error: describeError(error),
+			...describeErrorFields(error)
+		});
+		observability?.meter?.counter("fitz.request.retry", 1, {
+			domain: operation.domain,
+			operation: operation.operation,
+			boundary: meta?.boundary ?? "unknown"
+		});
+	};
+	const recordRetryExhausted = (operation, attempt, error) => {
+		const meta = getResilienceMeta(error);
+		log("warn", "fitz.request.retry_exhausted", {
+			domain: operation.domain,
+			operation: operation.operation,
+			attempt,
+			boundary: meta?.boundary ?? "unknown",
+			error: describeError(error),
+			...describeErrorFields(error)
+		});
+		observability?.meter?.counter("fitz.request.retry_exhausted", 1, {
+			domain: operation.domain,
+			operation: operation.operation,
+			boundary: meta?.boundary ?? "unknown"
+		});
+	};
+	const executeWithRetry = async (operation, task) => {
+		if (!retryEnabled || operation.retryClass === "wait_only") return task();
+		let attempt = 0;
+		let delayMs = retryBackoffMs;
+		while (true) {
+			attempt += 1;
+			try {
+				return await task();
+			} catch (error) {
+				if (isAbortError$1(error)) throw error;
+				if (!shouldRetryOperation(operation.retryClass, error)) throw error;
+				if (attempt >= retryMaxAttempts) {
+					recordRetryExhausted(operation, attempt, error);
+					throw error;
+				}
+				const actualDelayMs = getRetryDelayMs(delayMs);
+				recordRetry(operation, attempt, actualDelayMs, error);
+				await sleepWithAbort(actualDelayMs, operation.signal);
+				delayMs = Math.min(delayMs * 2, retryMaxBackoffMs);
+			}
+		}
+	};
 	const openAndAuthenticate = async (isReconnect, signal) => {
-		throwIfAborted(signal);
+		throwIfAborted$1(signal);
 		receiveLoopAbort = false;
 		frameParser.parseFrames(new Uint8Array(0));
 		requestGate = createRequestGate(maxInFlightRequests, maxRequestQueueSize);
@@ -1575,7 +1864,7 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 			if (transport === activeTransport) transport = null;
 			throw connectionClosedError();
 		}
-		throwIfAborted(signal);
+		throwIfAborted$1(signal);
 		receiveLoop = startReceiveLoop();
 		setState("CONNECTED");
 		setState("AUTHENTICATING");
@@ -1584,21 +1873,30 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 		try {
 			await sendConnect();
 			if (closeRequested) throw connectionClosedError();
-			throwIfAborted(signal);
+			throwIfAborted$1(signal);
 			await Promise.race([authOutcome.promise, sleep(authSettleDelayMs)]);
 			if (closeRequested) throw connectionClosedError();
-			throwIfAborted(signal);
+			throwIfAborted$1(signal);
 			authOutcome?.resolve();
 			authOutcome = null;
 			if (isReconnect) {
-				await restoreReconnectState();
-				if (closeRequested) throw connectionClosedError();
+				multiplexer.setConnected();
+				reconnectRestoreActive = true;
+				try {
+					await restoreReconnectState();
+					if (closeRequested) throw connectionClosedError();
+				} finally {
+					reconnectRestoreActive = false;
+				}
 			}
+			hasEstablishedSession = true;
+			reconnectExhausted = false;
 			setState("AUTHENTICATED");
-			multiplexer.setConnected();
+			if (!isReconnect) multiplexer.setConnected();
 			emitLifecycleEvent(isReconnect ? "reconnect_succeeded" : "connect_succeeded");
 		} catch (error) {
 			authOutcome = null;
+			reconnectRestoreActive = false;
 			multiplexer.setDisconnected();
 			emitDisconnect();
 			if (activeTransport) await activeTransport.close().catch(() => void 0);
@@ -1608,7 +1906,7 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 			if (closeRequested) setState("CLOSED");
 			else setState(rejectedAuth ? "CLOSED" : "DISCONNECTED");
 			emitLifecycleEvent(isReconnect ? "reconnect_failed" : "connect_failed", error);
-			if (isAbortError$1(error)) throw abortError();
+			if (isAbortError$1(error)) throw abortError$1();
 			throw error;
 		}
 	};
@@ -1649,6 +1947,7 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 			emitLifecycleEvent("auth_rejected", error);
 			return;
 		}
+		reconnectExhausted = false;
 		setState("DISCONNECTED");
 		emitLifecycleEvent("connection_lost", error);
 		if (!reconnectEnabled) return;
@@ -1670,12 +1969,13 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 			emitLifecycleEvent("reconnect_scheduled", void 0, attempts);
 			const actualDelayMs = getReconnectDelayMs(delayMs);
 			try {
-				await sleep(actualDelayMs);
+				await sleepWithAbort(actualDelayMs, closeAbortController.signal);
 				if (closeRequested) return;
 				await openAndAuthenticate(true);
 				return;
 			} catch (error) {
 				if (closeRequested) return;
+				if (isAbortError$1(error)) return;
 				log("warn", "fitz.connection.reconnect_retry", {
 					attempts,
 					delayMs: actualDelayMs,
@@ -1689,6 +1989,7 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 			setState("CLOSED");
 			return;
 		}
+		reconnectExhausted = true;
 		setState("DISCONNECTED");
 		emitLifecycleEvent("reconnect_exhausted", void 0, attempts);
 	};
@@ -1709,6 +2010,7 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 	};
 	const setState = (newState) => {
 		state = newState;
+		notifyReadyListeners();
 	};
 	const sendSerialized = async (transport, data) => {
 		const prior = writeChain;
@@ -1748,6 +2050,7 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 		connect,
 		close,
 		request,
+		requestDuringReconnectRestore,
 		send,
 		sendFireAndForget,
 		registerNotificationHandler,
@@ -1756,6 +2059,9 @@ function createConnection(transportFactory, tokenProvider, options = {}) {
 		onDisconnect,
 		getMultiplexer,
 		dispatchAsyncHandler,
+		executeWithRetry,
+		waitUntilReady,
+		shouldWaitForReconnect,
 		getScope,
 		getState,
 		isConnected,
@@ -2139,11 +2445,23 @@ function createTransport(url, transportType = "auto", options = {}) {
 //#region src/domains/base.ts
 function createDomainClient(connection) {
 	const requestFrame = async (messageType, payload, signal) => connection.request(messageType, payload, signal);
+	const requestReconnectFrame = async (messageType, payload, signal) => {
+		const resilientConnection = connection;
+		if (typeof resilientConnection.requestDuringReconnectRestore === "function") return await resilientConnection.requestDuringReconnectRestore(messageType, payload, signal);
+		return await connection.request(messageType, payload, signal);
+	};
 	const sendFrame = async (messageType, payload) => connection.send(messageType, payload);
+	const runWithRetry = async (operation, task) => {
+		const resilientConnection = connection;
+		if (typeof resilientConnection.executeWithRetry === "function") return resilientConnection.executeWithRetry(operation, task);
+		return task();
+	};
 	return {
 		connection,
 		requestFrame,
-		sendFrame
+		requestReconnectFrame,
+		sendFrame,
+		runWithRetry
 	};
 }
 //#endregion
@@ -2321,8 +2639,11 @@ function createAsyncIterableIterator(iterator) {
 //#region src/domains/kv/transaction.ts
 function createKvTransaction(connection, route, txId) {
 	let closed = false;
-	const unsubscribeDisconnect = connection.onDisconnect(() => {
+	const resilientConnection = connection;
+	let unsubscribeDisconnect = () => void 0;
+	unsubscribeDisconnect = connection.onDisconnect(() => {
 		closed = true;
+		unsubscribeDisconnect();
 	});
 	const ensureOpen = () => {
 		if (closed) throw new KvError("Transaction already closed", "TX_CLOSED");
@@ -2337,6 +2658,10 @@ function createKvTransaction(connection, route, txId) {
 			[5]: "OperationNotAllowed"
 		}[status] ?? `Unknown(${status})`}`, operation, status);
 	};
+	const runWithRetry = async (operation, task) => {
+		if (typeof resilientConnection.executeWithRetry === "function") return resilientConnection.executeWithRetry(operation, task);
+		return task();
+	};
 	const put = async (key, value, signal) => {
 		ensureOpen();
 		const payload = KvCodec.encodePut(txId, route, key, value);
@@ -2351,15 +2676,22 @@ function createKvTransaction(connection, route, txId) {
 	};
 	const get = async (key, signal) => {
 		ensureOpen();
-		const payload = KvCodec.encodeGet(txId, route, key);
-		const response = await connection.request(103, payload, signal);
-		const decoded = KvCodec.decodeGetResponse(response);
-		checkStatus(decoded.status, "GET");
-		if (!decoded.found || !decoded.value) return { type: "not-found" };
-		return {
-			type: "found",
-			value: decoded.value
-		};
+		return runWithRetry({
+			domain: "kv",
+			operation: "get",
+			retryClass: "replayable_read",
+			signal
+		}, async () => {
+			const payload = KvCodec.encodeGet(txId, route, key);
+			const response = await connection.request(103, payload, signal);
+			const decoded = KvCodec.decodeGetResponse(response);
+			checkStatus(decoded.status, "GET");
+			if (!decoded.found || !decoded.value) return { type: "not-found" };
+			return {
+				type: "found",
+				value: decoded.value
+			};
+		});
 	};
 	const deleteItem = async (key, signal) => {
 		ensureOpen();
@@ -2375,11 +2707,18 @@ function createKvTransaction(connection, route, txId) {
 	};
 	const scan = async (options = {}, signal) => {
 		ensureOpen();
-		const payload = KvCodec.encodeScan(txId, route, options);
-		const response = await connection.request(108, payload, signal);
-		const decoded = KvCodec.decodeScanResponse(response);
-		checkStatus(decoded.status, "SCAN");
-		return createAsyncIterableIterator(createSliceIterator(decoded.keys));
+		return runWithRetry({
+			domain: "kv",
+			operation: "scan",
+			retryClass: "replayable_read",
+			signal
+		}, async () => {
+			const payload = KvCodec.encodeScan(txId, route, options);
+			const response = await connection.request(108, payload, signal);
+			const decoded = KvCodec.decodeScanResponse(response);
+			checkStatus(decoded.status, "SCAN");
+			return createAsyncIterableIterator(createSliceIterator(decoded.keys));
+		});
 	};
 	const commit = async (signal) => {
 		ensureOpen();
@@ -2659,7 +2998,17 @@ const QueueCodec = {
 //#endregion
 //#region src/domains/queue/types.ts
 function createQueueItem(id, token, body, route, connection) {
+	let closed = false;
+	let unsubscribeDisconnect = () => void 0;
+	unsubscribeDisconnect = connection.onDisconnect(() => {
+		closed = true;
+		unsubscribeDisconnect();
+	});
+	const ensureOpen = () => {
+		if (closed) throw new QueueError("Queue item is no longer valid after disconnect", "ITEM_CLOSED");
+	};
 	const extend = async (leaseSecs, signal) => {
+		ensureOpen();
 		const payload = QueueCodec.encodeExtend(route, id, token, leaseSecs);
 		const response = await connection.request(203, payload, signal);
 		const decoded = QueueCodec.decodeExtendResponse(response);
@@ -2670,6 +3019,7 @@ function createQueueItem(id, token, body, route, connection) {
 		}
 	};
 	const complete = async (signal) => {
+		ensureOpen();
 		const requestPayload = QueueCodec.encodeComplete(route, id, token);
 		const response = await connection.request(204, requestPayload, signal);
 		const decoded = QueueCodec.decodeCompleteResponse(response);
@@ -2678,9 +3028,12 @@ function createQueueItem(id, token, body, route, connection) {
 			const statusName = QueueStatus[errorCode] || `Unknown(${errorCode})`;
 			throw new QueueError(`COMPLETE failed: ${decoded.errorMessage ?? statusName}`, statusName, errorCode);
 		}
+		closed = true;
+		unsubscribeDisconnect();
 	};
 	const testOnlyInvalidToken = () => id + 1n;
 	const testOnlyCompleteWithToken = async (tokenToUse, signal) => {
+		ensureOpen();
 		const requestPayload = QueueCodec.encodeComplete(route, id, tokenToUse);
 		const response = await connection.request(204, requestPayload, signal);
 		const decoded = QueueCodec.decodeCompleteResponse(response);
@@ -2689,6 +3042,8 @@ function createQueueItem(id, token, body, route, connection) {
 			const statusName = QueueStatus[errorCode] || `Unknown(${errorCode})`;
 			throw new QueueError(`COMPLETE failed: ${decoded.errorMessage ?? statusName}`, statusName, errorCode);
 		}
+		closed = true;
+		unsubscribeDisconnect();
 	};
 	return {
 		body,
@@ -2726,7 +3081,7 @@ let QueueStatus = /* @__PURE__ */ function(QueueStatus) {
 * Queue domain client.
 */
 function createQueueClient(connection) {
-	const { requestFrame } = createDomainClient(connection);
+	const { requestFrame, requestReconnectFrame, runWithRetry } = createDomainClient(connection);
 	const subscriptionsByPattern = /* @__PURE__ */ new Map();
 	const patternsBySubId = /* @__PURE__ */ new Map();
 	let notificationHandlerRegistered = false;
@@ -2740,7 +3095,7 @@ function createQueueClient(connection) {
 		subscriptionsByPattern.clear();
 		patternsBySubId.clear();
 		for (const subscription of subscriptions) {
-			const subId = await subscribeWire(subscription.pattern);
+			const subId = await subscribeWire(subscription.pattern, requestReconnectFrame);
 			subscriptionsByPattern.set(subscription.pattern, {
 				subId,
 				handlers: new Map(subscription.handlers)
@@ -2750,11 +3105,17 @@ function createQueueClient(connection) {
 	});
 	const enqueue = async (route, body, options) => {
 		assertQueueRoute(route);
-		const response = await requestFrame(200, QueueCodec.encodeEnqueue(route, body, options));
-		const decoded = QueueCodec.decodeEnqueueResponse(response);
-		checkStatus(decoded, "ENQUEUE");
-		if (decoded.messageId === void 0) throw new QueueError("ENQUEUE response missing messageId", "MISSING_MESSAGE_ID");
-		return decoded.messageId;
+		return runWithRetry({
+			domain: "queue",
+			operation: "enqueue",
+			retryClass: "confirmed_negative_retry"
+		}, async () => {
+			const response = await requestFrame(200, QueueCodec.encodeEnqueue(route, body, options));
+			const decoded = QueueCodec.decodeEnqueueResponse(response);
+			checkStatus(decoded, "ENQUEUE");
+			if (decoded.messageId === void 0) throw new QueueError("ENQUEUE response missing messageId", "MISSING_MESSAGE_ID");
+			return decoded.messageId;
+		});
 	};
 	const reserve = async (route, leaseSeconds, batchSize = 1, waitSeconds = 0) => {
 		assertQueueReserveRoute(route);
@@ -2810,8 +3171,8 @@ function createQueueClient(connection) {
 		if (existing) return addLocalSubscription(pattern, existing.subId, handler);
 		return addLocalSubscription(pattern, await subscribeWire(pattern), handler);
 	};
-	const subscribeWire = async (pattern) => {
-		const response = await requestFrame(207, QueueCodec.encodeSubscribe(wireWatchPattern(pattern)));
+	const subscribeWire = async (pattern, request = requestFrame) => {
+		const response = await request(207, QueueCodec.encodeSubscribe(wireWatchPattern(pattern)));
 		const decoded = QueueCodec.decodeSubscribeResponse(response);
 		checkStatus(decoded, "SUBSCRIBE");
 		if (decoded.subId === void 0) throw new QueueError("SUBSCRIBE response missing subId", "MISSING_SUB_ID");
@@ -2878,7 +3239,11 @@ function createQueueClient(connection) {
 			[4]: "QueueFull",
 			[5]: "InvalidDelay"
 		}[errorCode] ?? `Unknown(${errorCode})`;
-		throw new QueueError(`${operation} failed: ${response.errorMessage ?? statusName}`, statusName, errorCode);
+		throw attachResilienceMeta(new QueueError(`${operation} failed: ${response.errorMessage ?? statusName}`, statusName, errorCode), {
+			boundary: "post-send",
+			failureKind: "domain",
+			explicitNegative: true
+		});
 	};
 	return {
 		enqueue,
@@ -3193,16 +3558,35 @@ function createRpcSubscription(route, unsubscribeFn) {
 */
 function createRpcResponseWriter(connection, correlationId) {
 	let sequence = 0n;
+	let stale = false;
+	let unsubscribeDisconnect = () => void 0;
+	const dispose = () => {
+		if (stale) return;
+		stale = true;
+		unsubscribeDisconnect();
+		unsubscribeDisconnect = () => void 0;
+	};
+	unsubscribeDisconnect = connection.onDisconnect(() => {
+		dispose();
+	});
 	const send = async (body, isEnd) => {
+		if (stale) throw new ConnectionError("RPC response writer is no longer valid");
 		const payload = RpcCodec.encodeResponse(correlationId, sequence++, body, isEnd);
 		try {
 			await connection.send(303, payload);
+			if (isEnd) dispose();
 		} catch (error) {
-			if (isBenignShutdownError(error, connection)) return;
+			if (isBenignShutdownError(error, connection)) {
+				dispose();
+				return;
+			}
 			throw error;
 		}
 	};
-	return { send };
+	return {
+		send,
+		dispose
+	};
 }
 function isBenignShutdownError(error, connection) {
 	if (connection.getState() !== "AUTHENTICATED") return true;
@@ -3350,7 +3734,7 @@ const RpcClient = function(connection) {
 	return createRpcClient(connection);
 };
 function createRpcClient(connection) {
-	const { requestFrame } = createDomainClient(connection);
+	const { requestFrame, requestReconnectFrame } = createDomainClient(connection);
 	const pendingRpcs = /* @__PURE__ */ new Map();
 	const workers = /* @__PURE__ */ new Map();
 	let initialized = false;
@@ -3368,7 +3752,7 @@ function createRpcClient(connection) {
 		if (workers.size === 0) return;
 		const registeredWorkers = Array.from(workers.entries());
 		workers.clear();
-		for (const [route, handler] of registeredWorkers) await registerWorker(route, handler);
+		for (const [route, handler] of registeredWorkers) await registerWorkerInternal(route, handler, requestReconnectFrame);
 	});
 	const call = async (route, body, options) => {
 		assertRpcRoute(route);
@@ -3394,13 +3778,16 @@ function createRpcClient(connection) {
 			throw error;
 		}
 	};
-	const registerWorker = async (route, handler) => {
-		assertRpcRoute(route);
-		initRpcHandler();
-		const response = await requestFrame(300, RpcCodec.encodeSubscribeWorker(route));
+	const registerWorkerInternal = async (route, handler, request = requestFrame) => {
+		const response = await request(300, RpcCodec.encodeSubscribeWorker(route));
 		const decoded = RpcCodec.decodeSubscribeWorkerResponse(response);
 		if (decoded.status !== 0) throw new RpcError(`RPC SUBSCRIBE_WORKER failed: status ${decoded.status}`, "SUBSCRIBE_FAILED", decoded.status);
 		workers.set(route, handler);
+	};
+	const registerWorker = async (route, handler) => {
+		assertRpcRoute(route);
+		initRpcHandler();
+		await registerWorkerInternal(route, handler);
 		const unsubscribeFn = async (registeredRoute) => {
 			await unregisterWorker(registeredRoute);
 		};
@@ -3469,6 +3856,8 @@ function createRpcClient(connection) {
 				try {
 					await writer.send(utf8Encoder.encode(`Handler error: ${message}`), true);
 				} catch {}
+			} finally {
+				writer.dispose();
 			}
 		});
 	};
@@ -3704,7 +4093,17 @@ function createLeaseSubscription(subId, pattern, unsubscribeFn) {
 function createLease(token, expiresAt, route, connection) {
 	let currentToken = token;
 	let currentExpiry = expiresAt;
+	let closed = false;
+	let unsubscribeDisconnect = () => void 0;
+	unsubscribeDisconnect = connection.onDisconnect(() => {
+		closed = true;
+		unsubscribeDisconnect();
+	});
+	const ensureOpen = () => {
+		if (closed) throw new LeaseError("Lease handle is no longer valid after disconnect", "CLOSED");
+	};
 	const extend = async (ttlSecs, signal) => {
+		ensureOpen();
 		const requestPayload = LeaseCodec.encodeExtend(route, currentToken, ttlSecs);
 		const data = assertSuccess(await connection.request(401, requestPayload, signal), "EXTEND");
 		if (data && data.length >= 8) currentToken = new BufferReader(data).readU64BE();
@@ -3712,12 +4111,16 @@ function createLease(token, expiresAt, route, connection) {
 		return currentExpiry;
 	};
 	const release = async (signal) => {
+		ensureOpen();
 		const payload = LeaseCodec.encodeRelease(route, currentToken);
 		assertSuccess(await connection.request(402, payload, signal), "RELEASE");
+		closed = true;
+		unsubscribeDisconnect();
 	};
 	const getExpiry = () => currentExpiry;
 	const testOnlyInvalidToken = () => currentToken + 1n;
 	const testOnlyExtendWithToken = async (tokenToUse, ttlSecs, signal) => {
+		ensureOpen();
 		const requestPayload = LeaseCodec.encodeExtend(route, tokenToUse, ttlSecs);
 		const data = assertSuccess(await connection.request(401, requestPayload, signal), "EXTEND");
 		if (data && data.length >= 8) currentToken = new BufferReader(data).readU64BE();
@@ -3725,8 +4128,11 @@ function createLease(token, expiresAt, route, connection) {
 		return currentExpiry;
 	};
 	const testOnlyReleaseWithToken = async (tokenToUse, signal) => {
+		ensureOpen();
 		const payload = LeaseCodec.encodeRelease(route, tokenToUse);
 		assertSuccess(await connection.request(402, payload, signal), "RELEASE");
+		closed = true;
+		unsubscribeDisconnect();
 	};
 	return {
 		extend,
@@ -3743,7 +4149,7 @@ function createLease(token, expiresAt, route, connection) {
 * Lease domain client.
 */
 function createLeaseClient(connection) {
-	const { requestFrame } = createDomainClient(connection);
+	const { requestFrame, requestReconnectFrame, runWithRetry } = createDomainClient(connection);
 	const subscriptionsByPattern = /* @__PURE__ */ new Map();
 	let initialized = false;
 	let nextHandlerId = 1;
@@ -3755,7 +4161,7 @@ function createLeaseClient(connection) {
 		}));
 		subscriptionsByPattern.clear();
 		for (const subscription of subscriptions) {
-			const subId = await subscribeWire(subscription.pattern);
+			const subId = await subscribeWire(subscription.pattern, requestReconnectFrame);
 			subscriptionsByPattern.set(subscription.pattern, {
 				subId,
 				handlers: new Map(subscription.handlers)
@@ -3772,16 +4178,22 @@ function createLeaseClient(connection) {
 	};
 	const query = async (route) => {
 		assertExactLeaseRoute(route);
-		const response = await requestFrame(403, LeaseCodec.encodeQuery(route));
-		const decoded = LeaseCodec.decodeQueryResponse(response);
-		if (decoded.status !== 0) throw new LeaseError("QUERY failed", "QUERY_FAILED", decoded.status);
-		return {
-			isHeld: decoded.isHeld ?? false,
-			owner: decoded.owner,
-			token: decoded.token,
-			ttlRemainingSecs: decoded.ttlRemainingSecs,
-			expiresAt: decoded.expiresAt
-		};
+		return runWithRetry({
+			domain: "lease",
+			operation: "query",
+			retryClass: "replayable_read"
+		}, async () => {
+			const response = await requestFrame(403, LeaseCodec.encodeQuery(route));
+			const decoded = LeaseCodec.decodeQueryResponse(response);
+			if (decoded.status !== 0) throw new LeaseError("QUERY failed", "QUERY_FAILED", decoded.status);
+			return {
+				isHeld: decoded.isHeld ?? false,
+				owner: decoded.owner,
+				token: decoded.token,
+				ttlRemainingSecs: decoded.ttlRemainingSecs,
+				expiresAt: decoded.expiresAt
+			};
+		});
 	};
 	const subscribe = async (pattern, handler) => {
 		assertExactLeaseRoute(pattern);
@@ -3790,8 +4202,8 @@ function createLeaseClient(connection) {
 		if (existing) return addLocalSubscription(pattern, existing.subId, handler);
 		return addLocalSubscription(pattern, await subscribeWire(pattern), handler);
 	};
-	const subscribeWire = async (pattern) => {
-		const response = await requestFrame(407, LeaseCodec.encodeSubscribe(pattern));
+	const subscribeWire = async (pattern, request = requestFrame) => {
+		const response = await request(407, LeaseCodec.encodeSubscribe(pattern));
 		const decoded = LeaseCodec.decodeSubscribeResponse(response);
 		if (decoded.subId === void 0) throw new LeaseError("SUBSCRIBE failed", "SUBSCRIBE_FAILED");
 		return decoded.subId;
@@ -3938,7 +4350,7 @@ function createNoticeSubscription(subId, pattern, unsubscribeFn) {
 * Notice domain client.
 */
 function createNoticeClient(connection) {
-	const { requestFrame } = createDomainClient(connection);
+	const { requestFrame, requestReconnectFrame } = createDomainClient(connection);
 	const subscriptionsByPattern = /* @__PURE__ */ new Map();
 	const patternsBySubId = /* @__PURE__ */ new Map();
 	let initialized = false;
@@ -3952,7 +4364,7 @@ function createNoticeClient(connection) {
 		subscriptionsByPattern.clear();
 		patternsBySubId.clear();
 		for (const subscription of subscriptions) {
-			const subId = await subscribeWire(subscription.pattern);
+			const subId = await subscribeWire(subscription.pattern, requestReconnectFrame);
 			subscriptionsByPattern.set(subscription.pattern, {
 				subId,
 				handlers: new Map(subscription.handlers)
@@ -3978,8 +4390,8 @@ function createNoticeClient(connection) {
 		if (existing) return addLocalSubscription(pattern, existing.subId, handler);
 		return addLocalSubscription(pattern, await subscribeWire(pattern), handler);
 	};
-	const subscribeWire = async (pattern) => {
-		const response = await requestFrame(501, NoticeCodec.encodeSubscribe(pattern));
+	const subscribeWire = async (pattern, request = requestFrame) => {
+		const response = await request(501, NoticeCodec.encodeSubscribe(pattern));
 		const decoded = NoticeCodec.decodeSubscribeResponse(response);
 		if (decoded.subId === void 0) throw new NoticeError("SUBSCRIBE response missing subId", "MISSING_SUB_ID");
 		return decoded.subId;
@@ -4421,8 +4833,10 @@ function createStreamSubscription(subId, pattern, unsubscribeFn) {
 //#region src/domains/stream/session.ts
 function createStreamSession(connection, _route, sessionId) {
 	let closed = false;
-	const unsubscribeDisconnect = connection.onDisconnect(() => {
+	let unsubscribeDisconnect = () => void 0;
+	unsubscribeDisconnect = connection.onDisconnect(() => {
 		closed = true;
+		unsubscribeDisconnect();
 	});
 	const ensureOpen = () => {
 		if (closed) throw new StreamError("Stream session already closed", "SESSION_CLOSED");
@@ -4496,7 +4910,7 @@ function isAbortSignal(value) {
 * 3. `commit()` or `rollback()` finalizes the session
 */
 function createStreamClient(connection) {
-	const { requestFrame } = createDomainClient(connection);
+	const { requestFrame, requestReconnectFrame, runWithRetry } = createDomainClient(connection);
 	const subscriptionsByPattern = /* @__PURE__ */ new Map();
 	const patternsBySubId = /* @__PURE__ */ new Map();
 	let initialized = false;
@@ -4510,7 +4924,7 @@ function createStreamClient(connection) {
 		subscriptionsByPattern.clear();
 		patternsBySubId.clear();
 		for (const subscription of snapshot) {
-			const subId = await subscribeWire(subscription.pattern);
+			const subId = await subscribeWire(subscription.pattern, requestReconnectFrame);
 			subscriptionsByPattern.set(subscription.pattern, {
 				subId,
 				handlers: new Map(subscription.handlers)
@@ -4528,18 +4942,25 @@ function createStreamClient(connection) {
 	};
 	const readPage = async (route, startOffset, limit = 100, options) => {
 		assertStreamPattern(route);
-		const response = await requestFrame(604, StreamCodec.encodeRead(route, startOffset, limit, options), options?.signal);
-		const decoded = StreamCodec.decodeReadResponse(response);
-		checkStatus(decoded.status, "READ");
-		return {
-			items: decoded.items,
-			cursor: decoded.cursor ?? {
-				lastResourceOffset: startOffset,
-				lastAreaOffset: void 0,
-				lastRealmOffset: void 0,
-				hasMore: false
-			}
-		};
+		return runWithRetry({
+			domain: "stream",
+			operation: "read",
+			retryClass: "replayable_read",
+			signal: options?.signal
+		}, async () => {
+			const response = await requestFrame(604, StreamCodec.encodeRead(route, startOffset, limit, options), options?.signal);
+			const decoded = StreamCodec.decodeReadResponse(response);
+			checkStatus(decoded.status, "READ");
+			return {
+				items: decoded.items,
+				cursor: decoded.cursor ?? {
+					lastResourceOffset: startOffset,
+					lastAreaOffset: void 0,
+					lastRealmOffset: void 0,
+					hasMore: false
+				}
+			};
+		});
 	};
 	const read = async (route, startOffset, limit = 100, options) => {
 		const page = await readPage(route, startOffset, limit, options);
@@ -4550,21 +4971,33 @@ function createStreamClient(connection) {
 	};
 	const peek = async (route) => {
 		assertStreamRoute(route);
-		const response = await requestFrame(605, StreamCodec.encodeLast(route));
-		const decoded = StreamCodec.decodeLastResponse(response);
-		checkStatus(decoded.status, "LAST");
-		return decoded.record ?? null;
+		return runWithRetry({
+			domain: "stream",
+			operation: "last",
+			retryClass: "replayable_read"
+		}, async () => {
+			const response = await requestFrame(605, StreamCodec.encodeLast(route));
+			const decoded = StreamCodec.decodeLastResponse(response);
+			checkStatus(decoded.status, "LAST");
+			return decoded.record ?? null;
+		});
 	};
 	const metadata = async (route) => {
 		assertStreamRoute(route);
-		const response = await requestFrame(606, StreamCodec.encodeMetadata(route));
-		const decoded = StreamCodec.decodeMetadataResponse(response);
-		checkStatus(decoded.status, "GET_METADATA");
-		return decoded.metadata ?? {
-			firstOffset: 0n,
-			lastOffset: 0n,
-			recordCount: 0n
-		};
+		return runWithRetry({
+			domain: "stream",
+			operation: "metadata",
+			retryClass: "replayable_read"
+		}, async () => {
+			const response = await requestFrame(606, StreamCodec.encodeMetadata(route));
+			const decoded = StreamCodec.decodeMetadataResponse(response);
+			checkStatus(decoded.status, "GET_METADATA");
+			return decoded.metadata ?? {
+				firstOffset: 0n,
+				lastOffset: 0n,
+				recordCount: 0n
+			};
+		});
 	};
 	const subscribe = async (pattern, handler) => {
 		assertStreamPattern(pattern);
@@ -4573,8 +5006,8 @@ function createStreamClient(connection) {
 		if (existing) return addLocalSubscription(pattern, existing.subId, handler);
 		return addLocalSubscription(pattern, await subscribeWire(pattern), handler);
 	};
-	const subscribeWire = async (pattern) => {
-		const response = await requestFrame(607, StreamCodec.encodeSubscribe(pattern));
+	const subscribeWire = async (pattern, request = requestFrame) => {
+		const response = await request(607, StreamCodec.encodeSubscribe(pattern));
 		const decoded = StreamCodec.decodeSubscribeResponse(response);
 		checkStatus(decoded.status, "SUBSCRIBE");
 		if (decoded.subId === void 0) throw new StreamError("SUBSCRIBE response missing subId", "MISSING_SESSION_ID");
@@ -4829,7 +5262,7 @@ var ScheduleError$1 = class extends Error {
 * Schedule domain client.
 */
 function createScheduleClient(connection) {
-	const { requestFrame } = createDomainClient(connection);
+	const { requestFrame, requestReconnectFrame } = createDomainClient(connection);
 	const subscriptionsByPattern = /* @__PURE__ */ new Map();
 	const patternsBySubId = /* @__PURE__ */ new Map();
 	let notifyHandlerInitialized = false;
@@ -4843,7 +5276,7 @@ function createScheduleClient(connection) {
 		subscriptionsByPattern.clear();
 		patternsBySubId.clear();
 		for (const subscription of subscriptions) {
-			const subId = await subscribeWire(subscription.pattern);
+			const subId = await subscribeWire(subscription.pattern, requestReconnectFrame);
 			subscriptionsByPattern.set(subscription.pattern, {
 				subId,
 				handlers: new Map(subscription.handlers)
@@ -4873,8 +5306,8 @@ function createScheduleClient(connection) {
 		if (existing) return addLocalSubscription(pattern, existing.subId, handler);
 		return addLocalSubscription(pattern, await subscribeWire(pattern), handler);
 	};
-	const subscribeWire = async (pattern) => {
-		const response = await requestFrame(703, ScheduleCodec.encodeSubscribe(pattern));
+	const subscribeWire = async (pattern, request = requestFrame) => {
+		const response = await request(703, ScheduleCodec.encodeSubscribe(pattern));
 		return ScheduleCodec.decodeSubscribeResponse(assertSuccess(response, "SUBSCRIBE")).subId;
 	};
 	const addLocalSubscription = (pattern, subId, handler) => {
@@ -4947,6 +5380,39 @@ function assertConcreteScheduleRoute(route) {
 }
 //#endregion
 //#region src/client/client.ts
+const abortError = () => {
+	const error = /* @__PURE__ */ new Error("The operation was aborted");
+	error.name = "AbortError";
+	return error;
+};
+const throwIfAborted = (signal) => {
+	if (signal?.aborted) throw abortError();
+};
+const waitForSharedPromise = async (promise, signal) => {
+	if (!signal) return promise;
+	if (signal.aborted) throw abortError();
+	return await new Promise((resolve, reject) => {
+		let settled = false;
+		const cleanup = () => {
+			signal.removeEventListener("abort", onAbort);
+		};
+		const settle = (callback) => {
+			if (settled) return;
+			settled = true;
+			cleanup();
+			callback();
+		};
+		const onAbort = () => {
+			settle(() => reject(abortError()));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		promise.then((value) => {
+			settle(() => resolve(value));
+		}, (error) => {
+			settle(() => reject(error));
+		});
+	});
+};
 function createClient(config) {
 	const observability = config.observability;
 	const resolvedConfig = {
@@ -4958,12 +5424,19 @@ function createClient(config) {
 		maxRequestQueueSize: 1024,
 		observability: config.observability ?? {},
 		reconnect: {
-			enabled: false,
+			enabled: true,
 			maxAttempts: Infinity,
 			backoffMs: 250,
 			maxBackoffMs: 5e3,
 			...config.reconnect
 		},
+		retry: {
+			enabled: true,
+			maxAttempts: 3,
+			backoffMs: 100,
+			maxBackoffMs: 1e3,
+			...config.retry
+		},
 		asyncHandlers: {
 			maxConcurrency: Infinity,
 			timeoutMs: 3e4,
@@ -4980,16 +5453,19 @@ function createClient(config) {
 	let noticeClient = null;
 	let streamClient = null;
 	let scheduleClient = null;
+	let clientClosed = false;
+	let pendingConnectPromise = null;
 	const resolveTokenProvider = () => {
 		if (resolvedConfig.tokenProvider) return resolvedConfig.tokenProvider;
 		return () => "";
 	};
 	const ensureConnection = () => {
+		if (clientClosed) throw new ConnectionError("Client is closed", { state: "CLOSED" });
 		if (!connection) throw new ConnectionError("Not connected to Fitz server. Call connect() first.", { state: getState() });
 		return connection;
 	};
-	const connect = async (options = {}) => {
-		if (connection?.isConnected()) return;
+	const createOwnedConnection = () => {
+		if (connection) return connection;
 		connection = createConnection(() => createTransport(resolvedConfig.url, resolvedConfig.transport, {
 			timeout: resolvedConfig.timeout,
 			maxFrameSize: resolvedConfig.maxFrameSize
@@ -4999,15 +5475,48 @@ function createClient(config) {
 			maxInFlightRequests: resolvedConfig.maxInFlightRequests,
 			maxRequestQueueSize: resolvedConfig.maxRequestQueueSize,
 			reconnect: resolvedConfig.reconnect,
+			retry: resolvedConfig.retry,
 			observability,
 			asyncHandlers: resolvedConfig.asyncHandlers
 		});
-		await connection.connect(options);
+		return connection;
+	};
+	const connect = async (options = {}) => {
+		if (clientClosed) throw new ConnectionError("Client is closed", { state: "CLOSED" });
+		throwIfAborted(options.signal);
+		const activeConnection = createOwnedConnection();
+		if (activeConnection.isConnected()) return;
+		if (pendingConnectPromise) {
+			await waitForSharedPromise(pendingConnectPromise, options.signal);
+			return;
+		}
+		const state = activeConnection.getState();
+		const trackedConnectPromise = (state === "CONNECTING" || state === "CONNECTED" || state === "AUTHENTICATING" || state === "RECONNECTING" || state === "DISCONNECTED" && typeof activeConnection.shouldWaitForReconnect === "function" && activeConnection.shouldWaitForReconnect() ? typeof activeConnection.waitUntilReady === "function" ? activeConnection.waitUntilReady(void 0, resolvedConfig.timeout) : activeConnection.connect() : activeConnection.connect(options)).finally(() => {
+			if (pendingConnectPromise === trackedConnectPromise) pendingConnectPromise = null;
+		});
+		pendingConnectPromise = trackedConnectPromise;
+		await waitForSharedPromise(trackedConnectPromise, options.signal);
 	};
 	const close = async () => {
+		if (clientClosed && !connection) {
+			kvClient = null;
+			queueClient = null;
+			rpcClient = null;
+			leaseClient = null;
+			noticeClient = null;
+			streamClient = null;
+			scheduleClient = null;
+			return;
+		}
+		clientClosed = true;
+		pendingConnectPromise = null;
 		if (connection) {
-			await connection.close();
-			connection = null;
+			const activeConnection = connection;
+			try {
+				await activeConnection.close();
+			} finally {
+				if (connection === activeConnection) connection = null;
+			}
 		}
 		kvClient = null;
 		queueClient = null;
@@ -5018,7 +5527,7 @@ function createClient(config) {
 		scheduleClient = null;
 	};
 	const isConnected = () => {
-		return connection?.isConnected() ?? false;
+		return !clientClosed && (connection?.isConnected() ?? false);
 	};
 	const kv = () => {
 		const activeConnection = ensureConnection();
@@ -5059,7 +5568,10 @@ function createClient(config) {
 		return ensureConnection().getUrl();
 	};
 	const getState = () => {
-		return connection?.getState() ?? "DISCONNECTED";
+		if (clientClosed) return "CLOSED";
+		if (!connection) return "DISCONNECTED";
+		const state = connection.getState();
+		return state === "CLOSED" ? "DISCONNECTED" : state;
 	};
 	return {
 		config: resolvedConfig,