@tinycloud/sdk-services 3.2.6-beta.4 → 3.3.0-beta.25

package/dist/index.cjs

@@ -84,8 +84,8 @@ __export(src_exports, {
   authRequiredError: () => authRequiredError,
   authUnauthorizedError: () => authUnauthorizedError,
   authorizationVerdictOf: () => authorizationVerdictOf,
-  base64Decode: () => base64Decode2,
-  base64Encode: () => base64Encode2,
+  base64Decode: () => base64Decode,
+  base64Encode: () => base64Encode,
   buildCanonicalDecryptRequest: () => buildCanonicalDecryptRequest,
   buildDecryptAttenuation: () => buildDecryptAttenuation,
   buildDecryptFacts: () => buildDecryptFacts,
@@ -115,13 +115,14 @@ __export(src_exports, {
   generateRandomReceiverKey: () => generateRandomReceiverKey,
   getTinyCloudDebugLogs: () => getTinyCloudDebugLogs,
   hexDecode: () => hexDecode,
-  hexEncode: () => hexEncode2,
+  hexEncode: () => hexEncode,
   installTinyCloudDebugGlobals: () => installTinyCloudDebugGlobals,
   isNetworkId: () => isNetworkId,
   isStorageFullError: () => isStorageFullError,
   kvPrefixCovers: () => kvPrefixCovers,
   networkDiscoveryKey: () => networkDiscoveryKey,
   networkError: () => networkError,
+  nodeRetryError: () => nodeRetryError,
   notFoundError: () => notFoundError,
   ok: () => ok,
   openWrappedKey: () => openWrappedKey,
@@ -179,6 +180,14 @@ var ErrorCodes = {
   ABORTED: "ABORTED",
   INVALID_INPUT: "INVALID_INPUT",
   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`/`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",
+  /** HTTP 500 `outcome_unknown`: a write may have been applied; read back before retrying a non-idempotent operation. */
+  OUTCOME_UNKNOWN: "OUTCOME_UNKNOWN",
   // KV-specific errors
   KV_NOT_FOUND: "KV_NOT_FOUND",
   KV_WRITE_FAILED: "KV_WRITE_FAILED",
@@ -214,11 +223,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 TelemetryEvents = {
   SPAN: "telemetry.span",
@@ -645,7 +655,9 @@ var RetryPolicySchema = import_zod.z.object({
   /** Maximum delay in milliseconds between retries */
   maxDelayMs: import_zod.z.number().nonnegative(),
   /** Error codes that should trigger a retry */
-  retryableErrors: import_zod.z.array(import_zod.z.string())
+  retryableErrors: import_zod.z.array(import_zod.z.string()),
+  /** Total time budget for all attempts and waits, in milliseconds */
+  maxTotalMs: import_zod.z.number().positive().optional()
 });
 var ServiceSessionSchema = import_zod.z.object({
   /** The delegation header containing the UCAN */
@@ -782,412 +794,107 @@ function validateTelemetrySpanEvent(data) {
   return { ok: true, data: result.data };
 }
 
-// src/context.ts
-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 = {
-      ...defaultRetryPolicy,
-      ...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;
+// src/responseErrors.ts
+function parseServiceErrorBody(errorText) {
+  try {
+    return JSON.parse(errorText);
+  } catch {
+    return {};
   }
-  /**
-   * Check if the context has an authenticated session.
-   */
-  get isAuthenticated() {
-    return !this._retired && this._session !== null;
+}
+function formatServiceResponseError(serviceLabel, operation, status, errorText, parsed) {
+  if (parsed.message) {
+    return compactMessage(parsed.message);
   }
-  /**
-   * 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);
+  if (looksLikeHtml(errorText)) {
+    if (status === 524 || /524\s*[:-]/i.test(errorText) || /a timeout occurred/i.test(errorText)) {
+      return `${serviceLabel} ${operation} failed: upstream request timed out. Please retry.`;
     }
+    return `${serviceLabel} ${operation} failed: upstream service returned an HTML error page (${status}).`;
   }
-  // ============================================================
-  // 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;
+  return `${serviceLabel} ${operation} failed: ${status} - ${compactMessage(errorText)}`;
+}
+function responseErrorMeta(status, statusText, errorText) {
+  const meta = { status, statusText };
+  const snippet = compactMessage(errorText);
+  if (snippet) {
+    meta.responseSnippet = snippet.slice(0, 300);
   }
-  /**
-   * Get the fetch function for HTTP requests.
-   */
-  get fetch() {
-    this.assertActive();
-    return this._fetch;
+  return meta;
+}
+function looksLikeHtml(text) {
+  return /<!doctype html/i.test(text) || /<html[\s>]/i.test(text);
+}
+function compactMessage(message) {
+  const compact = message.replace(/\s+/g, " ").trim();
+  return compact.length > 500 ? `${compact.slice(0, 500)}...` : compact;
+}
+
+// src/errors.ts
+var import_bootstrap = require("@tinycloud/bootstrap");
+
+// src/encryption/networkId.ts
+var URN_PREFIX = "urn:tinycloud:encryption:";
+var NETWORK_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+var PKH_EIP155_DID_RE = /^did:pkh:eip155:(\d+):(0x[a-fA-F0-9]{40})$/;
+var NetworkIdError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "NetworkIdError";
   }
-  /**
-   * Get the list of TinyCloud host URLs.
-   */
-  get hosts() {
-    this.assertActive();
-    return this._hosts;
+};
+function parseNetworkId(networkId) {
+  if (typeof networkId !== "string" || networkId.length === 0) {
+    throw new NetworkIdError("networkId must be a non-empty string");
   }
-  // ============================================================
-  // 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);
+  if (!networkId.startsWith(URN_PREFIX)) {
+    throw new NetworkIdError(
+      `networkId must start with ${URN_PREFIX} (got ${JSON.stringify(networkId)})`
+    );
   }
-  /**
-   * Unregister a service from the context.
-   *
-   * @param name - Service name to remove
-   */
-  unregisterService(name) {
-    this._services.delete(name);
+  const body = networkId.slice(URN_PREFIX.length);
+  const lastColon = body.lastIndexOf(":");
+  if (lastColon <= 0 || lastColon === body.length - 1) {
+    throw new NetworkIdError(
+      `networkId missing ownerDid or name segment (got ${JSON.stringify(networkId)})`
+    );
   }
-  /**
-   * 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);
+  const ownerDid = body.slice(0, lastColon);
+  const name = body.slice(lastColon + 1);
+  if (!ownerDid.startsWith("did:")) {
+    throw new NetworkIdError(
+      `networkId ownerDid must be a DID (got ${JSON.stringify(ownerDid)})`
+    );
   }
-  // ============================================================
-  // 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);
-        }
-      }
-    }
+  const didParts = ownerDid.split(":");
+  if (didParts.length < 3 || didParts.some((p) => p.length === 0)) {
+    throw new NetworkIdError(
+      `networkId ownerDid is not a well-formed DID (got ${JSON.stringify(ownerDid)})`
+    );
   }
-  /**
-   * 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);
-        }
-      }
-    };
+  if (!NETWORK_NAME_RE.test(name)) {
+    throw new NetworkIdError(
+      `networkId name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
+    );
   }
-  /**
-   * 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();
-    }
+  return { networkId, ownerDid, name };
+}
+function buildNetworkId(ownerDid, name) {
+  if (typeof ownerDid !== "string" || !ownerDid.startsWith("did:")) {
+    throw new NetworkIdError("ownerDid must be a DID");
   }
-  // ============================================================
-  // Lifecycle
-  // ============================================================
-  /**
-   * Get the abort signal for cancelling operations.
-   */
-  get abortSignal() {
-    return this._abortController.signal;
+  if (typeof name !== "string" || !NETWORK_NAME_RE.test(name)) {
+    throw new NetworkIdError(
+      `network name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
+    );
   }
-  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;
-  }
-};
-
-// src/errors.ts
-var import_bootstrap = require("@tinycloud/bootstrap");
-
-// src/encryption/networkId.ts
-var URN_PREFIX = "urn:tinycloud:encryption:";
-var NETWORK_NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
-var PKH_EIP155_DID_RE = /^did:pkh:eip155:(\d+):(0x[a-fA-F0-9]{40})$/;
-var NetworkIdError = class extends Error {
-  constructor(message) {
-    super(message);
-    this.name = "NetworkIdError";
-  }
-};
-function parseNetworkId(networkId) {
-  if (typeof networkId !== "string" || networkId.length === 0) {
-    throw new NetworkIdError("networkId must be a non-empty string");
-  }
-  if (!networkId.startsWith(URN_PREFIX)) {
-    throw new NetworkIdError(
-      `networkId must start with ${URN_PREFIX} (got ${JSON.stringify(networkId)})`
-    );
-  }
-  const body = networkId.slice(URN_PREFIX.length);
-  const lastColon = body.lastIndexOf(":");
-  if (lastColon <= 0 || lastColon === body.length - 1) {
-    throw new NetworkIdError(
-      `networkId missing ownerDid or name segment (got ${JSON.stringify(networkId)})`
-    );
-  }
-  const ownerDid = body.slice(0, lastColon);
-  const name = body.slice(lastColon + 1);
-  if (!ownerDid.startsWith("did:")) {
-    throw new NetworkIdError(
-      `networkId ownerDid must be a DID (got ${JSON.stringify(ownerDid)})`
-    );
-  }
-  const didParts = ownerDid.split(":");
-  if (didParts.length < 3 || didParts.some((p) => p.length === 0)) {
-    throw new NetworkIdError(
-      `networkId ownerDid is not a well-formed DID (got ${JSON.stringify(ownerDid)})`
-    );
-  }
-  if (!NETWORK_NAME_RE.test(name)) {
-    throw new NetworkIdError(
-      `networkId name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
-    );
-  }
-  return { networkId, ownerDid, name };
-}
-function buildNetworkId(ownerDid, name) {
-  if (typeof ownerDid !== "string" || !ownerDid.startsWith("did:")) {
-    throw new NetworkIdError("ownerDid must be a DID");
-  }
-  if (typeof name !== "string" || !NETWORK_NAME_RE.test(name)) {
-    throw new NetworkIdError(
-      `network name ${JSON.stringify(name)} must match ${NETWORK_NAME_RE.source}`
-    );
-  }
-  const networkId = `${URN_PREFIX}${ownerDid}:${name}`;
-  parseNetworkId(networkId);
-  return networkId;
-}
-function isNetworkId(networkId) {
-  if (typeof networkId !== "string") {
-    return false;
+  const networkId = `${URN_PREFIX}${ownerDid}:${name}`;
+  parseNetworkId(networkId);
+  return networkId;
+}
+function isNetworkId(networkId) {
+  if (typeof networkId !== "string") {
+    return false;
   }
   try {
     parseNetworkId(networkId);
@@ -1282,6 +989,30 @@ function networkError(service, message, cause) {
     cause
   };
 }
+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" || token === "read_audit_busy")) {
+    code = ErrorCodes.NODE_BUSY;
+  } else if (response.status === 503 && token === "request_timeout") {
+    code = ErrorCodes.REQUEST_TIMEOUT;
+  } else if (response.status === 500 && token === "outcome_unknown") {
+    code = ErrorCodes.OUTCOME_UNKNOWN;
+  } else {
+    return void 0;
+  }
+  const retryable = code !== ErrorCodes.OUTCOME_UNKNOWN;
+  const retryAfter = response.headers.get("retry-after")?.trim();
+  return serviceError(code, message, service, {
+    meta: {
+      ...responseErrorMeta(response.status, response.statusText, errorText),
+      retryable,
+      ...token === "sql_busy" && stage ? { stage } : {},
+      ...retryable && retryAfter && /^\d{1,9}$/.test(retryAfter) ? { retryAfterMs: Number(retryAfter) * 1e3 } : {}
+    }
+  });
+}
 var RequestTimeoutError = class extends Error {
   constructor(timeoutMs) {
     super(`Request timed out after ${timeoutMs}ms.`);
@@ -1521,15 +1252,401 @@ function wrapError(service, error, defaultCode = ErrorCodes.NETWORK_ERROR) {
       cause: error
     };
   }
-  return {
-    code: defaultCode,
-    message: String(error),
-    service
-  };
-}
-function errorResult(error) {
-  return err(error);
-}
+  return {
+    code: defaultCode,
+    message: String(error),
+    service
+  };
+}
+function errorResult(error) {
+  return err(error);
+}
+
+// src/sleep.ts
+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);
+});
+
+// src/context.ts
+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 = {
+      ...defaultRetryPolicy,
+      ...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;
+      }
+    };
+  }
+  /** 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;
+    }
+  }
+  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;
+      }
+    };
+  }
+  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;
+  }
+};
 
 // src/base/BaseService.ts
 var MAX_TIMER_DELAY_MS = 2147483647;
@@ -1713,6 +1830,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.
    *
@@ -2080,15 +2209,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.
    *
@@ -2099,20 +2219,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.
@@ -2318,28 +2429,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) {
@@ -2385,10 +2496,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
         );
@@ -2396,7 +2507,7 @@ var KVService = class extends BaseService {
           key: keys[index],
           result: ok({
             data,
-            headers: this.createBatchResponseHeaders(headers2)
+            headers: this.createBatchResponseHeaders(headers)
           })
         };
       });
@@ -2620,15 +2731,18 @@ var KVService = class extends BaseService {
           { meta: { status: response.status, statusText: response.statusText } }
         ));
       }
+      const message = `Failed to get key ${JSON.stringify(key)}: ${response.status} - ${errorText}`;
+      const retryError = nodeRetryError("kv", message, response, errorText);
+      if (retryError) return err(retryError);
       return err(serviceError(
         ErrorCodes.NETWORK_ERROR,
-        `Failed to get key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+        message,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       ));
     }
     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(
@@ -2704,26 +2818,22 @@ var KVService = class extends BaseService {
           { meta: { status: response.status, statusText: response.statusText } }
         ));
       }
-      if (response.status === 503 && (options?.ifMatch !== void 0 || options?.ifNoneMatch !== void 0)) {
-        return err(serviceError(
-          ErrorCodes.KV_CONFLICT,
-          `Concurrent KV update conflicted for key ${JSON.stringify(key)}`,
-          "kv",
-          { meta: { status: response.status, statusText: response.statusText } }
-        ));
-      }
+      const message = `Failed to put key ${JSON.stringify(key)}: ${response.status} - ${errorText}`;
+      const retryError = nodeRetryError("kv", message, response, errorText);
+      if (retryError) return err(retryError);
       const quotaError = this.handleQuotaErrorResponse(response, errorText, key);
       if (quotaError) return quotaError;
       return err(serviceError(
         ErrorCodes.KV_WRITE_FAILED,
-        `Failed to put key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+        message,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       ));
     }
     return ok({
       data: void 0,
-      headers: this.createResponseHeaders(response.headers)
+      headers: this.createResponseHeaders(response.headers),
+      ...response.retry && { retry: response.retry }
     });
   }
   /**
@@ -2796,25 +2906,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 {
@@ -3016,9 +3124,12 @@ var KVService = class extends BaseService {
         );
       }
       const errorText = await response.text();
+      const message = `Failed to list keys: ${response.status} - ${errorText}`;
+      const retryError = nodeRetryError("kv", message, response, errorText);
+      if (retryError) return err(retryError);
       return err(serviceError(
         ErrorCodes.NETWORK_ERROR,
-        `Failed to list keys: ${response.status} - ${errorText}`,
+        message,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       ));
@@ -3269,24 +3380,20 @@ var KVService = class extends BaseService {
           { meta: { status: response.status, statusText: response.statusText } }
         ));
       }
-      if (response.status === 503 && options?.ifMatch !== void 0) {
-        return err(serviceError(
-          ErrorCodes.KV_CONFLICT,
-          `Concurrent KV delete conflicted for key ${JSON.stringify(key)}`,
-          "kv",
-          { meta: { status: response.status, statusText: response.statusText } }
-        ));
-      }
+      const message = `Failed to delete key ${JSON.stringify(key)}: ${response.status} - ${errorText}`;
+      const retryError = nodeRetryError("kv", message, response, errorText);
+      if (retryError) return err(retryError);
       return err(serviceError(
         ErrorCodes.NETWORK_ERROR,
-        `Failed to delete key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+        message,
         "kv",
         { meta: { status: response.status, statusText: response.statusText } }
       ));
     }
     return ok({
       data: void 0,
-      headers: this.createResponseHeaders(response.headers)
+      headers: this.createResponseHeaders(response.headers),
+      ...response.retry && { retry: response.retry }
     });
   }
   /**
@@ -3320,10 +3427,13 @@ var KVService = class extends BaseService {
             return await this.classifyNotFound(response, key);
           }
           const errorText = await response.text();
+          const message = `Failed to get metadata for key ${JSON.stringify(key)}: ${response.status} - ${errorText}`;
+          const retryError = nodeRetryError("kv", message, response, errorText);
+          if (retryError) return err(retryError);
           return err(
             serviceError(
               ErrorCodes.NETWORK_ERROR,
-              `Failed to get metadata for key ${JSON.stringify(key)}: ${response.status} - ${errorText}`,
+              message,
               "kv",
               { meta: { status: response.status, statusText: response.statusText } }
             )
@@ -3357,12 +3467,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,
@@ -3376,12 +3480,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);
         }
@@ -3515,42 +3622,6 @@ function requiresSecretsOptIn(space, prefix) {
   return prefix.split("/", 1)[0] === "vault";
 }
 
-// src/responseErrors.ts
-function parseServiceErrorBody(errorText) {
-  try {
-    return JSON.parse(errorText);
-  } catch {
-    return {};
-  }
-}
-function formatServiceResponseError(serviceLabel, operation, status, errorText, parsed) {
-  if (parsed.message) {
-    return compactMessage(parsed.message);
-  }
-  if (looksLikeHtml(errorText)) {
-    if (status === 524 || /524\s*[:-]/i.test(errorText) || /a timeout occurred/i.test(errorText)) {
-      return `${serviceLabel} ${operation} failed: upstream request timed out. Please retry.`;
-    }
-    return `${serviceLabel} ${operation} failed: upstream service returned an HTML error page (${status}).`;
-  }
-  return `${serviceLabel} ${operation} failed: ${status} - ${compactMessage(errorText)}`;
-}
-function responseErrorMeta(status, statusText, errorText) {
-  const meta = { status, statusText };
-  const snippet = compactMessage(errorText);
-  if (snippet) {
-    meta.responseSnippet = snippet.slice(0, 300);
-  }
-  return meta;
-}
-function looksLikeHtml(text) {
-  return /<!doctype html/i.test(text) || /<html[\s>]/i.test(text);
-}
-function compactMessage(message) {
-  const compact = message.replace(/\s+/g, " ").trim();
-  return compact.length > 500 ? `${compact.slice(0, 500)}...` : compact;
-}
-
 // src/sql/SQLMigrations.ts
 var SQLMigrations = class {
   constructor(service, dbName) {
@@ -3914,18 +3985,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);
@@ -3966,6 +4038,8 @@ var SQLService = class extends BaseService {
     if (response.status === 413 && parseStorageRejection(errorText)) {
       return err(storageRejectionError("sql", 413, meta, errorText));
     }
+    const retryError = nodeRetryError("sql", `SQL ${operation} failed: ${response.status} - ${errorText}`, response, errorText);
+    if (retryError) return err(retryError);
     const errorBody = parseServiceErrorBody(errorText);
     const errorCode = this.mapHttpStatusToErrorCode(
       response.status,
@@ -4384,22 +4458,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");
         }
@@ -4413,18 +4485,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();
@@ -4435,6 +4504,8 @@ var DuckDbService = class extends BaseService {
     if (response.status === 413 && parseStorageRejection(errorText)) {
       return err(storageRejectionError("duckdb", 413, meta, errorText));
     }
+    const retryError = nodeRetryError("duckdb", `DuckDB ${operation} failed: ${response.status} - ${errorText}`, response, errorText);
+    if (retryError) return err(retryError);
     const errorBody = parseServiceErrorBody(errorText);
     const errorCode = this.mapHttpStatusToErrorCode(
       response.status,
@@ -4611,26 +4682,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)
@@ -4668,17 +4737,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(
@@ -4705,20 +4770,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(
@@ -5174,23 +5235,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) => {
@@ -5607,40 +5652,150 @@ function parseStorageStatus(body) {
     if (status.account.plan) status.plan = status.account.plan;
     status.state = storageUsageState(account.usedBytes, account.limitBytes);
   }
-  return status;
+  return status;
+}
+
+// src/quota/TinyCloudQuota.ts
+var TinyCloudQuota = class {
+  constructor(config = {}) {
+    this.quotaUrl = null;
+    this.config = config;
+  }
+  /** Set the quota URL discovered from the /info endpoint */
+  setQuotaUrl(url) {
+    this.quotaUrl = url;
+  }
+  /** Whether a quota service is available */
+  get available() {
+    return this.quotaUrl !== null;
+  }
+  /** Query quota status for a space from the quota URL */
+  async getQuota(spaceId) {
+    if (!this.quotaUrl) return null;
+    const resp = await fetch(
+      `${this.quotaUrl}/api/quota/${encodeURIComponent(spaceId)}`
+    );
+    if (!resp.ok) return null;
+    const data = await resp.json();
+    return {
+      limitBytes: data.storage_limit_bytes ?? 0
+    };
+  }
+  /** Trigger the upgrade callback when a quota error is encountered */
+  handleQuotaError(info) {
+    this.config.onUpgradeRequired?.(info);
+  }
+};
+
+// src/encryption/canonical.ts
+function canonicalize(value) {
+  if (value === void 0) {
+    return "";
+  }
+  return stringify(value);
+}
+function stringify(value) {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "boolean":
+    case "number":
+      return JSON.stringify(value);
+    case "string":
+      return JSON.stringify(value);
+    case "object": {
+      if (Array.isArray(value)) {
+        return `[${value.map(stringify).join(",")}]`;
+      }
+      const keys = Object.keys(value).sort();
+      const parts = [];
+      for (const k of keys) {
+        const v = value[k];
+        if (v === void 0) continue;
+        parts.push(`${JSON.stringify(k)}:${stringify(v)}`);
+      }
+      return `{${parts.join(",")}}`;
+    }
+    default:
+      throw new TypeError(
+        `canonicalize: unsupported value type ${typeof value}`
+      );
+  }
+}
+var HEX = "0123456789abcdef";
+function hexEncode(bytes) {
+  let out = "";
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i];
+    out += HEX[b >> 4 & 15] + HEX[b & 15];
+  }
+  return out;
 }
-
-// src/quota/TinyCloudQuota.ts
-var TinyCloudQuota = class {
-  constructor(config = {}) {
-    this.quotaUrl = null;
-    this.config = config;
+function hexDecode(hex) {
+  if (hex.length % 2 !== 0) {
+    throw new Error("hex string must have even length");
   }
-  /** Set the quota URL discovered from the /info endpoint */
-  setQuotaUrl(url) {
-    this.quotaUrl = url;
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    const hi = parseInt(hex[i * 2], 16);
+    const lo = parseInt(hex[i * 2 + 1], 16);
+    if (Number.isNaN(hi) || Number.isNaN(lo)) {
+      throw new Error("invalid hex character");
+    }
+    out[i] = hi << 4 | lo;
   }
-  /** Whether a quota service is available */
-  get available() {
-    return this.quotaUrl !== null;
+  return out;
+}
+function base64Encode(bytes) {
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  let out = "";
+  for (let i = 0; i < bytes.length; i += 3) {
+    const b0 = bytes[i];
+    const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
+    const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
+    out += chars[b0 >> 2 & 63];
+    out += chars[(b0 << 4 | b1 >> 4) & 63];
+    out += i + 1 < bytes.length ? chars[(b1 << 2 | b2 >> 6) & 63] : "=";
+    out += i + 2 < bytes.length ? chars[b2 & 63] : "=";
   }
-  /** Query quota status for a space from the quota URL */
-  async getQuota(spaceId) {
-    if (!this.quotaUrl) return null;
-    const resp = await fetch(
-      `${this.quotaUrl}/api/quota/${encodeURIComponent(spaceId)}`
-    );
-    if (!resp.ok) return null;
-    const data = await resp.json();
-    return {
-      limitBytes: data.storage_limit_bytes ?? 0
-    };
+  return out;
+}
+function base64Decode(s) {
+  const clean = s.replace(/[^A-Za-z0-9+/=]/g, "");
+  const len = clean.length;
+  if (len % 4 !== 0) {
+    throw new Error("invalid base64 input");
   }
-  /** Trigger the upgrade callback when a quota error is encountered */
-  handleQuotaError(info) {
-    this.config.onUpgradeRequired?.(info);
+  const padding = clean.endsWith("==") ? 2 : clean.endsWith("=") ? 1 : 0;
+  const outLen = len / 4 * 3 - padding;
+  const out = new Uint8Array(outLen);
+  const lookup = {};
+  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+  for (let i = 0; i < chars.length; i++) lookup[chars[i]] = i;
+  let outIdx = 0;
+  for (let i = 0; i < len; i += 4) {
+    const v0 = lookup[clean[i]] ?? 0;
+    const v1 = lookup[clean[i + 1]] ?? 0;
+    const v2 = clean[i + 2] === "=" ? 0 : lookup[clean[i + 2]] ?? 0;
+    const v3 = clean[i + 3] === "=" ? 0 : lookup[clean[i + 3]] ?? 0;
+    const b0 = v0 << 2 | v1 >> 4;
+    const b1 = (v1 & 15) << 4 | v2 >> 2;
+    const b2 = (v2 & 3) << 6 | v3;
+    if (outIdx < outLen) out[outIdx++] = b0;
+    if (outIdx < outLen) out[outIdx++] = b1;
+    if (outIdx < outLen) out[outIdx++] = b2;
   }
-};
+  return out;
+}
+function utf8Encode(s) {
+  return new TextEncoder().encode(s);
+}
+function utf8Decode(b) {
+  return new TextDecoder().decode(b);
+}
+function canonicalHashHex(sha256, value) {
+  const canonical = canonicalize(value);
+  return hexEncode(sha256(utf8Encode(canonical)));
+}
 
 // src/vault/types.ts
 var VaultPublicSpaceKVActions = [
@@ -5811,7 +5966,7 @@ function toBytes(str) {
 function fromBytes(bytes) {
   return new TextDecoder().decode(bytes);
 }
-function hexEncode(bytes) {
+function hexEncode2(bytes) {
   return Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 function concatBytes(...arrays) {
@@ -5824,14 +5979,14 @@ function concatBytes(...arrays) {
   }
   return result;
 }
-function base64Encode(bytes) {
+function base64Encode2(bytes) {
   let binary = "";
   for (let i = 0; i < bytes.length; i++) {
     binary += String.fromCharCode(bytes[i]);
   }
   return btoa(binary);
 }
-function base64Decode(str) {
+function base64Decode2(str) {
   const binary = atob(str);
   const bytes = new Uint8Array(binary.length);
   for (let i = 0; i < binary.length; i++) {
@@ -5873,6 +6028,11 @@ function defaultVaultMessage(input) {
       return input.message;
     case "PERMISSION_DENIED":
       return input.message;
+    case "AAD_MISMATCH":
+    case "ETAG_MISMATCH":
+    case "INVALID_ETAG":
+    case "OUTCOME_UNKNOWN":
+    case "NODE_BUSY":
     case "STORAGE_QUOTA_EXCEEDED":
     case "STORAGE_LIMIT_REACHED":
       return input.message;
@@ -5895,6 +6055,37 @@ function typedKvCause(error) {
     ...error.cause !== void 0 ? { cause: error.cause } : {}
   });
 }
+function canonicalAadSpaceId(spaceId) {
+  return spaceId.replace(/0x[0-9a-fA-F]{40}/g, (address) => address.toLowerCase());
+}
+function checkEnvelopeAad(value, spaceId, key) {
+  const e = value;
+  if (typeof e !== "object" || e === null || Array.isArray(e) || !["networkId", "alg", "encryptedSymmetricKey", "encryptedSymmetricKeyHash", "ciphertext"].every(
+    (field) => typeof e[field] === "string" && e[field] !== ""
+  ) || !Number.isInteger(e.keyVersion) || e.aad !== void 0 && typeof e.aad !== "string") {
+    return "corrupt";
+  }
+  let aad = "";
+  try {
+    if (typeof e.aad === "string") aad = fromBytes(base64Decode(e.aad));
+  } catch {
+  }
+  const suffix = `:${key}`;
+  return aad.endsWith(suffix) && canonicalAadSpaceId(aad.slice(0, -suffix.length)) === canonicalAadSpaceId(`tinycloud.vault:${spaceId}`) ? "ok" : "mismatch";
+}
+var AMBIGUOUS_WRITE_STATUSES = [500, 502, 503, 504, 520, 522, 524];
+function ifMatchWriteError(key, error) {
+  const status = error.meta?.status;
+  const code = error.code === ErrorCodes.KV_PRECONDITION_FAILED ? "ETAG_MISMATCH" : error.code === ErrorCodes.KV_WRITE_FAILED && status === 400 ? "INVALID_ETAG" : error.code === ErrorCodes.OUTCOME_UNKNOWN || error.code === ErrorCodes.KV_WRITE_FAILED && typeof status === "number" && AMBIGUOUS_WRITE_STATUSES.includes(status) || (error.code === ErrorCodes.NETWORK_ERROR || error.code === ErrorCodes.TIMEOUT) && status === void 0 && error.meta?.requestMayHaveDispatched !== false ? "OUTCOME_UNKNOWN" : error.code === ErrorCodes.NODE_BUSY || error.code === ErrorCodes.REQUEST_TIMEOUT ? "NODE_BUSY" : void 0;
+  if (code === void 0) return void 0;
+  return vaultError({
+    code,
+    key,
+    message: error.message,
+    ...error.meta !== void 0 ? { meta: error.meta } : {},
+    cause: typedKvCause(error)
+  });
+}
 function kvWriteError(context, error) {
   if (error.code === ErrorCodes.STORAGE_QUOTA_EXCEEDED || error.code === ErrorCodes.STORAGE_LIMIT_REACHED) {
     return vaultError({ code: error.code, message: error.message, meta: error.meta });
@@ -6081,7 +6272,7 @@ var DataVaultService = class extends BaseService {
         }
         if (existingPubKey) {
           this.encryptionIdentity = {
-            publicKey: base64Decode(existingPubKey),
+            publicKey: base64Decode2(existingPubKey),
             privateKey: new Uint8Array(0)
             // private key not available without signing
           };
@@ -6106,7 +6297,7 @@ var DataVaultService = class extends BaseService {
           );
           this.encryptionIdentity = this.crypto.x25519FromSeed(seed);
           try {
-            const pubKeyB64 = base64Encode(this.encryptionIdentity.publicKey);
+            const pubKeyB64 = base64Encode2(this.encryptionIdentity.publicKey);
             await this.tc.ensurePublicSpace();
             await this.tc.publicKV.put(".well-known/vault-pubkey", pubKeyB64);
             await this.tc.publicKV.put(".well-known/vault-version", CURRENT_VAULT_VERSION);
@@ -6172,6 +6363,21 @@ var DataVaultService = class extends BaseService {
         message: "Authentication required"
       });
     }
+    if (options?.ifMatch !== void 0) {
+      if (options.ifNoneMatch !== void 0) {
+        return vaultError({
+          code: "STORAGE_ERROR",
+          cause: new Error("ifMatch cannot be combined with ifNoneMatch")
+        });
+      }
+      if (!/^"[^"\s]+"$/.test(options.ifMatch)) {
+        return vaultError({
+          code: "INVALID_ETAG",
+          key,
+          message: options.ifMatch.startsWith("W/") ? 'ifMatch is a weak etag (W/"..."): the node only issues strong etags, so the etag was weakened in transit (a proxy or CDN rewrote it). Read it from a connection that preserves strong ETags' : "ifMatch must be the strong, quoted ETag returned by a network read (VaultEntry.etag), passed exactly as returned"
+        });
+      }
+    }
     try {
       const { plaintext, contentType } = this.serializeValue(value, options);
       const metadata = {
@@ -6194,7 +6400,8 @@ var DataVaultService = class extends BaseService {
       }
       const valuePath = `vault/${key}`;
       const valueBody = JSON.stringify(envelopeResult.data);
-      const valuePutResult = options?.ifNoneMatch !== void 0 ? await this.tc.kv.put(valuePath, valueBody, { ifNoneMatch: options.ifNoneMatch }) : await this.tc.kv.put(valuePath, valueBody);
+      const putOptions = options?.ifMatch !== void 0 ? { ifMatch: options.ifMatch } : options?.ifNoneMatch !== void 0 ? { ifNoneMatch: options.ifNoneMatch } : void 0;
+      const valuePutResult = putOptions !== void 0 ? await this.tc.kv.put(valuePath, valueBody, putOptions) : await this.tc.kv.put(valuePath, valueBody);
       if (!valuePutResult.ok) {
         if (options?.ifNoneMatch !== void 0 && valuePutResult.error.code === ErrorCodes.KV_PRECONDITION_FAILED) {
           return vaultError({
@@ -6204,6 +6411,10 @@ var DataVaultService = class extends BaseService {
             cause: typedKvCause(valuePutResult.error)
           });
         }
+        if (options?.ifMatch !== void 0) {
+          const classified = ifMatchWriteError(key, valuePutResult.error);
+          if (classified !== void 0) return classified;
+        }
         return kvWriteError("Failed to store encrypted value", valuePutResult.error);
       }
       return { ok: true, data: void 0 };
@@ -6238,6 +6449,19 @@ var DataVaultService = class extends BaseService {
       }
       const rawEnvelope = unwrapKVData(valueResult.data);
       const envelope = typeof rawEnvelope === "string" ? JSON.parse(rawEnvelope) : rawEnvelope;
+      if (options?.expectAad === true) {
+        const verdict = checkEnvelopeAad(envelope, this.vaultConfig.spaceId, key);
+        if (verdict === "corrupt") {
+          return vaultError({ code: "DECRYPTION_FAILED", message: "envelope is malformed" });
+        }
+        if (verdict === "mismatch") {
+          return vaultError({
+            code: "AAD_MISMATCH",
+            key,
+            message: `Envelope at ${key} is not bound to this space and key`
+          });
+        }
+      }
       const proof = await this.decryptCapabilityProof();
       const plaintextResult = await config.service.decryptEnvelope(envelope, proof);
       if (!plaintextResult.ok) {
@@ -6254,7 +6478,11 @@ var DataVaultService = class extends BaseService {
         contentType,
         options
       );
-      return { ok: true, data: { value, metadata, keyId } };
+      const etag = options?.source === "network" ? valueResult.data.headers?.etag : void 0;
+      return {
+        ok: true,
+        data: { value, metadata, keyId, ...etag === void 0 ? {} : { etag } }
+      };
     } catch (error) {
       return vaultError({
         code: "STORAGE_ERROR",
@@ -6300,6 +6528,12 @@ var DataVaultService = class extends BaseService {
     } catch {
       return { status: "corrupt_envelope" };
     }
+    if (options?.expectAad === true) {
+      const verdict = checkEnvelopeAad(envelope, this.vaultConfig.spaceId, key);
+      if (verdict !== "ok") {
+        return { status: verdict === "corrupt" ? "corrupt_envelope" : "aad_mismatch" };
+      }
+    }
     let plaintextResult;
     try {
       const proof = await this.decryptCapabilityProof();
@@ -6331,7 +6565,11 @@ var DataVaultService = class extends BaseService {
         contentType,
         options
       );
-      return { status: "ok", entry: { value, metadata, keyId } };
+      const etag = valueResult.data.headers?.etag;
+      return {
+        status: "ok",
+        entry: { value, metadata, keyId, ...etag === void 0 ? {} : { etag } }
+      };
     } catch {
       return { status: "invalid_payload" };
     }
@@ -6381,6 +6619,14 @@ var DataVaultService = class extends BaseService {
           )
         });
       }
+      if (options?.ifMatch !== void 0) {
+        return vaultError({
+          code: "STORAGE_ERROR",
+          cause: new Error(
+            "ifMatch is only supported by network-encrypted vaults"
+          )
+        });
+      }
       if (!this._isUnlocked || !this.masterKey) {
         return vaultError({
           code: "VAULT_LOCKED",
@@ -6406,7 +6652,7 @@ var DataVaultService = class extends BaseService {
         }
         const contentType = options?.contentType ?? (value instanceof Uint8Array ? "application/octet-stream" : "application/json");
         const entryKey = this.crypto.randomBytes(32);
-        const keyId = hexEncode(this.crypto.sha256(entryKey)).slice(0, 16);
+        const keyId = hexEncode2(this.crypto.sha256(entryKey)).slice(0, 16);
         const encrypted = this.crypto.encrypt(entryKey, plaintext);
         const keyBlob = this.crypto.encrypt(this.masterKey, entryKey);
         const metadata = {
@@ -6424,7 +6670,7 @@ var DataVaultService = class extends BaseService {
           ...metadata
         });
         const keyPayload = JSON.stringify({
-          key: base64Encode(keyBlob),
+          key: base64Encode2(keyBlob),
           metadata: keyMetadata
         });
         const keyPutResult = await this.tc.kv.put(
@@ -6435,7 +6681,7 @@ var DataVaultService = class extends BaseService {
           return kvWriteError("Failed to store key blob", keyPutResult.error);
         }
         const valuePayload = JSON.stringify({
-          data: base64Encode(encrypted),
+          data: base64Encode2(encrypted),
           metadata
         });
         const valuePutResult = await this.tc.kv.put(
@@ -6466,6 +6712,12 @@ var DataVaultService = class extends BaseService {
       if (this.usesNetworkEncryption) {
         return this.getNetworkEncrypted(key, options);
       }
+      if (options?.expectAad === true) {
+        return vaultError({
+          code: "STORAGE_ERROR",
+          cause: new Error("expectAad is only supported by network-encrypted vaults")
+        });
+      }
       if (!this._isUnlocked || !this.masterKey) {
         return vaultError({
           code: "VAULT_LOCKED",
@@ -6487,7 +6739,7 @@ var DataVaultService = class extends BaseService {
           return vaultError({ code: "KEY_NOT_FOUND", key });
         }
         const keyEnvelope = JSON.parse(keyResult.data.data);
-        const keyBlobBytes = base64Decode(keyEnvelope.key);
+        const keyBlobBytes = base64Decode2(keyEnvelope.key);
         const entryKey = this.crypto.decrypt(this.masterKey, keyBlobBytes);
         const valueResult = await this.tc.kv.get(`vault/${key}`, {
           raw: true,
@@ -6497,7 +6749,7 @@ var DataVaultService = class extends BaseService {
           return vaultError({ code: "KEY_NOT_FOUND", key });
         }
         const valueEnvelope = JSON.parse(valueResult.data.data);
-        const encryptedBytes = base64Decode(valueEnvelope.data);
+        const encryptedBytes = base64Decode2(valueEnvelope.data);
         const plaintext = this.crypto.decrypt(entryKey, encryptedBytes);
         const metadata = valueEnvelope.metadata ?? {};
         const contentType = metadata[VaultHeaders.CONTENT_TYPE] ?? "application/json";
@@ -6745,7 +6997,7 @@ var DataVaultService = class extends BaseService {
           return vaultError({ code: "KEY_NOT_FOUND", key });
         }
         const keyEnvelope = JSON.parse(keyResult.data.data);
-        const keyBlobBytes = base64Decode(keyEnvelope.key);
+        const keyBlobBytes = base64Decode2(keyEnvelope.key);
         const entryKey = this.crypto.decrypt(this.masterKey, keyBlobBytes);
         const ephemeralSeed = this.crypto.randomBytes(32);
         const ephemeralKeyPair = this.crypto.x25519FromSeed(ephemeralSeed);
@@ -6764,7 +7016,7 @@ var DataVaultService = class extends BaseService {
           encryptedGrant
         );
         const grantPayload = JSON.stringify({
-          grant: base64Encode(grantBlob),
+          grant: base64Encode2(grantBlob),
           spaceId: this.vaultConfig.spaceId,
           metadata: {
             [VaultHeaders.GRANT_VERSION]: "1",
@@ -6804,6 +7056,14 @@ var DataVaultService = class extends BaseService {
    */
   async getShared(grantorDID, key, options) {
     return this.withTelemetry("getShared", key, async () => {
+      if (options?.expectAad === true) {
+        return vaultError({
+          code: "STORAGE_ERROR",
+          cause: new Error(
+            "expectAad is not supported by getShared: the AAD binds the grantor's space, which this vault does not know"
+          )
+        });
+      }
       if (this.usesNetworkEncryption) {
         const grantorKV = options?.kv;
         if (!grantorKV) {
@@ -6898,7 +7158,7 @@ var DataVaultService = class extends BaseService {
           });
         }
         const grantEnvelope = typeof grantResult.data?.data === "string" ? JSON.parse(grantResult.data.data) : grantResult.data?.data;
-        const grantBlobBytes = base64Decode(grantEnvelope.grant);
+        const grantBlobBytes = base64Decode2(grantEnvelope.grant);
         const ephemeralPubKey = grantBlobBytes.slice(0, 32);
         const encryptedGrant = grantBlobBytes.slice(32);
         const sharedSecret = this.crypto.x25519Dh(
@@ -6921,7 +7181,7 @@ var DataVaultService = class extends BaseService {
           });
         }
         const valueEnvelope = typeof valueResult.data?.data === "string" ? JSON.parse(valueResult.data.data) : valueResult.data?.data;
-        const encryptedBytes = base64Decode(valueEnvelope.data);
+        const encryptedBytes = base64Decode2(valueEnvelope.data);
         const plaintext = this.crypto.decrypt(entryKey, encryptedBytes);
         const metadata = valueEnvelope.metadata ?? {};
         const contentType = metadata[VaultHeaders.CONTENT_TYPE] ?? "application/json";
@@ -6975,7 +7235,7 @@ var DataVaultService = class extends BaseService {
       if (!result.ok) {
         return vaultError({ code: "PUBLIC_KEY_NOT_FOUND", did });
       }
-      const pubKeyBytes = base64Decode(result.data);
+      const pubKeyBytes = base64Decode2(result.data);
       return { ok: true, data: pubKeyBytes };
     } catch (error) {
       return vaultError({ code: "PUBLIC_KEY_NOT_FOUND", did });
@@ -7094,7 +7354,7 @@ var DataVaultService = class extends BaseService {
         }
         const currentEntry = getResult.data;
         const newEntryKey = this.crypto.randomBytes(32);
-        const newKeyId = hexEncode(this.crypto.sha256(newEntryKey)).slice(
+        const newKeyId = hexEncode2(this.crypto.sha256(newEntryKey)).slice(
           0,
           16
         );
@@ -7111,7 +7371,7 @@ var DataVaultService = class extends BaseService {
           [VaultHeaders.KEY_ID]: newKeyId
         };
         const keyPayload = JSON.stringify({
-          key: base64Encode(newKeyBlob),
+          key: base64Encode2(newKeyBlob),
           metadata: JSON.stringify({
             keyId: newKeyId,
             ...metadata
@@ -7125,7 +7385,7 @@ var DataVaultService = class extends BaseService {
           return kvWriteError("Failed to store rotated key blob", keyPutResult.error);
         }
         const valuePayload = JSON.stringify({
-          data: base64Encode(encrypted),
+          data: base64Encode2(encrypted),
           metadata
         });
         const valuePutResult = await this.tc.kv.put(
@@ -7417,116 +7677,6 @@ var SecretsService = class {
   }
 };
 
-// src/encryption/canonical.ts
-function canonicalize(value) {
-  if (value === void 0) {
-    return "";
-  }
-  return stringify(value);
-}
-function stringify(value) {
-  if (value === null) return "null";
-  switch (typeof value) {
-    case "boolean":
-    case "number":
-      return JSON.stringify(value);
-    case "string":
-      return JSON.stringify(value);
-    case "object": {
-      if (Array.isArray(value)) {
-        return `[${value.map(stringify).join(",")}]`;
-      }
-      const keys = Object.keys(value).sort();
-      const parts = [];
-      for (const k of keys) {
-        const v = value[k];
-        if (v === void 0) continue;
-        parts.push(`${JSON.stringify(k)}:${stringify(v)}`);
-      }
-      return `{${parts.join(",")}}`;
-    }
-    default:
-      throw new TypeError(
-        `canonicalize: unsupported value type ${typeof value}`
-      );
-  }
-}
-var HEX = "0123456789abcdef";
-function hexEncode2(bytes) {
-  let out = "";
-  for (let i = 0; i < bytes.length; i++) {
-    const b = bytes[i];
-    out += HEX[b >> 4 & 15] + HEX[b & 15];
-  }
-  return out;
-}
-function hexDecode(hex) {
-  if (hex.length % 2 !== 0) {
-    throw new Error("hex string must have even length");
-  }
-  const out = new Uint8Array(hex.length / 2);
-  for (let i = 0; i < out.length; i++) {
-    const hi = parseInt(hex[i * 2], 16);
-    const lo = parseInt(hex[i * 2 + 1], 16);
-    if (Number.isNaN(hi) || Number.isNaN(lo)) {
-      throw new Error("invalid hex character");
-    }
-    out[i] = hi << 4 | lo;
-  }
-  return out;
-}
-function base64Encode2(bytes) {
-  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
-  let out = "";
-  for (let i = 0; i < bytes.length; i += 3) {
-    const b0 = bytes[i];
-    const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
-    const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
-    out += chars[b0 >> 2 & 63];
-    out += chars[(b0 << 4 | b1 >> 4) & 63];
-    out += i + 1 < bytes.length ? chars[(b1 << 2 | b2 >> 6) & 63] : "=";
-    out += i + 2 < bytes.length ? chars[b2 & 63] : "=";
-  }
-  return out;
-}
-function base64Decode2(s) {
-  const clean = s.replace(/[^A-Za-z0-9+/=]/g, "");
-  const len = clean.length;
-  if (len % 4 !== 0) {
-    throw new Error("invalid base64 input");
-  }
-  const padding = clean.endsWith("==") ? 2 : clean.endsWith("=") ? 1 : 0;
-  const outLen = len / 4 * 3 - padding;
-  const out = new Uint8Array(outLen);
-  const lookup = {};
-  const chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
-  for (let i = 0; i < chars.length; i++) lookup[chars[i]] = i;
-  let outIdx = 0;
-  for (let i = 0; i < len; i += 4) {
-    const v0 = lookup[clean[i]] ?? 0;
-    const v1 = lookup[clean[i + 1]] ?? 0;
-    const v2 = clean[i + 2] === "=" ? 0 : lookup[clean[i + 2]] ?? 0;
-    const v3 = clean[i + 3] === "=" ? 0 : lookup[clean[i + 3]] ?? 0;
-    const b0 = v0 << 2 | v1 >> 4;
-    const b1 = (v1 & 15) << 4 | v2 >> 2;
-    const b2 = (v2 & 3) << 6 | v3;
-    if (outIdx < outLen) out[outIdx++] = b0;
-    if (outIdx < outLen) out[outIdx++] = b1;
-    if (outIdx < outLen) out[outIdx++] = b2;
-  }
-  return out;
-}
-function utf8Encode(s) {
-  return new TextEncoder().encode(s);
-}
-function utf8Decode(b) {
-  return new TextDecoder().decode(b);
-}
-function canonicalHashHex(sha256, value) {
-  const canonical = canonicalize(value);
-  return hexEncode2(sha256(utf8Encode(canonical)));
-}
-
 // src/encryption/types.ts
 var DEFAULT_ENCRYPTION_ALG = "x25519-aes256gcm/v1";
 var ENVELOPE_VERSION = 1;
@@ -7736,7 +7886,7 @@ function encryptToNetwork(crypto2, input) {
   const symmetricKey = crypto2.randomBytes(32);
   const ciphertext = crypto2.authEncrypt(symmetricKey, input.plaintext, input.aad);
   const wrapped = crypto2.sealToNetworkKey(input.networkPublicKey, symmetricKey);
-  const encryptedSymmetricKey = base64Encode2(wrapped);
+  const encryptedSymmetricKey = base64Encode(wrapped);
   const encryptedSymmetricKeyHash = canonicalHashHex(
     crypto2.sha256,
     encryptedSymmetricKey
@@ -7748,8 +7898,8 @@ function encryptToNetwork(crypto2, input) {
     keyVersion,
     encryptedSymmetricKey,
     encryptedSymmetricKeyHash,
-    ciphertext: base64Encode2(ciphertext),
-    ...input.aad !== void 0 ? { aad: base64Encode2(input.aad) } : {},
+    ciphertext: base64Encode(ciphertext),
+    ...input.aad !== void 0 ? { aad: base64Encode(input.aad) } : {},
     ...input.metadata !== void 0 ? { metadata: input.metadata } : {}
   };
   return { envelope, symmetricKey };
@@ -7823,8 +7973,8 @@ function validateEnvelope(crypto2, envelope) {
   return { ok: true, data: e };
 }
 function decryptEnvelopeWithKey(crypto2, envelope, symmetricKey) {
-  const ciphertext = base64Decode2(envelope.ciphertext);
-  const aad = envelope.aad !== void 0 ? base64Decode2(envelope.aad) : void 0;
+  const ciphertext = base64Decode(envelope.ciphertext);
+  const aad = envelope.aad !== void 0 ? base64Decode(envelope.aad) : void 0;
   return crypto2.authDecrypt(symmetricKey, ciphertext, aad);
 }
 
@@ -7842,7 +7992,7 @@ function buildCanonicalDecryptRequest(input) {
   return { canonicalBody, bodyHash, receiverPublicKeyHash };
 }
 function buildDecryptFacts(input) {
-  const bodyHash = input.canonicalBody !== void 0 ? hexEncode2(input.crypto.sha256(utf8Encode(input.canonicalBody))) : canonicalHashHex(
+  const bodyHash = input.canonicalBody !== void 0 ? hexEncode(input.crypto.sha256(utf8Encode(input.canonicalBody))) : canonicalHashHex(
     input.crypto.sha256,
     input.body
   );
@@ -8125,7 +8275,7 @@ function verifyDecryptResponse(input) {
       })
     };
   }
-  const expectedRequestHash = hexEncode2(
+  const expectedRequestHash = hexEncode(
     crypto2.sha256(utf8Encode(`${invocationCid}${requestBodyHash}`))
   );
   if (response.requestHash !== expectedRequestHash) {
@@ -8149,7 +8299,7 @@ function verifyDecryptResponse(input) {
   const signedBytes = new TextEncoder().encode(
     canonicalSignedResponse(response)
   );
-  const signatureBytes = base64Decode2(response.nodeSignature);
+  const signatureBytes = base64Decode(response.nodeSignature);
   if (!crypto2.verifyNodeSignature(response.nodeId, signedBytes, signatureBytes)) {
     return {
       ok: false,
@@ -8161,7 +8311,7 @@ function verifyDecryptResponse(input) {
   return { ok: true, data: response };
 }
 function openWrappedKey(crypto2, receiverPrivateKey, response) {
-  const wrapped = base64Decode2(response.wrappedKey);
+  const wrapped = base64Decode(response.wrappedKey);
   return crypto2.openWithReceiverKey(receiverPrivateKey, wrapped);
 }
 
@@ -8205,7 +8355,7 @@ var EncryptionService = class extends BaseService {
       const usable = ensureNetworkUsableForDecrypt(discovered.data);
       if (!usable.ok) return usable;
       const descriptor = usable.data;
-      const networkPublicKey = base64Decode2(descriptor.publicEncryptionKey);
+      const networkPublicKey = base64Decode(descriptor.publicEncryptionKey);
       const result = encryptToNetwork(this.crypto, {
         // Discovery returns the node's canonical network identifier. Persist
         // that spelling in the envelope so a later response can be compared
@@ -8233,7 +8383,7 @@ var EncryptionService = class extends BaseService {
       this.assertActive();
       const validated = validateEnvelope(this.crypto, envelope);
       if (!validated.ok) return validated;
-      if (options?.aad !== void 0 && validated.data.aad !== base64Encode2(options.aad)) {
+      if (options?.aad !== void 0 && validated.data.aad !== base64Encode(options.aad)) {
         return encErr(
           encryptionError({
             code: "INVALID_INPUT",
@@ -8261,7 +8411,7 @@ var EncryptionService = class extends BaseService {
         );
       }
       const receiverKey = generateRandomReceiverKey({ crypto: this.crypto });
-      const receiverPublicKey = base64Encode2(receiverKey.publicKey);
+      const receiverPublicKey = base64Encode(receiverKey.publicKey);
       const receiverPublicKeyHash = canonicalHashHex(
         this.crypto.sha256,
         receiverPublicKey
@@ -8476,6 +8626,7 @@ var import_decrypt_transport_response_error3 = require("@tinycloud/sdk-services/
   kvPrefixCovers,
   networkDiscoveryKey,
   networkError,
+  nodeRetryError,
   notFoundError,
   ok,
   openWrappedKey,