@lunora/client 1.0.0-alpha.9 → 1.0.0-alpha.91

package/dist/packem_shared/LunoraClient-C4eFp92b.mjs

@@ -1,2598 +0,0 @@
-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 { OfflineQueue, nextId, reportPersistenceError } from './OfflineQueue-eJBiWPfg.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;
-  /** Durable read cache (Pillar 2); `undefined` when `queryCache` is omitted or `false`. */
-  queryCache;
-  /**
-   * Values restored from the `queryCache` at construction, keyed by the
-   * read-cache key, awaiting the `subscribe()` that will consume them. A
-   * key is consumed (deleted) the first time its subscription is created, so
-   * the cache only ever seeds the initial value — live frames take over after.
-   */
-  hydratedQueryCache = /* @__PURE__ */ new Map();
-  /**
-   * Coalesced read-cache writes: the latest value per key, flushed to
-   * the `queryCache` on a short debounce so a burst of deltas persists once.
-   */
-  pendingCacheWrites = /* @__PURE__ */ new Map();
-  cacheFlushTimer;
-  subscriptions = new SubscriptionRegistry();
-  /** One {@link ShardConnection} per shard key (keyed by `shardKey ?? ""`). */
-  connections = /* @__PURE__ */ new Map();
-  /** Default `connect`-envelope context applied to a shard with no explicit override. */
-  defaultConnectionContext;
-  /**
-   * Per-shard `connect`-envelope context registered via `setConnectionContext`
-   * (keyed by `shardKey ?? ""`), overriding `defaultConnectionContext`. Sent
-   * on every socket open so it replays across reconnects, and forwarded to the
-   * server's `onConnect`/`onDisconnect` lifecycle hooks. This holds only the
-   * imperative (last-writer-wins) override; refcounted holders registered via
-   * `acquireConnectionContext` live in `connectionContextHolders` and take
-   * precedence — see `effectiveConnectionContext`.
-   */
-  connectionContexts = /* @__PURE__ */ new Map();
-  /**
-   * Per-shard stack of refcounted connection-context holders (keyed by
-   * `shardKey ?? ""`), registered via `acquireConnectionContext`. Each holder
-   * is an opaque token carrying its `context`; the most-recently acquired
-   * holder wins (last-writer-wins among live holders), and the context is only
-   * cleared for a shard once its last holder releases — so two concurrently
-   * mounted presence hooks on the same shard can't stomp each other's context
-   * on cleanup. A holder is identified by reference identity so a release
-   * removes exactly the right one regardless of stack position.
-   */
-  connectionContextHolders = /* @__PURE__ */ new Map();
-  // `null` is the public sentinel for "signed out" across getAuthToken /
-  // setAuthToken / onAuthTokenChange — part of the exported API contract.
-  // eslint-disable-next-line unicorn/no-null -- public auth-token contract sentinel
-  authToken = null;
-  /**
-   * Identity stamp recorded against each queued offline mutation, keyed by
-   * the queue-assigned mutation id. Captured at enqueue from the auth token
-   * in effect at the time, and re-checked at flush so a queued write can
-   * never replay under a different identity than the one that issued it.
-   * See `identityFingerprint` for the fingerprint shape.
-   */
-  queuedIdentities = /* @__PURE__ */ new Map();
-  closed = false;
-  /** Subscribers to auth-token changes (see `onAuthTokenChange`). */
-  authTokenListeners = 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();
-  /**
-   * 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.queryCache = options.queryCache === false ? void 0 : options.queryCache;
-    this.onPersistenceError = options.offlineQueue?.onPersistenceError;
-    this.offlineQueue = new OfflineQueue(options.offlineQueue, options.persistence, (entry, error) => {
-      this.emitItemSettled(entry, "rejected", error);
-    });
-    this.outbox = options.outbox;
-    this.clientId = options.clientId ?? `client-${nextId()}`;
-    if (this.persistence) {
-      queueMicrotask(() => {
-        this.hydratePersistedQueue().catch(() => void 0);
-      });
-    }
-    if (this.queryCache) {
-      queueMicrotask(() => {
-        this.hydrateQueryCache().catch(() => void 0);
-      });
-    }
-  }
-  // --- Auth helpers -------------------------------------------------------
-  /**
-   * Set (or clear) the bearer token sent on every HTTP RPC. Notifies any
-   * {@link onAuthTokenChange} listeners so React hooks like `useAuth` stay in
-   * sync across all mounted instances.
-   *
-   * Does NOT update the WebSocket auth — the WS token is fixed at upgrade
-   * time and lives in the URL. To refresh live WS auth, call
-   * {@link setWsToken} explicitly, which closes existing shard sockets to
-   * force a reconnect with the new credential.
-   */
-  setAuthToken(token) {
-    if (this.authToken === token) {
-      return;
-    }
-    this.authToken = token;
-    this.rejectQueuedForIdentityChange();
-    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;
-  }
-  /**
-   * 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;
-    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.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 {
-    }
-  }
-  /**
-   * Load every cached query into {@link hydratedQueryCache} so the next
-   * `subscribe()` for each key seeds its initial value off disk. A
-   * subscription created before this resolves simply misses the cache (it
-   * gets a live snapshot as before); the gate at seed time also drops any
-   * entry whose stamped identity no longer matches the current one.
-   */
-  async hydrateQueryCache() {
-    if (!this.queryCache) {
-      return;
-    }
-    try {
-      const entries = await this.queryCache.load();
-      for (const { key, ...entry } of entries) {
-        this.hydratedQueryCache.set(key, entry);
-      }
-    } catch {
-    }
-  }
-  /**
-   * Consume the hydrated read-cache entry for a key (if any), gated on
-   * identity. The entry is removed whether or not it matches — the cache only
-   * ever seeds a subscription's first value. A mismatch (the cache was written
-   * under a different identity) yields `undefined` so a signed-out cache never
-   * leaks into a new session.
-   */
-  takeHydratedCache(functionPath, argsKey, shardKey) {
-    const key = queryCacheKey(functionPath, argsKey, shardKey);
-    const entry = this.hydratedQueryCache.get(key);
-    if (entry === void 0) {
-      return void 0;
-    }
-    this.hydratedQueryCache.delete(key);
-    return entry.identity === this.identityFingerprint() ? entry : void 0;
-  }
-  /**
-   * Queue a coalesced read-cache write for a subscription's current value.
-   * Latest-wins per key; flushed on a short debounce so a delta burst writes
-   * once. No-op when the read cache is disabled or the value is undefined
-   * (nothing to render offline).
-   */
-  persistQueryValue(state) {
-    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.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() {
-    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();
-  }
-  /**
-   * 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 };