@lunora/client 0.0.0 → 1.0.0-alpha.10

package/dist/packem_shared/LunoraClient-CgZ6FhKP.mjs

@@ -0,0 +1,2721 @@
+import { S as SubscriptionRegistry, s as stableStringify } from './subscription-C1Jy7HiF.mjs';
+import createInMemoryBookmarkStorage from './createInMemoryBookmarkStorage-BoN7a7TH.mjs';
+import { isMutationDelta, applyDelta } from './applyDelta-4jFGTPA3.mjs';
+import { a as applyOptimisticLayer, d as dropConfirmedLayers, n as notifySubscription, f as foldOptimistic, c as createLocalStore } from './local-store-BNgN3Dw3.mjs';
+import { O as OfflineQueue, n as nextId, i as isStaleVersion, r as reportPersistenceError } from './offline-queue-7Wc4onA0.mjs';
+import { queryCacheKey } from './createInMemoryQueryCache-B1PQ9Twl.mjs';
+import { createReconnect } from './createReconnect-Di_-oHH7.mjs';
+import { createStream } from './DEFAULT_MAX_BUFFER-BDkqO5PW.mjs';
+
+class Listeners {
+  listeners = /* @__PURE__ */ new Set();
+  add(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  // The conditional rest tuple makes `emit()` argument-free for a
+  // `Listeners<void>` and one-argument for every other payload.
+  // eslint-disable-next-line @typescript-eslint/no-invalid-void-type -- `[T] extends [void]` is the discriminant for the payload-free overload, not a value-position void
+  emit(...args) {
+    const [value] = args;
+    for (const listener of this.listeners) {
+      try {
+        listener(value);
+      } catch {
+      }
+    }
+  }
+  clear() {
+    this.listeners.clear();
+  }
+}
+
+const RPC_PATH = "/_lunora/rpc";
+const WS_PATH = "/_lunora/ws";
+const bucketQuery = (bucket) => bucket === void 0 || bucket === "" ? "" : `&bucket=${encodeURIComponent(bucket)}`;
+const rollbackOptimistic = (optimisticRollbacks) => {
+  for (let index = optimisticRollbacks.length - 1; index >= 0; index -= 1) {
+    optimisticRollbacks[index]?.();
+  }
+};
+const applyRowOpsToView = (rows, ops) => {
+  for (const op of ops) {
+    if (op.op === "delete") {
+      rows.delete(op.key);
+    } else if (op.value !== void 0) {
+      rows.set(op.key, op.value);
+    }
+  }
+};
+const WS_KEEPALIVE_PING = "lunora-ping";
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 3e4;
+const DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
+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 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 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 fanSubscriptionError = (callbacks, error) => {
+  for (const errorCallback of callbacks) {
+    try {
+      errorCallback(error);
+    } catch {
+    }
+  }
+};
+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 {
+  /** Hard cap on concurrently-buffered pokes — a backstop that reclaims buffers abandoned by a mid-poke disconnect (no `pokeEnd`). Far above any real concurrent-in-flight count. */
+  static MAX_POKE_BUFFERS = 256;
+  url;
+  wsUrl;
+  wsToken;
+  /** Better-auth base path (trailing slash stripped) for the `get-session` lookup. */
+  authBasePath;
+  fetchImpl;
+  WebSocketImpl;
+  bookmark;
+  reconnectOptions;
+  /** WS connect timeout (ms); `0` disables it. See {@link LunoraClientOptions.connectTimeoutMs}. */
+  connectTimeoutMs;
+  /** Keepalive cadence (ms); `0` disables the heartbeat. See {@link LunoraClientOptions.heartbeatIntervalMs}. */
+  heartbeatIntervalMs;
+  offlineQueue;
+  /**
+   * Durable outbox seam (the `@lunora/db` `createExecutorOutboxSink`). When
+   * set, offline writes are delegated here and the built-in {@link OfflineQueue}
+   * is bypassed, so a db app has exactly one durable write path.
+   */
+  outbox;
+  /** Stable per-client id stamped onto every `OutboxMutation` (custom-mutator watermark). */
+  clientId;
+  /**
+   * Highest custom-mutator watermark the server has echoed for this client,
+   * keyed by shard bucket (`shardKey ?? ""`) since the DO tracks one
+   * `__client_watermark` per shard. `callMutator` bumps it from every
+   * ack; the `@lunora/db` mutator runtime seeds its `clientSeq` generator from
+   * it so a reload (which resets the in-memory counter) never reissues a stale
+   * sequence the server would silently swallow as a replay.
+   */
+  clientWatermarks = /* @__PURE__ */ new Map();
+  /** Monotonic per-client mutation counter backing the server `__client_watermark`. */
+  outboxMutationCounter = 0;
+  onPersistenceError;
+  persistence;
+  /** App/schema version stamped on persisted writes + cached reads; mismatches are purged. */
+  persistenceVersion;
+  /** Releases the multi-tab outbox-leader Web Lock on close (see `hydrateAsOutboxLeader`). */
+  outboxLeaderRelease;
+  /** 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;
+  /**
+   * Optional STABLE identity subject (a user id), the basis of the offline-queue
+   * identity stamp when supplied. Keeps a same-user token *refresh* from looking
+   * like an identity change (which would discard queued writes). `undefined` =
+   * not supplied, so identity falls back to a hash of the raw token. See
+   * `setAuthToken` / `identityFingerprint`.
+   */
+  authSubject = void 0;
+  /**
+   * 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 = new Listeners();
+  /** Subscribers to aggregate connection-status changes (see `onConnectionStatus`). */
+  statusListeners = new Listeners();
+  /** Subscribers notified when the server drops a socket for an expired token (see `onTokenExpired`). */
+  tokenExpiredListeners = new Listeners();
+  /** Subscribers to offline-queued mutation verdicts (see `onMutationSettled`). */
+  mutationSettledListeners = new Listeners();
+  /** Subscribers to the offline-queue pending-count (see `onPendingChange`). */
+  pendingChangeListeners = new Listeners();
+  /**
+   * 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();
+  /** Live shape subscriptions (partial replication), keyed by their wire id. */
+  shapeSubscriptions = /* @__PURE__ */ new Map();
+  /** In-flight pokes being assembled between `pokeStart` and `pokeEnd`, keyed by `pokeId`. */
+  pokeBuffers = /* @__PURE__ */ new Map();
+  nextShapeId = 0;
+  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.connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
+    this.defaultConnectionContext = options.connectionContext;
+    this.persistence = options.persistence;
+    this.persistenceVersion = options.persistenceVersion;
+    this.queryCache = options.queryCache === false ? void 0 : options.queryCache;
+    this.onPersistenceError = options.offlineQueue?.onPersistenceError;
+    this.offlineQueue = new OfflineQueue(options.offlineQueue, {
+      onEvict: (entry, error) => {
+        this.emitItemSettled(entry, "rejected", error);
+      },
+      onSizeChange: (size) => {
+        this.pendingChangeListeners.emit(size);
+      },
+      persistence: options.persistence,
+      version: options.persistenceVersion
+    });
+    this.outbox = options.outbox;
+    this.clientId = options.clientId ?? `client-${nextId()}`;
+    if (this.persistence) {
+      queueMicrotask(() => {
+        this.hydrateAsOutboxLeader();
+      });
+    }
+    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.
+   *
+   * Pass a STABLE `subject` (the user id) to key the offline-queue identity on
+   * it instead of the token bytes, so a token *refresh* (same user, new JWT)
+   * doesn't read as an identity change and discard queued writes. The subject is
+   * **sticky**: a later call that omits it (or passes `undefined`) keeps the
+   * established subject — so `setAuthToken(refreshedToken)` after a prior
+   * `setAuthToken(token, user.id)` retains the identity. Pass `null` to clear it
+   * (an explicit sign-out). Establishing the subject for the first time on an
+   * UNCHANGED token (e.g. the user id resolves a tick after the token was set)
+   * re-stamps any in-flight queued writes rather than dropping them — same
+   * credential, just a more stable label. A real user switch (the token AND
+   * subject both change) still drops the previous user's writes.
+   *
+   * 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, subject) {
+    const tokenChanged = this.authToken !== token;
+    const previousIdentity = this.identityFingerprint();
+    this.authToken = token;
+    if (subject !== void 0) {
+      this.authSubject = subject;
+    }
+    const newIdentity = this.identityFingerprint();
+    if (newIdentity !== previousIdentity) {
+      if (tokenChanged) {
+        this.rejectQueuedForIdentityChange();
+      } else {
+        this.restampQueuedIdentity(previousIdentity, newIdentity);
+      }
+    }
+    if (tokenChanged) {
+      this.authTokenListeners.emit(token);
+    }
+  }
+  getAuthToken() {
+    return this.authToken;
+  }
+  /**
+   * The current identity fingerprint (the same stamp queued offline writes
+   * carry). Exposed so a durable {@link OutboxSink}'s replay handler — which
+   * owns its own at-least-once replay outside the built-in `OfflineQueue` —
+   * can drop a persisted write whose captured `identity` no longer matches the
+   * signed-in user, the guard the queue path applies in `flushOfflineQueue`.
+   */
+  currentIdentity() {
+    return this.identityFingerprint();
+  }
+  /** This client's stable identifier — the watermark key the server's custom-mutator protocol advances per `clientSeq`. */
+  clientIdentifier() {
+    return this.clientId;
+  }
+  /**
+   * The highest custom-mutator watermark the server has echoed for this client
+   * on the given shard (0 if none yet). The `@lunora/db` mutator runtime seeds
+   * its `clientSeq` generator from this so a reload never reissues a sequence
+   * the server has already applied (which it would swallow as a replay, silently
+   * dropping the write).
+   */
+  confirmedMutationWatermark(shardKey) {
+    return this.clientWatermarks.get(shardKey ?? "") ?? 0;
+  }
+  /**
+   * Push a custom mutator to its authoritative server impl over the watermark
+   * protocol (Phase 4): the request carries `x-lunora-client-id` + a monotonic
+   * `x-lunora-client-seq`, so the DO runs it exactly once and advances this
+   * client's `__client_watermark`.
+   *
+   * Returns the server `result` plus `applied`: `true` when the DO ran this push
+   * as the next-in-order mutation, `false` when it was a replay ack (`clientSeq`
+   * was at or below the stored watermark — e.g. a stale sequence after a reload).
+   * A `false` verdict tells the caller to reissue above the now-known watermark
+   * (echoed into {@link confirmedMutationWatermark}) rather than treat the benign
+   * ack as a confirmed write. Every ack — applied or not — bumps the watermark.
+   *
+   * This is the online transport for `@lunora/db`'s client-mutator runtime; the
+   * optimistic overlay + durable-outbox concerns live in that runtime, not here.
+   */
+  async callMutator(functionPath, args, options) {
+    const clientSeq = options?.clientSeq;
+    if (clientSeq !== void 0 && (!Number.isInteger(clientSeq) || clientSeq <= 0)) {
+      throw new Error(`callMutator: clientSeq must be a positive integer, got ${String(clientSeq)}`);
+    }
+    const bucket = options?.shardKey ?? "";
+    let ackWatermark;
+    const result = await this.rpc(functionPath, args, options?.shardKey, {
+      captureBookmark: true,
+      clientId: this.clientId,
+      clientSeq,
+      onMutationAck: (lastMutationId) => {
+        ackWatermark = lastMutationId;
+      }
+    });
+    if (ackWatermark !== void 0 && ackWatermark > (this.clientWatermarks.get(bucket) ?? 0)) {
+      this.clientWatermarks.set(bucket, ackWatermark);
+    }
+    const applied = ackWatermark === void 0 || ackWatermark === clientSeq;
+    return { applied, result };
+  }
+  /**
+   * 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) {
+    return this.authTokenListeners.add(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) {
+    return this.tokenExpiredListeners.add(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) {
+    const unsubscribe = this.statusListeners.add(listener);
+    listener(this.computeStatus());
+    return unsubscribe;
+  }
+  /**
+   * Number of offline writes waiting in the built-in queue to be sent — the
+   * depth for a "N changes waiting to sync" indicator. Counts writes that are
+   * queued (offline / mid-reconnect), not ones already in flight on the wire.
+   * A `@lunora/db` app whose writes ride the unified outbox should read
+   * `LunoraDb.pendingCount()` instead (this counts only the built-in queue).
+   */
+  pendingCount() {
+    return this.offlineQueue.size;
+  }
+  /**
+   * Subscribe to changes in {@link pendingCount}. Invokes `listener` immediately
+   * with the current count, then whenever the queue depth changes (a write is
+   * enqueued, flushed, or discarded). Returns an unsubscribe function.
+   */
+  onPendingChange(listener) {
+    const unsubscribe = this.pendingChangeListeners.add(listener);
+    listener(this.offlineQueue.size);
+    return unsubscribe;
+  }
+  /**
+   * Subscribe to terminal verdicts for offline-queued mutations. The listener
+   * fires once per queued write that commits or is rejected — including a write
+   * restored from durable storage after a reload, whose original `mutation()`
+   * Promise no longer exists (`hadAwaiter: false`), and a write the queue
+   * evicts on overflow or discards on an identity change. This is the durable
+   * channel for surfacing a rolled-back optimistic write to the UI; an online
+   * mutation that never queued still surfaces through the Promise `mutation()`
+   * returns. The listener is NOT invoked on registration. Returns an
+   * unsubscribe function. See {@link MutationSettledEvent}.
+   */
+  onMutationSettled(listener) {
+    return this.mutationSettledListeners.add(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 = options.mutationId ?? nextId();
+    const { confirms: optimisticConfirms, rollbacks: optimisticRollbacks } = this.applyOptimisticUpdates(
+      function_.__lunoraRef,
+      argsRecord,
+      options.shardKey,
+      options.optimistic
+    );
+    if (options.optimisticUpdate) {
+      this.applyOptimisticUpdate(options.optimisticUpdate, args, options.shardKey, optimisticRollbacks, optimisticConfirms);
+    }
+    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) {
+      return this.enqueueOfflineMutation(function_, argsRecord, options.shardKey, mutationId, optimisticRollbacks, optimisticConfirms);
+    }
+    try {
+      let commitCursor;
+      const result = await this.rpc(function_.__lunoraRef, argsRecord, options.shardKey, {
+        captureBookmark: true,
+        mutationId,
+        onCommitCursor: (cursor) => {
+          commitCursor = cursor;
+        }
+      });
+      for (const confirm of optimisticConfirms) {
+        confirm(commitCursor);
+      }
+      return result;
+    } catch (error) {
+      rollbackOptimistic(optimisticRollbacks);
+      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). When one isn't
+   * configured this does NOT reject: the proxy returns a `200 { configured:
+   * false }` sentinel, so the result resolves with `configured === false` and an
+   * empty `instances` list — callers should branch on that flag rather than
+   * try/catch. (The instance-detail / status endpoints still reject with 501.)
+   * `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 {
+      configured: body.configured,
+      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(),
+        checkpointCallbacks: /* @__PURE__ */ new Set(),
+        errorCallbacks: /* @__PURE__ */ new Set(),
+        fn: function_,
+        id,
+        lastValue: cached?.value,
+        optimisticLayers: [],
+        serverBase: cached?.value,
+        serverCursor: cached?.serverCursor,
+        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 (options.onCheckpoint) {
+      state.checkpointCallbacks.add(options.onCheckpoint);
+    }
+    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 (options.onCheckpoint) {
+        subscriptionState.checkpointCallbacks.delete(options.onCheckpoint);
+      }
+      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({ id: subscriptionState.id, type: "unsubscribe" });
+        }
+        this.subscriptions.remove(subscriptionState);
+      }
+    };
+  }
+  /**
+   * Subscribe to a declarative **shape** — server-side partial replication
+   * scoped by `shardBy` + the shape's predicate + RLS. The parallel to
+   * {@link subscribe} for the poke protocol: the client sends the shape *name* +
+   * validated `args` (never a `where` the client could forge), the server seeds
+   * the current membership as an insert-poke and streams live membership diffs.
+   * Each applied poke materializes the shape's rowset and invokes `callback`.
+   *
+   * Unlike {@link subscribe}, shape subscriptions are NOT deduped by
+   * (name, args): the server resolves them under the socket's verified identity,
+   * so every call gets its own id + view. The returned function unsubscribes.
+   */
+  subscribeShape(shape, callback, options = {}) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    this.nextShapeId += 1;
+    const id = `shape_${this.nextShapeId.toString()}`;
+    const state = {
+      args: shape.args,
+      callbacks: /* @__PURE__ */ new Set([callback]),
+      errorCallbacks: options.onError ? /* @__PURE__ */ new Set([options.onError]) : /* @__PURE__ */ new Set(),
+      id,
+      name: shape.name,
+      onCheckpoint: options.onCheckpoint,
+      rows: /* @__PURE__ */ new Map(),
+      shardKey: options.shardKey
+    };
+    this.shapeSubscriptions.set(id, state);
+    this.ensureSocket(options.shardKey);
+    this.sendShapeSubscribeIfOpen(state);
+    return () => {
+      this.shapeSubscriptions.delete(id);
+      const conn = this.getConnection(state.shardKey);
+      const ok = conn ? sendOn(conn, { id, type: "shape_unsubscribe" }) : false;
+      if (!ok && conn) {
+        conn.pendingUnsubscribes.push({ id, type: "shape_unsubscribe" });
+      }
+    };
+  }
+  /**
+   * 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;
+    this.outboxLeaderRelease?.();
+    this.outboxLeaderRelease = void 0;
+    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;
+      }
+      if (conn.connectTimer !== void 0) {
+        clearTimeout(conn.connectTimer);
+        conn.connectTimer = 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.mutationSettledListeners.clear();
+    this.pendingChangeListeners.clear();
+    this.whisperHandlers.clear();
+    this.shapeSubscriptions.clear();
+    this.pokeBuffers.clear();
+  }
+  // --- Internals ----------------------------------------------------------
+  /**
+   * Persist a mutation that can't go out on the wire right now (offline, or
+   * mid-reconnect after a prior connect). The optimistic update has already
+   * been applied by `mutation`; this only chooses the durable write path and
+   * rolls the optimistic write back if persistence is rejected.
+   *
+   * Two paths: when an `outbox` sink is wired (the `@lunora/db` executor) it
+   * owns persistence + at-least-once replay, so we delegate and return
+   * optimistically (confirmation rides the synced view). Otherwise the
+   * built-in `OfflineQueue` resolves/rejects the returned promise on replay.
+   */
+  async enqueueOfflineMutation(function_, argsRecord, shardKey, mutationId, optimisticRollbacks, optimisticConfirms) {
+    const issuingIdentity = this.identityFingerprint();
+    if (this.outbox) {
+      this.outboxMutationCounter += 1;
+      const outboxMutationId = this.outboxMutationCounter;
+      try {
+        await this.outbox.enqueue({
+          args: argsRecord,
+          clientId: this.clientId,
+          functionPath: function_.__lunoraRef,
+          idempotencyKey: `${this.clientId}:${String(outboxMutationId)}`,
+          identity: issuingIdentity,
+          mutationId: outboxMutationId,
+          shardKey
+        });
+      } catch (error) {
+        rollbackOptimistic(optimisticRollbacks);
+        throw error instanceof Error ? error : new Error(String(error));
+      }
+      for (const confirm of optimisticConfirms) {
+        confirm(void 0);
+      }
+      return void 0;
+    }
+    return new Promise((resolve, reject) => {
+      const entry = {
+        args: argsRecord,
+        functionPath: function_.__lunoraRef,
+        // A live caller is awaiting this Promise, so a terminal verdict
+        // reaches them directly; the observer event carries
+        // `hadAwaiter: true`. Hydrated replays leave this unset.
+        liveAwaiter: true,
+        // 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,
+        // Confirm the per-call optimistic layer(s) against the commit cursor
+        // the flush replay echoes (see flushOfflineQueue).
+        onCommit: (commitCursor) => {
+          for (const confirm of optimisticConfirms) {
+            confirm(commitCursor);
+          }
+        },
+        reject: (error) => {
+          this.queuedIdentities.delete(mutationId);
+          rollbackOptimistic(optimisticRollbacks);
+          reject(error instanceof Error ? error : new Error(String(error)));
+        },
+        resolve,
+        shardKey
+      };
+      this.offlineQueue.enqueue(entry);
+      if (entry.id !== void 0) {
+        this.queuedIdentities.set(entry.id, issuingIdentity);
+      }
+    });
+  }
+  /**
+   * 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 {
+    }
+  }
+  /**
+   * Re-queue the durable offline writes — but only as the multi-tab LEADER. The
+   * persisted queue is shared across a profile's tabs; without coordination
+   * every tab would re-queue and replay the same writes (correct only because
+   * the server dedups by idempotency key, but wasteful + racy). A Web Lock makes
+   * exactly one tab hydrate; it holds the lock for its lifetime, so when it
+   * closes another tab acquires the lock and takes over. Falls back to
+   * unconditional hydration where Web Locks are unavailable (React Native, older
+   * browsers, SSR) — single-context there, so no coordination is needed.
+   */
+  hydrateAsOutboxLeader() {
+    const hydrate = () => {
+      this.hydratePersistedQueue().catch(() => void 0);
+    };
+    const locks = globalThis.navigator?.locks;
+    if (!locks) {
+      hydrate();
+      return;
+    }
+    locks.request(`lunora:outbox-leader:${this.url}`, () => {
+      if (!this.closed) {
+        hydrate();
+      }
+      return new Promise((resolve) => {
+        if (this.closed) {
+          resolve();
+          return;
+        }
+        this.outboxLeaderRelease = resolve;
+      });
+    }).catch(hydrate);
+  }
+  /**
+   * 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) {
+        if (isStaleVersion(this.persistenceVersion, entry.version)) {
+          this.queryCache.remove(key).catch(() => void 0);
+          continue;
+        }
+        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) {
+    const authoritative = state.serverBase;
+    if (!this.queryCache || authoritative === 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: authoritative,
+      ...state.serverEpoch === void 0 ? {} : { serverEpoch: state.serverEpoch },
+      ...this.persistenceVersion === void 0 ? {} : { version: this.persistenceVersion }
+    });
+    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;
+    this.statusListeners.emit(next);
+  }
+  /**
+   * Build a {@link MutationSettledEvent} from a queued entry and emit it on the
+   * {@link onMutationSettled} channel. `item.id` is always assigned by the time
+   * a write settles (`enqueue`/`hydrate` guarantee it), so the `?? ""` fallback
+   * is unreachable — present only to satisfy the optional queue-id type.
+   */
+  emitItemSettled(item, status, error) {
+    this.mutationSettledListeners.emit({
+      args: item.args,
+      code: error === void 0 ? void 0 : error.code,
+      error,
+      functionPath: item.functionPath,
+      hadAwaiter: item.liveAwaiter ?? false,
+      id: item.id ?? "",
+      shardKey: item.shardKey,
+      status
+    });
+  }
+  /**
+   * Apply an optimistic update to the subscription that matches the mutation's
+   * `(functionRef, args, shardKey)` triple, returning the rollback callbacks to
+   * invoke if the mutation later fails.
+   *
+   * The registry is already indexed by exactly this triple via
+   * `SubscriptionRegistry.key`, so at most one subscription can match. A direct
+   * O(1) keyed lookup replaces the former O(N) linear scan over all subscriptions.
+   *
+   * `shardKey` normalization: both `undefined` and `""` map to the empty string
+   * inside `SubscriptionRegistry.key` (via `?? ""`), so a mutation fired without
+   * a shardKey correctly matches a subscription registered without one regardless
+   * of whether the caller passed `undefined` or omitted the field.
+   */
+  applyOptimisticUpdates(functionRef, argsRecord, mutationShardKey, optimistic) {
+    const confirms = [];
+    const rollbacks = [];
+    if (!optimistic) {
+      return { confirms, rollbacks };
+    }
+    const matchKey = SubscriptionRegistry.key(functionRef, argsRecord, mutationShardKey);
+    const state = this.subscriptions.get(matchKey);
+    if (state) {
+      const handle = applyOptimisticLayer(state, optimistic);
+      if (handle) {
+        confirms.push(handle.confirm);
+        rollbacks.push(handle.rollback);
+      }
+    }
+    return { confirms, rollbacks };
+  }
+  /**
+   * Run a Convex-parity `optimisticUpdate` callback against a localStore bound
+   * to the live subscription registry. Each `setQuery` registers a constant
+   * optimistic LAYER on its target subscription (via the same engine the
+   * per-call `optimistic` path uses), so the multi-query patch rebases onto
+   * incoming deltas and drops gaplessly on its commit cursor — its `confirm` /
+   * `rollback` closures are appended to the mutation's settle lists. 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.
+   */
+  applyOptimisticUpdate(optimisticUpdate, args, shardKey, optimisticRollbacks, optimisticConfirms) {
+    const { confirms, rollbacks, store } = createLocalStore(this.subscriptions, shardKey, stableStringify);
+    try {
+      optimisticUpdate(store, args);
+    } catch {
+      for (let index = rollbacks.length - 1; index >= 0; index -= 1) {
+        rollbacks[index]?.();
+      }
+      return;
+    }
+    optimisticRollbacks.push(...rollbacks);
+    optimisticConfirms.push(...confirms);
+  }
+  getConnection(shardKey) {
+    return this.connections.get(connectionKey(shardKey));
+  }
+  getOrCreateConnection(shardKey) {
+    const key = connectionKey(shardKey);
+    let conn = this.connections.get(key);
+    if (!conn) {
+      conn = {
+        connectTimer: void 0,
+        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.clientId !== void 0) {
+      headers["x-lunora-client-id"] = flags.clientId;
+    }
+    if (flags.clientSeq !== void 0) {
+      headers["x-lunora-client-seq"] = flags.clientSeq.toString();
+    }
+    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})`);
+    }
+    flags.onMutationAck?.(body.lastMutationId);
+    flags.onCommitCursor?.(body.commitCursor);
+    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, {
+      // Lets the server scope this connection's `__client_watermark` so
+      // custom-mutator pokes can echo this client's `lastMutationId`.
+      clientId: this.clientId,
+      id: "connect",
+      type: "connect",
+      ...context === void 0 ? {} : { context }
+    });
+  }
+  /**
+   * Re-send every shape subscription bound to `shardKey` over its (now open)
+   * socket. Each frame carries the shape's last applied checkpoint, so the
+   * server resumes from it — or re-seeds when the cursor fell below CDC
+   * retention or the epoch forked.
+   */
+  resendShapeSubscriptions(shardKey) {
+    for (const state of this.shapeSubscriptions.values()) {
+      if (connectionKey(state.shardKey) === connectionKey(shardKey)) {
+        this.sendShapeSubscribeIfOpen(state);
+      }
+    }
+  }
+  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;
+    if (this.connectTimeoutMs > 0) {
+      conn.connectTimer = setTimeout(() => {
+        conn.connectTimer = void 0;
+        if (conn.socket !== socket || conn.wsState !== "connecting") {
+          return;
+        }
+        try {
+          socket.close();
+        } catch {
+        }
+        this.handleDisconnect(conn);
+      }, this.connectTimeoutMs);
+    }
+    socket.addEventListener("open", () => {
+      if (conn.socket !== socket) {
+        return;
+      }
+      if (conn.connectTimer !== void 0) {
+        clearTimeout(conn.connectTimer);
+        conn.connectTimer = void 0;
+      }
+      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);
+        }
+      }
+      this.resendShapeSubscriptions(shardKey);
+      if (conn.pendingUnsubscribes.length > 0) {
+        const pending = conn.pendingUnsubscribes;
+        conn.pendingUnsubscribes = [];
+        for (const { id, type } of pending) {
+          sendOn(conn, { id, type });
+        }
+      }
+      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 (conn.socket !== socket) {
+        return;
+      }
+      if (event?.code === 4001) {
+        this.notifyTokenExpired();
+      }
+      this.handleDisconnect(conn);
+    });
+    socket.addEventListener("error", () => {
+      if (conn.socket !== socket) {
+        return;
+      }
+      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);
+    if (conn.connectTimer !== void 0) {
+      clearTimeout(conn.connectTimer);
+      conn.connectTimer = void 0;
+    }
+    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"
+    });
+  }
+  sendShapeSubscribeIfOpen(state) {
+    const conn = this.getConnection(state.shardKey);
+    if (conn?.wsState !== "open") {
+      return;
+    }
+    sendOn(conn, {
+      id: state.id,
+      shape: { name: state.name, ...state.args === void 0 ? {} : { args: state.args } },
+      type: "shape_subscribe",
+      // Resume from the last applied checkpoint when we hold one; a cold
+      // subscribe omits it and the server seeds the full membership.
+      ...state.serverCursor === void 0 ? {} : { sinceCheckpoint: state.serverCursor },
+      ...state.serverEpoch === void 0 ? {} : { sinceEpoch: state.serverEpoch }
+    });
+  }
+  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 "pokeEnd": {
+        this.handlePokeEnd(message);
+        break;
+      }
+      case "pokePart": {
+        this.handlePokePart(message);
+        break;
+      }
+      case "pokeStart": {
+        this.handlePokeStart(message);
+        break;
+      }
+      case "resume": {
+        this.handleResumeMessage(message);
+        break;
+      }
+      case "settled": {
+        this.handleSettledMessage(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) {
+      fanSubscriptionError(state.errorCallbacks, buildSubscriptionError(message));
+      return;
+    }
+    const shapeState = id === void 0 ? void 0 : this.shapeSubscriptions.get(id);
+    if (shapeState) {
+      fanSubscriptionError(shapeState.errorCallbacks, buildSubscriptionError(message));
+    }
+  }
+  handlePokeStart(message) {
+    if (this.pokeBuffers.size >= LunoraClient.MAX_POKE_BUFFERS) {
+      const oldest = this.pokeBuffers.keys().next().value;
+      if (oldest !== void 0) {
+        this.pokeBuffers.delete(oldest);
+      }
+    }
+    this.pokeBuffers.set(message.pokeId, { baseCheckpoint: message.baseCheckpoint, epoch: message.epoch, lastMutationId: /* @__PURE__ */ new Map(), parts: /* @__PURE__ */ new Map() });
+  }
+  handlePokePart(message) {
+    const buffer = this.pokeBuffers.get(message.pokeId);
+    if (!buffer) {
+      return;
+    }
+    const existing = buffer.parts.get(message.shapeId) ?? [];
+    existing.push(...message.rowsPatch);
+    buffer.parts.set(message.shapeId, existing);
+    if (message.lastMutationId !== void 0) {
+      buffer.lastMutationId.set(message.shapeId, message.lastMutationId);
+    }
+  }
+  handlePokeEnd(message) {
+    const buffer = this.pokeBuffers.get(message.pokeId);
+    if (!buffer) {
+      return;
+    }
+    this.pokeBuffers.delete(message.pokeId);
+    for (const [shapeId, ops] of buffer.parts) {
+      const state = this.shapeSubscriptions.get(shapeId);
+      if (!state) {
+        continue;
+      }
+      const epochForked = buffer.epoch !== void 0 && state.serverEpoch !== void 0 && buffer.epoch !== state.serverEpoch;
+      const baseDiverged = buffer.baseCheckpoint !== void 0 && state.serverCursor !== void 0 && state.serverCursor !== buffer.baseCheckpoint;
+      if (epochForked || baseDiverged) {
+        state.rows.clear();
+        state.serverCursor = void 0;
+        state.serverEpoch = void 0;
+        this.emitShapeRows(state);
+        this.sendShapeSubscribeIfOpen(state);
+        continue;
+      }
+      applyRowOpsToView(state.rows, ops);
+      if (message.checkpoint !== void 0) {
+        state.serverCursor = message.checkpoint;
+      }
+      if (message.epoch !== void 0) {
+        state.serverEpoch = message.epoch;
+      }
+      const watermark = buffer.lastMutationId.get(shapeId);
+      if (watermark !== void 0) {
+        state.lastMutationId = watermark;
+      }
+      this.emitShapeRows(state);
+      state.onCheckpoint?.({ checkpoint: state.serverCursor, mutationId: state.lastMutationId });
+    }
+  }
+  /** Materialize a shape's keyed view to an array and invoke its callbacks. */
+  // eslint-disable-next-line class-methods-use-this -- a pure state→callback fan-out kept beside the shape-subscription pipeline it serves.
+  emitShapeRows(state) {
+    const rows = [...state.rows.values()];
+    for (const shapeCallback of state.callbacks) {
+      try {
+        shapeCallback(rows);
+      } 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.serverBase = payload;
+    if (message.cursor !== void 0) {
+      state.serverCursor = message.cursor;
+    }
+    if (message.epoch !== void 0) {
+      state.serverEpoch = message.epoch;
+    }
+    this.persistQueryValue(state);
+    dropConfirmedLayers(state, state.serverCursor);
+    notifySubscription(state, state.optimisticLayers.length === 0 ? payload : foldOptimistic(payload, state.optimisticLayers));
+  }
+  /**
+   * 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;
+    }
+    this.ackAndAdvanceCursor(state, message.cursor, message.epoch);
+  }
+  /**
+   * Handle a `settled` frame: a write touched one of this subscription's read
+   * tables but produced a byte-identical result, so the server suppressed the
+   * data frame. Like {@link handleResumeMessage} the value didn't change — we
+   * advance the resume position and re-persist — but we ALSO surface the echoed
+   * custom-mutator watermark via `onCheckpoint` so a `@lunora/db` list
+   * collection drops the optimistic overlay for the confirmed write (otherwise
+   * its checkpoint gate, fed only by data frames, would hang forever). Sent
+   * only to custom-mutator clients; plain `useQuery` subscribers leave
+   * `onCheckpoint` unset and this is a near no-op.
+   */
+  handleSettledMessage(message) {
+    const state = this.subscriptions.getById(message.id);
+    if (!state) {
+      return;
+    }
+    this.ackAndAdvanceCursor(state, message.cursor, message.epoch);
+    if (message.lastMutationId !== void 0) {
+      state.lastMutationId = message.lastMutationId;
+    }
+    for (const onCheckpoint of state.checkpointCallbacks) {
+      onCheckpoint({ checkpoint: state.serverCursor, mutationId: state.lastMutationId });
+    }
+  }
+  /**
+   * Mark `state` acked and, when the frame carries a newer cursor/epoch than
+   * the cached position, advance the resume watermark and re-persist. Shared by
+   * the `resume` and `settled` frame handlers — both acknowledge "nothing the
+   * client must re-render changed, but the resume position may have moved".
+   */
+  ackAndAdvanceCursor(state, cursor, epoch) {
+    state.acked = true;
+    if (cursor !== void 0 && cursor !== state.serverCursor || epoch !== void 0 && epoch !== state.serverEpoch) {
+      if (cursor !== void 0) {
+        state.serverCursor = cursor;
+      }
+      if (epoch !== void 0) {
+        state.serverEpoch = epoch;
+      }
+      this.persistQueryValue(state);
+      if (dropConfirmedLayers(state, state.serverCursor)) {
+        notifySubscription(state, foldOptimistic(state.serverBase, state.optimisticLayers));
+      }
+    }
+  }
+  /**
+   * 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.serverBase !== void 0) {
+      const merged = applyDelta(state.serverBase, 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() {
+    this.tokenExpiredListeners.emit();
+  }
+  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() {
+    if (this.authSubject !== void 0) {
+      return this.authSubject === null ? null : `subj:${this.authSubject}`;
+    }
+    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.emitItemSettled(item, "rejected", error);
+    }
+    this.clearQueryCacheForIdentityChange();
+  }
+  /**
+   * Migrate every live identity stamp from `from` to `to` — used when the auth
+   * identity label changes but the underlying credential (token) does NOT, e.g.
+   * the user id resolves a tick after the token was set. The in-memory
+   * `queuedIdentities` map is the flush-time source of truth, so re-stamping it
+   * keeps the in-flight writes replayable under the new (more stable) identity
+   * instead of the flush guard discarding them as a mismatch.
+   */
+  restampQueuedIdentity(from, to) {
+    for (const [id, stamp] of this.queuedIdentities) {
+      if (stamp === from) {
+        this.queuedIdentities.set(id, to);
+      }
+    }
+  }
+  /**
+   * 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);
+        this.emitItemSettled(item, "rejected", error);
+        continue;
+      }
+      this.queuedIdentities.delete(item.id ?? "");
+      try {
+        let commitCursor;
+        const value = await this.rpc(item.functionPath, item.args, item.shardKey, {
+          captureBookmark: true,
+          mutationId: item.id,
+          onCommitCursor: (cursor) => {
+            commitCursor = cursor;
+          }
+        });
+        this.unpersist(item.id);
+        item.onCommit?.(commitCursor);
+        item.resolve(value);
+        this.emitItemSettled(item, "committed");
+      } catch (error) {
+        if (error.code !== void 0) {
+          this.unpersist(item.id);
+          item.reject(error);
+          this.emitItemSettled(item, "rejected", error);
+          continue;
+        }
+        this.offlineQueue.requeue(drained.slice(index));
+        return;
+      }
+    }
+  }
+}
+
+export { LunoraClient };