@lunora/client 0.0.0 → 1.0.0-alpha.2

package/dist/packem_shared/LunoraClient-UiULzH_1.mjs

@@ -0,0 +1,2165 @@
+import createInMemoryBookmarkStorage from './createInMemoryBookmarkStorage-BoN7a7TH.mjs';
+import { isMutationDelta, applyDelta } from './applyDelta-4jFGTPA3.mjs';
+import { createLocalStore } from './createLocalStore-DSUfoLqY.mjs';
+import { OfflineQueue, nextId, reportPersistenceError } from './OfflineQueue-D5p_QgF_.mjs';
+import { queryCacheKey } from './createInMemoryQueryCache-B1PQ9Twl.mjs';
+import { createReconnect } from './createReconnect-Di_-oHH7.mjs';
+import { createStream } from './DEFAULT_MAX_BUFFER-BDkqO5PW.mjs';
+import { SubscriptionRegistry } from './SubscriptionRegistry-B-Qx_Gux.mjs';
+
+const RPC_PATH = "/_lunora/rpc";
+const WS_PATH = "/_lunora/ws";
+const bucketQuery = (bucket) => bucket === void 0 || bucket === "" ? "" : `&bucket=${encodeURIComponent(bucket)}`;
+const WS_KEEPALIVE_PING = "lunora-ping";
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 3e4;
+const QUERY_CACHE_DEBOUNCE_MS = 250;
+const MAX_PENDING_STREAMS = 64;
+const SHARD_TRAFFIC_PATH = "/_lunora/admin/shard-traffic";
+const SCHEDULED_PATH = "/_lunora/admin/scheduled";
+const SCHEDULED_STATUS_PATH = "/_lunora/admin/scheduled/status";
+const SCHEDULED_WS_PATH = "/_lunora/admin/scheduled/ws";
+const SCHEDULED_CANCEL_PATH = "/_lunora/admin/scheduled/cancel";
+const SCHEDULED_DEAD_PATH = "/_lunora/admin/scheduled/dead";
+const SCHEDULED_DEAD_RETRY_PATH = "/_lunora/admin/scheduled/dead/retry";
+const SCHEDULED_DEAD_CANCEL_PATH = "/_lunora/admin/scheduled/dead/cancel";
+const WORKFLOWS_INSTANCES_PATH = "/_lunora/admin/workflows/instances";
+const WORKFLOWS_INSTANCE_PATH = "/_lunora/admin/workflows/instance";
+const WORKFLOWS_STATUS_PATH = "/_lunora/admin/workflows/status";
+const STORAGE_PATH = "/_lunora/admin/storage";
+const STORAGE_URL_PATH = "/_lunora/admin/storage/url";
+const STORAGE_BUCKETS_PATH = "/_lunora/admin/storage/buckets";
+const FUNCTIONS_PATH = "/_lunora/admin/functions";
+const CRON_JOBS_PATH = "/_lunora/admin/cron-jobs";
+const CRON_JOBS_RUN_PATH = "/_lunora/admin/cron-jobs/run";
+const OPENAPI_PATH = "/_lunora/admin/openapi";
+const OPENRPC_PATH = "/_lunora/admin/openrpc";
+const GLOBAL_TABLES_PATH = "/_lunora/admin/global/tables";
+const GLOBAL_TABLE_PATH = "/_lunora/admin/global/table";
+const GLOBAL_FACET_PATH = "/_lunora/admin/global/facet";
+const VECTOR_INDEXES_PATH = "/_lunora/admin/vector/indexes";
+const VECTOR_QUERY_PATH = "/_lunora/admin/vector/query";
+const AUTH_USERS_PATH = "/_lunora/admin/auth/users";
+const AUTH_SESSIONS_PATH = "/_lunora/admin/auth/sessions";
+const AUTH_CREATE_USER_PATH = "/_lunora/admin/auth/users/create";
+const AUTH_SET_ROLE_PATH = "/_lunora/admin/auth/users/role";
+const AUTH_BAN_PATH = "/_lunora/admin/auth/users/ban";
+const AUTH_UNBAN_PATH = "/_lunora/admin/auth/users/unban";
+const AUTH_SET_PASSWORD_PATH = "/_lunora/admin/auth/users/password";
+const AUTH_REMOVE_USER_PATH = "/_lunora/admin/auth/users/remove";
+const AUTH_IMPERSONATE_PATH = "/_lunora/admin/auth/users/impersonate";
+const AUTH_REVOKE_SESSION_PATH = "/_lunora/admin/auth/sessions/revoke";
+const AUTH_REVOKE_SESSIONS_PATH = "/_lunora/admin/auth/sessions/revoke-all";
+const AUTH_CAPABILITIES_PATH = "/_lunora/admin/auth/capabilities";
+const AUTH_UPDATE_USER_PATH = "/_lunora/admin/auth/users/update";
+const AUTH_ACCOUNTS_PATH = "/_lunora/admin/auth/accounts";
+const AUTH_UNLINK_ACCOUNT_PATH = "/_lunora/admin/auth/accounts/unlink";
+const AUTH_PASSKEYS_PATH = "/_lunora/admin/auth/passkeys";
+const AUTH_DELETE_PASSKEY_PATH = "/_lunora/admin/auth/passkeys/delete";
+const AUTH_DISABLE_2FA_PATH = "/_lunora/admin/auth/two-factor/disable";
+const AUTH_ORGS_PATH = "/_lunora/admin/auth/organizations";
+const AUTH_ORG_MEMBERS_PATH = "/_lunora/admin/auth/organizations/members";
+const AUTH_ORG_INVITATIONS_PATH = "/_lunora/admin/auth/organizations/invitations";
+const AUTH_REMOVE_MEMBER_PATH = "/_lunora/admin/auth/organizations/members/remove";
+const AUTH_CANCEL_INVITATION_PATH = "/_lunora/admin/auth/organizations/invitations/cancel";
+const DEFAULT_AUTH_BASE_PATH = "/api/auth";
+const GET_SESSION_PATH = "/get-session";
+const compareEntryKeys = ([a], [b]) => {
+  if (a < b) {
+    return -1;
+  }
+  return a > b ? 1 : 0;
+};
+const stableStringify = (value) => {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
+  }
+  const entries = Object.entries(value).toSorted(compareEntryKeys);
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
+};
+const deriveWsUrl = (url) => {
+  if (url.startsWith("https://")) {
+    return `wss://${url.slice("https://".length)}`;
+  }
+  if (url.startsWith("http://")) {
+    return `ws://${url.slice("http://".length)}`;
+  }
+  return url;
+};
+const joinUrl = (base, path) => {
+  const trimmed = base.endsWith("/") ? base.slice(0, -1) : base;
+  return `${trimmed}${path}`;
+};
+const withQuery = (path, params) => {
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== void 0 && value !== "") {
+      search.set(key, String(value));
+    }
+  }
+  const query = search.toString();
+  return query === "" ? path : `${path}?${query}`;
+};
+const connectionKey = (shardKey) => shardKey ?? "";
+const writeOptimisticToState = (state, next) => {
+  const previous = state.lastValue;
+  const versionAtApply = state.serverVersion;
+  state.lastValue = next;
+  for (const callback of state.callbacks) {
+    try {
+      callback(next);
+    } catch {
+    }
+  }
+  return () => {
+    if (state.serverVersion > versionAtApply) {
+      return;
+    }
+    if (state.lastValue !== next) {
+      return;
+    }
+    state.lastValue = previous;
+    for (const callback of state.callbacks) {
+      try {
+        callback(previous);
+      } catch {
+      }
+    }
+  };
+};
+const applyOptimisticToState = (state, optimistic) => {
+  let next;
+  try {
+    next = optimistic(state.lastValue);
+  } catch {
+    return void 0;
+  }
+  return writeOptimisticToState(state, next);
+};
+const buildStreamError = (message) => {
+  const errorEnvelope = message.error;
+  const code = typeof errorEnvelope?.code === "string" ? errorEnvelope.code : void 0;
+  const nestedMessage = typeof errorEnvelope?.message === "string" ? errorEnvelope.message : void 0;
+  const messageText = (typeof message.message === "string" ? message.message : void 0) ?? nestedMessage ?? "stream error";
+  return Object.assign(new Error(messageText), code === void 0 ? void 0 : { code });
+};
+const buildSubscriptionError = (message) => {
+  const errorEnvelope = message.error;
+  const code = typeof errorEnvelope?.code === "string" ? errorEnvelope.code : void 0;
+  const nestedMessage = typeof errorEnvelope?.message === "string" ? errorEnvelope.message : void 0;
+  const messageText = (typeof message.message === "string" ? message.message : void 0) ?? nestedMessage ?? "subscription error";
+  return { message: messageText, ...code === void 0 ? {} : { code } };
+};
+const sharedDecoder = new TextDecoder();
+const decodeServerFrame = (raw) => {
+  if (typeof raw === "string") {
+    return raw;
+  }
+  if (raw instanceof ArrayBuffer) {
+    return sharedDecoder.decode(raw);
+  }
+  return void 0;
+};
+const sendOn = (conn, message) => {
+  if (!conn.socket || conn.wsState !== "open") {
+    return false;
+  }
+  try {
+    conn.socket.send(JSON.stringify(message));
+    return true;
+  } catch {
+    return false;
+  }
+};
+class LunoraClient {
+  url;
+  wsUrl;
+  wsToken;
+  /** Better-auth base path (trailing slash stripped) for the `get-session` lookup. */
+  authBasePath;
+  fetchImpl;
+  WebSocketImpl;
+  bookmark;
+  reconnectOptions;
+  /** Keepalive cadence (ms); `0` disables the heartbeat. See {@link LunoraClientOptions.heartbeatIntervalMs}. */
+  heartbeatIntervalMs;
+  offlineQueue;
+  onPersistenceError;
+  persistence;
+  /** Durable read cache (Pillar 2); `undefined` when `queryCache` is omitted or `false`. */
+  queryCache;
+  /**
+   * Values restored from the `queryCache` at construction, keyed by the
+   * read-cache key, awaiting the `subscribe()` that will consume them. A
+   * key is consumed (deleted) the first time its subscription is created, so
+   * the cache only ever seeds the initial value — live frames take over after.
+   */
+  hydratedQueryCache = /* @__PURE__ */ new Map();
+  /**
+   * Coalesced read-cache writes: the latest value per key, flushed to
+   * the `queryCache` on a short debounce so a burst of deltas persists once.
+   */
+  pendingCacheWrites = /* @__PURE__ */ new Map();
+  cacheFlushTimer;
+  subscriptions = new SubscriptionRegistry();
+  /** One {@link ShardConnection} per shard key (keyed by `shardKey ?? ""`). */
+  connections = /* @__PURE__ */ new Map();
+  /** Default `connect`-envelope context applied to a shard with no explicit override. */
+  defaultConnectionContext;
+  /**
+   * Per-shard `connect`-envelope context registered via `setConnectionContext`
+   * (keyed by `shardKey ?? ""`), overriding `defaultConnectionContext`. Sent
+   * on every socket open so it replays across reconnects, and forwarded to the
+   * server's `onConnect`/`onDisconnect` lifecycle hooks. This holds only the
+   * imperative (last-writer-wins) override; refcounted holders registered via
+   * `acquireConnectionContext` live in `connectionContextHolders` and take
+   * precedence — see `effectiveConnectionContext`.
+   */
+  connectionContexts = /* @__PURE__ */ new Map();
+  /**
+   * Per-shard stack of refcounted connection-context holders (keyed by
+   * `shardKey ?? ""`), registered via `acquireConnectionContext`. Each holder
+   * is an opaque token carrying its `context`; the most-recently acquired
+   * holder wins (last-writer-wins among live holders), and the context is only
+   * cleared for a shard once its last holder releases — so two concurrently
+   * mounted presence hooks on the same shard can't stomp each other's context
+   * on cleanup. A holder is identified by reference identity so a release
+   * removes exactly the right one regardless of stack position.
+   */
+  connectionContextHolders = /* @__PURE__ */ new Map();
+  // `null` is the public sentinel for "signed out" across getAuthToken /
+  // setAuthToken / onAuthTokenChange — part of the exported API contract.
+  // eslint-disable-next-line unicorn/no-null -- public auth-token contract sentinel
+  authToken = null;
+  /**
+   * Identity stamp recorded against each queued offline mutation, keyed by
+   * the queue-assigned mutation id. Captured at enqueue from the auth token
+   * in effect at the time, and re-checked at flush so a queued write can
+   * never replay under a different identity than the one that issued it.
+   * See `identityFingerprint` for the fingerprint shape.
+   */
+  queuedIdentities = /* @__PURE__ */ new Map();
+  closed = false;
+  /** Subscribers to auth-token changes (see `onAuthTokenChange`). */
+  authTokenListeners = /* @__PURE__ */ new Set();
+  /** Subscribers to aggregate connection-status changes (see `onConnectionStatus`). */
+  statusListeners = /* @__PURE__ */ new Set();
+  /** Subscribers notified when the server drops a socket for an expired token (see `onTokenExpired`). */
+  tokenExpiredListeners = /* @__PURE__ */ new Set();
+  /**
+   * Whisper-topic handlers, keyed by `connectionKey(shardKey)` → topic → set
+   * of callbacks. Membership doubles as the resubscribe set replayed on every
+   * (re)connect so a topic survives a socket bounce.
+   */
+  whisperHandlers = /* @__PURE__ */ new Map();
+  /** Last status broadcast, so we only notify listeners on an actual change. */
+  lastStatus = "idle";
+  nextSubId = 0;
+  nextStreamId = 0;
+  /**
+   * In-flight client-side stream readers, keyed by the stream id sent on the
+   * wire. The handle drives the underlying iterator queue and `shardKey`
+   * tells us which socket to push the cancel frame onto when the consumer
+   * calls `.cancel()` or the iterator is garbage-collected.
+   */
+  streams = /* @__PURE__ */ new Map();
+  constructor(options) {
+    this.url = options.url;
+    this.wsUrl = options.wsUrl ?? joinUrl(deriveWsUrl(options.url), WS_PATH);
+    this.wsToken = options.wsToken;
+    const authBase = options.authBasePath ?? DEFAULT_AUTH_BASE_PATH;
+    this.authBasePath = authBase.endsWith("/") ? authBase.slice(0, -1) : authBase;
+    this.fetchImpl = options.fetch ?? (typeof fetch === "function" ? fetch.bind(globalThis) : void 0);
+    this.WebSocketImpl = options.WebSocket ?? (typeof WebSocket === "function" ? WebSocket : void 0);
+    this.bookmark = options.bookmarkStorage ?? createInMemoryBookmarkStorage();
+    this.reconnectOptions = options.reconnect;
+    this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    this.defaultConnectionContext = options.connectionContext;
+    this.persistence = options.persistence;
+    this.queryCache = options.queryCache === false ? void 0 : options.queryCache;
+    this.onPersistenceError = options.offlineQueue?.onPersistenceError;
+    this.offlineQueue = new OfflineQueue(options.offlineQueue, options.persistence);
+    if (this.persistence) {
+      queueMicrotask(() => {
+        this.hydratePersistedQueue().catch(() => void 0);
+      });
+    }
+    if (this.queryCache) {
+      queueMicrotask(() => {
+        this.hydrateQueryCache().catch(() => void 0);
+      });
+    }
+  }
+  // --- Auth helpers -------------------------------------------------------
+  /**
+   * Set (or clear) the bearer token sent on every HTTP RPC. Notifies any
+   * {@link onAuthTokenChange} listeners so React hooks like `useAuth` stay in
+   * sync across all mounted instances.
+   *
+   * Does NOT update the WebSocket auth — the WS token is fixed at upgrade
+   * time and lives in the URL. To refresh live WS auth, call
+   * {@link setWsToken} explicitly, which closes existing shard sockets to
+   * force a reconnect with the new credential.
+   */
+  setAuthToken(token) {
+    if (this.authToken === token) {
+      return;
+    }
+    this.authToken = token;
+    this.rejectQueuedForIdentityChange();
+    for (const listener of this.authTokenListeners) {
+      try {
+        listener(token);
+      } catch {
+      }
+    }
+  }
+  getAuthToken() {
+    return this.authToken;
+  }
+  /**
+   * Subscribe to auth-token changes. Returns an unsubscribe function. The
+   * listener is NOT invoked on registration — use {@link getAuthToken} for
+   * the current value.
+   */
+  onAuthTokenChange(listener) {
+    this.authTokenListeners.add(listener);
+    return () => {
+      this.authTokenListeners.delete(listener);
+    };
+  }
+  /**
+   * Fetch the currently authenticated user from better-auth's `get-session`
+   * endpoint, returning the `user` record or `null` when signed out. Sends
+   * the stored bearer token (if any) and `credentials: "include"` so a
+   * cookie-session is also honoured. A network/parse failure or a non-OK
+   * response resolves to `null` rather than throwing — callers treat "couldn't
+   * resolve identity" as "signed out".
+   *
+   * Framework-agnostic: pair it with {@link onAuthTokenChange} to refetch when
+   * the token changes (that's what `@lunora/react`'s `useAuth` does).
+   */
+  async getCurrentUser() {
+    if (this.closed || !this.fetchImpl) {
+      return null;
+    }
+    const headers = {};
+    if (this.authToken) {
+      headers["authorization"] = `Bearer ${this.authToken}`;
+    }
+    try {
+      const response = await this.fetchImpl(joinUrl(this.url, `${this.authBasePath}${GET_SESSION_PATH}`), {
+        credentials: "include",
+        headers,
+        method: "GET"
+      });
+      if (!response.ok) {
+        return null;
+      }
+      const body = await response.json();
+      return body?.user ?? null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Replace the token appended to WS upgrade URLs as `?token=…` and close
+   * every open shard socket so the reconnect picks up the new value. Call
+   * this whenever the user's WS credential changes (rotating the admin token
+   * in the studio, switching workspaces, etc.). Bearer tokens for HTTP
+   * RPC are independent — see {@link setAuthToken}.
+   */
+  setWsToken(token) {
+    if (this.wsToken === token) {
+      return;
+    }
+    this.wsToken = token;
+    for (const conn of this.connections.values()) {
+      if (conn.socket) {
+        try {
+          conn.socket.close();
+        } catch {
+        }
+      }
+    }
+  }
+  /**
+   * Register (or clear, with `undefined`) the app context sent in the `connect`
+   * envelope for a shard's socket, overriding the client-wide
+   * {@link LunoraClientOptions.connectionContext}. The server forwards it to the
+   * `onConnect`/`onDisconnect` lifecycle hooks as `event.context` — e.g.
+   * `@lunora/react`'s `usePresence` registers `{ roomId, sessionId }` so the
+   * presence row is removed the instant the socket drops, with no TTL lag.
+   *
+   * Stored per shard and replayed on every (re)connect. When a socket for the
+   * shard is already open, a fresh `connect` envelope is sent immediately so the
+   * server sees the new context without waiting for a reconnect.
+   */
+  setConnectionContext(context, options = {}) {
+    const key = connectionKey(options.shardKey);
+    if (context === void 0) {
+      this.connectionContexts.delete(key);
+    } else {
+      this.connectionContexts.set(key, context);
+    }
+    this.refreshConnectionContext(key);
+  }
+  /**
+   * Refcounted variant of {@link setConnectionContext}: register a connection
+   * `context` for a shard and get back a release function. Unlike the imperative
+   * setter, the context is only cleared once the *last* acquired holder releases
+   * it — so two components (e.g. two mounted `usePresence` hooks) on the same
+   * shard no longer clobber each other's context when one of them unmounts. The
+   * most-recently acquired live holder wins (last-writer-wins), and releasing
+   * the top holder falls back to the previous one rather than clearing.
+   *
+   * With a single holder the behaviour is identical to a
+   * `setConnectionContext(context)` / `setConnectionContext(undefined)` pair.
+   * Releasing more than once is a no-op (the holder is matched by reference, so
+   * a double release can't drop a different holder).
+   */
+  acquireConnectionContext(context, options = {}) {
+    const key = connectionKey(options.shardKey);
+    const holder = { context };
+    const holders = this.connectionContextHolders.get(key);
+    if (holders) {
+      holders.push(holder);
+    } else {
+      this.connectionContextHolders.set(key, [holder]);
+    }
+    this.refreshConnectionContext(key);
+    let released = false;
+    return () => {
+      if (released) {
+        return;
+      }
+      released = true;
+      const live = this.connectionContextHolders.get(key);
+      if (!live) {
+        return;
+      }
+      const index = live.indexOf(holder);
+      if (index !== -1) {
+        live.splice(index, 1);
+      }
+      if (live.length === 0) {
+        this.connectionContextHolders.delete(key);
+      }
+      this.refreshConnectionContext(key);
+    };
+  }
+  // --- Whispering ---------------------------------------------------------
+  /**
+   * Join a whisper `topic` and receive every ephemeral message other members
+   * broadcast to it on the same shard (typing indicators, live cursors,
+   * presence pings). Whispers never touch the server's durable state — there's
+   * no query, no row, no CDC entry. Returns an unsubscribe function; the topic
+   * is left on the server once its last local handler unsubscribes.
+   *
+   * `handler` receives the raw `data` and the sender's verified `from` user id
+   * (omitted for an anonymous sender). The topic is scoped to `options.shardKey`
+   * (the default shard when omitted) — use the same shard you target with the
+   * matching queries/mutations so members land on the same Durable Object.
+   *
+   * Security: whisper topics are NOT access-controlled beyond the shard
+   * boundary — any client that can open a socket to the shard can join, read,
+   * and inject on any topic name. `from` is server-stamped and unforgeable, but
+   * do not put data on a whisper topic that some shard members shouldn't see,
+   * and don't trust a whisper's `data` as authorization. Use a query/mutation
+   * (with RLS) for anything privileged; whispers are for transient awareness.
+   */
+  whisperSubscribe(topic, handler, options = {}) {
+    const key = connectionKey(options.shardKey);
+    let byTopic = this.whisperHandlers.get(key);
+    if (!byTopic) {
+      byTopic = /* @__PURE__ */ new Map();
+      this.whisperHandlers.set(key, byTopic);
+    }
+    let handlers = byTopic.get(topic);
+    const first = handlers === void 0;
+    if (!handlers) {
+      handlers = /* @__PURE__ */ new Set();
+      byTopic.set(topic, handlers);
+    }
+    handlers.add(handler);
+    this.ensureSocket(options.shardKey);
+    if (first) {
+      const conn = this.getConnection(options.shardKey);
+      if (conn) {
+        sendOn(conn, { topic, type: "whisper_subscribe" });
+      }
+    }
+    return () => {
+      const stillByTopic = this.whisperHandlers.get(key);
+      const stillHandlers = stillByTopic?.get(topic);
+      if (!stillHandlers?.delete(handler) || stillHandlers.size > 0) {
+        return;
+      }
+      stillByTopic?.delete(topic);
+      if (stillByTopic?.size === 0) {
+        this.whisperHandlers.delete(key);
+      }
+      const conn = this.getConnection(options.shardKey);
+      if (conn) {
+        sendOn(conn, { topic, type: "whisper_unsubscribe" });
+      }
+    };
+  }
+  /**
+   * Broadcast an ephemeral `data` payload to the other members of a whisper
+   * `topic` on `options.shardKey`'s shard. Fire-and-forget: the frame is
+   * dropped when the shard socket isn't open (whispers are transient, never
+   * queued), and the server silently drops it if the sender exceeds its
+   * whisper rate budget. The sender never receives its own whisper. Omitting
+   * `data` delivers JSON `null` to receivers (not `undefined`).
+   */
+  whisper(topic, data, options = {}) {
+    this.ensureSocket(options.shardKey);
+    const conn = this.getConnection(options.shardKey);
+    if (conn) {
+      sendOn(conn, { data, topic, type: "whisper" });
+    }
+  }
+  /**
+   * Subscribe to token-expiry events: invoked whenever the server drops a
+   * shard socket because the connection's credential lapsed (close code
+   * `4001`). The client already reconnects automatically (re-resolving
+   * identity from the cookie/token in effect); use this to refresh a
+   * short-lived token first — e.g. call {@link setWsToken} / {@link setAuthToken}
+   * with a freshly minted one. Returns an unsubscribe function.
+   */
+  onTokenExpired(listener) {
+    this.tokenExpiredListeners.add(listener);
+    return () => {
+      this.tokenExpiredListeners.delete(listener);
+    };
+  }
+  // --- Connection status --------------------------------------------------
+  /**
+   * Current aggregate live-socket status across all shard connections. See
+   * {@link ConnectionStatus}.
+   */
+  connectionStatus() {
+    return this.computeStatus();
+  }
+  /**
+   * Subscribe to aggregate connection-status changes. Invokes `listener`
+   * immediately with the current status, then on every transition. Returns an
+   * unsubscribe function.
+   */
+  onConnectionStatus(listener) {
+    this.statusListeners.add(listener);
+    listener(this.computeStatus());
+    return () => {
+      this.statusListeners.delete(listener);
+    };
+  }
+  // --- RPC ---------------------------------------------------------------
+  async query(function_, args, options = {}) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    return await this.rpc(function_.__lunoraRef, args, options.shardKey, { attachBookmark: true });
+  }
+  /**
+   * Invoke a mutation. Errors propagate as rejections.
+   *
+   * Offline-queue semantics: a mutation is queued (and replayed on reconnect)
+   * only when the targeted shard's socket was open at least once already
+   * (`wasEverConnected`), so the registry / resubscribe handshake has run.
+   * Mutations issued before the very first WS connect to a shard fail fast.
+   * Opt into queueing-before-first-connect via
+   * `OfflineQueueOptions.queueBeforeFirstConnect`.
+   */
+  async mutation(function_, args, options = {}) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const argsRecord = args;
+    const mutationId = nextId();
+    const optimisticRollbacks = this.applyOptimisticUpdates(function_.__lunoraRef, argsRecord, options.shardKey, options.optimistic);
+    if (options.optimisticUpdate) {
+      this.applyOptimisticUpdate(options.optimisticUpdate, args, options.shardKey, optimisticRollbacks);
+    }
+    const conn = this.getConnection(options.shardKey);
+    const wsState = conn?.wsState ?? "idle";
+    const hasSocket = conn?.socket !== void 0;
+    const wasEverConnected = conn?.wasEverConnected ?? false;
+    const { queueBeforeFirstConnect } = this.offlineQueue;
+    const connectedGate = wasEverConnected || queueBeforeFirstConnect;
+    const shouldQueueOffline = this.WebSocketImpl !== void 0 && connectedGate;
+    const midReconnect = wsState === "connecting" && connectedGate;
+    if (wsState !== "open" && !hasSocket && shouldQueueOffline || midReconnect) {
+      const issuingIdentity = this.identityFingerprint();
+      return new Promise((resolve, reject) => {
+        const entry = {
+          args: argsRecord,
+          functionPath: function_.__lunoraRef,
+          // Reuse the call's idempotency key as the queue id so the
+          // replay carries the same `x-lunora-mutation-id` the server
+          // dedups on.
+          id: mutationId,
+          // Persist the stamp alongside the record so a hydrated write
+          // can only replay under the identity that queued it.
+          identity: issuingIdentity,
+          reject: (error) => {
+            this.queuedIdentities.delete(mutationId);
+            for (let index = optimisticRollbacks.length - 1; index >= 0; index -= 1) {
+              optimisticRollbacks[index]?.();
+            }
+            reject(error instanceof Error ? error : new Error(String(error)));
+          },
+          resolve,
+          shardKey: options.shardKey
+        };
+        this.offlineQueue.enqueue(entry);
+        if (entry.id !== void 0) {
+          this.queuedIdentities.set(entry.id, issuingIdentity);
+        }
+      });
+    }
+    try {
+      return await this.rpc(function_.__lunoraRef, argsRecord, options.shardKey, { captureBookmark: true, mutationId });
+    } catch (error) {
+      for (let index = optimisticRollbacks.length - 1; index >= 0; index -= 1) {
+        optimisticRollbacks[index]?.();
+      }
+      throw error;
+    }
+  }
+  async action(function_, args, options = {}) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    return await this.rpc(function_.__lunoraRef, args, options.shardKey);
+  }
+  // --- Advisor admin ------------------------------------------------------
+  /**
+   * Read the cross-shard request distribution for a `.shardBy(...)` table —
+   * the feed the studio's `hot_shard` advisor lint consumes. Hits the
+   * admin-gated `POST /_lunora/admin/shard-traffic` endpoint, which fans the
+   * cheap per-shard `getMetrics` read out across every live shard and returns
+   * each shard's `{ shardKey, requests }` total (a failed shard surfaces with
+   * `requests: 0`). Requires the worker to be built with a `queryCoordinator`
+   * and `adminToken`, and this client's auth token to match; defaults any
+   * absent field so an older worker yields an empty-but-valid shape.
+   */
+  async shardTraffic(table) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const body = await this.adminFetch(SHARD_TRAFFIC_PATH, "POST", { table });
+    return { failed: body.failed ?? 0, ok: body.ok ?? 0, shards: body.shards ?? [] };
+  }
+  // --- Scheduler admin ----------------------------------------------------
+  /**
+   * List the functions queued via `runAfter` / `runAt`, soonest-due last
+   * (the worker returns them in storage order). Hits the admin-gated
+   * `/_lunora/admin/scheduled` endpoint, so the worker must be built with a
+   * `schedulerDO` namespace and `adminToken`, and this client's auth token
+   * must match. Powers `@lunora/studio`'s scheduled-jobs panel.
+   */
+  async listScheduledJobs() {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const body = await this.adminFetch(SCHEDULED_PATH, "GET");
+    return body.records ?? [];
+  }
+  /**
+   * Read the app-level workpool backlog that powers `@lunora/studio`'s SLO
+   * view: per-pool `{ name, queued, inFlight, maxConcurrency }` plus the
+   * app-wide `backlog` (total queued) and `inFlight` (total held slots) sums.
+   * Hits the admin-gated `GET /_lunora/admin/scheduled/status` endpoint, so the
+   * same preconditions as {@link listScheduledJobs} apply (a `schedulerDO`
+   * namespace + `adminToken` on the worker and a matching auth token here).
+   * Defaults any absent field so an older worker still yields a valid shape.
+   */
+  async schedulerStatus() {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const body = await this.adminFetch(SCHEDULED_STATUS_PATH, "GET");
+    return {
+      backlog: body.backlog ?? 0,
+      inFlight: body.inFlight ?? 0,
+      pools: body.pools ?? []
+    };
+  }
+  /** Cancel a pending scheduled job by id. Returns whether a job was removed. */
+  async cancelScheduledJob(id) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const body = await this.adminFetch(SCHEDULED_CANCEL_PATH, "POST", { id });
+    return { cancelled: body.cancelled === true };
+  }
+  /**
+   * List the dead-letter jobs: schedules that exhausted their retry budget
+   * and were parked instead of dropped. These never appear in
+   * {@link listScheduledJobs} (their live header is gone), so this is the only
+   * way the studio surfaces a permanently-failed job. Hits the admin-gated
+   * `GET /_lunora/admin/scheduled/dead`; same preconditions as
+   * {@link listScheduledJobs}. Powers `@lunora/studio`'s dead-letter panel.
+   */
+  async listDeadJobs() {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const body = await this.adminFetch(SCHEDULED_DEAD_PATH, "GET");
+    return body.records ?? [];
+  }
+  /**
+   * Resurrect a dead-letter job by id: it re-enters the schedule with a fresh
+   * retry budget and fires on the next drain. Returns whether a parked record
+   * matched. Hits the admin-gated `POST /_lunora/admin/scheduled/dead/retry`.
+   */
+  async retryDeadJob(id) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const body = await this.adminFetch(SCHEDULED_DEAD_RETRY_PATH, "POST", { id });
+    return { retried: body.retried === true };
+  }
+  /**
+   * Permanently drop a dead-letter job by id (the operator has decided not to
+   * recover it). Returns whether a parked record was removed. Hits the
+   * admin-gated `POST /_lunora/admin/scheduled/dead/cancel`.
+   */
+  async removeDeadJob(id) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const body = await this.adminFetch(SCHEDULED_DEAD_CANCEL_PATH, "POST", { id });
+    return { removed: body.removed === true };
+  }
+  /**
+   * List a workflow's instances via the admin Workflows proxy
+   * (`/_lunora/admin/workflows/instances`) — the Cloudflare control-plane data
+   * the `Workflow` binding can't expose. Requires the worker to be built with a
+   * `workflowsClient` (Cloudflare account id + API token); otherwise the proxy
+   * responds 501 and this rejects. `name` is the deployed workflow name.
+   */
+  async listWorkflowInstances(options) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const query = new URLSearchParams({ name: options.name });
+    if (options.status !== void 0) {
+      query.set("status", options.status);
+    }
+    if (options.page !== void 0) {
+      query.set("page", String(options.page));
+    }
+    if (options.perPage !== void 0) {
+      query.set("perPage", String(options.perPage));
+    }
+    const body = await this.adminFetch(`${WORKFLOWS_INSTANCES_PATH}?${query.toString()}`, "GET");
+    return { instances: body.instances ?? [], page: body.page ?? 1, perPage: body.perPage ?? options.perPage ?? 0, totalCount: body.totalCount };
+  }
+  /** Read one workflow instance with its step timeline (`/_lunora/admin/workflows/instance`). */
+  async getWorkflowInstance(options) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const query = new URLSearchParams({ id: options.id, name: options.name });
+    const body = await this.adminFetch(`${WORKFLOWS_INSTANCE_PATH}?${query.toString()}`, "GET");
+    return {
+      createdOn: body.createdOn,
+      endedOn: body.endedOn,
+      error: body.error,
+      id: body.id ?? options.id,
+      output: body.output,
+      params: body.params,
+      startedOn: body.startedOn,
+      status: body.status ?? "unknown",
+      steps: body.steps ?? []
+    };
+  }
+  /** Pause / resume / terminate a workflow instance (`/_lunora/admin/workflows/status`). Needs an Edit-scoped Cloudflare token. */
+  async setWorkflowInstanceStatus(options) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const body = await this.adminFetch(WORKFLOWS_STATUS_PATH, "POST", { action: options.action, id: options.id, name: options.name });
+    return { status: body.status ?? "unknown" };
+  }
+  /**
+   * Subscribe to the live scheduled-jobs list over the SchedulerDO's admin
+   * WebSocket. `onJobs` fires with the full list on connect and on every
+   * change (schedule / cancel / alarm-fire). Reconnects with the client's
+   * configured backoff. Requires `wsToken` to be set to the admin token (the
+   * browser can't send an `Authorization` header on a WS). Returns an
+   * unsubscribe function that closes the socket and stops reconnecting.
+   */
+  subscribeScheduledJobs(onJobs) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    if (this.WebSocketImpl === void 0) {
+      return () => void 0;
+    }
+    const base = joinUrl(deriveWsUrl(this.url), SCHEDULED_WS_PATH);
+    const reconnect = createReconnect(this.reconnectOptions);
+    let socket;
+    let timer;
+    let closed = false;
+    const connect = () => {
+      if (closed || this.WebSocketImpl === void 0) {
+        return;
+      }
+      const url = this.wsToken === void 0 ? base : `${base}?token=${encodeURIComponent(this.wsToken)}`;
+      socket = new this.WebSocketImpl(url);
+      socket.addEventListener("open", () => {
+        reconnect.reset();
+      });
+      socket.addEventListener("message", (event) => {
+        try {
+          const message = JSON.parse(typeof event.data === "string" ? event.data : "");
+          if (message.type === "jobs" && Array.isArray(message.records)) {
+            onJobs(message.records);
+          }
+        } catch {
+        }
+      });
+      socket.addEventListener("close", () => {
+        socket = void 0;
+        if (!closed) {
+          timer = setTimeout(connect, reconnect.next());
+        }
+      });
+      socket.addEventListener("error", () => {
+      });
+    };
+    connect();
+    return () => {
+      closed = true;
+      if (timer !== void 0) {
+        clearTimeout(timer);
+      }
+      socket?.close();
+    };
+  }
+  // --- Functions admin ----------------------------------------------------
+  /**
+   * List the registered public functions (queries / mutations / actions) with
+   * their kinds. Hits the admin-gated `GET /_lunora/admin/functions` endpoint —
+   * the worker must be built with a `functions` registry and `adminToken`, and
+   * this client's auth token must match. Powers `@lunora/studio`'s function
+   * runner auto-discovery.
+   */
+  async listFunctions() {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const body = await this.adminFetch(FUNCTIONS_PATH, "GET");
+    return body.functions ?? [];
+  }
+  /**
+   * List the code-defined cron triggers (the `cronJobs()` map injected on the
+   * worker), each flattened to its firing `cron` expression. Hits the
+   * admin-gated `GET /_lunora/admin/cron-jobs` endpoint — the worker must be
+   * built with a `cronJobs` map and `adminToken`, and this client's auth token
+   * must match. These are static (Cloudflare exposes no runtime cron
+   * introspection), so the studio renders them read-only alongside the dynamic
+   * scheduler jobs.
+   */
+  async getCronJobs() {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const body = await this.adminFetch(CRON_JOBS_PATH, "GET");
+    return body.jobs ?? [];
+  }
+  /**
+   * Manually fire one code-defined cron job by name — the same dispatch the
+   * scheduled trigger runs (dispatch the function, or start the durable
+   * workflow), on demand. Hits the admin-gated `POST /_lunora/admin/cron-jobs/run`
+   * endpoint; the worker must be built with a `cronJobs` map and `adminToken`,
+   * and this client's auth token must match. Resolves when the job has run (a
+   * function job's shard response is 2xx, or the workflow instance was created)
+   * and rejects with the dispatch error otherwise.
+   */
+  async runCronJob(name) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const body = await this.adminFetch(CRON_JOBS_RUN_PATH, "POST", { name });
+    return { name: body.name ?? name, ran: body.ran === true };
+  }
+  /**
+   * Fetch the generated OpenAPI 3.1 document. Hits the admin-gated
+   * `GET /_lunora/admin/openapi` endpoint — the worker must be built with an
+   * `openApiSpec` and `adminToken`, and this client's auth token must match.
+   * Powers `@lunora/studio`'s API-reference (Scalar) view. When the worker has
+   * no spec wired, the endpoint still resolves with an empty-but-valid OpenAPI
+   * document (no `paths`), so callers can render a "not configured" state.
+   */
+  async fetchOpenApi() {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    return await this.adminFetch(OPENAPI_PATH, "GET");
+  }
+  /**
+   * Fetch the generated OpenRPC 1.x document. Hits the admin-gated
+   * `GET /_lunora/admin/openrpc` endpoint — the worker must be built with an
+   * `openRpcSpec` and `adminToken`, and this client's auth token must match.
+   * OpenRPC is the RPC-native spec (a `methods` array over the JSON-RPC-shaped
+   * `POST /_lunora/rpc` transport); it documents the RPC functions only.
+   * Powers `@lunora/studio`'s OpenRPC API-reference view. When the worker has
+   * no spec wired, the endpoint still resolves with an empty-but-valid OpenRPC
+   * document (no `methods`), so callers can render a "not configured" state.
+   */
+  async fetchOpenRpc() {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    return await this.adminFetch(OPENRPC_PATH, "GET");
+  }
+  // --- Storage admin ------------------------------------------------------
+  /**
+   * List objects in the storage bucket, optionally under a `prefix` and from a
+   * pagination `cursor`. Hits the admin-gated `GET /_lunora/admin/storage`
+   * endpoint — the worker must be built with a `storageList` function and
+   * `adminToken`, and this client's auth token must match. Powers
+   * `@lunora/studio`'s file browser.
+   */
+  async listStorageObjects(options = {}) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const params = new URLSearchParams();
+    if (options.prefix !== void 0 && options.prefix !== "") {
+      params.set("prefix", options.prefix);
+    }
+    if (options.cursor !== void 0 && options.cursor !== "") {
+      params.set("cursor", options.cursor);
+    }
+    if (options.limit !== void 0) {
+      params.set("limit", String(options.limit));
+    }
+    if (options.bucket !== void 0 && options.bucket !== "") {
+      params.set("bucket", options.bucket);
+    }
+    const query = params.toString();
+    const path = query === "" ? STORAGE_PATH : `${STORAGE_PATH}?${query}`;
+    const body = await this.adminFetch(path, "GET");
+    return { cursor: body.cursor, objects: body.objects ?? [] };
+  }
+  /**
+   * Delete one object from the storage bucket by key. Hits the admin-gated
+   * `DELETE /_lunora/admin/storage?key=…` endpoint — the worker must be built
+   * with a `storageDelete` function and `adminToken`. Powers the studio file
+   * browser's per-row delete; resolves `{ deleted, key }`.
+   */
+  async deleteStorageObject(key, options) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const path = `${STORAGE_PATH}?key=${encodeURIComponent(key)}${bucketQuery(options?.bucket)}`;
+    const body = await this.adminFetch(path, "DELETE");
+    return { deleted: body.deleted ?? true, key: body.key ?? key };
+  }
+  /**
+   * List the storage bucket names the worker exposes, for the studio file
+   * browser's bucket picker. Hits the admin-gated
+   * `GET /_lunora/admin/storage/buckets` endpoint — always resolves (an empty
+   * array when the worker configures no `storageBuckets`, i.e. single-bucket).
+   */
+  async listStorageBuckets() {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const body = await this.adminFetch(STORAGE_BUCKETS_PATH, "GET");
+    return body.buckets ?? [];
+  }
+  /**
+   * Upload one object to the storage bucket. Hits the admin-gated
+   * `PUT /_lunora/admin/storage?key=…` endpoint with the raw body and an
+   * optional `contentType` header — the worker must be built with a
+   * `storageUpload` function and `adminToken`. Powers the studio file
+   * browser's upload control; resolves `{ etag?, key }`.
+   */
+  async uploadStorageObject(options) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const path = `${STORAGE_PATH}?key=${encodeURIComponent(options.key)}${bucketQuery(options.bucket)}`;
+    const body = await this.adminFetch(path, "PUT", options.body, options.contentType);
+    return { etag: body.etag, key: body.key ?? options.key };
+  }
+  /**
+   * Build a (signed or public) URL for one object. Hits the admin-gated
+   * `GET /_lunora/admin/storage/url?key=…` endpoint — the worker must be built
+   * with a `storageSignedUrl` function and `adminToken`. Powers the studio
+   * file browser's copy-URL action; resolves the URL string.
+   *
+   * `options.expiresInSeconds` requests a share-link lifetime, which is
+   * validated/clamped server-side. The options object mirrors the worker's
+   * `StorageSignedUrlFunction` options (a `password` / download-limit are noted
+   * as future fields there).
+   */
+  async signedStorageUrl(key, options) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const expiresInSeconds = options?.expiresInSeconds;
+    const expiryQuery = expiresInSeconds === void 0 ? "" : `&expiresIn=${encodeURIComponent(expiresInSeconds.toString())}`;
+    const path = `${STORAGE_URL_PATH}?key=${encodeURIComponent(key)}${expiryQuery}${bucketQuery(options?.bucket)}`;
+    const body = await this.adminFetch(path, "GET");
+    if (typeof body.url !== "string") {
+      throw new TypeError("LunoraClient: storage URL endpoint returned no `url`");
+    }
+    return body.url;
+  }
+  // --- Global (D1) tables admin -------------------------------------------
+  /**
+   * List the `.global()` (D1-backed) tables with their row counts. Hits the
+   * admin-gated `GET /_lunora/admin/global/tables` endpoint — the worker must
+   * be built with a `globalIntrospector` and `adminToken`. Powers the data
+   * browser's global mode.
+   */
+  async listGlobalTables() {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    return await this.adminFetch(GLOBAL_TABLES_PATH, "GET");
+  }
+  /**
+   * Read a page of rows from one `.global()` table. `filters` AND-narrows the
+   * page to rows matching each `column = value` eq constraint — the drill-down a
+   * facet-value click applies; the array is JSON-encoded into the `filters`
+   * query param and the values are bound server-side.
+   */
+  async readGlobalTablePage(options) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const params = new URLSearchParams({ table: options.table });
+    if (options.limit !== void 0) {
+      params.set("limit", String(options.limit));
+    }
+    if (options.offset !== void 0) {
+      params.set("offset", String(options.offset));
+    }
+    if (options.filters !== void 0 && options.filters.length > 0) {
+      params.set("filters", JSON.stringify(options.filters));
+    }
+    return await this.adminFetch(`${GLOBAL_TABLE_PATH}?${params.toString()}`, "GET");
+  }
+  /**
+   * Summarise the distinct values of one column in a `.global()` table over the
+   * active view (the same eq `filters` the browser is previewing) — the global
+   * twin of the shard browser's facet. Hits the admin-gated
+   * `GET /_lunora/admin/global/facet` endpoint; `column` is validated + bound
+   * server-side. Powers the global data browser's facet sidebar.
+   */
+  async facetGlobalColumn(options) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const params = new URLSearchParams({ column: options.column, table: options.table });
+    if (options.limit !== void 0) {
+      params.set("limit", String(options.limit));
+    }
+    if (options.filters !== void 0 && options.filters.length > 0) {
+      params.set("filters", JSON.stringify(options.filters));
+    }
+    return await this.adminFetch(`${GLOBAL_FACET_PATH}?${params.toString()}`, "GET");
+  }
+  // --- Vector indexes admin -----------------------------------------------
+  /**
+   * List the schema's Vectorize indexes with their declared shape (table,
+   * field, dimensions, metric, metadata) and live stats (vector count,
+   * processing watermark) when the binding is reachable. Hits the admin-gated
+   * `GET /_lunora/admin/vector/indexes` endpoint — the worker must be built
+   * with a `vectorIntrospector` and `adminToken`. Powers the studio's vector
+   * browser. Vectorize can't enumerate indexes at runtime, so this list comes
+   * from the generated `LUNORA_VECTOR_INDEXES` registry.
+   */
+  async listVectorIndexes() {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const body = await this.adminFetch(VECTOR_INDEXES_PATH, "GET");
+    return body.indexes ?? [];
+  }
+  /**
+   * Run a nearest-neighbour similarity query against one vector index: the
+   * worker embeds `text` via the index's embedder and returns the top matches.
+   * Hits the admin-gated `POST /_lunora/admin/vector/query` endpoint. Throws
+   * `VECTOR_QUERY_UNSUPPORTED` when the worker's introspector has no embedder
+   * wired (the index lists read-only).
+   */
+  async queryVectorIndex(options) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const body = await this.adminFetch(VECTOR_QUERY_PATH, "POST", options);
+    return body.matches ?? [];
+  }
+  // --- Auth admin ---------------------------------------------------------
+  /**
+   * List authenticated users, paged and optionally searched / filtered / sorted.
+   * Hits the admin-gated `GET /_lunora/admin/auth/users` endpoint — the worker
+   * must be built with an `authAdmin` and `adminToken`. Powers the studio's
+   * users dashboard.
+   */
+  async listAuthUsers(options = {}) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const path = withQuery(AUTH_USERS_PATH, {
+      filterField: options.filterField,
+      filterValue: options.filterValue,
+      limit: options.limit,
+      offset: options.offset,
+      search: options.search,
+      searchField: options.searchField,
+      sortBy: options.sortBy,
+      sortDirection: options.sortDirection
+    });
+    return await this.adminFetch(path, "GET");
+  }
+  /**
+   * Create a user. Hits the admin-gated `POST /_lunora/admin/auth/users/create`
+   * endpoint (requires the worker's `authAdmin` to implement `createUser`).
+   * `data` carries any app-defined `user.additionalFields`.
+   */
+  async createAuthUser(input) {
+    return await this.adminFetch(AUTH_CREATE_USER_PATH, "POST", input);
+  }
+  /** Set a user's role (string, or array joined comma-wise server-side). */
+  async setAuthUserRole(input) {
+    return await this.adminFetch(AUTH_SET_ROLE_PATH, "POST", input);
+  }
+  /** Ban a user. `expiresInSeconds` sets a temporary ban; omit it for a permanent one. Revokes the user's live sessions. */
+  async banAuthUser(input) {
+    return await this.adminFetch(AUTH_BAN_PATH, "POST", input);
+  }
+  /** Lift a user's ban. */
+  async unbanAuthUser(input) {
+    return await this.adminFetch(AUTH_UNBAN_PATH, "POST", input);
+  }
+  /** Set a user's password (admin override — no current-password challenge). */
+  async setAuthUserPassword(input) {
+    await this.adminFetch(AUTH_SET_PASSWORD_PATH, "POST", input);
+  }
+  /** Permanently delete a user and revoke their sessions. */
+  async removeAuthUser(input) {
+    await this.adminFetch(AUTH_REMOVE_USER_PATH, "POST", input);
+  }
+  /**
+   * Mint an impersonation session for a user, returning its bearer `token`.
+   * The caller is responsible for using the token (e.g. setting the session
+   * cookie); the server performs no cookie round-trip.
+   */
+  async impersonateAuthUser(input) {
+    return await this.adminFetch(AUTH_IMPERSONATE_PATH, "POST", input);
+  }
+  /** Revoke a single session by its id (force sign-out of one device). */
+  async revokeAuthSession(input) {
+    await this.adminFetch(AUTH_REVOKE_SESSION_PATH, "POST", input);
+  }
+  /** Revoke every session for a user (force sign-out everywhere). */
+  async revokeAuthUserSessions(input) {
+    await this.adminFetch(AUTH_REVOKE_SESSIONS_PATH, "POST", input);
+  }
+  /**
+   * Report which auth dashboard surfaces are available — derived server-side
+   * from the enabled better-auth plugins. The studio renders only the panels
+   * whose capability is `true`.
+   */
+  async getAuthCapabilities() {
+    return await this.adminFetch(AUTH_CAPABILITIES_PATH, "GET");
+  }
+  /** Update a user's fields (name/email/app-defined `additionalFields`). */
+  async updateAuthUser(input) {
+    return await this.adminFetch(AUTH_UPDATE_USER_PATH, "POST", input);
+  }
+  /** List a user's linked accounts (credential / OAuth providers). Token material is stripped server-side. */
+  async listAuthAccounts(input) {
+    return await this.adminFetch(withQuery(AUTH_ACCOUNTS_PATH, { userId: input.userId }), "GET");
+  }
+  /** Unlink a linked account from a user. */
+  async unlinkAuthAccount(input) {
+    await this.adminFetch(AUTH_UNLINK_ACCOUNT_PATH, "POST", input);
+  }
+  /** List a user's registered passkeys (requires the passkey plugin). */
+  async listAuthPasskeys(input) {
+    return await this.adminFetch(withQuery(AUTH_PASSKEYS_PATH, { userId: input.userId }), "GET");
+  }
+  /** Delete a passkey by id (requires the passkey plugin). */
+  async deleteAuthPasskey(input) {
+    await this.adminFetch(AUTH_DELETE_PASSKEY_PATH, "POST", input);
+  }
+  /** Disable two-factor auth for a user (requires the two-factor plugin). */
+  async disableAuthTwoFactor(input) {
+    await this.adminFetch(AUTH_DISABLE_2FA_PATH, "POST", input);
+  }
+  /** List organizations, paged (requires the organization plugin). */
+  async listAuthOrganizations(options = {}) {
+    return await this.adminFetch(withQuery(AUTH_ORGS_PATH, { limit: options.limit, offset: options.offset }), "GET");
+  }
+  /** List the members of an organization (requires the organization plugin). */
+  async listAuthOrgMembers(input) {
+    const path = withQuery(AUTH_ORG_MEMBERS_PATH, { limit: input.limit, offset: input.offset, organizationId: input.organizationId });
+    return await this.adminFetch(path, "GET");
+  }
+  /** List an organization's pending invitations (requires the organization plugin). */
+  async listAuthOrgInvitations(input) {
+    const path = withQuery(AUTH_ORG_INVITATIONS_PATH, { limit: input.limit, offset: input.offset, organizationId: input.organizationId });
+    return await this.adminFetch(path, "GET");
+  }
+  /** Remove a member from an organization. */
+  async removeAuthOrgMember(input) {
+    await this.adminFetch(AUTH_REMOVE_MEMBER_PATH, "POST", input);
+  }
+  /** Cancel a pending organization invitation. */
+  async cancelAuthOrgInvitation(input) {
+    await this.adminFetch(AUTH_CANCEL_INVITATION_PATH, "POST", input);
+  }
+  /** List auth sessions, paged and optionally filtered to one user. */
+  async listAuthSessions(options = {}) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const params = new URLSearchParams();
+    if (options.userId !== void 0 && options.userId !== "") {
+      params.set("userId", options.userId);
+    }
+    if (options.limit !== void 0) {
+      params.set("limit", String(options.limit));
+    }
+    if (options.offset !== void 0) {
+      params.set("offset", String(options.offset));
+    }
+    const query = params.toString();
+    return await this.adminFetch(query === "" ? AUTH_SESSIONS_PATH : `${AUTH_SESSIONS_PATH}?${query}`, "GET");
+  }
+  // --- Subscriptions ------------------------------------------------------
+  subscribe(function_, args, callback, options = {}) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    const argsRecord = args ?? {};
+    const key = SubscriptionRegistry.key(function_.__lunoraRef, argsRecord, options.shardKey);
+    let state = this.subscriptions.get(key);
+    const subscriptionCallback = callback;
+    const errorCallback = options.onError;
+    if (!state) {
+      this.nextSubId += 1;
+      const id = `sub_${this.nextSubId.toString()}`;
+      const argsKey = stableStringify(argsRecord);
+      const cached = this.takeHydratedCache(function_.__lunoraRef, argsKey, options.shardKey);
+      state = {
+        acked: false,
+        args: argsRecord,
+        argsKey,
+        callbacks: /* @__PURE__ */ new Set(),
+        errorCallbacks: /* @__PURE__ */ new Set(),
+        fn: function_,
+        id,
+        lastValue: cached?.value,
+        serverCursor: cached?.serverCursor,
+        serverVersion: 0,
+        shardKey: options.shardKey,
+        ...cached?.serverEpoch === void 0 ? {} : { serverEpoch: cached.serverEpoch }
+      };
+      this.subscriptions.add(state);
+    }
+    state.callbacks.add(subscriptionCallback);
+    if (errorCallback) {
+      state.errorCallbacks.add(errorCallback);
+    }
+    if (state.lastValue !== void 0) {
+      try {
+        subscriptionCallback(state.lastValue);
+      } catch {
+      }
+    }
+    this.ensureSocket(options.shardKey);
+    this.sendSubscribeIfOpen(state);
+    const subscriptionState = state;
+    return () => {
+      subscriptionState.callbacks.delete(subscriptionCallback);
+      if (errorCallback) {
+        subscriptionState.errorCallbacks.delete(errorCallback);
+      }
+      if (subscriptionState.callbacks.size === 0) {
+        const conn = this.getConnection(subscriptionState.shardKey);
+        const ok = conn ? sendOn(conn, { id: subscriptionState.id, type: "unsubscribe" }) : false;
+        if (!ok && conn) {
+          conn.pendingUnsubscribes.push(subscriptionState.id);
+        }
+        this.subscriptions.remove(subscriptionState);
+      }
+    };
+  }
+  /**
+   * Open a streaming query. The function reference must be a
+   * `kind:"stream"` registration (built with `c.query.input(...).stream(...)`);
+   * the type constraint catches accidental use of a query/mutation/action
+   * reference at compile time. The returned iterable yields one element per
+   * chunk frame the server pushes, terminating when the server sends
+   * `complete` or the consumer calls `.cancel()`. Errors arrive as a
+   * rejection on the next `next()`.
+   *
+   * Streams ride the same WS as subscriptions and share the unsubscribe
+   * channel: cancelling sends `{type:"unsubscribe", id}` with the stream id,
+   * which the DO recognises as an abort signal for the in-flight iterator.
+   *
+   * Stream-start frames buffered while the socket is (re)connecting are
+   * capped at {@link MAX_PENDING_STREAMS} per connection — overflowing the
+   * cap drops the oldest queued frame (and fails its consumer) so a stuck
+   * reconnect can't OOM the page.
+   */
+  stream(function_, args, options = {}) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    if (this.WebSocketImpl === void 0) {
+      throw new Error("LunoraClient: streams require a WebSocket implementation");
+    }
+    this.nextStreamId += 1;
+    const id = `stream_${this.nextStreamId.toString()}`;
+    const { shardKey } = options;
+    const argsRecord = args ?? {};
+    const { handle, iterable } = createStream({
+      maxBuffer: options.maxBuffer,
+      onCancel: () => {
+        const conn2 = this.getConnection(shardKey);
+        if (conn2) {
+          sendOn(conn2, { id, type: "unsubscribe" });
+        }
+        this.streams.delete(id);
+      }
+    });
+    this.streams.set(id, { handle, shardKey });
+    this.ensureSocket(shardKey);
+    const conn = this.getConnection(shardKey);
+    const message = {
+      id,
+      query: { args: argsRecord, functionPath: function_.__lunoraRef, shardKey },
+      type: "stream"
+    };
+    const sentImmediately = conn?.wsState === "open" && sendOn(conn, message);
+    if (!sentImmediately && conn) {
+      conn.pendingStreams = conn.pendingStreams ?? [];
+      while (conn.pendingStreams.length >= MAX_PENDING_STREAMS) {
+        const dropped = conn.pendingStreams.shift();
+        const droppedId = dropped?.id;
+        const droppedStream = droppedId ? this.streams.get(droppedId) : void 0;
+        if (droppedStream) {
+          droppedStream.handle.fail(
+            Object.assign(new Error("stream-start frame evicted while socket was unreachable"), { code: "STREAM_QUEUE_OVERFLOW" })
+          );
+          this.streams.delete(droppedId);
+        }
+      }
+      conn.pendingStreams.push(message);
+    }
+    return iterable;
+  }
+  close() {
+    this.closed = true;
+    for (const stream of this.streams.values()) {
+      stream.handle.fail(Object.assign(new Error("LunoraClient closed"), { code: "CLIENT_CLOSED" }));
+    }
+    this.streams.clear();
+    for (const conn of this.connections.values()) {
+      if (conn.reconnectTimer !== void 0) {
+        clearTimeout(conn.reconnectTimer);
+        conn.reconnectTimer = void 0;
+      }
+      this.stopHeartbeat(conn);
+      if (conn.socket) {
+        try {
+          conn.socket.close();
+        } catch {
+        }
+        conn.socket = void 0;
+      }
+      conn.wsState = "closed";
+    }
+    this.offlineQueue.clear();
+    this.queuedIdentities.clear();
+    if (this.cacheFlushTimer !== void 0) {
+      clearTimeout(this.cacheFlushTimer);
+      this.cacheFlushTimer = void 0;
+    }
+    if (this.pendingCacheWrites.size > 0) {
+      this.flushQueryCacheWrites().catch(() => void 0);
+    }
+    this.authTokenListeners.clear();
+    this.statusListeners.clear();
+    this.tokenExpiredListeners.clear();
+    this.whisperHandlers.clear();
+  }
+  // --- Internals ----------------------------------------------------------
+  /**
+   * Restore offline mutations persisted in a prior session and open a socket
+   * for each shard they target so they flush once the WS reconnects. Failures
+   * are swallowed — a broken durable store must not stop the client booting.
+   */
+  async hydratePersistedQueue() {
+    try {
+      const shardKeys = await this.offlineQueue.hydrate();
+      for (const shardKey of shardKeys) {
+        this.ensureSocket(shardKey);
+      }
+    } catch {
+    }
+  }
+  /**
+   * Load every cached query into {@link hydratedQueryCache} so the next
+   * `subscribe()` for each key seeds its initial value off disk. A
+   * subscription created before this resolves simply misses the cache (it
+   * gets a live snapshot as before); the gate at seed time also drops any
+   * entry whose stamped identity no longer matches the current one.
+   */
+  async hydrateQueryCache() {
+    if (!this.queryCache) {
+      return;
+    }
+    try {
+      const entries = await this.queryCache.load();
+      for (const { key, ...entry } of entries) {
+        this.hydratedQueryCache.set(key, entry);
+      }
+    } catch {
+    }
+  }
+  /**
+   * Consume the hydrated read-cache entry for a key (if any), gated on
+   * identity. The entry is removed whether or not it matches — the cache only
+   * ever seeds a subscription's first value. A mismatch (the cache was written
+   * under a different identity) yields `undefined` so a signed-out cache never
+   * leaks into a new session.
+   */
+  takeHydratedCache(functionPath, argsKey, shardKey) {
+    const key = queryCacheKey(functionPath, argsKey, shardKey);
+    const entry = this.hydratedQueryCache.get(key);
+    if (entry === void 0) {
+      return void 0;
+    }
+    this.hydratedQueryCache.delete(key);
+    return entry.identity === this.identityFingerprint() ? entry : void 0;
+  }
+  /**
+   * Queue a coalesced read-cache write for a subscription's current value.
+   * Latest-wins per key; flushed on a short debounce so a delta burst writes
+   * once. No-op when the read cache is disabled or the value is undefined
+   * (nothing to render offline).
+   */
+  persistQueryValue(state) {
+    if (!this.queryCache || state.lastValue === void 0) {
+      return;
+    }
+    const key = queryCacheKey(state.fn.__lunoraRef, state.argsKey, state.shardKey);
+    this.pendingCacheWrites.set(key, {
+      identity: this.identityFingerprint(),
+      serverCursor: state.serverCursor,
+      ts: Date.now(),
+      value: state.lastValue,
+      ...state.serverEpoch === void 0 ? {} : { serverEpoch: state.serverEpoch }
+    });
+    this.cacheFlushTimer ??= setTimeout(() => {
+      this.flushQueryCacheWrites().catch(() => void 0);
+    }, QUERY_CACHE_DEBOUNCE_MS);
+  }
+  /** Drain {@link pendingCacheWrites} to the durable store. */
+  async flushQueryCacheWrites() {
+    this.cacheFlushTimer = void 0;
+    const { queryCache } = this;
+    if (!queryCache) {
+      this.pendingCacheWrites.clear();
+      return;
+    }
+    const batch = [...this.pendingCacheWrites.entries()];
+    this.pendingCacheWrites.clear();
+    await Promise.allSettled(batch.map(([key, entry]) => queryCache.put(key, entry)));
+  }
+  /** Derive the aggregate status from the per-shard socket states. */
+  computeStatus() {
+    const conns = [...this.connections.values()];
+    if (conns.length === 0) {
+      return "idle";
+    }
+    if (conns.some((conn) => conn.wsState === "open")) {
+      return "connected";
+    }
+    if (conns.some((conn) => conn.wsState === "connecting")) {
+      return "connecting";
+    }
+    return "offline";
+  }
+  /** Recompute the aggregate status and notify listeners if it changed. */
+  emitConnectionStatus() {
+    const next = this.computeStatus();
+    if (next === this.lastStatus) {
+      return;
+    }
+    this.lastStatus = next;
+    for (const listener of this.statusListeners) {
+      try {
+        listener(next);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Apply an optimistic update to every subscription that matches the
+   * mutation's function ref, shard key, and args, returning the rollback
+   * callbacks to invoke if the mutation later fails. Scoping to the same
+   * (fn, shardKey, args) keeps one user's mutation from clobbering another
+   * subscriber's value on the same function (e.g. two users on different rooms).
+   */
+  applyOptimisticUpdates(functionRef, argsRecord, mutationShardKey, optimistic) {
+    const optimisticRollbacks = [];
+    if (!optimistic) {
+      return optimisticRollbacks;
+    }
+    const mutationArgsKey = stableStringify(argsRecord);
+    for (const state of this.subscriptions.all()) {
+      if (state.fn.__lunoraRef !== functionRef || state.shardKey !== mutationShardKey || state.argsKey !== mutationArgsKey) {
+        continue;
+      }
+      const rollback = applyOptimisticToState(state, optimistic);
+      if (rollback) {
+        optimisticRollbacks.push(rollback);
+      }
+    }
+    return optimisticRollbacks;
+  }
+  /**
+   * Run a Convex-parity `optimisticUpdate` callback against a localStore bound
+   * to the live subscription registry, appending each `setQuery` write's
+   * rollback to `optimisticRollbacks` (the same LIFO list the legacy path uses,
+   * unwound on settle/error). A throwing callback unwinds its own partial
+   * writes — LIFO over just the rollbacks it produced — and is swallowed, so a
+   * buggy optimistic update can never fail the mutation or leave a partial
+   * patch live, mirroring the legacy transform's throw handling.
+   */
+  applyOptimisticUpdate(optimisticUpdate, args, shardKey, optimisticRollbacks) {
+    const { rollbacks, store } = createLocalStore(this.subscriptions, shardKey, writeOptimisticToState, stableStringify);
+    try {
+      optimisticUpdate(store, args);
+    } catch {
+      for (let index = rollbacks.length - 1; index >= 0; index -= 1) {
+        rollbacks[index]?.();
+      }
+      return;
+    }
+    optimisticRollbacks.push(...rollbacks);
+  }
+  getConnection(shardKey) {
+    return this.connections.get(connectionKey(shardKey));
+  }
+  getOrCreateConnection(shardKey) {
+    const key = connectionKey(shardKey);
+    let conn = this.connections.get(key);
+    if (!conn) {
+      conn = {
+        heartbeatTimer: void 0,
+        pendingUnsubscribes: [],
+        reconnect: createReconnect(this.reconnectOptions),
+        reconnectTimer: void 0,
+        shardKey,
+        socket: void 0,
+        wasEverConnected: false,
+        wsState: "idle"
+      };
+      this.connections.set(key, conn);
+    }
+    return conn;
+  }
+  wsUrlFor(shardKey) {
+    const params = [];
+    if (shardKey !== void 0) {
+      params.push(`shard=${encodeURIComponent(shardKey)}`);
+    }
+    if (this.wsToken !== void 0) {
+      params.push(`token=${encodeURIComponent(this.wsToken)}`);
+    }
+    if (params.length === 0) {
+      return this.wsUrl;
+    }
+    const separator = this.wsUrl.includes("?") ? "&" : "?";
+    return `${this.wsUrl}${separator}${params.join("&")}`;
+  }
+  /**
+   * Build the outbound RPC headers: JSON content type, optional bearer auth,
+   * the optional mutation-replay idempotency key, and the D1 read-your-writes
+   * bookmark when the caller opted into `attachBookmark`. The mutation id
+   * rides both the direct send and any offline-queue replay of the same write,
+   * so a mutation the server already committed returns its cached result
+   * instead of running twice.
+   */
+  rpcRequestHeaders(flags) {
+    const headers = { "content-type": "application/json" };
+    if (this.authToken) {
+      headers["authorization"] = `Bearer ${this.authToken}`;
+    }
+    if (flags.mutationId) {
+      headers["x-lunora-mutation-id"] = flags.mutationId;
+    }
+    if (flags.attachBookmark) {
+      const bookmark = this.bookmark.get();
+      if (bookmark) {
+        headers["x-d1-bookmark"] = bookmark;
+      }
+    }
+    return headers;
+  }
+  async rpc(functionPath, args, shardKey, flags = {}) {
+    if (!this.fetchImpl) {
+      throw new Error("LunoraClient: no `fetch` implementation available");
+    }
+    const headers = this.rpcRequestHeaders(flags);
+    const response = await this.fetchImpl(joinUrl(this.url, RPC_PATH), {
+      body: JSON.stringify({ args, functionPath, shardKey }),
+      headers,
+      method: "POST"
+    });
+    if (flags.captureBookmark) {
+      const value = response.headers.get("x-d1-bookmark");
+      if (value) {
+        this.bookmark.set(value);
+      }
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      const statusText = response.statusText ? ` ${response.statusText}` : "";
+      throw new Error(`LunoraClient: response was not JSON (status ${response.status.toString()}${statusText})`);
+    }
+    if ("error" in body) {
+      const error = new Error(body.error.message);
+      error.code = body.error.code;
+      throw error;
+    }
+    if (!response.ok) {
+      const statusText = response.statusText ? ` ${response.statusText}` : "";
+      throw new Error(`LunoraClient: request failed (status ${response.status.toString()}${statusText})`);
+    }
+    return body.result;
+  }
+  /**
+   * Authenticated request to a non-RPC admin endpoint (the scheduler list /
+   * cancel routes). Attaches the bearer token, parses JSON, and surfaces the
+   * worker's `{ error: { code, message } }` envelope as a coded `Error` —
+   * mirroring {@link rpc} so callers see the same failure shape.
+   */
+  async adminFetch(path, method, payload, contentType) {
+    if (!this.fetchImpl) {
+      throw new Error("LunoraClient: no `fetch` implementation available");
+    }
+    const headers = {};
+    if (this.authToken) {
+      headers["authorization"] = `Bearer ${this.authToken}`;
+    }
+    const isBinary = payload instanceof ArrayBuffer || payload instanceof Blob;
+    let requestBody;
+    if (payload === void 0) {
+      requestBody = void 0;
+    } else if (isBinary) {
+      requestBody = payload;
+      if (contentType !== void 0) {
+        headers["content-type"] = contentType;
+      }
+    } else {
+      requestBody = JSON.stringify(payload);
+      headers["content-type"] = "application/json";
+    }
+    const response = await this.fetchImpl(joinUrl(this.url, path), {
+      body: requestBody,
+      headers,
+      method
+    });
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      const statusText = response.statusText ? ` ${response.statusText}` : "";
+      throw new Error(`LunoraClient: response was not JSON (status ${response.status.toString()}${statusText})`);
+    }
+    if (typeof body === "object" && body !== null && "error" in body) {
+      const envelope = body.error;
+      const error = new Error(envelope.message ?? "admin request failed");
+      error.code = envelope.code;
+      throw error;
+    }
+    if (!response.ok) {
+      const statusText = response.statusText ? ` ${response.statusText}` : "";
+      throw new Error(`LunoraClient: admin request failed (status ${response.status.toString()}${statusText})`);
+    }
+    return body;
+  }
+  /**
+   * Resolve the effective connection context for a shard: the most-recently
+   * acquired refcounted holder ({@link acquireConnectionContext}) wins, falling
+   * back to the imperative {@link setConnectionContext} override, then the
+   * client-wide default. Returns `undefined` when none apply.
+   */
+  effectiveConnectionContext(key) {
+    const holders = this.connectionContextHolders.get(key);
+    if (holders && holders.length > 0) {
+      return holders[holders.length - 1]?.context;
+    }
+    return this.connectionContexts.get(key) ?? this.defaultConnectionContext;
+  }
+  /** Re-send the `connect` envelope for a shard whose effective context just changed (if its socket is open). */
+  refreshConnectionContext(key) {
+    const conn = this.connections.get(key);
+    if (conn?.wsState === "open") {
+      this.sendConnectEnvelope(conn);
+    }
+  }
+  /**
+   * Send the one-shot `connect` envelope on an open shard socket. Always sent
+   * once per socket open, so the server's `onConnect` hooks fire symmetrically
+   * with `onDisconnect` (which the DO dispatches unconditionally at close for
+   * every lifecycle-aware socket). The DO no-ops cheaply when no `onConnect`
+   * hooks are registered, so the single frame costs nothing in the common case.
+   *
+   * The shard's registered context (or the client-wide default) rides along
+   * when one is set — the DO records it on the attachment for replay to
+   * `onDisconnect`. A socket with no registered context still announces itself;
+   * the envelope simply omits `context`, which is optional on the wire.
+   * Register a context — e.g. `setConnectionContext({})` — to attach app state
+   * to the lifecycle dispatch.
+   */
+  sendConnectEnvelope(conn) {
+    const context = this.effectiveConnectionContext(connectionKey(conn.shardKey));
+    sendOn(conn, {
+      id: "connect",
+      type: "connect",
+      ...context === void 0 ? {} : { context }
+    });
+  }
+  ensureSocket(shardKey) {
+    if (this.closed || this.WebSocketImpl === void 0) {
+      return;
+    }
+    const conn = this.getOrCreateConnection(shardKey);
+    if (conn.wsState === "open" || conn.wsState === "connecting") {
+      return;
+    }
+    conn.wsState = "connecting";
+    this.emitConnectionStatus();
+    const socket = new this.WebSocketImpl(this.wsUrlFor(shardKey));
+    conn.socket = socket;
+    socket.addEventListener("open", () => {
+      conn.wsState = "open";
+      conn.wasEverConnected = true;
+      conn.reconnect.reset();
+      this.emitConnectionStatus();
+      this.sendConnectEnvelope(conn);
+      this.markShardPendingAck(shardKey);
+      for (const state of this.subscriptions.all()) {
+        if (connectionKey(state.shardKey) === connectionKey(shardKey)) {
+          this.sendSubscribeIfOpen(state);
+        }
+      }
+      if (conn.pendingUnsubscribes.length > 0) {
+        const pending = conn.pendingUnsubscribes;
+        conn.pendingUnsubscribes = [];
+        for (const id of pending) {
+          sendOn(conn, { id, type: "unsubscribe" });
+        }
+      }
+      if (conn.pendingStreams && conn.pendingStreams.length > 0) {
+        const pending = conn.pendingStreams;
+        conn.pendingStreams = [];
+        for (const message of pending) {
+          sendOn(conn, message);
+        }
+      }
+      const byTopic = this.whisperHandlers.get(connectionKey(shardKey));
+      if (byTopic) {
+        for (const topic of byTopic.keys()) {
+          sendOn(conn, { topic, type: "whisper_subscribe" });
+        }
+      }
+      this.flushOfflineQueue(shardKey).catch(() => void 0);
+      this.startHeartbeat(conn);
+    });
+    socket.addEventListener("message", (event) => {
+      this.handleServerMessage(event.data, shardKey);
+    });
+    socket.addEventListener("close", (event) => {
+      if (event?.code === 4001) {
+        this.notifyTokenExpired();
+      }
+      this.handleDisconnect(conn);
+    });
+    socket.addEventListener("error", () => {
+      if (conn.wsState === "connecting" || conn.wsState === "open") {
+        this.handleDisconnect(conn);
+      }
+    });
+  }
+  handleDisconnect(conn) {
+    if (this.closed) {
+      return;
+    }
+    if (conn.wsState === "idle" || conn.wsState === "closed") {
+      return;
+    }
+    this.stopHeartbeat(conn);
+    conn.socket = void 0;
+    conn.wsState = "idle";
+    this.emitConnectionStatus();
+    this.markShardPendingAck(conn.shardKey);
+    if (this.WebSocketImpl === void 0) {
+      return;
+    }
+    const delay = conn.reconnect.next();
+    conn.reconnectTimer = setTimeout(() => {
+      conn.reconnectTimer = void 0;
+      this.ensureSocket(conn.shardKey);
+    }, delay);
+  }
+  /**
+   * Begin the keepalive heartbeat on an open connection. Each tick sends a
+   * {@link WS_KEEPALIVE_PING} text frame the server answers from its
+   * hibernation auto-response without waking the DO. A no-op when the
+   * heartbeat is disabled (an interval of zero or less); idempotent — any
+   * existing timer is cleared first so a reconnect can't leak intervals.
+   */
+  startHeartbeat(conn) {
+    this.stopHeartbeat(conn);
+    if (this.heartbeatIntervalMs <= 0) {
+      return;
+    }
+    conn.heartbeatTimer = setInterval(() => {
+      if (conn.wsState !== "open" || !conn.socket) {
+        return;
+      }
+      try {
+        conn.socket.send(WS_KEEPALIVE_PING);
+      } catch {
+      }
+    }, this.heartbeatIntervalMs);
+  }
+  /** Clear a connection's keepalive timer, if any. Safe to call repeatedly. */
+  // eslint-disable-next-line class-methods-use-this -- cohesive connection helper; pairs with startHeartbeat
+  stopHeartbeat(conn) {
+    if (conn.heartbeatTimer !== void 0) {
+      clearInterval(conn.heartbeatTimer);
+      conn.heartbeatTimer = void 0;
+    }
+  }
+  /** Mark every subscription bound to `shardKey` as needing a fresh ack. */
+  markShardPendingAck(shardKey) {
+    const key = connectionKey(shardKey);
+    for (const state of this.subscriptions.all()) {
+      if (connectionKey(state.shardKey) === key) {
+        state.acked = false;
+      }
+    }
+  }
+  sendSubscribeIfOpen(state) {
+    const conn = this.getConnection(state.shardKey);
+    if (conn?.wsState !== "open" || state.acked) {
+      return;
+    }
+    const table = state.fn.__lunoraTable ?? state.fn.__lunoraRef;
+    sendOn(conn, {
+      id: state.id,
+      // `sinceSeq` rides along when we hold a persisted cursor for this
+      // sub (a hydrated read or an earlier frame), so the server can
+      // resume instead of re-snapshotting. Omitted on a cold sub.
+      query: {
+        args: state.args,
+        functionPath: state.fn.__lunoraRef,
+        table,
+        ...state.serverCursor === void 0 ? {} : { sinceSeq: state.serverCursor },
+        ...state.serverEpoch === void 0 ? {} : { sinceEpoch: state.serverEpoch }
+      },
+      type: "subscribe"
+    });
+  }
+  handleServerMessage(raw, shardKey) {
+    const text = decodeServerFrame(raw);
+    if (text === void 0) {
+      return;
+    }
+    let message;
+    try {
+      message = JSON.parse(text);
+    } catch {
+      return;
+    }
+    switch (message.type) {
+      case "ack": {
+        const state = this.subscriptions.getById(message.id);
+        if (state) {
+          state.acked = true;
+        }
+        return;
+      }
+      case "chunk": {
+        const { data, id } = message;
+        const stream = this.streams.get(id);
+        stream?.handle.push(data);
+        return;
+      }
+      case "complete": {
+        this.handleCompleteMessage(message.id);
+        return;
+      }
+      case "data":
+      case "delta": {
+        this.handleDataMessage(message);
+        return;
+      }
+      case "error": {
+        this.handleErrorMessage(message);
+        break;
+      }
+      case "resume": {
+        this.handleResumeMessage(message);
+        break;
+      }
+      case "whisper": {
+        this.dispatchWhisper(message, shardKey);
+        break;
+      }
+    }
+  }
+  handleErrorMessage(message) {
+    const errorCode = message.error?.code;
+    if (errorCode === "TOKEN_EXPIRED") {
+      this.notifyTokenExpired();
+      return;
+    }
+    const { id } = message;
+    const stream = id === void 0 ? void 0 : this.streams.get(id);
+    if (stream && id !== void 0) {
+      stream.handle.fail(buildStreamError(message));
+      this.streams.delete(id);
+      return;
+    }
+    const state = id === void 0 ? void 0 : this.subscriptions.getById(id);
+    if (state) {
+      const error = buildSubscriptionError(message);
+      for (const errorCallback of state.errorCallbacks) {
+        try {
+          errorCallback(error);
+        } catch {
+        }
+      }
+    }
+  }
+  handleDataMessage(message) {
+    const { id } = message;
+    const state = id ? this.subscriptions.getById(id) : void 0;
+    if (!state) {
+      return;
+    }
+    const payload = this.resolveDataPayload(message, state);
+    state.lastValue = payload;
+    state.serverVersion += 1;
+    if (message.cursor !== void 0) {
+      state.serverCursor = message.cursor;
+    }
+    if (message.epoch !== void 0) {
+      state.serverEpoch = message.epoch;
+    }
+    this.persistQueryValue(state);
+    for (const callback of state.callbacks) {
+      try {
+        callback(payload);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Handle a `resume` frame (Pillar 1b): the server proved nothing the
+   * subscription reads changed since our `sinceSeq`, so the cached value is
+   * still current. We keep `lastValue` as-is, mark the sub acked, and advance
+   * the cursor (re-persisting so the next reconnect resumes from the newer
+   * watermark). No callback fires — the value didn't change, and `subscribe()`
+   * already replayed the cached value to every consumer synchronously.
+   */
+  handleResumeMessage(message) {
+    const state = this.subscriptions.getById(message.id);
+    if (!state) {
+      return;
+    }
+    state.acked = true;
+    if (message.cursor !== void 0 && message.cursor !== state.serverCursor || message.epoch !== void 0 && message.epoch !== state.serverEpoch) {
+      if (message.cursor !== void 0) {
+        state.serverCursor = message.cursor;
+      }
+      if (message.epoch !== void 0) {
+        state.serverEpoch = message.epoch;
+      }
+      this.persistQueryValue(state);
+    }
+  }
+  /**
+   * Resolve the value to publish for a `data`/`delta` frame.
+   *
+   * A `data` frame is an authoritative snapshot (the server re-execution path)
+   * and always replaces the cached value wholesale. A `delta` frame carrying a
+   * structured `MutationDelta` (the `broadcastDelta` row-change path) is
+   * merged incrementally into the cached list — preserving order, no dup/loss —
+   * so each subscription (including every paginated page) updates by delta
+   * rather than a full re-send. We fall back to full replacement when the
+   * delta isn't a recognisable row change, when there's no cached value yet,
+   * or when it can't be applied cleanly against the current cached shape.
+   */
+  // eslint-disable-next-line class-methods-use-this -- instance method for symmetry with the other message handlers; reads no shared client state
+  resolveDataPayload(message, state) {
+    if ("data" in message && message.data !== void 0) {
+      return message.data;
+    }
+    const { delta } = message;
+    if (isMutationDelta(delta) && state.lastValue !== void 0) {
+      const merged = applyDelta(state.lastValue, delta);
+      if (merged !== void 0) {
+        return merged;
+      }
+    }
+    return delta;
+  }
+  /** Route an inbound whisper to the topic's handlers on the originating shard. */
+  dispatchWhisper(message, shardKey) {
+    const handlers = this.whisperHandlers.get(connectionKey(shardKey))?.get(message.topic);
+    if (!handlers) {
+      return;
+    }
+    for (const handler of handlers) {
+      try {
+        handler(message.data, message.from);
+      } catch {
+      }
+    }
+  }
+  /** Notify every {@link onTokenExpired} listener (best-effort, listener throws swallowed). */
+  notifyTokenExpired() {
+    for (const listener of this.tokenExpiredListeners) {
+      try {
+        listener();
+      } catch {
+      }
+    }
+  }
+  handleCompleteMessage(id) {
+    const stream = this.streams.get(id);
+    if (stream) {
+      stream.handle.complete();
+      this.streams.delete(id);
+      return;
+    }
+    const state = this.subscriptions.getById(id);
+    if (state) {
+      this.subscriptions.remove(state);
+    }
+  }
+  unpersist(id) {
+    if (id) {
+      this.persistence?.remove(id).catch((error) => {
+        reportPersistenceError(this.onPersistenceError, "remove", error, id);
+      });
+    }
+  }
+  /**
+   * Stable, non-reversible fingerprint of the current auth identity used to
+   * stamp queued offline writes. `null` (signed out) is its own identity and
+   * never matches a bearer-token fingerprint. The raw token is never stored;
+   * a length-prefixed FNV-1a hash is enough to detect an identity *change*
+   * without keeping the credential around in the queue map.
+   */
+  // `null` is the distinct "signed out" identity (separate from `undefined`,
+  // which means "not stamped / hydrated"); the two must not be conflated.
+  identityFingerprint() {
+    const token = this.authToken;
+    if (token === null) {
+      return null;
+    }
+    let hash = 2166136261;
+    for (let index = 0; index < token.length; index += 1) {
+      hash ^= token.charCodeAt(index);
+      hash = Math.imul(hash, 16777619);
+    }
+    return `${token.length.toString(36)}:${(hash >>> 0).toString(36)}`;
+  }
+  /**
+   * Drain every in-memory offline write and reject it because the auth
+   * identity changed. Durable entries are also dropped from persistence so a
+   * later `hydrate` can't resurrect another user's writes. Stamps are cleared
+   * alongside. Persisted entries restored without a live awaiter still get
+   * unpersisted here.
+   */
+  rejectQueuedForIdentityChange() {
+    const drained = this.offlineQueue.drain();
+    for (const item of drained) {
+      this.queuedIdentities.delete(item.id ?? "");
+      this.unpersist(item.id);
+      const error = new Error("offline mutation discarded: auth identity changed before replay");
+      error.code = "OFFLINE_IDENTITY_CHANGED";
+      item.reject(error);
+    }
+    this.clearQueryCacheForIdentityChange();
+  }
+  /**
+   * Drop the durable read cache on an identity change so a cached value stamped
+   * under the previous identity can never hydrate into a new session. Clears
+   * the in-flight write batch and the not-yet-consumed hydrated entries too;
+   * the durable `clear()` is best-effort.
+   */
+  clearQueryCacheForIdentityChange() {
+    if (this.cacheFlushTimer !== void 0) {
+      clearTimeout(this.cacheFlushTimer);
+      this.cacheFlushTimer = void 0;
+    }
+    this.pendingCacheWrites.clear();
+    this.hydratedQueryCache.clear();
+    this.queryCache?.clear().catch(() => void 0);
+  }
+  async flushOfflineQueue(shardKey) {
+    const key = connectionKey(shardKey);
+    const drained = this.offlineQueue.drain((item) => connectionKey(item.shardKey) === key);
+    for (let index = 0; index < drained.length; index += 1) {
+      const item = drained[index];
+      if (!item) {
+        continue;
+      }
+      const currentIdentity = this.identityFingerprint();
+      const liveStamp = item.id === void 0 ? void 0 : this.queuedIdentities.get(item.id);
+      const stamped = liveStamp === void 0 ? item.identity : liveStamp;
+      if (stamped !== void 0 && stamped !== currentIdentity) {
+        this.queuedIdentities.delete(item.id ?? "");
+        this.unpersist(item.id);
+        const error = new Error("offline mutation skipped: auth identity changed before replay");
+        error.code = "OFFLINE_IDENTITY_CHANGED";
+        item.reject(error);
+        continue;
+      }
+      this.queuedIdentities.delete(item.id ?? "");
+      try {
+        const value = await this.rpc(item.functionPath, item.args, item.shardKey, { captureBookmark: true, mutationId: item.id });
+        this.unpersist(item.id);
+        item.resolve(value);
+      } catch (error) {
+        if (error.code !== void 0) {
+          this.unpersist(item.id);
+          item.reject(error);
+          continue;
+        }
+        this.offlineQueue.requeue(drained.slice(index));
+        return;
+      }
+    }
+  }
+}
+
+export { LunoraClient };