@tinycloud/replica 0.3.0-beta.5 → 0.3.0-beta.7

package/dist/{kv-storage.worker.67e46cebbda277040312a770449123633491901d6cceacea95754a843e01e9c9.js → kv-storage.worker.850a5e19b486939f03586f7d1294934f54f44cca0224450b1ba94dfb07912a75.js}

@@ -2814,7 +2814,7 @@ var ErrorCodes = {
   PERMISSION_DENIED: "PERMISSION_DENIED",
   // Node retry signals (tinycloud-node #347). `meta.retryable` says whether a
   // retry is safe; `meta.retryAfterMs` carries the node's Retry-After.
-  /** HTTP 503 `sql_busy:<stage>` / `unavailable_retryable`: nothing was applied; retry after `meta.retryAfterMs`. */
+  /** HTTP 503 `sql_busy:<stage>` / `unavailable_retryable`/`read_audit_busy`: nothing was applied; retry after `meta.retryAfterMs`. */
   NODE_BUSY: "NODE_BUSY",
   /** HTTP 503 `request_timeout`: the node's deadline passed before any write began; nothing was applied. */
   REQUEST_TIMEOUT: "REQUEST_TIMEOUT",
@@ -2855,11 +2855,12 @@ var ErrorCodes = {
   DUCKDB_READONLY_VIOLATION: "DUCKDB_READONLY_VIOLATION"
 };
 var defaultRetryPolicy = {
-  maxAttempts: 3,
+  maxAttempts: 4,
   backoff: "exponential",
-  baseDelayMs: 1e3,
-  maxDelayMs: 1e4,
-  retryableErrors: [ErrorCodes.NETWORK_ERROR, ErrorCodes.TIMEOUT]
+  baseDelayMs: 250,
+  maxDelayMs: 4e3,
+  retryableErrors: [ErrorCodes.NODE_BUSY, ErrorCodes.REQUEST_TIMEOUT],
+  maxTotalMs: 12e3
 };
 var grantableActions = new Set(
   CAPABILITY_REGISTRY.map(({ urn }) => urn).filter((urn) => !urn.endsWith("/*"))
@@ -11169,7 +11170,7 @@ var ErrorCodes2 = {
   PERMISSION_DENIED: "PERMISSION_DENIED",
   // Node retry signals (tinycloud-node #347). `meta.retryable` says whether a
   // retry is safe; `meta.retryAfterMs` carries the node's Retry-After.
-  /** HTTP 503 `sql_busy:<stage>` / `unavailable_retryable`: nothing was applied; retry after `meta.retryAfterMs`. */
+  /** HTTP 503 `sql_busy:<stage>` / `unavailable_retryable`/`read_audit_busy`: nothing was applied; retry after `meta.retryAfterMs`. */
   NODE_BUSY: "NODE_BUSY",
   /** HTTP 503 `request_timeout`: the node's deadline passed before any write began; nothing was applied. */
   REQUEST_TIMEOUT: "REQUEST_TIMEOUT",
@@ -11210,11 +11211,12 @@ var ErrorCodes2 = {
   DUCKDB_READONLY_VIOLATION: "DUCKDB_READONLY_VIOLATION"
 };
 var defaultRetryPolicy2 = {
-  maxAttempts: 3,
+  maxAttempts: 4,
   backoff: "exponential",
-  baseDelayMs: 1e3,
-  maxDelayMs: 1e4,
-  retryableErrors: [ErrorCodes2.NETWORK_ERROR, ErrorCodes2.TIMEOUT]
+  baseDelayMs: 250,
+  maxDelayMs: 4e3,
+  retryableErrors: [ErrorCodes2.NODE_BUSY, ErrorCodes2.REQUEST_TIMEOUT],
+  maxTotalMs: 12e3
 };
 var TelemetryEvents = {
   SPAN: "telemetry.span",
@@ -11634,7 +11636,9 @@ var RetryPolicySchema = external_exports.object({
   /** Maximum delay in milliseconds between retries */
   maxDelayMs: external_exports.number().nonnegative(),
   /** Error codes that should trigger a retry */
-  retryableErrors: external_exports.array(external_exports.string())
+  retryableErrors: external_exports.array(external_exports.string()),
+  /** Total time budget for all attempts and waits, in milliseconds */
+  maxTotalMs: external_exports.number().positive().optional()
 });
 var ServiceSessionSchema = external_exports.object({
   /** The delegation header containing the UCAN */
@@ -11650,345 +11654,6 @@ var ServiceSessionSchema = external_exports.object({
   /** The session key JWK (required for invoke) */
   jwk: external_exports.object({}).passthrough()
 });
-var ServiceContext = class {
-  constructor(config) {
-    this._session = null;
-    this._services = /* @__PURE__ */ new Map();
-    this._eventHandlers = /* @__PURE__ */ new Map();
-    this._abortController = new AbortController();
-    this._retired = false;
-    this._invoke = this.wrapInvoke(config.invoke);
-    this._invokeAny = config.invokeAny ? this.wrapInvokeAny(config.invokeAny) : void 0;
-    this._fetch = this.wrapFetch(config.fetch ?? globalThis.fetch.bind(globalThis));
-    this._hosts = config.hosts;
-    this._session = config.session ?? null;
-    this._retryPolicy = {
-      ...defaultRetryPolicy2,
-      ...config.retryPolicy
-    };
-    this._telemetryEnabled = typeof config.telemetry === "boolean" ? config.telemetry : config.telemetry?.enabled === true;
-    this._telemetryHandler = typeof config.telemetry === "object" ? config.telemetry.onEvent : void 0;
-  }
-  // ============================================================
-  // Session Management
-  // ============================================================
-  /**
-   * Get the current session.
-   */
-  get session() {
-    return this._retired ? null : this._session;
-  }
-  /**
-   * Check if the context has an authenticated session.
-   */
-  get isAuthenticated() {
-    return !this._retired && this._session !== null;
-  }
-  /**
-   * Update the session and notify all registered services.
-   *
-   * @param session - New session or null to clear
-   */
-  setSession(session) {
-    this.assertActive();
-    this._session = session;
-    this.emit("session.changed", { authenticated: session !== null });
-    for (const service of this._services.values()) {
-      service.onSessionChange(session);
-    }
-  }
-  // ============================================================
-  // Platform Dependencies
-  // ============================================================
-  /**
-   * Get the invoke function for WASM operations.
-   */
-  get invoke() {
-    this.assertActive();
-    return this._invoke;
-  }
-  /**
-   * Get the multi-resource invoke function when available.
-   */
-  get invokeAny() {
-    this.assertActive();
-    return this._invokeAny;
-  }
-  /**
-   * Get the fetch function for HTTP requests.
-   */
-  get fetch() {
-    this.assertActive();
-    return this._fetch;
-  }
-  /**
-   * Get the list of TinyCloud host URLs.
-   */
-  get hosts() {
-    this.assertActive();
-    return this._hosts;
-  }
-  // ============================================================
-  // Service Registry
-  // ============================================================
-  /**
-   * Register a service with the context.
-   *
-   * @param name - Service name (e.g., 'kv')
-   * @param service - Service instance
-   */
-  registerService(name, service) {
-    this._services.set(name, service);
-  }
-  /**
-   * Unregister a service from the context.
-   *
-   * @param name - Service name to remove
-   */
-  unregisterService(name) {
-    this._services.delete(name);
-  }
-  /**
-   * Get a registered service by name.
-   *
-   * @param name - Service name
-   * @returns The service instance or undefined if not registered
-   */
-  getService(name) {
-    return this._services.get(name);
-  }
-  // ============================================================
-  // Event System (Telemetry)
-  // ============================================================
-  /**
-   * Emit a telemetry event.
-   *
-   * @param event - Event name
-   * @param data - Event data
-   */
-  emit(event, data) {
-    tinyCloudDebugLogger.log(event, data);
-    if (this._telemetryEnabled && this._telemetryHandler) {
-      try {
-        this._telemetryHandler(event, projectDiagnosticData(data));
-      } catch (error) {
-        console.error(`Error in telemetry handler for "${event}":`, error);
-      }
-    }
-    const handlers = this._eventHandlers.get(event);
-    if (handlers) {
-      for (const handler of handlers) {
-        try {
-          handler(data);
-        } catch (error) {
-          console.error(`Error in event handler for "${event}":`, error);
-        }
-      }
-    }
-  }
-  /**
-   * Subscribe to telemetry events.
-   *
-   * @param event - Event name to subscribe to
-   * @param handler - Handler function
-   * @returns Unsubscribe function
-   */
-  on(event, handler) {
-    if (!this._eventHandlers.has(event)) {
-      this._eventHandlers.set(event, /* @__PURE__ */ new Set());
-    }
-    this._eventHandlers.get(event).add(handler);
-    return () => {
-      const handlers = this._eventHandlers.get(event);
-      if (handlers) {
-        handlers.delete(handler);
-        if (handlers.size === 0) {
-          this._eventHandlers.delete(event);
-        }
-      }
-    };
-  }
-  /**
-   * Remove all event handlers for an event.
-   *
-   * @param event - Event name (if omitted, clears all events)
-   */
-  clearEventHandlers(event) {
-    if (event) {
-      this._eventHandlers.delete(event);
-    } else {
-      this._eventHandlers.clear();
-    }
-  }
-  // ============================================================
-  // Lifecycle
-  // ============================================================
-  /**
-   * Get the abort signal for cancelling operations.
-   */
-  get abortSignal() {
-    return this._abortController.signal;
-  }
-  get operationAbortSignal() {
-    return this._operationAbortSignal;
-  }
-  setOperationAbortSignal(signal) {
-    this._operationAbortSignal = signal;
-  }
-  /**
-   * Permanently retire this graph after its owner installs a replacement.
-   * Unlike `abort()`, retirement never creates a fresh controller, so captured
-   * services cannot resume calls under a superseded session.
-   */
-  retire() {
-    if (this._retired) return;
-    this._retired = true;
-    this._session = null;
-    this._abortController.abort();
-    for (const service of this._services.values()) {
-      try {
-        service.onSignOut();
-      } catch (error) {
-        console.error("Error retiring service:", error);
-      }
-    }
-  }
-  /**
-   * Abort all pending operations and notify services.
-   * Creates a new AbortController for future operations.
-   */
-  abort() {
-    if (this._retired) return;
-    this._abortController.abort();
-    this._abortController = new AbortController();
-    for (const service of this._services.values()) {
-      try {
-        service.onSignOut();
-      } catch (error) {
-        console.error("Error signing out service:", error);
-      }
-    }
-  }
-  /**
-   * Sign out - abort operations and clear session.
-   */
-  signOut() {
-    if (this._retired) return;
-    this.abort();
-    this.setSession(null);
-    this.emit("session.expired", {});
-  }
-  // ============================================================
-  // Retry Policy
-  // ============================================================
-  /**
-   * Get the retry policy configuration.
-   */
-  get retryPolicy() {
-    return this._retryPolicy;
-  }
-  wrapInvoke(invoke) {
-    return (session, service, path, action, facts) => {
-      this.assertActive();
-      if (!tinyCloudDebugLogger.isEnabled()) {
-        return invoke(session, service, path, action, facts);
-      }
-      const timer = tinyCloudDebugLogger.startTimer("sdk.invoke", {
-        service,
-        path,
-        action,
-        facts
-      });
-      try {
-        const result = invoke(session, service, path, action, facts);
-        timer.stop({ ok: true, service, path, action });
-        return result;
-      } catch (error) {
-        timer.stop({ ok: false, service, path, action, error });
-        throw error;
-      }
-    };
-  }
-  assertActive() {
-    if (this._retired) {
-      throw new Error("Service graph has been retired: its session was replaced or signed out.");
-    }
-  }
-  wrapInvokeAny(invokeAny) {
-    return (session, entries, facts) => {
-      this.assertActive();
-      if (!tinyCloudDebugLogger.isEnabled()) {
-        return invokeAny(session, entries, facts);
-      }
-      const timer = tinyCloudDebugLogger.startTimer("sdk.invokeAny", {
-        entries,
-        facts
-      });
-      try {
-        const result = invokeAny(session, entries, facts);
-        timer.stop({ ok: true, entries });
-        return result;
-      } catch (error) {
-        timer.stop({ ok: false, entries, error });
-        throw error;
-      }
-    };
-  }
-  wrapFetch(fetchFn) {
-    return async (url, init) => {
-      this.assertActive();
-      const request = {
-        ...init,
-        signal: this.combineSignals(init?.signal)
-      };
-      if (!tinyCloudDebugLogger.isEnabled()) {
-        return fetchFn(url, request);
-      }
-      const timer = tinyCloudDebugLogger.startTimer("sdk.fetch", {
-        url,
-        method: request.method ?? "GET",
-        init: request
-      });
-      try {
-        const response = await fetchFn(url, request);
-        timer.stop({
-          ok: response.ok,
-          url,
-          method: request.method ?? "GET",
-          status: response.status,
-          statusText: response.statusText
-        });
-        return response;
-      } catch (error) {
-        timer.stop({
-          ok: false,
-          url,
-          method: request.method ?? "GET",
-          error
-        });
-        throw error;
-      }
-    };
-  }
-  combineSignals(signal) {
-    if (!signal) return this._abortController.signal;
-    const combined = new AbortController();
-    const abort = (source) => combined.abort(source.reason);
-    if (signal.aborted) {
-      abort(signal);
-    } else if (this._abortController.signal.aborted) {
-      abort(this._abortController.signal);
-    } else {
-      signal.addEventListener("abort", () => abort(signal), { once: true });
-      this._abortController.signal.addEventListener(
-        "abort",
-        () => abort(this._abortController.signal),
-        { once: true }
-      );
-    }
-    return combined.signal;
-  }
-};
 function parseServiceErrorBody(errorText) {
   try {
     return JSON.parse(errorText);
@@ -12139,7 +11804,7 @@ function nodeRetryError(service, message, response, errorText) {
   const body = errorText.trim();
   const [, token, stage] = /^([a-z_]+)(?::\s*([a-z_]+):)?/.exec(body) ?? [];
   let code;
-  if (response.status === 503 && (token === "sql_busy" || token === "unavailable_retryable")) {
+  if (response.status === 503 && (token === "sql_busy" || token === "unavailable_retryable" || token === "read_audit_busy")) {
     code = ErrorCodes2.NODE_BUSY;
   } else if (response.status === 503 && token === "request_timeout") {
     code = ErrorCodes2.REQUEST_TIMEOUT;
@@ -12343,50 +12008,432 @@ function parseStorageRejection(responseText) {
   } catch {
     return parseStorageQuotaBytes(responseText);
   }
-  if (typeof body !== "object" || body === null) return void 0;
-  const record = body;
-  const message = typeof record.message === "string" ? record.message : "";
-  const space = byteCountsOf(record.space) ?? parseStorageQuotaBytes(message);
-  const isStorageBody = typeof record.error === "string" && STORAGE_REJECTION_BODY_ERRORS[record.error] === true;
-  if (!space && !isStorageBody) {
-    return void 0;
+  if (typeof body !== "object" || body === null) return void 0;
+  const record = body;
+  const message = typeof record.message === "string" ? record.message : "";
+  const space = byteCountsOf(record.space) ?? parseStorageQuotaBytes(message);
+  const isStorageBody = typeof record.error === "string" && STORAGE_REJECTION_BODY_ERRORS[record.error] === true;
+  if (!space && !isStorageBody) {
+    return void 0;
+  }
+  const details = { ...space };
+  const account = byteCountsOf(record.account);
+  if (account) {
+    const plan = record.account.plan;
+    details.account = typeof plan === "string" && plan !== "" ? { ...account, plan } : account;
+  }
+  return details;
+}
+function storageRejectionError(service, status, meta, responseText) {
+  const quotaMeta = { ...meta, ...parseStorageRejection(responseText) };
+  return status === 402 ? storageQuotaExceededError(service, STORAGE_FULL_MESSAGE, quotaMeta) : storageLimitReachedError(service, STORAGE_WRITE_TOO_LARGE_MESSAGE, quotaMeta);
+}
+function wrapError(service, error, defaultCode = ErrorCodes2.NETWORK_ERROR) {
+  if (error instanceof Error) {
+    if (isRequestTimeoutError(error)) {
+      return timeoutError(service, error.timeoutMs, error);
+    }
+    if (error.name === "AbortError") {
+      return abortedError(service);
+    }
+    if (error.name === "TimeoutError" || error.message.toLowerCase().includes("timeout")) {
+      return timeoutError(service);
+    }
+    return {
+      code: defaultCode,
+      message: error.message,
+      service,
+      cause: error
+    };
+  }
+  return {
+    code: defaultCode,
+    message: String(error),
+    service
+  };
+}
+var abortableSleep = (ms, signal, unref = false) => new Promise((resolve) => {
+  const done = () => {
+    clearTimeout(timer);
+    signal.removeEventListener("abort", done);
+    resolve();
+  };
+  const timer = setTimeout(done, ms);
+  if (unref) timer.unref?.();
+  signal.aborted ? done() : signal.addEventListener("abort", done);
+});
+var ServiceContext = class {
+  constructor(config) {
+    this._session = null;
+    this._services = /* @__PURE__ */ new Map();
+    this._eventHandlers = /* @__PURE__ */ new Map();
+    this._abortController = new AbortController();
+    this._retired = false;
+    this._invoke = this.wrapInvoke(config.invoke);
+    this._invokeAny = config.invokeAny ? this.wrapInvokeAny(config.invokeAny) : void 0;
+    this._fetch = this.wrapFetch(config.fetch ?? globalThis.fetch.bind(globalThis));
+    this._hosts = config.hosts;
+    this._session = config.session ?? null;
+    this._retryPolicy = {
+      ...defaultRetryPolicy2,
+      ...config.retryPolicy
+    };
+    this._telemetryEnabled = typeof config.telemetry === "boolean" ? config.telemetry : config.telemetry?.enabled === true;
+    this._telemetryHandler = typeof config.telemetry === "object" ? config.telemetry.onEvent : void 0;
+  }
+  // ============================================================
+  // Session Management
+  // ============================================================
+  /**
+   * Get the current session.
+   */
+  get session() {
+    return this._retired ? null : this._session;
+  }
+  /**
+   * Check if the context has an authenticated session.
+   */
+  get isAuthenticated() {
+    return !this._retired && this._session !== null;
+  }
+  /**
+   * Update the session and notify all registered services.
+   *
+   * @param session - New session or null to clear
+   */
+  setSession(session) {
+    this.assertActive();
+    this._session = session;
+    this.emit("session.changed", { authenticated: session !== null });
+    for (const service of this._services.values()) {
+      service.onSessionChange(session);
+    }
+  }
+  // ============================================================
+  // Platform Dependencies
+  // ============================================================
+  /**
+   * Get the invoke function for WASM operations.
+   */
+  get invoke() {
+    this.assertActive();
+    return this._invoke;
+  }
+  /**
+   * Get the multi-resource invoke function when available.
+   */
+  get invokeAny() {
+    this.assertActive();
+    return this._invokeAny;
+  }
+  /**
+   * Get the fetch function for HTTP requests.
+   */
+  get fetch() {
+    this.assertActive();
+    return this._fetch;
+  }
+  /**
+   * Get the list of TinyCloud host URLs.
+   */
+  get hosts() {
+    this.assertActive();
+    return this._hosts;
+  }
+  // ============================================================
+  // Service Registry
+  // ============================================================
+  /**
+   * Register a service with the context.
+   *
+   * @param name - Service name (e.g., 'kv')
+   * @param service - Service instance
+   */
+  registerService(name, service) {
+    this._services.set(name, service);
+  }
+  /**
+   * Unregister a service from the context.
+   *
+   * @param name - Service name to remove
+   */
+  unregisterService(name) {
+    this._services.delete(name);
+  }
+  /**
+   * Get a registered service by name.
+   *
+   * @param name - Service name
+   * @returns The service instance or undefined if not registered
+   */
+  getService(name) {
+    return this._services.get(name);
+  }
+  // ============================================================
+  // Event System (Telemetry)
+  // ============================================================
+  /**
+   * Emit a telemetry event.
+   *
+   * @param event - Event name
+   * @param data - Event data
+   */
+  emit(event, data) {
+    tinyCloudDebugLogger.log(event, data);
+    if (this._telemetryEnabled && this._telemetryHandler) {
+      try {
+        this._telemetryHandler(event, projectDiagnosticData(data));
+      } catch (error) {
+        console.error(`Error in telemetry handler for "${event}":`, error);
+      }
+    }
+    const handlers = this._eventHandlers.get(event);
+    if (handlers) {
+      for (const handler of handlers) {
+        try {
+          handler(data);
+        } catch (error) {
+          console.error(`Error in event handler for "${event}":`, error);
+        }
+      }
+    }
+  }
+  /**
+   * Subscribe to telemetry events.
+   *
+   * @param event - Event name to subscribe to
+   * @param handler - Handler function
+   * @returns Unsubscribe function
+   */
+  on(event, handler) {
+    if (!this._eventHandlers.has(event)) {
+      this._eventHandlers.set(event, /* @__PURE__ */ new Set());
+    }
+    this._eventHandlers.get(event).add(handler);
+    return () => {
+      const handlers = this._eventHandlers.get(event);
+      if (handlers) {
+        handlers.delete(handler);
+        if (handlers.size === 0) {
+          this._eventHandlers.delete(event);
+        }
+      }
+    };
+  }
+  /**
+   * Remove all event handlers for an event.
+   *
+   * @param event - Event name (if omitted, clears all events)
+   */
+  clearEventHandlers(event) {
+    if (event) {
+      this._eventHandlers.delete(event);
+    } else {
+      this._eventHandlers.clear();
+    }
+  }
+  // ============================================================
+  // Lifecycle
+  // ============================================================
+  /**
+   * Get the abort signal for cancelling operations.
+   */
+  get abortSignal() {
+    return this._abortController.signal;
+  }
+  get operationAbortSignal() {
+    return this._operationAbortSignal;
+  }
+  setOperationAbortSignal(signal) {
+    this._operationAbortSignal = signal;
+  }
+  /**
+   * Permanently retire this graph after its owner installs a replacement.
+   * Unlike `abort()`, retirement never creates a fresh controller, so captured
+   * services cannot resume calls under a superseded session.
+   */
+  retire() {
+    if (this._retired) return;
+    this._retired = true;
+    this._session = null;
+    this._abortController.abort();
+    for (const service of this._services.values()) {
+      try {
+        service.onSignOut();
+      } catch (error) {
+        console.error("Error retiring service:", error);
+      }
+    }
+  }
+  /**
+   * Abort all pending operations and notify services.
+   * Creates a new AbortController for future operations.
+   */
+  abort() {
+    if (this._retired) return;
+    this._abortController.abort();
+    this._abortController = new AbortController();
+    for (const service of this._services.values()) {
+      try {
+        service.onSignOut();
+      } catch (error) {
+        console.error("Error signing out service:", error);
+      }
+    }
+  }
+  /**
+   * Sign out - abort operations and clear session.
+   */
+  signOut() {
+    if (this._retired) return;
+    this.abort();
+    this.setSession(null);
+    this.emit("session.expired", {});
   }
-  const details = { ...space };
-  const account = byteCountsOf(record.account);
-  if (account) {
-    const plan = record.account.plan;
-    details.account = typeof plan === "string" && plan !== "" ? { ...account, plan } : account;
+  // ============================================================
+  // Retry Policy
+  // ============================================================
+  /**
+   * Get the retry policy configuration.
+   */
+  get retryPolicy() {
+    return this._retryPolicy;
   }
-  return details;
-}
-function storageRejectionError(service, status, meta, responseText) {
-  const quotaMeta = { ...meta, ...parseStorageRejection(responseText) };
-  return status === 402 ? storageQuotaExceededError(service, STORAGE_FULL_MESSAGE, quotaMeta) : storageLimitReachedError(service, STORAGE_WRITE_TOO_LARGE_MESSAGE, quotaMeta);
-}
-function wrapError(service, error, defaultCode = ErrorCodes2.NETWORK_ERROR) {
-  if (error instanceof Error) {
-    if (isRequestTimeoutError(error)) {
-      return timeoutError(service, error.timeoutMs, error);
-    }
-    if (error.name === "AbortError") {
-      return abortedError(service);
+  wrapInvoke(invoke) {
+    return (session, service, path, action, facts) => {
+      this.assertActive();
+      if (!tinyCloudDebugLogger.isEnabled()) {
+        return invoke(session, service, path, action, facts);
+      }
+      const timer = tinyCloudDebugLogger.startTimer("sdk.invoke", {
+        service,
+        path,
+        action,
+        facts
+      });
+      try {
+        const result = invoke(session, service, path, action, facts);
+        timer.stop({ ok: true, service, path, action });
+        return result;
+      } catch (error) {
+        timer.stop({ ok: false, service, path, action, error });
+        throw error;
+      }
+    };
+  }
+  assertActive() {
+    if (this._retired) {
+      throw new Error("Service graph has been retired: its session was replaced or signed out.");
     }
-    if (error.name === "TimeoutError" || error.message.toLowerCase().includes("timeout")) {
-      return timeoutError(service);
+  }
+  wrapInvokeAny(invokeAny) {
+    return (session, entries, facts) => {
+      this.assertActive();
+      if (!tinyCloudDebugLogger.isEnabled()) {
+        return invokeAny(session, entries, facts);
+      }
+      const timer = tinyCloudDebugLogger.startTimer("sdk.invokeAny", {
+        entries,
+        facts
+      });
+      try {
+        const result = invokeAny(session, entries, facts);
+        timer.stop({ ok: true, entries });
+        return result;
+      } catch (error) {
+        timer.stop({ ok: false, entries, error });
+        throw error;
+      }
+    };
+  }
+  /** Retry `NODE_BUSY` / `REQUEST_TIMEOUT`; `build` must re-sign per attempt (the node 409s a repeated invocation). */
+  async invokeWithRetry(url, build) {
+    this.assertActive();
+    const policy = this._retryPolicy;
+    const startedAt = Date.now();
+    let backoffMs = 0;
+    let signal;
+    for (let attempt = 1; ; attempt++) {
+      const init = await build();
+      signal ?? (signal = this.combineSignals(init.signal));
+      const response = await this._fetch(url, init);
+      const done = () => {
+        try {
+          response.retry = { attempts: attempt, backoffMs };
+        } catch {
+        }
+        return response;
+      };
+      if (attempt >= policy.maxAttempts || response.status !== 503 || !response.clone) return done();
+      const text = await response.clone().text().catch(() => "");
+      const error = nodeRetryError("", "", response, text);
+      if (!error || error.meta?.retryable !== true || !policy.retryableErrors.includes(error.code)) {
+        return done();
+      }
+      const remaining = (policy.maxTotalMs ?? Infinity) - (Date.now() - startedAt);
+      if (remaining <= 0) return done();
+      const retryAfterMs = error.meta.retryAfterMs;
+      const step = Math.min(
+        policy.maxDelayMs,
+        policy.backoff === "exponential" ? policy.baseDelayMs * 2 ** (attempt - 1) : policy.backoff === "linear" ? policy.baseDelayMs * attempt : 0
+      );
+      const delay = Math.min(
+        typeof retryAfterMs === "number" ? retryAfterMs : Math.random() * step,
+        remaining
+      );
+      response.body?.cancel?.()?.catch?.(() => {
+      });
+      await abortableSleep(delay, signal);
+      if (signal.aborted) throw signal.reason;
+      backoffMs += delay;
     }
-    return {
-      code: defaultCode,
-      message: error.message,
-      service,
-      cause: error
+  }
+  wrapFetch(fetchFn) {
+    return async (url, init) => {
+      this.assertActive();
+      const request = {
+        ...init,
+        signal: this.combineSignals(init?.signal)
+      };
+      if (!tinyCloudDebugLogger.isEnabled()) {
+        return fetchFn(url, request);
+      }
+      const meta = { url, method: request.method ?? "GET" };
+      const timer = tinyCloudDebugLogger.startTimer("sdk.fetch", { ...meta, init: request });
+      try {
+        const response = await fetchFn(url, request);
+        timer.stop({
+          ...meta,
+          ok: response.ok,
+          status: response.status,
+          statusText: response.statusText
+        });
+        return response;
+      } catch (error) {
+        timer.stop({ ...meta, ok: false, error });
+        throw error;
+      }
     };
   }
-  return {
-    code: defaultCode,
-    message: String(error),
-    service
-  };
-}
+  combineSignals(signal) {
+    if (!signal) return this._abortController.signal;
+    const combined = new AbortController();
+    const abort = (source) => combined.abort(source.reason);
+    if (signal.aborted) {
+      abort(signal);
+    } else if (this._abortController.signal.aborted) {
+      abort(this._abortController.signal);
+    } else {
+      signal.addEventListener("abort", () => abort(signal), { once: true });
+      this._abortController.signal.addEventListener(
+        "abort",
+        () => abort(this._abortController.signal),
+        { once: true }
+      );
+    }
+    return combined.signal;
+  }
+};
 var MAX_TIMER_DELAY_MS = 2147483647;
 var BaseService = class {
   constructor() {
@@ -12561,6 +12608,18 @@ var BaseService = class {
     }
     return controller.signal;
   }
+  /** POST a signed invocation with retry; `mint` re-signs per attempt, `init.headers` add to the signed ones. */
+  invokeWithRetry(url, mint, { headers: extra, ...init } = {}) {
+    const build = () => {
+      const signed = mint();
+      return {
+        method: "POST",
+        ...init,
+        headers: Array.isArray(signed) ? [...signed, ...Object.entries(extra ?? {})] : { ...signed, ...extra }
+      };
+    };
+    return this.context.invokeWithRetry ? this.context.invokeWithRetry(url, build) : this.context.fetch(url, build());
+  }
   /**
    * Create the abort signal for one request, bounded by the request timeout.
    *
@@ -12922,15 +12981,6 @@ var KVService = class extends BaseService {
   get host() {
     return this.context.hosts[0];
   }
-  withJsonContentType(headers) {
-    if (Array.isArray(headers)) {
-      return [...headers, ["content-type", "application/json"]];
-    }
-    return {
-      ...headers,
-      "content-type": "application/json"
-    };
-  }
   /**
    * Execute an invoke operation.
    *
@@ -12941,20 +12991,11 @@ var KVService = class extends BaseService {
    * @returns Fetch response
    */
   async invokeOperation(path, action, body, signal, extraHeaders) {
-    const session = this.context.session;
-    const headers = this.context.invoke(
-      session,
-      "kv",
-      path,
-      action
+    return this.invokeWithRetry(
+      `${this.host}/invoke`,
+      () => this.context.invoke(this.context.session, "kv", path, action),
+      { headers: extraHeaders, body, signal }
     );
-    const requestHeaders = Array.isArray(headers) ? [...headers, ...Object.entries(extraHeaders ?? {})] : { ...headers, ...extraHeaders };
-    return this.context.fetch(`${this.host}/invoke`, {
-      method: "POST",
-      headers: requestHeaders,
-      body,
-      signal
-    });
   }
   /**
    * Serialize a single put value into a fetch body.
@@ -13160,28 +13201,28 @@ var KVService = class extends BaseService {
     }
     const request = this.createRequestSignal(options?.signal, options?.timeout);
     try {
-      const session = this.context.session;
-      const invocationHeaders = this.context.invokeAny(
-        session,
-        paths.map((path) => ({
-          spaceId: session.spaceId,
-          service: "kv",
-          path,
-          action
-        }))
-      );
       const limitHeaders = {};
       if (getOptions?.maxResponseBytes !== void 0) {
         limitHeaders["x-tinycloud-max-response-bytes"] = String(
           getOptions.maxResponseBytes
         );
       }
-      const headers = Array.isArray(invocationHeaders) ? [...invocationHeaders, ...Object.entries(limitHeaders)] : { ...invocationHeaders, ...limitHeaders };
-      const response = await this.context.fetch(`${this.host}/invoke`, {
-        method: "POST",
-        headers,
-        signal: request.signal
-      });
+      const response = await this.invokeWithRetry(
+        `${this.host}/invoke`,
+        () => {
+          const session = this.context.session;
+          return this.context.invokeAny(
+            session,
+            paths.map((path) => ({
+              spaceId: session.spaceId,
+              service: "kv",
+              path,
+              action
+            }))
+          );
+        },
+        { headers: limitHeaders, signal: request.signal }
+      );
       if (!response.ok) {
         const errorText = response.status === 401 || response.status === 403 ? await this.readAuthorizationText(response) : await response.text();
         if (response.status === 401 || response.status === 403) {
@@ -13227,10 +13268,10 @@ var KVService = class extends BaseService {
             result: err(serviceError(item.error.code, item.error.message, "kv"))
           };
         }
-        const headers2 = item.headers;
+        const headers = item.headers;
         const data = action === KVAction.HEAD ? void 0 : this.parseBatchValue(
           item.dataBase64,
-          headers2,
+          headers,
           getOptions?.raw,
           getOptions?.binary
         );
@@ -13238,7 +13279,7 @@ var KVService = class extends BaseService {
           key: keys[index],
           result: ok({
             data,
-            headers: this.createBatchResponseHeaders(headers2)
+            headers: this.createBatchResponseHeaders(headers)
           })
         };
       });
@@ -13473,7 +13514,7 @@ var KVService = class extends BaseService {
       ));
     }
     const data = await this.parseResponse(response, options?.raw, options?.binary);
-    return ok({ data, headers: this.createResponseHeaders(response.headers) });
+    return ok({ data, headers: this.createResponseHeaders(response.headers), ...response.retry && { retry: response.retry } });
   }
   async batchGet(keys, options) {
     return this.withTelemetry(
@@ -13563,7 +13604,8 @@ var KVService = class extends BaseService {
     }
     return ok({
       data: void 0,
-      headers: this.createResponseHeaders(response.headers)
+      headers: this.createResponseHeaders(response.headers),
+      ...response.retry && { retry: response.retry }
     });
   }
   /**
@@ -13636,25 +13678,23 @@ var KVService = class extends BaseService {
           entries?.[index]?.body ?? this.serializeBatchPutValue(items[index])
         );
       }
-      const headers = this.context.invokeAny(
-        session,
-        paths.map((path) => ({
-          spaceId: session.spaceId,
-          service: "kv",
-          path,
-          action: KVAction.PUT
-        }))
+      const response = await this.invokeWithRetry(
+        `${this.host}/invoke`,
+        () => {
+          const headers = this.context.invokeAny(
+            session,
+            paths.map((path) => ({
+              spaceId: session.spaceId,
+              service: "kv",
+              path,
+              action: KVAction.PUT
+            }))
+          );
+          requestMayHaveDispatched = true;
+          return headers;
+        },
+        { body, signal }
       );
-      const url = `${this.host}/invoke`;
-      const init = {
-        method: "POST",
-        headers,
-        body,
-        signal
-      };
-      const fetchFn = this.context.fetch;
-      requestMayHaveDispatched = true;
-      const response = await fetchFn(url, init);
       if (!response.ok) {
         let errorText;
         try {
@@ -14124,7 +14164,8 @@ var KVService = class extends BaseService {
     }
     return ok({
       data: void 0,
-      headers: this.createResponseHeaders(response.headers)
+      headers: this.createResponseHeaders(response.headers),
+      ...response.retry && { retry: response.retry }
     });
   }
   /**
@@ -14198,12 +14239,6 @@ var KVService = class extends BaseService {
       }
       const path = this.getFullPath(key, options?.prefix);
       const session = this.context.session;
-      const headers = this.context.invoke(
-        session,
-        "kv",
-        path,
-        KVAction.GET
-      );
       const body = {
         space: session.spaceId,
         path,
@@ -14217,12 +14252,15 @@ var KVService = class extends BaseService {
       }
       const request = this.createRequestSignal(options?.signal, options?.timeout);
       try {
-        const response = await this.context.fetch(`${this.host}/signed/kv`, {
-          method: "POST",
-          headers: this.withJsonContentType(headers),
-          body: JSON.stringify(body),
-          signal: request.signal
-        });
+        const response = await this.invokeWithRetry(
+          `${this.host}/signed/kv`,
+          () => this.context.invoke(session, "kv", path, KVAction.GET),
+          {
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(body),
+            signal: request.signal
+          }
+        );
         if (!response.ok) {
           return await this.createSignedReadUrlError(response, key, path);
         }
@@ -14648,18 +14686,19 @@ var SQLService = class extends BaseService {
   }
   // === Private helpers ===
   async invokeSQL(dbName, actions, body, signal) {
-    const session = this.context.session;
     const actionList = Array.isArray(actions) ? actions : [actions];
-    const headers = actionList.length === 1 ? this.context.invoke(session, "sql", dbName, actionList[0]) : this.invokeSQLAny(session, dbName, actionList);
-    return this.context.fetch(`${this.host}/invoke`, {
-      method: "POST",
-      headers: {
-        ...headers,
-        "Content-Type": "application/json"
+    return this.invokeWithRetry(
+      `${this.host}/invoke`,
+      () => {
+        const session = this.context.session;
+        return actionList.length === 1 ? this.context.invoke(session, "sql", dbName, actionList[0]) : this.invokeSQLAny(session, dbName, actionList);
       },
-      body: JSON.stringify(body),
-      signal
-    });
+      {
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+        signal
+      }
+    );
   }
   actionForSql(sql, fallback) {
     const token = firstSqlToken(sql);
@@ -15113,22 +15152,20 @@ var DuckDbService = class extends BaseService {
       }
       const request = this.createRequestSignal(options?.signal);
       try {
-        const session = this.context.session;
-        const headers = this.context.invoke(
-          session,
-          "duckdb",
-          dbName,
-          DuckDbAction.IMPORT
+        const response = await this.invokeWithRetry(
+          `${this.host}/invoke`,
+          () => this.context.invoke(
+            this.context.session,
+            "duckdb",
+            dbName,
+            DuckDbAction.IMPORT
+          ),
+          {
+            headers: { "Content-Type": "application/x-duckdb" },
+            body: new Blob([data]),
+            signal: request.signal
+          }
         );
-        const response = await this.context.fetch(`${this.host}/invoke`, {
-          method: "POST",
-          headers: {
-            ...headers,
-            "Content-Type": "application/x-duckdb"
-          },
-          body: new Blob([data]),
-          signal: request.signal
-        });
         if (!response.ok) {
           return await this.handleErrorResponse(response, "import");
         }
@@ -15142,18 +15179,15 @@ var DuckDbService = class extends BaseService {
   }
   // === Private helpers ===
   async invokeDuckDb(dbName, action, body, signal, extraHeaders) {
-    const session = this.context.session;
-    const headers = this.context.invoke(session, "duckdb", dbName, action);
-    return this.context.fetch(`${this.host}/invoke`, {
-      method: "POST",
-      headers: {
-        ...headers,
-        "Content-Type": "application/json",
-        ...extraHeaders
-      },
-      body: JSON.stringify(body),
-      signal
-    });
+    return this.invokeWithRetry(
+      `${this.host}/invoke`,
+      () => this.context.invoke(this.context.session, "duckdb", dbName, action),
+      {
+        headers: { "Content-Type": "application/json", ...extraHeaders },
+        body: JSON.stringify(body),
+        signal
+      }
+    );
   }
   async handleErrorResponse(response, operation) {
     const errorText = await response.text();
@@ -15338,26 +15372,24 @@ var HooksService = class extends BaseService {
       );
     }
     try {
-      const response = await this.context.fetch(`${this.host}/hooks/webhooks`, {
-        method: "POST",
-        headers: {
-          ...serviceHeadersToRecord(
-            this.createHookHeaders(
-              "tinycloud.hooks/register",
-              buildScopePath(webhook.service, webhook.pathPrefix)
-            )
-          ),
-          "content-type": "application/json"
-        },
-        body: JSON.stringify({
-          space: webhook.space,
-          service: webhook.service,
-          pathPrefix: normalizePathPrefix(webhook.pathPrefix),
-          abilities: webhook.abilities ?? [],
-          callbackUrl: webhook.callbackUrl,
-          secret: webhook.secret
-        })
-      });
+      const response = await this.invokeWithRetry(
+        `${this.host}/hooks/webhooks`,
+        () => this.createHookHeaders(
+          "tinycloud.hooks/register",
+          buildScopePath(webhook.service, webhook.pathPrefix)
+        ),
+        {
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            space: webhook.space,
+            service: webhook.service,
+            pathPrefix: normalizePathPrefix(webhook.pathPrefix),
+            abilities: webhook.abilities ?? [],
+            callbackUrl: webhook.callbackUrl,
+            secret: webhook.secret
+          })
+        }
+      );
       if (!response.ok) {
         return err(
           await responseError("hooks", "failed to register webhook", response)
@@ -15395,17 +15427,13 @@ var HooksService = class extends BaseService {
           query.set("prefix", normalizedPrefix);
         }
       }
-      const response = await this.context.fetch(
+      const response = await this.invokeWithRetry(
         `${this.host}/hooks/webhooks${query.size > 0 ? `?${query.toString()}` : ""}`,
-        {
-          method: "GET",
-          headers: serviceHeadersToRecord(
-            this.createHookHeaders(
-              "tinycloud.hooks/list",
-              options.service ? buildScopePath(options.service, options.pathPrefix) : "webhooks"
-            )
-          )
-        }
+        () => this.createHookHeaders(
+          "tinycloud.hooks/list",
+          options.service ? buildScopePath(options.service, options.pathPrefix) : "webhooks"
+        ),
+        { method: "GET" }
       );
       if (!response.ok) {
         return err(
@@ -15432,20 +15460,16 @@ var HooksService = class extends BaseService {
       return err(authRequiredError("hooks"));
     }
     try {
-      const response = await this.context.fetch(
+      const response = await this.invokeWithRetry(
         `${this.host}/hooks/webhooks/${encodeURIComponent(id)}`,
-        {
-          method: "DELETE",
-          headers: serviceHeadersToRecord(
-            this.createHookHeaders(
-              "tinycloud.hooks/unregister",
-              options.target ? buildScopePath(
-                options.target.service,
-                options.target.pathPrefix
-              ) : `webhooks/${id}`
-            )
-          )
-        }
+        () => this.createHookHeaders(
+          "tinycloud.hooks/unregister",
+          options.target ? buildScopePath(
+            options.target.service,
+            options.target.pathPrefix
+          ) : `webhooks/${id}`
+        ),
+        { method: "DELETE" }
       );
       if (!response.ok) {
         return err(
@@ -15901,23 +15925,7 @@ function readProperty(value, key) {
     return void 0;
   }
 }
-function sleep(delayMs, _attempt, signal) {
-  return new Promise((resolve) => {
-    const finish = () => {
-      clearTimeout(timer);
-      signal.removeEventListener("abort", stop);
-      resolve();
-    };
-    const timer = setTimeout(finish, delayMs);
-    timer.unref?.();
-    const stop = () => finish();
-    if (signal.aborted) {
-      finish();
-    } else {
-      signal.addEventListener("abort", stop, { once: true });
-    }
-  });
-}
+var sleep = (delayMs, _attempt, signal) => abortableSleep(delayMs, signal, true);
 function abortPromise(signal) {
   let resolve;
   const promise = new Promise((done) => {