@lunora/client 1.0.0-alpha.6 → 1.0.0-alpha.60

package/dist/packem_shared/lunora-client.d-CEJvJAXn.d.mts

@@ -0,0 +1,2295 @@
+import { F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClientOptions, a as Unsubscribe, U as User, W as WsTokenProvider, S as ShardTrafficResult, b as ScheduleRecord, c as SchedulerStatus, d as WorkflowInstanceStatus, e as WorkflowInstancePage, f as WorkflowInstanceDetail, g as WorkflowInstanceAction, h as FunctionDescriptor, i as StorageListPage, G as GlobalTableInfo, j as GlobalFilterClause, k as GlobalTablePage, l as GlobalFacetResult, H as HttpStreamRef, m as HttpStreamArgsOf, n as HttpStreamChunkOf } from "./types.d-BOB755CV.mjs";
+import { CronJobInfo, VectorIndexSummary, VectorQueryMatch, PipelineLogQuery, PipelineLogPage, KvNamespaceSummary, KvKeyListResult, KvValueResult, AuthUser, AuthPage, AuthImpersonation, AuthCapabilities, AuthConfigInfo, AuthSession } from '@lunora/runtime';
+/**
+ * Reactive key-value store for local-only client state.
+ *
+ * Unlike a server {@link SubscriptionState} (which tracks a live WS connection,
+ * an `acked` flag, `serverBase`, optimistic layers, and the full subscription
+ * machinery), a `ClientQueryRef` is purely local — no server round-trip, no
+ * WebSocket, no persistence. It exists so framework adapters can offer a
+ * `useClientQuery` hook whose values survive component remounts and are shared
+ * across every consumer of the same ref, with none of the ceremony or coupling
+ * of a dedicated context provider.
+ *
+ * The store lives inside `LunoraClient` (a private field) and is surfaced through
+ * `client.getClientQuery(ref)` / `setClientQuery(ref, value)` /
+ * `subscribeClientQuery(ref, callback)`.
+ */
+/** Opaque handle for a typed client-local query slot. */
+interface ClientQueryRef<T = unknown> {
+  /** Default value when no value has been set explicitly. */
+  readonly defaultValue: T;
+  /** Stable identity for the slot. Must be unique within a client instance. */
+  readonly key: string;
+}
+/**
+ * Create a typed {@link ClientQueryRef}. Call once per slot at module scope
+ * (or inside a component module) — the ref object is the stable identity.
+ * @example
+ * ```ts
+ * // lunora/client-queries.ts
+ * import { createClientQuery } from "@lunora/client";
+ *
+ * export const sidebarOpen = createClientQuery("sidebarOpen", true);
+ * export const selectedMessageId = createClientQuery("selectedMessageId", undefined as string | undefined);
+ * ```
+ */
+declare const createClientQuery: <T>(key: string, defaultValue: T) => ClientQueryRef<T>;
+/**
+ * The machine-readable error codes a client can observe on a failed
+ * RPC/batch/subscription. Mirrors the server's `CODE_STATUS` keys
+ * (`@lunora/server`'s `error.ts`) by hand — the client is framework-neutral and
+ * must never import the server package (wrong dependency direction / would pull
+ * the server into the browser bundle). Keep this list in sync when a server code
+ * is added or removed (see the drift-guard note in the plan/maintenance docs).
+ */
+declare const LUNORA_ERROR_CODES: readonly ["BAD_REQUEST", "CONFLICT", "COUNT_RLS_UNSUPPORTED", "FORBIDDEN", "INTERNAL_SERVER_ERROR", "MASK_UNSUPPORTED", "NOT_FOUND", "NOT_IMPLEMENTED", "RELATION_PREDICATE_UNSUPPORTED", "TOO_MANY_REQUESTS", "UNAUTHORIZED", "UNPROCESSABLE"];
+/** A machine-readable error `code` the client may observe. Mirror of the server's `LunoraErrorCode`. */
+type LunoraErrorCode = (typeof LUNORA_ERROR_CODES)[number];
+/** Error code the server uses for optimistic-concurrency conflicts (HTTP 409). */
+declare const CONFLICT_ERROR_CODE = "CONFLICT";
+/**
+ * Whether an unknown rejection is an optimistic-concurrency conflict — the
+ * server lost a write race and the caller should refetch and retry (or surface
+ * the conflict). Structural check on the `code` property the client attaches
+ * when decoding the worker's `{ error: { code, message } }` envelope.
+ */
+declare const isConflictError: (error: unknown) => error is Error & {
+  code: "CONFLICT";
+};
+/**
+ * Whether a rejection is an RLS/policy denial (`FORBIDDEN`, HTTP 403) — the
+ * caller is authenticated but not permitted to read/write the row. The most
+ * common per-call error a UI must handle in an RLS-first app.
+ */
+declare const isForbiddenError: (error: unknown) => error is Error & {
+  code: "FORBIDDEN";
+};
+/** Whether a rejection is an authentication failure (`UNAUTHORIZED`, HTTP 401) — no/invalid identity. */
+declare const isUnauthorizedError: (error: unknown) => error is Error & {
+  code: "UNAUTHORIZED";
+};
+/**
+ * Whether a rejection is a rate-limit denial (`TOO_MANY_REQUESTS`, HTTP 429).
+ * The retry hint (if the server sent one) is read with {@link getRetryAfterMs}.
+ */
+declare const isRateLimitedError: (error: unknown) => error is Error & {
+  code: "TOO_MANY_REQUESTS";
+};
+/**
+ * Read the server's machine-readable `code` off a rejection, narrowed to the
+ * known {@link LunoraErrorCode} union. Returns `undefined` for a non-`Error`, a
+ * missing code, or an unrecognized code string (forward-compat server codes read
+ * as `undefined` here rather than being falsely narrowed).
+ */
+declare const getErrorCode: (error: unknown) => LunoraErrorCode | undefined;
+/**
+ * Read the rate-limit retry hint (`data.retryAfterMs`) off a
+ * `TOO_MANY_REQUESTS` rejection without hand-casting the `unknown` `data`
+ * payload. Returns the finite millisecond value the server sent, or `undefined`
+ * when absent/non-numeric. Pair with {@link isRateLimitedError}.
+ */
+declare const getRetryAfterMs: (error: unknown) => number | undefined;
+type SubscriptionCallback = (data: unknown) => void;
+/** A subscription-scoped error the server pushed for this subscription id. */
+interface SubscriptionError {
+  code?: string;
+  message: string;
+}
+type SubscriptionErrorCallback = (error: SubscriptionError) => void;
+/**
+ * One active per-call optimistic transform layered onto a subscription. The
+ * displayed value is the authoritative {@link SubscriptionState.serverBase}
+ * folded through every layer's `transform`, in order — so an incoming server
+ * frame re-folds the still-pending layers onto the new base (rebasing) instead
+ * of clobbering them. A layer is dropped — gaplessly — once a `data`/`delta`
+ * frame whose `cursor >= commitCursor` arrives (its write is now reflected in
+ * `serverBase`); `commitCursor` is the CDC cursor the server echoed on the
+ * mutation's response, and stays `undefined` while the write is still queued/
+ * in-flight (so the overlay survives unrelated deltas until confirmed).
+ */
+interface OptimisticLayer {
+  /** The committed CDC cursor (from the mutation response); `undefined` until confirmed. */
+  commitCursor?: number;
+  readonly id: symbol;
+  readonly transform: (current: unknown) => unknown;
+}
+interface SubscriptionState {
+  /** True once the server has acked the subscription on the current socket. */
+  acked: boolean;
+  readonly args: Record<string, unknown>;
+  /**
+   * Stable wire-key of `args` (`stableWireKey`), computed once at subscribe
+   * time. Cached so the optimistic-update fan-out can compare against a
+   * mutation's args key without re-serializing every subscription's args on
+   * every mutation.
+   */
+  readonly argsKey: string;
+  readonly callbacks: Set<SubscriptionCallback>;
+  /**
+   * Notified when a `settled` frame advances this subscription's watermark — a
+   * write touched the subscription's tables but the result was byte-identical,
+   * so the server suppressed the data frame. A `@lunora/db` list collection
+   * uses this to drop the optimistic overlay for the confirmed write.
+   *
+   * A SET (not a single slot) because `SubscriptionState` is SHARED across
+   * every subscriber to the same `(fn, args, shardKey)`: a `@lunora/db`
+   * collection may subscribe to a query a plain `useQuery` already opened, so
+   * each subscriber registers its own callback (mirroring `callbacks` /
+   * `errorCallbacks`) and a `settled` frame fans out to all of them. Plain
+   * `useQuery` consumers register nothing, leaving the set empty.
+   */
+  readonly checkpointCallbacks: Set<(watermark: {
+    checkpoint?: number;
+    mutationId?: number;
+  }) => void>;
+  /** Notified when the server rejects this subscription (e.g. admin auth). */
+  readonly errorCallbacks: Set<SubscriptionErrorCallback>;
+  readonly fn: FunctionReference;
+  readonly id: string;
+  /**
+   * The highest custom-mutator `mutationId` from this client the server has
+   * applied, captured from the last `settled` frame (the suppressed-list-frame
+   * watermark). Forwarded to {@link SubscriptionState.checkpointCallbacks}.
+   * Absent until a `settled` frame arrives.
+   */
+  lastMutationId?: number;
+  /** Last known value, used to short-circuit `useQuery`-style consumers. */
+  lastValue: unknown;
+  /**
+   * Active per-call optimistic layers, in application order (see
+   * {@link OptimisticLayer}). Empty for subscriptions with no pending per-call
+   * optimistic write — the common case, where `lastValue` tracks `serverBase`
+   * exactly and behaviour is identical to a plain server-value assignment.
+   */
+  optimisticLayers: OptimisticLayer[];
+  /**
+   * The authoritative server value the optimistic layers fold onto — the value
+   * with NO optimistic overlay. Tracks `lastValue` exactly whenever no layers
+   * are active; diverges only while a per-call optimistic write is pending. A
+   * server frame updates this (and re-folds the layers); the durable read cache
+   * persists this, never the optimistic overlay.
+   */
+  serverBase: unknown;
+  /**
+   * The `__cdc_log` high-watermark (`cursor`) the `lastValue` reflects,
+   * captured from the last `data`/`delta`/`resume` frame. Persisted to the
+   * durable read cache and replayed as `sinceSeq` on reconnect so the server
+   * can resume instead of re-snapshotting (Pillar 1b/2). Absent until the
+   * first cursor-stamped frame arrives.
+   */
+  serverCursor?: number;
+  /**
+   * The CDC `epoch` token the `serverCursor` belongs to, captured from the
+   * same frame. Replayed as `sinceEpoch` on reconnect so the server resumes
+   * only when the client is still on the same changelog timeline — a reset or
+   * recycled shard advertises a new epoch, forcing a fresh snapshot. Absent
+   * until the first epoch-stamped frame arrives.
+   */
+  serverEpoch?: string;
+  readonly shardKey?: string;
+}
+/**
+ * Active subscription registry. The client keys subscriptions by
+ * `(functionPath, stableWireKey(args), shardKey)` so duplicate calls share a
+ * single server-side registration. Args are stably encoded (keys sorted at every
+ * depth) so two structurally-equal arg records constructed with a different key
+ * order (`{ a, b }` vs `{ b, a }`) collapse to the same key instead of leaking a
+ * duplicate subscription. Encoding the args' **wire form** keeps the key
+ * byte-identical for pure-JSON args while giving wire-typed args (`bigint`,
+ * `Date`, bytes, …) distinct stable tokens instead of a throw.
+ */
+declare class SubscriptionRegistry {
+  static key(functionPath: string, args: Record<string, unknown>, shardKey?: string): string;
+  private readonly byKey;
+  private readonly byId;
+  get(key: string): SubscriptionState | undefined;
+  getById(id: string): SubscriptionState | undefined;
+  add(state: SubscriptionState): void;
+  remove(state: SubscriptionState): void;
+  all(): SubscriptionState[];
+}
+/**
+ * Read/write handle over the client's live query cache, handed to a mutation's
+ * `withOptimisticUpdate` callback so a single mutation can optimistically patch
+ * many subscribed queries at once (Convex's `OptimisticLocalStore` model).
+ *
+ * `getQuery` reads the current value (server value or any still-pending
+ * optimistic override) of a subscribed query; `setQuery` registers a constant
+ * optimistic layer on top. The whole batch rebases onto incoming deltas and
+ * settles together — confirmed on the mutation's commit cursor, or rolled back
+ * on failure — the same per-subscription layer machinery the single-query
+ * per-call `optimistic` transform uses, generalized to N queries.
+ */
+interface OptimisticLocalStore {
+  /**
+   * Every loaded subscription on `function_`, regardless of args, paired with
+   * the args it was subscribed under. Mirrors Convex's `getAllQueries` — handy
+   * when a write must patch every variant of a list query (all channels,
+   * all filters) without enumerating their args up front.
+   */
+  getAllQueries: <F extends FunctionReference>(function_: F) => {
+    args: ArgsOf<F>;
+    value: ReturnOf<F> | undefined;
+  }[];
+  /**
+   * Current cached value for the subscribed `(function_, args)` query, or
+   * `undefined` when nothing is subscribed/loaded for it. Reflects any
+   * optimistic override already written in this batch.
+   */
+  getQuery: <F extends FunctionReference>(function_: F, args: ArgsOf<F>) => ReturnOf<F> | undefined;
+  /**
+   * Write an optimistic override for the subscribed `(function_, args)`
+   * query. A no-op (returns without effect) when no subscription matches —
+   * mirroring Convex, where you only patch queries the page is watching.
+   */
+  setQuery: <F extends FunctionReference>(function_: F, args: ArgsOf<F>, value: ReturnOf<F> | undefined) => void;
+}
+/** A mutation's multi-query optimistic update: read/write the cache via `localStore`. */
+type OptimisticUpdate<Args> = (localStore: OptimisticLocalStore, args: Args) => void;
+/**
+ * Build an {@link OptimisticLocalStore} bound to a subscription registry and the
+ * mutation's shard key. Each `setQuery(value)` registers a constant-value layer
+ * on its target subscription (via `applyOptimisticLayer`): the predicted value
+ * survives incoming server deltas (re-clamped, masking concurrent changes to that
+ * query — not merged) and drops gaplessly on the mutation's commit cursor, like
+ * the single-query per-call `optimistic` path. Returns the store plus the ordered
+ * `confirm` (success) and `rollback` (failure) closures every `setQuery` produced,
+ * so the caller settles the whole batch when the mutation does.
+ */
+declare const createLocalStore: (subscriptions: SubscriptionRegistry, shardKey: string | undefined) => {
+  confirms: ((commitCursor: number | undefined) => void)[];
+  rollbacks: (() => void)[];
+  store: OptimisticLocalStore;
+};
+declare const DEFAULT_MAX_BUFFER = 1024;
+interface StreamHandle<T = unknown> {
+  /** Mark the stream complete (no more chunks); resolves any pending consumer to `done:true`. */
+  readonly complete: () => void;
+  /** Surface an error to any pending consumer; subsequent pushes are dropped. */
+  readonly fail: (error: Error) => void;
+  /**
+   * Push one chunk. Silent no-op once the stream is `complete`, `fail`-ed,
+   * or `cancel`-ed. When the buffer is already at `maxBuffer`, the stream
+   * is failed with a `STREAM_BACKPRESSURE` error and the push is dropped —
+   * the producer never sees a thrown exception.
+   */
+  readonly push: (value: T) => void;
+}
+interface StreamIterable<T> extends AsyncIterable<T> {
+  /** Cancel the stream from the consumer side: closes the iterator and notifies the registered canceller. */
+  cancel: () => void;
+}
+/**
+ * Build a stream handle paired with an async-iterable. The handle is the
+ * server-driven side (the WS dispatcher pushes chunks / completes / errors);
+ * the iterable is what the user awaits. `onCancel` is invoked exactly once
+ * when the consumer calls `.cancel()` (or `.return()`) so the client can
+ * send a `{type:"unsubscribe"}` frame to the server.
+ */
+declare const createStream: <T>(options: {
+  maxBuffer?: number;
+  onCancel: () => void;
+}) => {
+  handle: StreamHandle<T>;
+  iterable: StreamIterable<T>;
+};
+type WSState = "idle" | "connecting" | "open" | "closed";
+/**
+ * Aggregate live-socket health across every shard connection, for a UI status
+ * indicator. `idle` = no socket opened yet; `connecting` = at least one socket
+ * is (re)connecting and none is open; `connected` = at least one socket is open;
+ * `offline` = sockets exist but all are down (between reconnect attempts).
+ */
+type ConnectionStatus = "connected" | "connecting" | "idle" | "offline";
+/** One shard's socket + watermark state in a {@link LunoraClient.debug} snapshot. */
+interface ClientDebugShard {
+  /**
+   * Highest custom-mutator watermark the server has echoed for this client on this
+   * shard. A write whose `clientSeq` is above this has been sent but not confirmed
+   * — the first thing to check when an optimistic overlay won't clear.
+   */
+  confirmedMutationWatermark: number;
+  /** Whether a `WebSocket` object currently exists (distinct from it being open). */
+  hasSocket: boolean;
+  /** `undefined` for the default (unsharded) connection. */
+  shardKey: string | undefined;
+  /** Whether this shard's socket has ever completed a handshake — gates offline queueing. */
+  wasEverConnected: boolean;
+  wsState: WSState;
+}
+/** One live query or shape subscription in a {@link LunoraClient.debug} snapshot. */
+interface ClientDebugSubscription {
+  /** Whether the server has acknowledged the subscription on the current socket. */
+  acked: boolean;
+  /** `namespace:fn` for a query, `shape:<name>` for a replication shape. */
+  functionPath: string;
+  id: string;
+  kind: "query" | "shape";
+  /** Highest custom-mutator watermark echoed on THIS subscription (absent until a `settled`/poke frame arrives). */
+  lastMutationId?: number;
+  /** Per-call optimistic layers still folded onto this subscription's value — a non-zero count with no pending write is a leak. */
+  pendingOptimisticLayers: number;
+  /** Replicated rowset size (shapes only). */
+  rowCount?: number;
+  /** The `__cdc_log` cursor the current value reflects. */
+  serverCursor?: number;
+  shardKey: string | undefined;
+  /** How many callers share this subscription (subscriptions are deduped by `(fn, args, shard)`). */
+  subscriberCount: number;
+}
+/**
+ * Everything the sync engine believes at one instant — see
+ * {@link LunoraClient.debug} for why this exists.
+ */
+interface ClientDebugSnapshot {
+  /** The watermark key the server's custom-mutator protocol advances per `clientSeq`. */
+  clientId: string;
+  closed: boolean;
+  connectionStatus: ConnectionStatus;
+  /** Writes waiting in the built-in offline queue (not the `@lunora/db` outbox). */
+  pendingWrites: number;
+  shards: ClientDebugShard[];
+  subscriptions: ClientDebugSubscription[];
+}
+/**
+ * Terminal verdict for a mutation that passed through the offline queue,
+ * delivered to {@link LunoraClient.onMutationSettled}.
+ *
+ * Unlike the Promise returned by {@link LunoraClient.mutation} — which only the
+ * original caller can await, and which no longer exists after a reload — this
+ * fires for *every* queued write the server (or the queue) reaches a verdict on,
+ * including writes restored from durable storage in a later session. It is the
+ * channel a UI uses to tell the user "your queued change couldn't be saved"
+ * instead of silently dropping a rolled-back optimistic row.
+ *
+ * `status: "rejected"` carries the failure `code` (e.g. `CONFLICT`,
+ * `OFFLINE_QUEUE_OVERFLOW`, `OFFLINE_IDENTITY_CHANGED`) and the `error`.
+ * `hadAwaiter` is `false` for a write whose original `mutation()` Promise is
+ * gone (a hydrated/post-reload replay or an eviction), so a listener can tell
+ * "the caller already saw this" apart from "nothing else will report this".
+ */
+interface MutationSettledEvent {
+  /** The write's args, so a listener can describe or re-offer the change. */
+  readonly args: Record<string, unknown>;
+  /** Server/queue error code on `rejected` (e.g. `CONFLICT`), when present. */
+  readonly code?: string;
+  /** The rejection error on `status: "rejected"`. */
+  readonly error?: unknown;
+  /** The `<file>:<function>` reference of the mutation. */
+  readonly functionPath: string;
+  /** Whether a live caller was still awaiting this write's `mutation()` Promise. */
+  readonly hadAwaiter: boolean;
+  /** The write's stable id (idempotency key / queue id). */
+  readonly id: string;
+  /** Shard the write targeted, if any. */
+  readonly shardKey?: string;
+  /** Terminal outcome. */
+  readonly status: "committed" | "rejected";
+}
+/**
+ * Per-call options for {@link LunoraClient.action} — just `shardKey`, since an
+ * action is not a write and carries none of the optimistic machinery. Exported
+ * (at the end of this file) for the same reason {@link MutationCallOptions} is:
+ * so the framework adapters (`@lunora/react`, `/solid`, `/svelte`, `/vue`,
+ * `/angular`) type their `call(args, options?)` against one canonical
+ * definition. Add an option here and every adapter forwards it; re-declare it
+ * per adapter and they silently cannot.
+ */
+interface ActionCallOptions {
+  /** Route the call to a specific shard. */
+  shardKey?: string;
+}
+/**
+ * Per-call options for {@link LunoraClient.mutation} — the optimistic-update
+ * machinery plus `shardKey`. Exported (at the end of this file) so the framework
+ * adapters (`@lunora/react`, `/solid`, `/svelte`, `/vue`) can type their
+ * `mutate(args, options?)` against one canonical definition instead of
+ * re-declaring it.
+ */
+interface MutationCallOptions<TCurrent = unknown, TValue = unknown, TArgs = unknown> {
+  /**
+   * Override the auto-generated idempotency key (`x-lunora-mutation-id`). Lets a
+   * durable outbox replay a committed-but-unacked write under its *original* key
+   * so the server dedups it instead of applying it twice. Omit for normal calls —
+   * each then gets a fresh key.
+   */
+  mutationId?: string;
+  optimistic?: (current: TCurrent | undefined) => TValue;
+  /**
+   * Convex-parity multi-query optimistic update. Receives an
+   * `OptimisticLocalStore` over the live subscription cache plus the
+   * mutation's args, so one mutation can patch many subscribed queries at
+   * once; every write is rolled back atomically if the mutation fails.
+   */
+  optimisticUpdate?: OptimisticUpdate<TArgs>;
+  /**
+   * Sync predicate evaluated just before the offline queue replays this
+   * write on reconnect. When it returns `false` the mutation is dropped
+   * instead of replayed — use it to guard against replaying writes whose
+   * assumptions are no longer valid (e.g. the document it referred to was
+   * deleted by another client while this tab was offline).
+   */
+  precondition?: () => boolean;
+  shardKey?: string;
+}
+/** Callback a shape subscription invokes with its materialized rowset on every applied poke. */
+type ShapeCallback = (rows: Record<string, unknown>[]) => void;
+/**
+ * The high-water marks a shape poke has now synced to the client: `checkpoint`
+ * is the op-log cursor and `mutationId` the highest custom-mutator id the server
+ * echoed for this client. A `@lunora/db` collection feeds these into its
+ * checkpoint registry to drop optimistic overlays once the server's authoritative
+ * rows have landed.
+ */
+interface SyncWatermark {
+  checkpoint?: number;
+  mutationId?: number;
+}
+/**
+ * An `Error` carrying the server's machine-readable `code` and (for a
+ * `LunoraError`) structured `data`, plus an optional actionable `hint` (Markdown)
+ * and `docsUrl` resolved from the central error catalog. The client's public
+ * error contract for RPC/batch failures — a UI can render `hint`/`docsUrl` to
+ * tell the user how to fix the error. The `(string & {})` arm keeps
+ * forward-compat/unknown server codes assignable without losing autocomplete on
+ * the known {@link LunoraErrorCode} union.
+ */
+type LunoraClientError = Error & {
+  code?: LunoraErrorCode | (string & {});
+  data?: unknown;
+  docsUrl?: string;
+  hint?: string | string[];
+};
+/** One demuxed result slot of a {@link LunoraClient.batch} call (plan 088). */
+type BatchSlot = {
+  error: LunoraClientError;
+  ok: false;
+} | {
+  ok: true;
+  value: unknown;
+};
+/**
+ * Lunora browser/edge client. Talks RPC over HTTP and real-time deltas over
+ * a single multiplexed WebSocket.
+ *
+ * Reconnect, offline queueing, and optimistic updates are all handled here;
+ * see the package README for the wire protocol.
+ */
+declare 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. */
+  private static readonly MAX_POKE_BUFFERS;
+  /**
+   * Create a typed {@link ClientQueryRef}. Convenience wrapper around
+   * {@link createClientQuery} so you don't need a separate import.
+   * @example
+   * ```ts
+   * const sidebarOpen = LunoraClient.createClientQuery("sidebarOpen", true);
+   * ```
+   */
+  static createClientQuery<T>(key: string, defaultValue: T): ClientQueryRef<T>;
+  readonly url: string;
+  readonly wsUrl: string;
+  /** Local reactive store for {@link ClientQueryRef} values — no server round-trip. Private; reach it via `getClientQuery` / `setClientQuery` / `subscribeClientQuery`. */
+  private readonly clientQueryStore;
+  private wsToken;
+  /** Better-auth base path (trailing slash stripped) for the `get-session` lookup. */
+  private readonly authBasePath;
+  private readonly fetchImpl;
+  private readonly WebSocketImpl;
+  private readonly bookmark;
+  private readonly reconnectOptions;
+  /** WS connect timeout (ms); `0` disables it. See {@link LunoraClientOptions.connectTimeoutMs}. */
+  private readonly connectTimeoutMs;
+  /** Keepalive cadence (ms); `0` disables the heartbeat. See {@link LunoraClientOptions.heartbeatIntervalMs}. */
+  private readonly heartbeatIntervalMs;
+  private readonly 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.
+   */
+  private readonly outbox;
+  /** Stable per-client id stamped onto every `OutboxMutation` (custom-mutator watermark). */
+  private readonly clientId;
+  /**
+   * Highest CDC cursor this client has seen a write commit at, per shard key
+   * (`""` for the default shard) — the read-your-writes bookmark sent as
+   * `x-lunora-min-seq`.
+   *
+   * In memory only, and deliberately: it exists to keep THIS session's reads
+   * behind THIS session's writes. Persisting it across reloads would pin a
+   * fresh page to a cursor it has no reason to require and force needless
+   * fallbacks to the owner.
+   */
+  private readonly shardCursors;
+  /**
+   * The server's own name for the default shard (`defaultShardKey`), learned
+   * from the first response to a call that named no shard. `undefined` until
+   * then, which is why `cursorKeyFor` falls back to a placeholder entry that
+   * `learnDefaultShardKey` folds in once the name arrives.
+   */
+  private defaultShardKey;
+  /**
+   * `true` when the constructor's hydration microtask has finished loading the
+   * durable read cache (Pillar 2) into `hydratedQueryCache`. Signals that
+   * the cache is ready for synchronous `peekHydratedQuery` reads.
+   */
+  private readyResolved;
+  /** Resolvers for `whenReady()` — called once hydration completes. */
+  private readyResolve;
+  /**
+   * Promise that resolves once the durable read cache has been loaded. When
+   * `hydrateOnStart` is not set or no query cache is configured, resolves
+   * immediately (the constructor creates an already-resolved promise).
+   */
+  private readonly readyPromise;
+  /**
+   * Highest custom-mutator watermark the server has echoed for this client,
+   * nested by identity fingerprint (`identityFingerprint() ?? ""`) then shard
+   * bucket (`shardKey ?? ""`) — the DO tracks one `__client_watermark` per
+   * `(identity, clientId)` pair, not per bucket alone, so a bucket-only key
+   * would let a user switch claim the previous identity's sequence and wedge
+   * every push on `OUT_OF_ORDER` until a reload (plan 316). A nested map
+   * (rather than a single map composite-keyed by a joined string) is what a
+   * previous fix here tried and got wrong: an identity fingerprint or a
+   * `shardKey` is an arbitrary string, so any string delimiter — even one as
+   * exotic as U+FFFD — can appear in one operand and collide with the other
+   * (a fingerprint of `a<SEP>x` + bucket `y` joins to the same string as
+   * a fingerprint of `a` + bucket `x<SEP>y`), mixing two identities' watermarks.
+   * The nested map has no join step, so there is no delimiter to collide.
+   * `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.
+   */
+  private readonly clientWatermarks;
+  /** Monotonic per-client mutation counter backing the server `__client_watermark`. */
+  private outboxMutationCounter;
+  private readonly onPersistenceError;
+  private readonly persistence;
+  /** App/schema version stamped on persisted writes + cached reads; mismatches are purged. */
+  private readonly persistenceVersion;
+  /** Releases the multi-tab outbox-leader Web Lock on close (see `hydrateAsOutboxLeader`). */
+  private outboxLeaderRelease;
+  /** Durable read cache (Pillar 2); `undefined` when `queryCache` is omitted or `false`. */
+  private readonly 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.
+   */
+  private readonly hydratedQueryCache;
+  /**
+   * Coalesced read-cache writes: the latest value per key, flushed to
+   * the `queryCache` on a short debounce so a burst of deltas persists once.
+   */
+  private readonly pendingCacheWrites;
+  private cacheFlushTimer;
+  private readonly subscriptions;
+  /**
+   * Cross-tab coordinator; created only when `crossTabSync: true`. When the
+   * client is not the elected leader, all WebSocket operations are skipped.
+   * Not `readonly` — `close()` clears it (mirrors `outboxLeaderRelease`).
+   */
+  private tabCoordinator;
+  /**
+   * The leader's last-broadcast aggregate {@link ConnectionStatus}, mirrored
+   * on a follower tab — which owns no `ShardConnection` of its own to
+   * compute a status from (see `computeStatus`). `undefined` until the
+   * leader's first broadcast (falls back to `"idle"`), and reset back to
+   * `undefined` whenever this tab stops being a follower of the CURRENT
+   * leader (becomes leader itself, or the leader changes), so a stale
+   * mirror from a previous leader never survives a leadership change.
+   */
+  private leaderStatus;
+  /**
+   * Sticky "has the mirrored leader status ever reported `connected`" flag —
+   * the follower's counterpart to {@link ShardConnection.wasEverConnected},
+   * since a follower has no `ShardConnection` of its own. Feeds the
+   * offline-queue gate (see `mutation`) exactly like the real per-shard flag
+   * does on the leader/single-tab path.
+   */
+  private leaderWasEverConnected;
+  /** One {@link ShardConnection} per shard key (keyed by `shardKey ?? ""`). */
+  private readonly connections;
+  /** Default `connect`-envelope context applied to a shard with no explicit override. */
+  private readonly 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`.
+   */
+  private readonly connectionContexts;
+  /**
+   * 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.
+   */
+  private readonly connectionContextHolders;
+  private authToken;
+  /**
+   * Optional STABLE identity subject (a user id), the basis of the offline-queue
+   * identity stamp when supplied. Keeps a same-user token *refresh* from looking
+   * like an identity change (which would discard queued writes). `undefined` =
+   * not supplied, so identity falls back to a hash of the raw token. See
+   * `setAuthToken` / `identityFingerprint`.
+   */
+  private authSubject;
+  /**
+   * 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.
+   */
+  private readonly queuedIdentities;
+  /**
+   * Distinct shard keys with a mutation currently sitting in `offlineQueue`
+   * — fresh writes queued this session (`enqueueOfflineMutation`) or writes
+   * restored from durable storage (`hydratePersistedQueue`). A follower tab
+   * has no per-shard `ShardConnection` to iterate when its mirrored leader
+   * status turns `"connected"` (see the `onConnectionStatus` coordinator
+   * option), so this is what that flush walks instead. Entries are never
+   * removed — flushing an already-empty shard is a cheap no-op, and the set
+   * is bounded by the app's own distinct shard-key cardinality.
+   */
+  private readonly queuedOfflineShardKeys;
+  private closed;
+  /** Subscribers to auth-token changes (see `onAuthTokenChange`). */
+  private readonly authTokenListeners;
+  /** Subscribers to aggregate connection-status changes (see `onConnectionStatus`). */
+  private readonly statusListeners;
+  /** Subscribers notified when the server drops a socket for an expired token (see `onTokenExpired`). */
+  private readonly tokenExpiredListeners;
+  /** Subscribers to offline-queued mutation verdicts (see `onMutationSettled`). */
+  private readonly mutationSettledListeners;
+  /** Subscribers to the offline-queue pending-count (see `onPendingChange`). */
+  private readonly pendingChangeListeners;
+  /**
+   * 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.
+   */
+  private readonly whisperHandlers;
+  /** Last status broadcast, so we only notify listeners on an actual change. */
+  private lastStatus;
+  private nextSubId;
+  private nextStreamId;
+  /**
+   * 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.
+   */
+  private readonly streams;
+  /** Live shape subscriptions (partial replication), keyed by their wire id. */
+  private readonly shapeSubscriptions;
+  /**
+   * In-flight pokes being assembled between `pokeStart` and `pokeEnd`, keyed by
+   * `<connectionKey>\u0000<pokeId>`.
+   *
+   * The connection has to be in the key: `pokeId` is a per-DO counter that also
+   * resets on eviction, so a multi-shard client — one socket per shard, one map
+   * here — sees two shards mint `poke-1` concurrently. Keyed by `pokeId` alone
+   * their frames interleave into a single buffer: one shard applies the other's
+   * epoch (spurious fork → view wiped) and the other finds no buffer for its
+   * parts at all, silently dropping rows while the server's memo advances.
+   */
+  private readonly pokeBuffers;
+  private nextShapeId;
+  constructor(options: LunoraClientOptions);
+  /**
+   * Set (or clear) the bearer token sent on every HTTP RPC. Notifies any
+   * {@link onAuthTokenChange} listeners so React hooks like `useAuth` stay in
+   * sync across all mounted instances.
+   *
+   * Pass a STABLE `subject` (the user id) to key the offline-queue identity on
+   * it instead of the token bytes, so a token *refresh* (same user, new JWT)
+   * doesn't read as an identity change and discard queued writes. The subject is
+   * **sticky**: a later call that omits it (or passes `undefined`) keeps the
+   * established subject — so `setAuthToken(refreshedToken)` after a prior
+   * `setAuthToken(token, user.id)` retains the identity. Pass `null` to clear it
+   * (an explicit sign-out). Establishing the subject for the first time on an
+   * UNCHANGED token (e.g. the user id resolves a tick after the token was set)
+   * re-stamps any in-flight queued writes rather than dropping them — same
+   * credential, just a more stable label. A real user switch (the token AND
+   * subject both change) still drops the previous user's writes.
+   *
+   * Does NOT update the WebSocket auth — the WS token is fixed at upgrade
+   * time and lives in the URL. To refresh live WS auth, call
+   * {@link setWsToken} explicitly, which closes existing shard sockets to
+   * force a reconnect with the new credential.
+   */
+  setAuthToken(token: string | null, subject?: string | null): void;
+  getAuthToken(): string | null;
+  /**
+   * 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(): string | null;
+  /** This client's stable identifier — the watermark key the server's custom-mutator protocol advances per `clientSeq`. */
+  clientIdentifier(): string;
+  /**
+   * 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?: string): number;
+  /**
+   * 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.
+   */
+  callMutator(functionPath: string, args: Record<string, unknown>, options?: {
+    clientSeq?: number;
+    shardKey?: string;
+  }): Promise<{
+    applied: boolean;
+    result: unknown;
+  }>;
+  /**
+   * 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: (token: string | null) => void): Unsubscribe;
+  /**
+   * 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).
+   */
+  getCurrentUser(): Promise<User | 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.). Accepts a static string or a
+   * {@link WsTokenProvider} resolved fresh at every (re)connect — the channel
+   * for short-lived credentials like the minted ephemeral admin sub-token.
+   * Bearer tokens for HTTP RPC are independent — see {@link setAuthToken}.
+   */
+  setWsToken(token: string | undefined | WsTokenProvider): void;
+  /**
+   * 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: Record<string, unknown> | undefined, options?: {
+    shardKey?: string;
+  }): void;
+  /**
+   * 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: Record<string, unknown>, options?: {
+    shardKey?: string;
+  }): Unsubscribe;
+  /**
+   * 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: string, handler: (data: unknown, from?: string) => void, options?: {
+    shardKey?: string;
+  }): 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: string, data?: unknown, options?: {
+    shardKey?: string;
+  }): void;
+  /**
+   * 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: () => void): Unsubscribe;
+  /**
+   * Current aggregate live-socket status across all shard connections. See
+   * {@link ConnectionStatus}.
+   */
+  connectionStatus(): ConnectionStatus;
+  /**
+   * Subscribe to aggregate connection-status changes. Invokes `listener`
+   * immediately with the current status, then on every transition. Returns an
+   * unsubscribe function.
+   */
+  onConnectionStatus(listener: (status: ConnectionStatus) => void): Unsubscribe;
+  /**
+   * Number of offline writes waiting in the built-in queue to be sent — the
+   * depth for a "N changes waiting to sync" indicator. Counts writes that are
+   * queued (offline / mid-reconnect), not ones already in flight on the wire.
+   * A `@lunora/db` app whose writes ride the unified outbox should read
+   * `LunoraDb.pendingCount()` instead (this counts only the built-in queue).
+   */
+  pendingCount(): number;
+  /**
+   * A point-in-time snapshot of everything the sync engine believes right now:
+   * per-shard sockets and watermarks, every live query and shape subscription with
+   * its cursor and ack state, and the offline-queue depth.
+   *
+   * This exists because the alternative is `console.log`. When an optimistic
+   * overlay doesn't clear, the questions are always the same — *is the socket open?
+   * what watermark has the server confirmed for this shard? has this shape been
+   * poked since my write? is anything stuck in the queue?* — and none of them were
+   * answerable from outside the client, so every adopter ends up instrumenting the
+   * library by hand or building a bespoke policy layer around a symptom.
+   *
+   * Read it from a devtools console, log it next to a bug report, or render it in a
+   * debug panel. Pull-only and allocation-cheap; nothing here is reactive, so poll
+   * it or read it on demand.
+   *
+   * ```ts
+   * const { shards, subscriptions } = client.debug();
+   * // shards: [{ shardKey: "user-1", wsState: "open", confirmedMutationWatermark: 42, … }]
+   * ```
+   */
+  debug(): ClientDebugSnapshot;
+  /**
+   * Subscribe to changes in {@link pendingCount}. Invokes `listener` immediately
+   * with the current count, then whenever the queue depth changes (a write is
+   * enqueued, flushed, or discarded). Returns an unsubscribe function.
+   */
+  onPendingChange(listener: (pending: number) => void): 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: (event: MutationSettledEvent) => void): Unsubscribe;
+  /**
+   * The `WebSocket` implementation this client was constructed with (an
+   * explicit `options.WebSocket`, or the ambient global on platforms that have
+   * one) — `undefined` if neither is available. This is the seam a feature
+   * that opens its OWN socket outside the client's multiplexed connection
+   * (e.g. a voice-agent hook) should default to, instead of reaching for
+   * `globalThis.WebSocket` directly: on React Native the client wraps this
+   * constructor to inject the auth-headers factory's credential onto the
+   * upgrade request (`createLunoraClient`'s `withAuthWebSocket`), which a raw
+   * `new globalThis.WebSocket(url)` would silently bypass.
+   */
+  getWebSocketImpl(): typeof WebSocket | undefined;
+  /**
+   * Read the current value for a {@link ClientQueryRef}. Returns
+   * `ref.defaultValue` when no value has been explicitly set.
+   */
+  getClientQuery<T>(ref: ClientQueryRef<T>): T;
+  /**
+   * Set a new value for `ref` and notify every subscriber. Pass `undefined`
+   * to reset the slot to `ref.defaultValue`.
+   */
+  setClientQuery<T>(ref: ClientQueryRef<T>, value: T): void;
+  /**
+   * Subscribe to changes for `ref`. The callback is NOT invoked on
+   * registration — call {@link getClientQuery} for the current value.
+   * Returns an unsubscribe function.
+   */
+  subscribeClientQuery(ref: ClientQueryRef, callback: (value: unknown) => void): Unsubscribe;
+  /**
+   * Reset a {@link ClientQueryRef} to its default value, notifying every
+   * subscriber. Equivalent to `setClientQuery(ref, ref.defaultValue)` but
+   * removes the stored entry so a future {@link getClientQuery} returns
+   * the default rather than an explicitly-set value.
+   */
+  resetClientQuery(ref: ClientQueryRef): void;
+  /**
+   * Capture a snapshot of the current live query value at call time and
+   * produce a `() => boolean` precondition that compares it against the
+   * value at replay time (on queue drain / reconnect).
+   *
+   * Delegates to {@link createSnapshotPrecondition} with this client bound —
+   * no need to pass `client` explicitly. The comparison semantics (including
+   * how an absent subscription is treated) live there, in one place.
+   * @example
+   * ```ts
+   * client.mutation(api.todos.update, { id, text }, {
+   *   precondition: client.snapshotPrecondition(api.todos.list, { userId }),
+   * });
+   * ```
+   */
+  snapshotPrecondition(functionRef: FunctionReference, args: Record<string, unknown>, shardKey?: string): () => boolean;
+  /**
+   * Resolves once the durable read cache has been loaded into memory. When
+   * `hydrateOnStart` is not configured or no query cache adapter is active,
+   * returns an already-resolved promise so callers can always await it
+   * unconditionally.
+   *
+   * Framework adapters (React, Vue, etc.) use this to gate the first
+   * (enabled) render of a live query behind hydration, so the user sees
+   * cached data instead of an undefined flash before the socket round-trip.
+   */
+  whenReady(): Promise<void>;
+  /**
+   * Synchronously reports whether {@link whenReady} has already resolved (the
+   * durable read cache is loaded, or none is configured). Framework adapters
+   * read this to seed the hydration-gate state on the first render without
+   * awaiting, then subscribe via {@link whenReady} for the pending case.
+   */
+  get isReady(): boolean;
+  /**
+   * Synchronously peek at a value the durable read cache loaded for the given
+   * function path + args + shard key. Returns `undefined` when:
+   *
+   * - No query cache adapter is configured.
+   * - Hydration hasn't completed yet (race — await {@link whenReady} first).
+   * - The cached value's identity fingerprint doesn't match the current auth.
+   *
+   * Unlike the internal {@link takeHydratedCache}, this is a READ-ONLY peek:
+   * the cached entry stays in `hydratedQueryCache` so the subscription created
+   * later by {@link subscribe} consumes it normally.
+   */
+  peekHydratedQuery(functionPath: string, args: Record<string, unknown>, shardKey?: string): unknown;
+  /**
+   * Peek at the **current live value** of an active subscription, reporting
+   * whether one exists at all rather than just its value. `present` is `false`
+   * when no subscription is open for the given `(functionPath, args, shardKey)`;
+   * `value` is the subscription's `lastValue`, which includes any optimistic
+   * overlay.
+   *
+   * The two are separate because a caller like the snapshot precondition has to
+   * tell "no subscription is active, so this read knows nothing" apart from
+   * "the subscription is active and its value is `undefined`" — collapsing both
+   * into a bare `undefined` return makes an unmounted component look like a
+   * changed value, and drops the queued write.
+   *
+   * Unlike {@link peekHydratedQuery} (which reads from the durable read cache
+   * and is independent of active subscriptions), this reflects the current
+   * in-memory state of an already-opened subscription.
+   */
+  peekActiveQuerySnapshot(functionPath: string, args: Record<string, unknown>, shardKey?: string): {
+    present: boolean;
+    value: unknown;
+  };
+  query<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: {
+    shardKey?: string;
+  }): Promise<ReturnOf<F>>;
+  /**
+   * Batch several independent calls into ONE round trip (plan 088). Each call is
+   * dispatched server-side exactly as an individual RPC — per-shard
+   * authorization, `(identity, mutationId)` idempotency, and custom-mutator
+   * watermark ordering are all preserved — and the worker splits the batch by
+   * shard so calls to different shards fan out to their own DOs. Results are
+   * demuxed back in input order; a failing call does NOT fail the batch (its
+   * slot carries `{ ok: false, error }`, with `.code`/`.data` reconstructed like
+   * a single call). Args/results ride the value codec (bytes/bigint survive).
+   *
+   * No promise pipelining and no capability passing — a call's args cannot
+   * reference another call's result (see plan 088 §fence; capabilities are
+   * incompatible with DO hibernation).
+   */
+  batch(calls: ReadonlyArray<{
+    args?: Record<string, unknown>;
+    fn: FunctionReference;
+    shardKey?: string;
+  }>): Promise<BatchSlot[]>;
+  /**
+   * 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`.
+   */
+  mutation<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>): Promise<ReturnOf<F>>;
+  action<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: ActionCallOptions): Promise<ReturnOf<F>>;
+  /**
+   * Bulk-import `rows` through a mutation that accepts a batch, chunked so a large
+   * dataset lands in a bounded number of round-trips.
+   *
+   * **Offline caveat:** each chunk is sent with {@link LunoraClient.mutation}, which
+   * resolves once the write is durably queued rather than once the server has applied
+   * it. So an import run while offline resolves `{ chunks, imported }` with nothing
+   * committed yet — the counts describe what was *handed over*, and the outbox
+   * replays them on reconnect. Don't report "migration complete" on this alone.
+   *
+   * This is the one-shot migration / seed path: "I have 20k rows client-side and a
+   * server mutation that inserts many at once". Doing it by hand goes wrong in two
+   * predictable ways — a serial per-row loop pays one round-trip *and* one watermark
+   * wait per row (a 200-row import becomes 200 sequential hops), while a single
+   * giant call blows the DO's batch limit. So: chunk, send sequentially, and give
+   * each chunk a stable idempotency key derived from `importId` + its index, so a
+   * resumed or retried import doesn't double-insert the chunks that already landed.
+   *
+   * The server mutation is yours (Lunora can't guess the table or the row shape);
+   * back it with `ctx.db.insertMany(...)`, or `insertManyUnsafe(...)` for data you
+   * vouch for. `chunkSize` defaults to 500, matching the DO's default batch cap.
+   *
+   * ```ts
+   * await client.importRows(api.migrate.importNodes, nodes, {
+   *     importId: `migrate-${userId}`,
+   *     onProgress: ({ done, total }) => setProgress(done / total),
+   *     shardKey: userId,
+   *     toArgs: (chunk) => ({ nodes: chunk }),
+   * });
+   * ```
+   */
+  importRows(function_: FunctionReference, rows: ReadonlyArray<unknown>, options?: {
+    /** Rows per call. Defaults to 500 — the DO's default batch cap. */
+    chunkSize?: number;
+    /**
+     * Stable id for this import run. Each chunk is sent under
+     * `${importId}:${chunkIndex}` as its mutation id, so re-running an import
+     * that uses the SAME `chunkSize` re-sends each chunk under its prior key
+     * and the server dedupes it instead of inserting twice.
+     *
+     * CAVEAT — the key is POSITIONAL, not content-based: it pins on the chunk
+     * INDEX, not on the rows inside it. Resume or retry with a DIFFERENT
+     * `chunkSize` (or a changed row ordering) and index N now covers different
+     * rows than the first run's index N; the server sees a duplicate key and
+     * SILENTLY DROPS those rows. Keep `chunkSize` (and the row order) identical
+     * across resumes of the same `importId`. Omit `importId` only for a
+     * throwaway import where double-insertion is acceptable.
+     */
+    importId?: string;
+    /**
+     * Called after each chunk is accepted — for a progress bar.
+     *
+     * "Accepted" is not always "committed": while offline (or mid-reconnect) a
+     * `mutation` resolves as soon as the write is durably **queued**, so a fully
+     * offline import reports completion with nothing yet applied server-side.
+     * Gate a migration's "done" state on connectivity, not just on this.
+     */
+    onProgress?: (progress: {
+      done: number;
+      total: number;
+    }) => void;
+    /** Routes every chunk to one shard's DO. */
+    shardKey?: string;
+    /** Build the mutation args for one chunk. Defaults to `{ rows: chunk }`. */
+    toArgs?: (chunk: ReadonlyArray<unknown>) => Record<string, unknown>;
+  }): Promise<{
+    chunks: number;
+    imported: number;
+  }>;
+  /**
+   * 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.
+   */
+  shardTraffic(table: string): Promise<ShardTrafficResult>;
+  /**
+   * 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.
+   */
+  listScheduledJobs(): Promise<ScheduleRecord[]>;
+  /**
+   * 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.
+   */
+  schedulerStatus(): Promise<SchedulerStatus>;
+  /** Cancel a pending scheduled job by id. Returns whether a job was removed. */
+  cancelScheduledJob(id: string): Promise<{
+    cancelled: boolean;
+  }>;
+  /**
+   * 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.
+   */
+  listDeadJobs(): Promise<ScheduleRecord[]>;
+  /**
+   * 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`.
+   */
+  retryDeadJob(id: string): Promise<{
+    retried: boolean;
+  }>;
+  /**
+   * 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`.
+   */
+  removeDeadJob(id: string): Promise<{
+    removed: boolean;
+  }>;
+  /**
+   * 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.
+   */
+  listWorkflowInstances(options: {
+    name: string;
+    page?: number;
+    perPage?: number;
+    status?: WorkflowInstanceStatus;
+  }): Promise<WorkflowInstancePage>;
+  /** Read one workflow instance with its step timeline (`/_lunora/admin/workflows/instance`). */
+  getWorkflowInstance(options: {
+    id: string;
+    name: string;
+  }): Promise<WorkflowInstanceDetail>;
+  /** Pause / resume / terminate a workflow instance (`/_lunora/admin/workflows/status`). Needs an Edit-scoped Cloudflare token. */
+  setWorkflowInstanceStatus(options: {
+    action: WorkflowInstanceAction;
+    id: string;
+    name: string;
+  }): Promise<{
+    status: WorkflowInstanceStatus;
+  }>;
+  /**
+   * 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 an admin credential
+   * (the browser can't send an `Authorization` header on a WS) — the master
+   * token, or preferably a {@link WsTokenProvider} minting the ephemeral
+   * sub-token so the master credential stays out of the URL. Returns an
+   * unsubscribe function that closes the socket and stops reconnecting.
+   */
+  subscribeScheduledJobs(onJobs: (jobs: ScheduleRecord[]) => void): Unsubscribe;
+  /**
+   * 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.
+   */
+  listFunctions(): Promise<FunctionDescriptor[]>;
+  /**
+   * 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.
+   */
+  getCronJobs(): Promise<CronJobInfo[]>;
+  /**
+   * 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.
+   */
+  runCronJob(name: string): Promise<{
+    name: string;
+    ran: boolean;
+  }>;
+  /**
+   * 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.
+   */
+  fetchOpenApi(): Promise<Record<string, unknown>>;
+  /**
+   * 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.
+   */
+  fetchOpenRpc(): Promise<Record<string, unknown>>;
+  /**
+   * 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.
+   */
+  listStorageObjects(options?: {
+    bucket?: string;
+    cursor?: string;
+    limit?: number;
+    prefix?: string;
+  }): Promise<StorageListPage>;
+  /**
+   * 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 }`.
+   */
+  deleteStorageObject(key: string, options?: {
+    bucket?: string;
+  }): Promise<{
+    deleted: boolean;
+    key: string;
+  }>;
+  /**
+   * 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).
+   */
+  listStorageBuckets(): Promise<string[]>;
+  /**
+   * 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 }`.
+   */
+  uploadStorageObject(options: {
+    body: ArrayBuffer | Blob;
+    bucket?: string;
+    contentType?: string;
+    key: string;
+  }): Promise<{
+    etag?: string;
+    key: string;
+  }>;
+  /**
+   * 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).
+   */
+  signedStorageUrl(key: string, options?: {
+    bucket?: string;
+    expiresInSeconds?: number;
+  }): Promise<string>;
+  /**
+   * 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.
+   */
+  listGlobalTables(): Promise<GlobalTableInfo[]>;
+  /**
+   * 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.
+   */
+  readGlobalTablePage(options: {
+    filters?: GlobalFilterClause[];
+    limit?: number;
+    offset?: number;
+    table: string;
+  }): Promise<GlobalTablePage>;
+  /**
+   * 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.
+   */
+  facetGlobalColumn(options: {
+    column: string;
+    filters?: GlobalFilterClause[];
+    limit?: number;
+    table: string;
+  }): Promise<GlobalFacetResult>;
+  /**
+   * 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.
+   */
+  listVectorIndexes(): Promise<VectorIndexSummary[]>;
+  /**
+   * 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).
+   */
+  queryVectorIndex(options: {
+    name: string;
+    text: string;
+    topK?: number;
+  }): Promise<VectorQueryMatch[]>;
+  /**
+   * Read one keyset-paginated page of the durable `ctx.log` archive that
+   * `pipelineLogSink` writes to R2. Server-side only — the worker holds the R2
+   * SQL credentials and runs the reader; the browser only sees the decoded
+   * `{ rows, nextCursor }`. Pass the previous page's `nextCursor` as
+   * `query.cursor` to page. Admin-gated. When the operator hasn't wired the
+   * archive, `adminFetch` throws a `LunoraClientError` with `.code ===
+   * "LOG_ARCHIVE_NOT_CONFIGURED"`, so a caller can render a "not configured"
+   * state rather than an error.
+   */
+  queryLogArchive(query?: PipelineLogQuery): Promise<PipelineLogPage>;
+  /**
+   * List the worker's registered Workers KV namespaces (binding names). Hits
+   * the admin-gated `GET /_lunora/admin/kv/namespaces` endpoint — the worker
+   * must be built with a `kvIntrospector` and `adminToken`. Powers the
+   * studio's KV browser.
+   */
+  listKvNamespaces(): Promise<KvNamespaceSummary[]>;
+  /**
+   * List keys in a KV namespace, optionally filtered by `prefix` and
+   * paginated via `cursor`. Hits the admin-gated
+   * `GET /_lunora/admin/kv/keys` endpoint.
+   */
+  listKvKeys(options: {
+    cursor?: string;
+    limit?: number;
+    namespace: string;
+    prefix?: string;
+  }): Promise<KvKeyListResult>;
+  /**
+   * Read a KV value (as text) and its metadata. Hits the admin-gated
+   * `GET /_lunora/admin/kv/value` endpoint. Returns `{ value: null, metadata: null }`
+   * when the key is absent.
+   */
+  getKvValue(options: {
+    key: string;
+    namespace: string;
+  }): Promise<KvValueResult>;
+  /**
+   * Write a string value to a KV namespace. Accepts an absolute `expiration`
+   * (Unix seconds) or a relative `expirationTtl`, plus optional `metadata` —
+   * re-send the loaded values on edit so a save preserves rather than clears
+   * them. Hits the admin-gated `PUT /_lunora/admin/kv/value` endpoint.
+   */
+  putKvValue(options: {
+    expiration?: number;
+    expirationTtl?: number;
+    key: string;
+    metadata?: unknown;
+    namespace: string;
+    value: string;
+  }): Promise<void>;
+  /**
+   * Delete a key from a KV namespace. No-op when the key is absent. Hits the
+   * admin-gated `DELETE /_lunora/admin/kv/value` endpoint.
+   */
+  deleteKvKey(options: {
+    key: string;
+    namespace: string;
+  }): Promise<void>;
+  /**
+   * 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.
+   */
+  listAuthUsers(options?: {
+    filterField?: string;
+    filterValue?: string;
+    limit?: number;
+    offset?: number;
+    search?: string;
+    searchField?: string;
+    sortBy?: string;
+    sortDirection?: "asc" | "desc";
+  }): Promise<AuthPage<AuthUser>>;
+  /**
+   * 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`.
+   */
+  createAuthUser(input: {
+    data?: Record<string, unknown>;
+    email: string;
+    name: string;
+    password?: string;
+    role?: string | string[];
+  }): Promise<AuthUser>;
+  /** Set a user's role (string, or array joined comma-wise server-side). */
+  setAuthUserRole(input: {
+    role: string | string[];
+    userId: string;
+  }): Promise<AuthUser>;
+  /** Ban a user. `expiresInSeconds` sets a temporary ban; omit it for a permanent one. Revokes the user's live sessions. */
+  banAuthUser(input: {
+    expiresInSeconds?: number;
+    reason?: string;
+    userId: string;
+  }): Promise<AuthUser>;
+  /** Lift a user's ban. */
+  unbanAuthUser(input: {
+    userId: string;
+  }): Promise<AuthUser>;
+  /** Set a user's password (admin override — no current-password challenge). */
+  setAuthUserPassword(input: {
+    newPassword: string;
+    userId: string;
+  }): Promise<void>;
+  /** Permanently delete a user and revoke their sessions. */
+  removeAuthUser(input: {
+    userId: string;
+  }): Promise<void>;
+  /**
+   * 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.
+   */
+  impersonateAuthUser(input: {
+    userId: string;
+  }): Promise<AuthImpersonation>;
+  /** Revoke a single session by its id (force sign-out of one device). */
+  revokeAuthSession(input: {
+    sessionId: string;
+  }): Promise<void>;
+  /** Revoke every session for a user (force sign-out everywhere). */
+  revokeAuthUserSessions(input: {
+    userId: string;
+  }): Promise<void>;
+  /**
+   * 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`.
+   */
+  getAuthCapabilities(): Promise<AuthCapabilities>;
+  /** Update a user's fields (name/email/app-defined `additionalFields`). */
+  updateAuthUser(input: {
+    data: Record<string, unknown>;
+    userId: string;
+  }): Promise<AuthUser>;
+  /** List a user's linked accounts (credential / OAuth providers). Token material is stripped server-side. */
+  listAuthAccounts(input: {
+    userId: string;
+  }): Promise<Record<string, unknown>[]>;
+  /** Unlink a linked account from a user. */
+  unlinkAuthAccount(input: {
+    accountId: string;
+    userId: string;
+  }): Promise<void>;
+  /** List a user's registered passkeys (requires the passkey plugin). */
+  listAuthPasskeys(input: {
+    userId: string;
+  }): Promise<Record<string, unknown>[]>;
+  /** Delete a passkey by id (requires the passkey plugin). */
+  deleteAuthPasskey(input: {
+    passkeyId: string;
+  }): Promise<void>;
+  /** Disable two-factor auth for a user (requires the two-factor plugin). */
+  disableAuthTwoFactor(input: {
+    userId: string;
+  }): Promise<void>;
+  /** List organizations, paged (requires the organization plugin). */
+  listAuthOrganizations(options?: {
+    limit?: number;
+    offset?: number;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** List the members of an organization (requires the organization plugin). */
+  listAuthOrgMembers(input: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** List an organization's pending invitations (requires the organization plugin). */
+  listAuthOrgInvitations(input: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** Remove a member from an organization. */
+  removeAuthOrgMember(input: {
+    memberId: string;
+  }): Promise<void>;
+  /** Cancel a pending organization invitation. */
+  cancelAuthOrgInvitation(input: {
+    invitationId: string;
+  }): Promise<void>;
+  /**
+   * Report the deployment's auth configuration — enabled plugins, sign-in
+   * methods, user-settable create-user fields, organization sub-features
+   * (teams / roles), and session / rate-limit policy. Drives the config panel
+   * and the dynamic create-user form. Never carries a secret.
+   */
+  getAuthConfig(): Promise<AuthConfigInfo>;
+  /** Create an organization; optionally seed an `owner` member for `ownerId`. */
+  createAuthOrganization(input: {
+    logo?: string;
+    metadata?: Record<string, unknown>;
+    name: string;
+    ownerId?: string;
+    slug?: string;
+  }): Promise<Record<string, unknown>>;
+  /** Update an organization's name/slug/logo/metadata. */
+  updateAuthOrganization(input: {
+    logo?: string;
+    metadata?: Record<string, unknown>;
+    name?: string;
+    organizationId: string;
+    slug?: string;
+  }): Promise<Record<string, unknown>>;
+  /** Delete an organization and cascade its members, invitations, teams, and custom roles. */
+  deleteAuthOrganization(input: {
+    organizationId: string;
+  }): Promise<void>;
+  /** Directly add an existing user to an organization (no invitation/acceptance). */
+  addAuthOrgMember(input: {
+    organizationId: string;
+    role?: string;
+    userId: string;
+  }): Promise<Record<string, unknown>>;
+  /** Create a pending email invitation to an organization. */
+  inviteAuthOrgMember(input: {
+    email: string;
+    inviterId?: string;
+    organizationId: string;
+    role?: string;
+  }): Promise<Record<string, unknown>>;
+  /** Change a member's role. */
+  setAuthOrgMemberRole(input: {
+    memberId: string;
+    role: string | string[];
+  }): Promise<Record<string, unknown>>;
+  /** List an organization's teams (requires the organization plugin with teams enabled). */
+  listAuthOrgTeams(input: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** Create a team under an organization. */
+  createAuthOrgTeam(input: {
+    name: string;
+    organizationId: string;
+  }): Promise<Record<string, unknown>>;
+  /** Rename a team. */
+  updateAuthOrgTeam(input: {
+    name: string;
+    teamId: string;
+  }): Promise<Record<string, unknown>>;
+  /** Delete a team and its memberships. */
+  removeAuthOrgTeam(input: {
+    teamId: string;
+  }): Promise<void>;
+  /** List a team's members. */
+  listAuthOrgTeamMembers(input: {
+    limit?: number;
+    offset?: number;
+    teamId: string;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** Add a user to a team. */
+  addAuthOrgTeamMember(input: {
+    teamId: string;
+    userId: string;
+  }): Promise<Record<string, unknown>>;
+  /** Remove a member from a team. */
+  removeAuthOrgTeamMember(input: {
+    teamMemberId: string;
+  }): Promise<void>;
+  /** List an organization's custom roles (requires the organization plugin with dynamic access control). */
+  listAuthOrgRoles(input: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** Create a custom org role with a permission grant (a `resource -> actions[]` map). */
+  createAuthOrgRole(input: {
+    organizationId: string;
+    permission: Record<string, string[]>;
+    role: string;
+  }): Promise<Record<string, unknown>>;
+  /** Replace a custom org role's permission grant. */
+  updateAuthOrgRole(input: {
+    permission: Record<string, string[]>;
+    roleId: string;
+  }): Promise<Record<string, unknown>>;
+  /** Delete a custom org role. */
+  deleteAuthOrgRole(input: {
+    roleId: string;
+  }): Promise<void>;
+  /** List auth sessions, paged and optionally filtered to one user. */
+  listAuthSessions(options?: {
+    limit?: number;
+    offset?: number;
+    userId?: string;
+  }): Promise<AuthPage<AuthSession>>;
+  subscribe<F extends FunctionReference>(function_: F, args: ArgsOf<F>, callback: (data: ReturnOf<F>) => void, options?: {
+    onCheckpoint?: (watermark: SyncWatermark) => void;
+    onError?: SubscriptionErrorCallback;
+    shardKey?: string;
+  }): Unsubscribe;
+  /**
+   * 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: {
+    args?: Record<string, unknown>;
+    name: string;
+  }, callback: ShapeCallback, options?: {
+    onCheckpoint?: (watermark: SyncWatermark) => void;
+    onError?: SubscriptionErrorCallback;
+    shardKey?: string;
+  }): 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<F extends FunctionReference<"stream">>(function_: F, args: ArgsOf<F>, options?: {
+    durable?: boolean;
+    maxBuffer?: number;
+    shardKey?: string;
+  }): StreamIterable<ReturnOf<F>>;
+  /**
+   * Open a typed **HTTP-SSE route stream** (`httpRoute.<verb>(path).stream()`).
+   * Distinct from {@link LunoraClient.stream}, which consumes the WS procedure
+   * stream (`kind: "stream"`): this one opens the route's own URL with `fetch`
+   * and parses the Server-Sent Events framing the route pump writes (`data:`
+   * chunks, a final `event: complete`, an `event: error` on throw).
+   *
+   * The reference comes from the generated `httpStreams.*` registry, so the
+   * yielded chunk type is the route handler's yielded type. Cancelling the
+   * returned iterable (or aborting `options.signal`) aborts the fetch, which
+   * the server handler observes via its `signal`. The client's bearer token
+   * (when set) rides as an `authorization` header.
+   * @experimental Reconnect/POST-body/wire-fidelity design questions are still open, so the shape may change.
+   */
+  httpStream<Ref extends HttpStreamRef>(route: Ref, args?: HttpStreamArgsOf<Ref>, options?: {
+    headers?: Record<string, string>;
+    maxBuffer?: number;
+    signal?: AbortSignal;
+  }): StreamIterable<HttpStreamChunkOf<Ref>>;
+  close(): void;
+  /** Guard shared by every public entry point: a closed client accepts no further calls. */
+  private assertOpen;
+  /**
+   * Tear down one {@link ShardConnection}'s live state: clear its reconnect/
+   * connect timers, stop its heartbeat, and close its socket (if any).
+   * Shared by `close()` (terminal) and the cross-tab `onStopBeingLeader`
+   * handler (demoted, but still alive) so a demoted leader can't leak a
+   * pending `reconnectTimer` or an open socket's `heartbeatTimer` the way
+   * an inline `conn.socket?.close()` — which skips both — used to.
+   */
+  private teardownConnection;
+  /**
+   * Build (but do not start) this client's `TabCoordinator`. Extracted out of
+   * the constructor so `setAuthToken` can rebuild it on an identity change —
+   * the default channel name embeds the identity fingerprint (see below), so
+   * a new identity needs a new coordinator on a new channel. The callback
+   * bodies are the drift-sensitive region (a hand-merged identity guard on
+   * the shard message listener sits ahead of an extracted `lastFrameAt`
+   * stamp elsewhere in this file) — moved verbatim, not reflowed.
+   */
+  private createTabCoordinator;
+  /**
+   * 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.
+   */
+  private enqueueOfflineMutation;
+  /**
+   * 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.
+   */
+  private hydratePersistedQueue;
+  /**
+   * Re-queue the durable offline writes — but only as the multi-tab LEADER. The
+   * persisted queue is shared across a profile's tabs; without coordination
+   * every tab would re-queue and replay the same writes (correct only because
+   * the server dedups by idempotency key, but wasteful + racy). A Web Lock makes
+   * exactly one tab hydrate; it holds the lock for its lifetime, so when it
+   * closes another tab acquires the lock and takes over. Falls back to
+   * unconditional hydration where Web Locks are unavailable (React Native, older
+   * browsers, SSR) — single-context there, so no coordination is needed.
+   */
+  private hydrateAsOutboxLeader;
+  /**
+   * 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.
+   */
+  private hydrateQueryCache;
+  /**
+   * 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.
+   */
+  private takeHydratedCache;
+  /**
+   * 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).
+   */
+  private persistQueryValue;
+  /** Drain {@link pendingCacheWrites} to the durable store. */
+  private flushQueryCacheWrites;
+  /** Derive the aggregate status from the per-shard socket states. */
+  private computeStatus;
+  /** Recompute the aggregate status and notify listeners if it changed. */
+  private emitConnectionStatus;
+  /**
+   * 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.
+   */
+  private emitItemSettled;
+  /**
+   * 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.
+   */
+  private applyOptimisticUpdates;
+  /**
+   * 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.
+   */
+  private applyOptimisticUpdate;
+  private getConnection;
+  /**
+   * Send an unsubscribe frame (tagged with its wire type) on the shard's
+   * socket, or queue it for the next reconnect when the send can't go out.
+   */
+  private sendOrQueueUnsubscribe;
+  /**
+   * The `(wsState, hasSocket, wasEverConnected)` triple `mutation()`'s
+   * offline-queue gate reads. On the leader/single-tab path this is exactly
+   * the real `ShardConnection`'s state (byte-identical to the pre-cross-tab
+   * behavior). A follower has no `ShardConnection` of its own (see
+   * `ensureSocket`), so it derives the same triple from the mirrored
+   * `leaderStatus`/`leaderWasEverConnected` instead: `"connected"` maps to
+   * `"open"` (queue-eligible once `wasEverConnected`), `"connecting"` stays
+   * `"connecting"` (the mid-reconnect queue branch), anything else is
+   * `"idle"`. `hasSocket` is always `false` for a follower — it never has
+   * one.
+   */
+  private connectionGateState;
+  private getOrCreateConnection;
+  private wsUrlFor;
+  /**
+   * 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.
+   */
+  private rpcRequestHeaders;
+  private rpc;
+  /**
+   * 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.
+   */
+  private adminFetch;
+  /**
+   * 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.
+   */
+  private effectiveConnectionContext;
+  /** Re-send the `connect` envelope for a shard whose effective context just changed (if its socket is open). */
+  private refreshConnectionContext;
+  /**
+   * 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.
+   */
+  private sendConnectEnvelope;
+  /**
+   * 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.
+   */
+  private resendShapeSubscriptions;
+  private ensureSocket;
+  /**
+   * Resolve the {@link WsTokenProvider} and open the shard socket with the
+   * minted token. The connection is already in the `connecting` state, so the
+   * async gap is race-guarded: a client `close()`, a `setWsToken` bounce, or a
+   * competing connect that landed first all abandon this attempt. A provider
+   * failure fails the attempt through {@link handleDisconnect}, which arms the
+   * normal reconnect backoff — a broken mint endpoint degrades to retries, not
+   * a silent tokenless socket the admin gate would reject.
+   */
+  private openSocketWithProvidedToken;
+  /**
+   * Construct one WebSocket connection attempt and wire the shared
+   * lifecycle guarantees around it — the fail-fast connect-timeout, the
+   * identity guard that stops a superseded attempt's late `open`/`message`/
+   * `close`/`error` from touching a connection a newer attempt already
+   * owns, and (once open) the keepalive heartbeat with its half-open
+   * watchdog (plan 217). One call opens ONE attempt; the caller owns
+   * reconnect scheduling from `onClose` — mirrors the shard's existing
+   * `ensureSocket` / `handleDisconnect` split, now shared with
+   * `subscribeScheduledJobs` so it stops re-living the bug that split
+   * already fixed once (CLIENT-05).
+   *
+   * The identity guard is `conn.socket !== socket`, re-checked before every
+   * action below. `conn.socket` is reassigned to a new attempt's socket
+   * synchronously — right here, before `open` ever fires — so an older
+   * attempt's guard trips the instant it's superseded, even if its
+   * underlying socket only fires its real `close`/`error` much later. This
+   * ordering is load-bearing: preserve it exactly.
+   */
+  private openManagedSocket;
+  /** Construct the shard socket and wire its lifecycle handlers. The connection must already be in the `connecting` state. */
+  private openSocket;
+  private handleDisconnect;
+  /**
+   * Begin the keepalive heartbeat on an open connection attempt — the only
+   * caller is {@link openManagedSocket}'s own `open` handler, so both the
+   * shard socket and `subscribeScheduledJobs` share this one implementation
+   * instead of each hand-rolling their own (plan 217, generalized).
+   *
+   * Each tick first checks the half-open watchdog (see
+   * {@link ManagedSocketState.lastFrameAt}): if no frame at all has arrived
+   * within `heartbeatIntervalMs * 2.5`, the far end has gone quiet without
+   * the socket ever firing `close` — force it closed and report it through
+   * `onWatchdogTrip` (the caller's `onClose`) so the normal reconnect/backoff
+   * takes over instead of every live query on it silently staling forever.
+   * Otherwise it 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.
+   */
+  private startHeartbeat;
+  /** Clear a connection's keepalive timer, if any. Safe to call repeatedly. */
+  private stopHeartbeat;
+  /** Mark every subscription bound to `shardKey` as needing a fresh ack. */
+  private markShardPendingAck;
+  private sendSubscribeIfOpen;
+  private sendShapeSubscribeIfOpen;
+  private handleServerMessage;
+  private handleErrorMessage;
+  /** Buffer key for an in-flight poke: `pokeId` is only unique per shard socket, so it is scoped by connection. */
+  private pokeBufferKey;
+  private handlePokeStart;
+  private handlePokePart;
+  private handlePokeEnd;
+  /**
+   * Commit one shape's slice of a poke, or refuse it and re-seed.
+   *
+   * Split out of {@link handlePokeEnd} because every decision here is PER SHAPE
+   * — the reset flag, the base checkpoint, the watermark — while the poke
+   * envelope around it is not.
+   */
+  private applyPokePart;
+  /**
+   * Force the server to re-send a full snapshot for `state`, leaving the
+   * currently displayed value alone until it lands. Used when a delta frame
+   * cannot be applied: dropping the resume cursor is what makes the resubscribe
+   * a snapshot rather than a `resume`, and un-acking is what lets
+   * `sendSubscribeIfOpen` put the frame on the wire at all. Mirrors the shape
+   * path's re-seed on a diverged base.
+   */
+  private resnapshotSubscription;
+  /** Materialize a shape's keyed view to an array and invoke its callbacks. */
+  private emitShapeRows;
+  private handleDataMessage;
+  /**
+   * 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.
+   */
+  private handleResumeMessage;
+  /**
+   * 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.
+   */
+  private handleSettledMessage;
+  /**
+   * 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".
+   */
+  private ackAndAdvanceCursor;
+  /**
+   * 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.
+   */
+  private resolveDataPayload;
+  /** Route an inbound whisper to the topic's handlers on the originating shard. */
+  private dispatchWhisper;
+  /** Notify every {@link onTokenExpired} listener (best-effort, listener throws swallowed). */
+  private notifyTokenExpired;
+  /**
+   * CLIENT-04: `type: "complete"` today is sent ONLY by `@lunora/do`'s
+   * `handleStream` (see `shard-do.ts`), gated to the `stream` envelope type
+   * and minting only `stream_*` ids — the `subscribe` path never sends it, so
+   * a live SUBSCRIPTION provably never receives `complete` from the current
+   * server. But `ServerCompleteMessage` is a generic `id`-keyed frame and
+   * `ShardDO` is user-subclassable, so this stays defensive rather than
+   * assuming a `sub_*` id can never reach here: unlike the historical
+   * `subscriptions.remove(state)`, which dropped the state out of
+   * `subscriptions.all()` — the set the reconnect resubscribe loop walks
+   * (`ensureSocket`'s `open` handler) — and so froze the query forever across
+   * every future reconnect, this fans a cancellation error to any listener
+   * and marks the registration un-acked instead. Non-destructive: the state
+   * stays in the registry, so the very next reconnect resubscribes it. The
+   * two id-spaces don't overlap (`sub_*` vs `stream_*`), so the stream and
+   * subscription lookups below are mutually exclusive.
+   */
+  private handleCompleteMessage;
+  private unpersist;
+  /**
+   * 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.
+   */
+  private identityFingerprint;
+  /**
+   * Stable token-hash fingerprint of a bearer token (the `<len>:<fnv>:<djb2>`
+   * format a token-stamped queued write carries). Extracted so the replay gate
+   * can recompute the hash of the current credential and recognise a write
+   * stamped under it — even after the fingerprint was relabelled to a subject.
+   *
+   * Two independent 32-bit passes (FNV-1a + djb2) give a ~64-bit digest, so
+   * two distinct equal-length tokens are astronomically unlikely to share a
+   * fingerprint. A single 32-bit hash collides ~1-in-4e9 per equal-length
+   * pair — enough that, on a shared device, user B could hydrate A's cached
+   * reads. Different algorithms (not the same FNV with a different seed, which
+   * would be affine-related) keep the two passes genuinely independent.
+   * Still synchronous (no crypto) and stable across surrogate pairs.
+   */
+  private hashToken;
+  /**
+   * True when `stamped` is a token-hash of the SAME credential still held now,
+   * even though the live identity has since been relabelled to a subject. Covers
+   * `setAuthToken(token, userId)` where the subject resolved a tick after the
+   * token was set: a write persisted (or requeued) under the token hash must
+   * still replay — the credential never changed, only its label — instead of
+   * being dropped as an identity mismatch. This is the durable counterpart to
+   * {@link restampQueuedIdentity}, which only relabels the in-memory live stamp
+   * (consumed on the first flush) and never touches `item.identity` or the
+   * persisted record, so a reload or a transient-failure requeue would otherwise
+   * fall back to the stale token-hash and wrongly reject the same user's write.
+   */
+  private isSameCredentialUnderTokenHash;
+  /**
+   * 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.
+   */
+  private rejectQueuedForIdentityChange;
+  /**
+   * Migrate every live identity stamp from `from` to `to` — used when the auth
+   * identity label changes but the underlying credential (token) does NOT, e.g.
+   * the user id resolves a tick after the token was set. The in-memory
+   * `queuedIdentities` map is the flush-time source of truth, so re-stamping it
+   * keeps the in-flight writes replayable under the new (more stable) identity
+   * instead of the flush guard discarding them as a mismatch.
+   */
+  private restampQueuedIdentity;
+  /**
+   * Migrate the {@link clientWatermarks} bucket map nested under identity
+   * `from` to identity `to` — the sibling of {@link restampQueuedIdentity},
+   * for the same same-credential-subject-resolves case. Without this, a
+   * bucket's watermark cached under the token-hash fingerprint would look
+   * unset once the fingerprint relabels to `subj:…`, so the next push
+   * re-derives `1` against a server watermark the DO already advanced — the
+   * OUT_OF_ORDER wedge this cache-keying scheme exists to fix, reintroduced
+   * by the fix itself. `to` may already hold a bucket map (switching back to
+   * an identity that has its own cached watermarks); merge into it rather
+   * than clobbering it, with `from`'s entries winning on a colliding bucket —
+   * the same overwrite a plain `Map.set` would have done before this was a
+   * nested map.
+   */
+  private restampWatermarks;
+  /**
+   * 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.
+   */
+  private clearQueryCacheForIdentityChange;
+  /**
+   * Flush every shard with a mutation currently queued in `offlineQueue`
+   * (see `queuedOfflineShardKeys`). Used on a FOLLOWER tab when the
+   * mirrored leader status transitions to `"connected"` — a follower has no
+   * per-shard `ShardConnection` reconnect event to hang the usual
+   * single-shard `flushOfflineQueue(shardKey)` call off of (see the
+   * `handleConnect` call site), so this walks every shard that might have
+   * something queued instead. Flushing an already-empty shard is a cheap
+   * no-op (`flushOfflineQueue` returns immediately once `drain` yields
+   * nothing), so over-inclusion here is harmless.
+   */
+  private flushAllOfflineQueues;
+  private flushOfflineQueue;
+  /**
+   * Partition already-gated writes into the encodable ones (returned) and reject
+   * the rest terminally. A write whose args can't be wire-encoded (e.g. a RegExp
+   * or class instance in a `v.any()` field) can NEVER replay — the codec failure
+   * is deterministic, not transient. Rejecting here is essential: otherwise
+   * `encodeWire` throws mid-flush, is classified as transient (a codec error has
+   * no `.code`), and re-queues forever — a silent hang where the caller's Promise
+   * never settles and the optimistic write never rolls back. Encoding is cheap;
+   * the flush is the slow reconnect path.
+   */
+  private encodableOrSettleTerminal;
+  /**
+   * Identity guard for one queued write about to replay: a write stamped under
+   * one identity must never replay under another. The live `queuedIdentities`
+   * map is the source of truth for the current session; a hydrated write whose
+   * id isn't in the map falls back to the stamp persisted with the record
+   * (`item.identity`), so a reload can't replay another user's queued writes.
+   * Only legacy records (persisted before stamps were durable —
+   * `item.identity === undefined`) replay under whatever identity is current.
+   *
+   * `Map.get` returns `undefined` for unstamped/hydrated ids and `item.identity`
+   * is `undefined` for legacy records; a persisted `null` (queued while signed
+   * out) is a real value that must not collapse into `undefined` — hence the
+   * explicit `=== undefined` check rather than `??`. Returns `true` when the
+   * write may replay; otherwise settles it `OFFLINE_IDENTITY_CHANGED` and returns
+   * `false`. Either way the live stamp is consumed.
+   */
+  private passesReplayIdentityGate;
+  /** Settle a write that replayed successfully: confirm its optimistic layer against the echoed commit cursor BEFORE resolving, so the gapless drop is in place when the awaiter (and any confirming frame) observes the settle. */
+  private settleReplaySuccess;
+  /**
+   * The entry a shard's cursor lives under.
+   *
+   * Only the server knows that an omitted `shardKey` and an explicit one
+   * spelling out its configured default name are the same shard — the default
+   * is server-side configuration the client never sees. Keying on what was
+   * SENT would split one shard's cursor across two entries, so a write under
+   * one spelling would stop constraining a read under the other. Resolving
+   * `undefined` through the learned name is what keeps both spellings on one
+   * entry.
+   */
+  private cursorKeyFor;
+  /**
+   * Learn the server's own name for the default shard from a response to a
+   * call that named no shard.
+   *
+   * Any cursor recorded before the name was known sits under the placeholder
+   * entry, so it is folded in rather than stranded — otherwise the requirement
+   * from a client's first write would be lost exactly once, which is the kind
+   * of gap that only shows up as a stale read under load.
+   */
+  private learnDefaultShardKey;
+  /**
+   * Record the cursor a write committed at as this shard's read-your-writes
+   * requirement.
+   *
+   * Monotonic: responses can land out of order, and moving the requirement
+   * BACKWARDS would let a later read be answered from a replica copy that
+   * predates a write this client already saw.
+   */
+  private recordShardCursor;
+  /** Settle a write the server reached a coded verdict on: replaying would re-trigger the same failure (a poison-message loop), so drop it. */
+  private settleReplayTerminal;
+  /**
+   * Replay already-identity-gated writes one at a time on the single-call `/rpc`
+   * path, preserving FIFO order (parallel `.then()` chains would race the
+   * ordering callers depend on). Each replays under its stable `mutationId` so
+   * the server dedups a write it already committed (exactly-once). A coded error
+   * is a server verdict (drop it); a codeless (transport/transient) failure stops
+   * the flush and re-queues this write and every unreplayed one for the next
+   * reconnect — their callers stay pending, and the identity guard re-applies on
+   * retry via each record's persisted stamp.
+   */
+  private replaySequential;
+  /**
+   * Coalesce already-identity-gated writes for a single shard into ONE
+   * `/_lunora/rpc-batch` round trip (plan 088 follow-on). The worker forwards
+   * them to the shard DO, which replays each through its single-call dispatch, so
+   * per-entry `mutationId` idempotency and in-order application are inherited from
+   * the proven path. Per-slot demux mirrors {@link replaySequential}'s
+   * classification: success confirms the optimistic layer against the echoed
+   * `commitCursor`; a coded application verdict is terminal; a transient shard
+   * failure (`SHARD_UNAVAILABLE`/`SHARD_ERROR`), a missing slot, or a whole-batch
+   * transport failure re-queues for the next reconnect (never dropping a durable
+   * write). A whole-batch coded rejection (bad request / authorization denial the
+   * server reached a verdict on) is terminal for every entry.
+   *
+   * Returns the writes that must be re-queued and `stop` — `true` when the whole
+   * chunk failed at the transport level, so the caller leaves later chunks queued
+   * rather than sending on. The caller re-queues once, in order, so requeuing is
+   * NOT done here.
+   */
+  private replayBatched;
+  /**
+   * Demux a `/_lunora/rpc-batch` reply back onto the queued writes it replayed,
+   * in input order. Each slot's envelope classifies its write the same way
+   * {@link replaySequential} does: a success confirms the optimistic layer
+   * against the echoed `commitCursor`; a coded application verdict is terminal;
+   * a transient shard failure ({@link TRANSIENT_BATCH_ERROR_CODES}) or a slot the
+   * server never returned is returned for the caller to re-queue.
+   * @returns the writes that must be re-queued (transient slots), in input order
+   */
+  private settleReplayBatchSlots;
+}
+export { ActionCallOptions as A, BatchSlot as B, ConnectionStatus as C, DEFAULT_MAX_BUFFER as D, LunoraClient as L, MutationCallOptions as M, OptimisticLocalStore as O, SubscriptionError as S, SubscriptionErrorCallback as a, StreamIterable as b, CONFLICT_ERROR_CODE as c, ClientDebugShard as d, ClientDebugSnapshot as e, ClientDebugSubscription as f, ClientQueryRef as g, LunoraClientError as h, LunoraErrorCode as i, MutationSettledEvent as j, OptimisticUpdate as k, StreamHandle as l, SubscriptionCallback as m, SubscriptionRegistry as n, SubscriptionState as o, SyncWatermark as p, createClientQuery as q, createLocalStore as r, createStream as s, getErrorCode as t, getRetryAfterMs as u, isConflictError as v, isForbiddenError as w, isRateLimitedError as x, isUnauthorizedError as y };