@tinycloud/sdk-services 3.5.0 → 3.6.0-beta.2

package/dist/context.cjs

@@ -0,0 +1,831 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/context.ts
+var context_exports = {};
+__export(context_exports, {
+  ServiceContext: () => ServiceContext
+});
+module.exports = __toCommonJS(context_exports);
+
+// src/types.ts
+var ErrorCodes = {
+  // Common errors
+  NOT_FOUND: "NOT_FOUND",
+  AUTH_EXPIRED: "AUTH_EXPIRED",
+  AUTH_REQUIRED: "AUTH_REQUIRED",
+  AUTH_UNAUTHORIZED: "AUTH_UNAUTHORIZED",
+  /** HTTP 401: the delegation the invocation cites was revoked. */
+  AUTH_DELEGATION_REVOKED: "AUTH_DELEGATION_REVOKED",
+  /** HTTP 401: a delegation the cited one rests on was revoked. */
+  AUTH_DELEGATION_ANCESTOR_REVOKED: "AUTH_DELEGATION_ANCESTOR_REVOKED",
+  NETWORK_ERROR: "NETWORK_ERROR",
+  TIMEOUT: "TIMEOUT",
+  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",
+  KV_PRECONDITION_FAILED: "KV_PRECONDITION_FAILED",
+  KV_CONFLICT: "KV_CONFLICT",
+  KV_RESPONSE_TOO_LARGE: "KV_RESPONSE_TOO_LARGE",
+  /** HTTP 410 from the change feed: discard sync state and restart without a cursor; `meta.reason` says why. */
+  KV_SYNC_RESET_REQUIRED: "KV_SYNC_RESET_REQUIRED",
+  /** HTTP 403 from the change feed: the retention grant was refused; `meta.reason` says why. */
+  KV_RETENTION_GRANT_REFUSED: "KV_RETENTION_GRANT_REFUSED",
+  // SQL-specific errors
+  SQL_ERROR: "SQL_ERROR",
+  SQL_PERMISSION_DENIED: "SQL_PERMISSION_DENIED",
+  SQL_DATABASE_NOT_FOUND: "SQL_DATABASE_NOT_FOUND",
+  SQL_RESPONSE_TOO_LARGE: "SQL_RESPONSE_TOO_LARGE",
+  SQL_QUOTA_EXCEEDED: "SQL_QUOTA_EXCEEDED",
+  SQL_INVALID_STATEMENT: "SQL_INVALID_STATEMENT",
+  SQL_SCHEMA_ERROR: "SQL_SCHEMA_ERROR",
+  SQL_READONLY_VIOLATION: "SQL_READONLY_VIOLATION",
+  // Storage quota errors
+  STORAGE_QUOTA_EXCEEDED: "STORAGE_QUOTA_EXCEEDED",
+  STORAGE_LIMIT_REACHED: "STORAGE_LIMIT_REACHED",
+  /** The node answered the usage read without usage numbers (it predates the read). */
+  STORAGE_STATUS_UNAVAILABLE: "STORAGE_STATUS_UNAVAILABLE",
+  // DuckDB-specific errors
+  DUCKDB_ERROR: "DUCKDB_ERROR",
+  DUCKDB_PERMISSION_DENIED: "DUCKDB_PERMISSION_DENIED",
+  DUCKDB_DATABASE_NOT_FOUND: "DUCKDB_DATABASE_NOT_FOUND",
+  DUCKDB_RESPONSE_TOO_LARGE: "DUCKDB_RESPONSE_TOO_LARGE",
+  DUCKDB_QUOTA_EXCEEDED: "DUCKDB_QUOTA_EXCEEDED",
+  DUCKDB_INVALID_STATEMENT: "DUCKDB_INVALID_STATEMENT",
+  DUCKDB_SCHEMA_ERROR: "DUCKDB_SCHEMA_ERROR",
+  DUCKDB_READONLY_VIOLATION: "DUCKDB_READONLY_VIOLATION"
+};
+var defaultRetryPolicy = {
+  maxAttempts: 4,
+  backoff: "exponential",
+  baseDelayMs: 250,
+  maxDelayMs: 4e3,
+  retryableErrors: [ErrorCodes.NODE_BUSY, ErrorCodes.REQUEST_TIMEOUT],
+  maxTotalMs: 12e3
+};
+function serviceError(code, message, service, options) {
+  return {
+    code,
+    message,
+    service,
+    cause: options?.cause,
+    meta: options?.meta
+  };
+}
+
+// src/diagnostics.ts
+var REDACTED = "[REDACTED]";
+var SAFE_NUMBER_FIELDS = /* @__PURE__ */ new Set([
+  "duration",
+  "durationMs",
+  "endedAt",
+  "startedAt",
+  "status",
+  "timestamp",
+  "latencyMs",
+  "stalenessMs",
+  "count",
+  "changes",
+  "deleted",
+  "fetched",
+  "pages",
+  "lagMs",
+  "pendingCleared",
+  "partitions",
+  "remaining",
+  "expiryMs"
+]);
+var SAFE_BOOLEAN_FIELDS = /* @__PURE__ */ new Set(["authenticated", "ok", "persisted", "purgePending"]);
+var SAFE_REPLICATION_FIELDS = {
+  source: ["replica", "network", "none"],
+  reason: ["hit", "absent", "deleted", "content_missing", "coverage_incomplete", "not_covered", "pending_write", "grant_missing", "grant_expired", "grant_revoked", "grant_not_yet_valid", "stale", "replica_error", "runtime_unsupported", "replica_unavailable", "unsupported_option", "network_cursor", "cursor_restart", "aborted", "REPLICA_BEHIND_OWN_WRITES", "REPLICA_UNPROVEN_SINCE_START", "NETWORK_REQUESTED", "replica_gated", "sign_out", "account_switch", "consent_expired", "startup"],
+  op: ["get", "list", "put", "delete", "batchPut"],
+  trigger: ["start", "interval", "stale_read", "manual", "peer"],
+  origin: ["peer"],
+  outcome: ["found", "not_found", "error", "committed", "failed", "ambiguous", "ok", "busy", "aborted"],
+  class: ["offline", "authority", "storage", "node", "lifecycle"],
+  state: ["opened", "grant_installed", "grant_missing", "runtime_unsupported", "unavailable", "revoked", "recreated", "purged", "purge_failed", "pending_store_error", "pinned", "pending_cleared", "closed", "idle", "ready", "gated"],
+  action: ["minted", "renewed", "renewal_refused", "renewal_deferred", "capped", "expired", "consent_deadline_reached", "denied", "deny_stale", "deny_failed", "database_deleted", "marker_set", "marker_cleared", "unguarded", "drained", "erased", "erase_failed", "activation_blocked", "activated", "recovered"],
+  gate: ["not_established", "stamp_stale", "principal_mismatch", "purge_pending", "logout_pending", "gate_unavailable"],
+  kind: ["value", "missing_local", "extra_local", "keys", "order"],
+  coverage: ["empty", "bootstrapping", "complete"],
+  authority: ["valid", "expired", "revoked", "not-yet-valid"],
+  code: ["NETWORK_ERROR", "TIMEOUT", "ABORTED", "REPLICA_BUSY", "REPLICA_BEHIND_OWN_WRITES", "REPLICA_UNPROVEN_SINCE_START", "NETWORK_REQUESTED", "INTEGRITY_ERROR", "STORAGE_ERROR", "REPLICA_CLOSED", "RUNTIME_UNSUPPORTED", "GRANT_EXPIRED", "GRANT_REVOKED", "GRANT_NOT_YET_VALID", "GRANT_MISSING", "GRANT_INVALID", "SOURCE_CHANGED", "PROTOCOL_ERROR", "SCOPE_VIOLATION", "NODE_ERROR", "CONTENT_MISMATCH", "STORAGE_FULL", "REPLICA_GATED", "RESET_REQUIRED", "STORAGE_BUDGET", "CONSENT_EXPIRED"],
+  pendingState: ["in_flight", "committed", "ambiguous"],
+  strategy: ["session", "minted", "installed"],
+  verify: ["match", "diverged", "error", "aborted"]
+};
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function isBinaryData(value) {
+  try {
+    return Array.isArray(value) || ArrayBuffer.isView(value) || value instanceof ArrayBuffer;
+  } catch {
+    return true;
+  }
+}
+function read(value, key) {
+  try {
+    return value[key];
+  } catch {
+    return REDACTED;
+  }
+}
+function projectDiagnosticError(error) {
+  if (typeof error !== "object" || error === null) return {};
+  const status = finiteNumber(read(error, "status"));
+  return status !== void 0 && status >= 100 && status <= 599 ? { status } : {};
+}
+function projectDiagnosticData(value) {
+  if (value === null || value === void 0) return value;
+  if (typeof value !== "object") return REDACTED;
+  try {
+    if (isBinaryData(value)) return REDACTED;
+    const projected = {};
+    for (const key of SAFE_NUMBER_FIELDS) {
+      const number = finiteNumber(read(value, key));
+      if (number !== void 0) projected[key] = number;
+    }
+    for (const key of SAFE_BOOLEAN_FIELDS) {
+      const boolean = read(value, key);
+      if (typeof boolean === "boolean") projected[key] = boolean;
+    }
+    for (const [key, allowed] of Object.entries(SAFE_REPLICATION_FIELDS)) {
+      const candidate = read(value, key);
+      if (typeof candidate === "string" && allowed.includes(candidate)) {
+        projected[key] = candidate;
+      }
+    }
+    const url = read(value, "url");
+    if (url !== void 0) projected.url = REDACTED;
+    const error = read(value, "error");
+    if (error !== void 0) projected.error = projectDiagnosticError(error);
+    return projected;
+  } catch {
+    return REDACTED;
+  }
+}
+
+// src/debug.ts
+var DEBUG_FLAG = "TinyCloud_debug";
+var MAX_EVENTS = 1e3;
+function getGlobal() {
+  return globalThis;
+}
+function nowMs() {
+  const performanceNow = globalThis.performance?.now?.bind(globalThis.performance);
+  return typeof performanceNow === "function" ? performanceNow() : Date.now();
+}
+function isTrue(value) {
+  return value === true || value === "true" || value === "1";
+}
+function getProcessDebugFlag() {
+  const processLike = globalThis.process;
+  return processLike?.env?.[DEBUG_FLAG];
+}
+function isBrowserWindow() {
+  const global = getGlobal();
+  return global.window === globalThis;
+}
+function getLocalStorage() {
+  if (!isBrowserWindow()) {
+    return void 0;
+  }
+  try {
+    return globalThis.localStorage;
+  } catch {
+    return void 0;
+  }
+}
+function getStoredDebugFlag() {
+  const storage = getLocalStorage();
+  if (!storage) {
+    return void 0;
+  }
+  try {
+    return storage.getItem(DEBUG_FLAG);
+  } catch {
+    return void 0;
+  }
+}
+function setStoredDebugFlag(enabled) {
+  const storage = getLocalStorage();
+  if (!storage) {
+    return;
+  }
+  try {
+    if (enabled) {
+      storage.setItem(DEBUG_FLAG, "true");
+    } else {
+      storage.removeItem(DEBUG_FLAG);
+    }
+  } catch {
+  }
+}
+function shouldStartEnabled() {
+  const global = getGlobal();
+  return isTrue(global[DEBUG_FLAG]) || isTrue(getStoredDebugFlag()) || isTrue(getProcessDebugFlag());
+}
+var TinyCloudDebugLogger = class {
+  constructor() {
+    this.enabled = shouldStartEnabled();
+    this.sequence = 0;
+    this.events = [];
+    this.maxEvents = MAX_EVENTS;
+  }
+  isEnabled() {
+    return this.enabled || isTrue(getGlobal()[DEBUG_FLAG]) || isTrue(getProcessDebugFlag());
+  }
+  enable(options = {}) {
+    this.enabled = true;
+    getGlobal()[DEBUG_FLAG] = true;
+    if (options.persist !== false) {
+      setStoredDebugFlag(true);
+    }
+    this.log("debug.enabled", { persisted: options.persist !== false });
+  }
+  disable(options = {}) {
+    this.log("debug.disabled", { persisted: options.persist !== false });
+    this.enabled = false;
+    getGlobal()[DEBUG_FLAG] = false;
+    if (options.persist !== false) {
+      setStoredDebugFlag(false);
+    }
+  }
+  clear() {
+    this.events = [];
+  }
+  getLogs() {
+    return [...this.events];
+  }
+  log(event, data, message) {
+    if (!this.isEnabled()) {
+      return void 0;
+    }
+    return this.record({
+      event,
+      data,
+      message,
+      level: "debug",
+      timestamp: Date.now(),
+      timestampIso: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  startTimer(event, data) {
+    if (!this.isEnabled()) {
+      return { stop: () => void 0 };
+    }
+    const startedAt = nowMs();
+    this.log(`${event}.start`, data);
+    return {
+      stop: (finishData) => {
+        const endedAt = nowMs();
+        return this.record({
+          event: `${event}.end`,
+          data: finishData,
+          durationMs: endedAt - startedAt,
+          startedAt,
+          endedAt,
+          level: "debug",
+          timestamp: Date.now(),
+          timestampIso: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+    };
+  }
+  async timeAsync(event, operation, data) {
+    if (!this.isEnabled()) {
+      return operation();
+    }
+    const timer = this.startTimer(event, data);
+    try {
+      const result = await operation();
+      timer.stop({ ok: true });
+      return result;
+    } catch (error) {
+      timer.stop({ ok: false, error });
+      throw error;
+    }
+  }
+  time(event, operation, data) {
+    if (!this.isEnabled()) {
+      return operation();
+    }
+    const timer = this.startTimer(event, data);
+    try {
+      const result = operation();
+      timer.stop({ ok: true });
+      return result;
+    } catch (error) {
+      timer.stop({ ok: false, error });
+      throw error;
+    }
+  }
+  record(event) {
+    const debugEvent = {
+      ...event,
+      ...event.data === void 0 ? {} : { data: projectDiagnosticData(event.data) },
+      ...event.message === void 0 ? {} : { message: "[REDACTED]" },
+      sequence: ++this.sequence
+    };
+    this.events.push(debugEvent);
+    if (this.events.length > this.maxEvents) {
+      this.events.splice(0, this.events.length - this.maxEvents);
+    }
+    try {
+      globalThis.console?.debug?.("[TinyCloud]", debugEvent.event, debugEvent);
+    } catch {
+    }
+    return debugEvent;
+  }
+};
+var tinyCloudDebugLogger = new TinyCloudDebugLogger();
+function enableTinyCloudDebug(options) {
+  tinyCloudDebugLogger.enable(options);
+  return tinyCloudDebugLogger;
+}
+function disableTinyCloudDebug(options) {
+  tinyCloudDebugLogger.disable(options);
+  return tinyCloudDebugLogger;
+}
+function getTinyCloudDebugLogs() {
+  return tinyCloudDebugLogger.getLogs();
+}
+function clearTinyCloudDebugLogs() {
+  tinyCloudDebugLogger.clear();
+}
+function installTinyCloudDebugGlobals() {
+  const global = getGlobal();
+  global.TinyCloudDebug = tinyCloudDebugLogger;
+  global.enableTinyCloudDebug = enableTinyCloudDebug;
+  global.disableTinyCloudDebug = disableTinyCloudDebug;
+  global.getTinyCloudDebugLogs = getTinyCloudDebugLogs;
+  global.clearTinyCloudDebugLogs = clearTinyCloudDebugLogs;
+}
+installTinyCloudDebugGlobals();
+
+// src/responseErrors.ts
+function responseErrorMeta(status, statusText, errorText) {
+  const meta = { status, statusText };
+  const snippet = compactMessage(errorText);
+  if (snippet) {
+    meta.responseSnippet = snippet.slice(0, 300);
+  }
+  return meta;
+}
+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");
+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 grantableActions = new Set(
+  import_bootstrap.CAPABILITY_REGISTRY.map(({ urn }) => urn).filter((urn) => !urn.endsWith("/*"))
+);
+var capabilityServices = new Set(
+  import_bootstrap.CAPABILITY_REGISTRY.map(({ service }) => service.slice("tinycloud.".length))
+);
+
+// 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;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ServiceContext
+});
+//# sourceMappingURL=context.cjs.map