@lunora/client 1.0.0-alpha.13 → 1.0.0-alpha.131

package/dist/packem_shared/lunora-client.d-BiwicHKh.d.ts

@@ -0,0 +1,4378 @@
+import { LunoraErrorCodeInput, LunoraErrorCode } from '@lunora/errors';
+import { F as FunctionReference, A as ArgsOf, R as ReturnOf } from "./function-reference.d-Br_hsKje.js";
+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>;
+/**
+ * Typed reference to an HTTP-SSE stream route (`httpRoute.<verb>(path).stream()`)
+ * emitted by `@lunora/codegen` as `httpStreams.<namespace>.<name>`.
+ *
+ * Distinct from {@link FunctionReference}: this is the **HTTP-SSE route stream**
+ * (opened with `fetch` + `ReadableStream` against the route's own URL), not the
+ * WS procedure stream (`kind: "stream"`). At runtime it carries the HTTP verb
+ * and the route path; the phantom marker carries the chunk / searchParams /
+ * params types so `httpStream` (and the framework hooks over it) infer the
+ * chunk type end-to-end.
+ * @experimental Reconnect/POST-body/wire-fidelity design questions are still open, so the shape may change.
+ */
+interface HttpStreamRef<Chunk = unknown, SearchParams = unknown, Params = unknown> {
+  /**
+   * Phantom marker carrying the `Chunk`/`SearchParams`/`Params` type
+   * parameters for inference. Never present at runtime; declared in a
+   * covariant (output) position so a concrete reference stays assignable to
+   * a widened one.
+   */
+  readonly __lunoraHttpStream?: {
+    chunk: Chunk;
+    params: Params;
+    searchParams: SearchParams;
+  };
+  /** HTTP verb the route binds to (uppercased), e.g. `"GET"`. */
+  readonly method: string;
+  /** The route path as declared, e.g. `/api/tokens/:id` — `:name` segments are filled from `params`. */
+  readonly path: string;
+}
+/**
+ * The call-side args of an HTTP-SSE stream route: `:name` path params plus URL query params.
+ * @experimental Part of the HTTP-SSE stream surface.
+ */
+interface HttpStreamCallArgs<SearchParams = unknown, Params = unknown> {
+  /** Values for the route path's `:name` segments. */
+  params?: Params;
+  /** URL query params, appended to the request URL (undefined entries are skipped). */
+  searchParams?: SearchParams;
+}
+/**
+ * Extract the chunk type from a {@link HttpStreamRef}.
+ * @experimental Part of the HTTP-SSE stream surface.
+ */
+type HttpStreamChunkOf<R> = R extends HttpStreamRef<infer Chunk, infer _S, infer _P> ? Chunk : never;
+/**
+ * Extract the call-side args type from a {@link HttpStreamRef}.
+ * @experimental Part of the HTTP-SSE stream surface.
+ */
+type HttpStreamArgsOf<R> = R extends HttpStreamRef<infer _C, infer S, infer P> ? HttpStreamCallArgs<S, P> : never;
+type Unsubscribe = () => void;
+/**
+ * Serializable result of `preloadQuery`. Produced on the server during SSR,
+ * embedded in the rendered HTML, then handed to `usePreloadedQuery` on the
+ * client so the first render shows the server value with no loading flash
+ * before a live subscription attaches. Every field survives `JSON.stringify`.
+ */
+interface Preloaded<T = unknown> {
+  readonly __lunoraPreloaded: true;
+  readonly args: Record<string, unknown>;
+  readonly functionPath: string;
+  readonly shardKey?: string;
+  readonly value: T;
+}
+/**
+ * Pluggable storage for the `x-d1-bookmark` value used to provide
+ * read-your-writes between a mutation and subsequent queries.
+ */
+interface BookmarkStorage {
+  get: () => string | null;
+  set: (value: string | null) => void;
+}
+interface ReconnectOptions {
+  initialDelayMs?: number;
+  jitter?: boolean;
+  maxDelayMs?: number;
+}
+/** Which durable-storage operation failed, passed to {@link OfflineQueueOptions.onPersistenceError}. */
+type PersistenceOperation = "append" | "clear" | "load" | "remove" | "replace";
+/** Context handed to a persistence-error handler. */
+interface PersistenceErrorContext {
+  readonly error: unknown;
+  /** The mutation id involved, when the failing op was scoped to one (`append`/`remove`). */
+  readonly mutationId?: string;
+  readonly operation: PersistenceOperation;
+}
+interface OfflineQueueOptions {
+  maxItems?: number;
+  /**
+   * Invoked when a {@link PersistenceAdapter} call rejects (e.g. IndexedDB quota
+   * exceeded). Without a handler, failures are logged via `console.warn` so they
+   * are never fully silent. Note: a failed `append` means the write is queued in
+   * memory but NOT durable — it will not survive a reload.
+   */
+  onPersistenceError?: (context: PersistenceErrorContext) => void;
+  /**
+   * Queue mutations issued before a shard's first successful WebSocket
+   * connect (defaults to `false`). The standard behaviour (`LunoraClient`'s
+   * `mutation()`) queues only when the targeted shard has been connected at
+   * least once (`wasEverConnected`), so the registry / resubscribe handshake
+   * has run. Set this to `true` for offline-first apps that want to enqueue
+   * writes on the very first session before the WS is up.
+   */
+  queueBeforeFirstConnect?: boolean;
+}
+/**
+ * Serializable shape of an offline mutation, durably stored by a
+ * {@link PersistenceAdapter} so queued writes survive a reload/crash. The live
+ * `resolve`/`reject` callbacks of an in-flight `QueuedMutation` are *not*
+ * persisted — a restored mutation is replayed with no original awaiter.
+ */
+interface PersistedMutation {
+  args: Record<string, unknown>;
+  /**
+   * The CDC cursor this write was composed against, persisted so a replay —
+   * including one after a reload, days later — is still judged against what its
+   * author could actually see. Consumed only by `.dropStalePatches()` tables.
+   *
+   * Persisting it is the entire point of the feature. Re-deriving a baseline at
+   * replay time would read the cursor the client has ADVANCED to while the write
+   * sat in the queue, which is the newer state the write must be compared
+   * against — so the stale write would always look fresh and always clobber.
+   *
+   * Absent on records written by older client versions, and on a client with no
+   * live subscription to take a cursor from; both replay with no baseline, which
+   * applies the write unchanged.
+   */
+  baselineSeq?: number;
+  /**
+   * The client id that queued this write, persisted so a replay after a reload
+   * lands in the SAME server-side dedup namespace it was issued under. The
+   * standalone client's own `clientId` is minted per session, so replaying under
+   * the live one would miss the `__idempotency` row for an anonymous caller and
+   * re-run a write the server already committed. Absent on records written by
+   * older client versions, which replay under the live id.
+   */
+  clientId?: string;
+  functionPath: string;
+  id: string;
+  /**
+   * Issuing identity fingerprint, persisted so a hydrated write replays only
+   * under the identity that queued it (`null` = queued while signed out).
+   * Absent on records written by older client versions, which replay under
+   * the ambient identity for back-compat.
+   */
+  identity?: string | null;
+  shardKey?: string;
+  /**
+   * App/schema version stamped at enqueue (from `LunoraClientOptions.persistenceVersion`).
+   * On hydrate, a record whose `version` doesn't match the current one is dropped
+   * and purged rather than replayed — so a write persisted by an older deploy
+   * (with a now-changed function signature) can't replay against the new schema.
+   * Absent when no `persistenceVersion` is configured (no version gating).
+   */
+  version?: string;
+}
+/**
+ * Durable store for the offline mutation queue. The default client keeps the
+ * queue in memory; supplying an adapter (e.g. `createIndexedDbPersistence`)
+ * makes queued writes survive a page reload. Implementations must preserve FIFO
+ * (enqueue) order in `PersistenceAdapter.load`.
+ *
+ * Replay semantics are at-least-once: a mutation is removed only after the
+ * server confirms (or rejects) it, so a crash between commit and `remove` can
+ * replay it again on the next load.
+ */
+interface PersistenceAdapter {
+  /** Append a mutation to durable storage (called on enqueue). */
+  append: (mutation: PersistedMutation) => Promise<void>;
+  /** Drop every persisted mutation (e.g. on logout). */
+  clear: () => Promise<void>;
+  /** Load all persisted mutations in FIFO order — called once at startup. */
+  load: () => Promise<PersistedMutation[]>;
+  /** Remove a mutation by id once it has been replayed (resolved or rejected). */
+  remove: (id: string) => Promise<void>;
+  /**
+   * Overwrite an already-persisted mutation IN PLACE, keeping its position in
+   * FIFO order. Used when a queued write's identity stamp is rewritten after a
+   * sign-in / sign-out.
+   *
+   * Must be atomic: a `remove` + `append` pair has a window where a process
+   * stop leaves the mutation in no durable store at all, and the in-memory
+   * entry has already advanced, so a reload loses the write outright. It also
+   * moved the record to the BACK of the queue, replaying it out of the order
+   * it was issued in. Implementations do the whole swap under one transaction
+   * (or one serialized blob write).
+   *
+   * A mutation whose id is not present is left alone — the record was drained
+   * concurrently and re-inserting it would replay a settled write.
+   */
+  replace: (mutation: PersistedMutation) => Promise<void>;
+}
+/**
+ * One write handed to an {@link OutboxSink}. Mirrors {@link PersistedMutation}
+ * plus the custom-mutator identity (`clientId`/`mutationId`/`idempotencyKey`)
+ * the durable outbox needs to dedupe and watermark replays.
+ */
+interface OutboxMutation {
+  args: Record<string, unknown>;
+  /**
+   * The CDC cursor this write was composed against — see
+   * {@link PersistedMutation.baselineSeq}, whose contract this mirrors.
+   *
+   * A sink MUST persist it and hand it back unchanged on replay. This is the
+   * canonical statement of that rule for the durable path; every other site
+   * that carries the field points here. Re-deriving one at replay time reads
+   * the cursor the client has since advanced to — the newer state the write is
+   * supposed to be judged against — so a stale write always looks fresh and
+   * always clobbers.
+   *
+   * `undefined` when the client has no live subscription to take a cursor from,
+   * which replays the write unchanged.
+   */
+  baselineSeq?: number;
+  /** Stable per-client id; pairs with {@link OutboxMutation.mutationId} as `idempotencyKey`. */
+  clientId: string;
+  functionPath: string;
+  /** `${clientId}:${mutationId}` — sent as `x-lunora-mutation-id` so a replay is server-idempotent. */
+  idempotencyKey: string;
+  /** Issuing identity fingerprint (`null` = signed out); drives the sink's identity guard. */
+  identity: string | null;
+  /** Monotonic per-client mutation id, backing the server `__client_watermark`. */
+  mutationId: number;
+  /**
+   * Roll this write's optimistic patch back. The sink's owner invokes it when
+   * the replay reaches a PERMANENT verdict (a coded rejection, an identity
+   * drop) — never on a transient failure it will retry, and never on success.
+   *
+   * Without it a rejected replay leaves its predicted value on screen until an
+   * unrelated frame or a reload: the client drops the layer when it hands the
+   * write over (it cannot cursor-confirm through this path) and has no other
+   * signal that the write died. Absent when the write carried no optimistic
+   * update, and safe to ignore — a sink that never calls it behaves as before.
+   */
+  onRejected?: () => void;
+  shardKey?: string;
+}
+/**
+ * Pluggable durable outbox seam. When set on {@link LunoraClientOptions.outbox},
+ * the client delegates offline write durability + at-least-once replay to this
+ * sink instead of its built-in {@link PersistenceAdapter}-backed `OfflineQueue`.
+ * `@lunora/db` supplies the blessed implementation (`createExecutorOutboxSink`,
+ * backed by the TanStack `OfflineExecutor`); the interface itself is
+ * dependency-free so `@lunora/client` stays TanStack-free.
+ */
+interface OutboxSink {
+  /**
+   * Persist and schedule a write for replay. Rejects with an
+   * `OFFLINE_QUEUE_OVERFLOW`-coded error when the sink's cap is exceeded, so
+   * the caller can surface back-pressure to the issuing mutation.
+   */
+  enqueue: (mutation: OutboxMutation) => Promise<void>;
+  /**
+   * Whether the sink still holds writes that have not replayed. The client
+   * consults this before sending a fresh mutation live, so a new write can
+   * never overtake an older one the sink is still holding (a write deferred
+   * because its identity isn't re-confirmed yet is held indefinitely, with
+   * nothing for the client's flush barrier to wait on).
+   *
+   * Optional: a sink that cannot answer never engages the ordering gate, so
+   * such a sink behaves exactly as before.
+   */
+  pending?: () => boolean;
+}
+/**
+ * One persisted query result in the durable read cache (Pillar 2). Keyed in the
+ * store by `shardKey + functionPath + argsKey`; the record carries everything
+ * needed to render offline on reload and to resume the live subscription.
+ */
+interface CachedQuery {
+  /**
+   * Token-hash fingerprint of the bearer the value was cached under, when the
+   * entry was written by the identity the client currently advertises.
+   *
+   * The second half of the identity gate, and the half that makes the cache
+   * usable at all for a bearer-token app. `identity` settles on the resolved
+   * subject (`subj:<id>`) once the session resolves, but on the NEXT reload
+   * every adapter can only offer the stored token first — the subject arrives
+   * a round trip later, and offline it never arrives at all. Matching the
+   * credential the entry was written under is what lets the seed happen before
+   * (or without) that round trip. Absent when signed out, or when the value
+   * arrived over a socket authenticated as someone else.
+   */
+  credential?: string;
+  /**
+   * Issuing identity fingerprint (same shape the offline queue stamps). A
+   * cached value only hydrates when it matches the current identity, so a
+   * signed-out cache never leaks into a new session.
+   *
+   * `null` = cached by a client that had no subject to name — an app with no
+   * auth at all, or one the server answered "no session" to. It is never
+   * written while a session resolve is in flight, because a `null` written
+   * there belongs to a user the client was about to name, and every
+   * unidentified session would match it.
+   */
+  identity: string | null;
+  /**
+   * The `cursor` high-watermark this value reflects, replayed as `sinceSeq`
+   * on reconnect so the server can resume instead of re-snapshotting. Absent
+   * when the value predates CDC / no cursor was advertised.
+   */
+  serverCursor?: number;
+  /**
+   * The CDC `epoch` the `serverCursor` belongs to, replayed as `sinceEpoch`
+   * on reconnect so the server only resumes when the client is still on the
+   * same changelog timeline. Absent when no epoch was advertised.
+   */
+  serverEpoch?: string;
+  /** Wall-clock millis the value was written — drives LRU eviction. */
+  ts: number;
+  /** The full query result last seen from the server. */
+  value: unknown;
+  /**
+   * App/schema version stamped when persisted (from `LunoraClientOptions.persistenceVersion`).
+   * A cached value whose `version` doesn't match the current one is not hydrated —
+   * so a result of a now-changed shape from an older deploy can't render. Absent
+   * when no `persistenceVersion` is configured (no version gating).
+   */
+  version?: string;
+}
+/** A stored read-cache row: the {@link CachedQuery} plus the key it is stored under. */
+interface StoredQuery extends CachedQuery {
+  key: string;
+}
+/**
+ * Durable store for the client read cache (Pillar 2): query results survive a
+ * reload so reads hydrate from disk and render immediately while the socket
+ * reconnects. Opt-in via {@link LunoraClientOptions.queryCache}; omit to keep
+ * reads in memory only (today's behaviour). Mirrors {@link PersistenceAdapter}'s
+ * shape over the same IndexedDB plumbing.
+ */
+interface QueryCacheAdapter {
+  /** Drop every cached query (e.g. on logout / identity change). */
+  clear: () => Promise<void>;
+  /** Load every cached query — called once at startup to hydrate reads. */
+  load: () => Promise<StoredQuery[]>;
+  /** Upsert one cached query by key (called when a subscription value advances). */
+  put: (key: string, entry: CachedQuery) => Promise<void>;
+  /** Remove one cached query by key. */
+  remove: (key: string) => Promise<void>;
+}
+/**
+ * Resolves the WS `?token=` credential fresh at every (re)connect — the channel
+ * for short-lived tokens (e.g. the ephemeral admin sub-token the worker mints
+ * at `POST /_lunora/admin/ws-token`) instead of a static secret in the URL.
+ * May return the token synchronously or as a Promise; returning `undefined`
+ * connects without a token. A thrown error / rejected Promise fails that
+ * connect attempt, and the client retries with its normal reconnect backoff.
+ */
+type WsTokenProvider = () => Promise<string | undefined> | string | undefined;
+interface LunoraClientOptions {
+  /**
+   * Base path the worker mounts better-auth at, used by the client's
+   * `getCurrentUser()` to reach the `get-session` route. Defaults to
+   * `/api/auth` (matching `@lunora/auth`'s `DEFAULT_AUTH_BASE_PATH`).
+   */
+  authBasePath?: string;
+  bookmarkStorage?: BookmarkStorage;
+  /**
+   * Stable per-client id backing the custom-mutator watermark. Sent on the
+   * `connect` envelope (so the server can scope this client's
+   * `__client_watermark`) and stamped onto every {@link OutboxMutation} the
+   * {@link LunoraClientOptions.outbox} sink persists, where it pairs with the
+   * monotonic mutation id to form the idempotency key. The `@lunora/db` path
+   * persists a stable id alongside the outbox and passes it here; omit for the
+   * standalone client, which generates an ephemeral per-session id.
+   */
+  clientId?: string;
+  /**
+   * Default app context sent in the `connect` envelope right after each socket
+   * opens, forwarded to the server's `onConnect`/`onDisconnect` lifecycle hooks
+   * as `event.context`. A per-shard context registered via
+   * `setConnectionContext` overrides this for that shard. Omit when no lifecycle
+   * hook needs connection context.
+   */
+  connectionContext?: Record<string, unknown>;
+  /**
+   * Fail-fast timeout (ms) for opening a subscription WebSocket. If the
+   * handshake doesn't complete within this window — a hung dev proxy or a cold
+   * worker that never upgrades — the client force-closes the socket and routes
+   * through its normal reconnect/backoff (surfacing `offline` status) instead
+   * of leaving the live channel silently stuck on the browser's much longer
+   * default. Does not affect HTTP queries/mutations (those never ride the WS).
+   * Defaults to 10000 (10s); set to `0` (or negative) to disable.
+   */
+  connectTimeoutMs?: number;
+  /**
+   * When `true`, tabs sharing the same origin (and the same signed-in identity)
+   * coordinate via BroadcastChannel so only one tab — the "leader" — opens
+   * WebSocket connections to the server. Reduces simultaneous WS connections,
+   * bandwidth, and cross-tab state drift. Requires `BroadcastChannel`
+   * (browser-only); silently ignored otherwise. Defaults to `false`.
+   *
+   * **The channel is one-directional: leader → follower.** The leader
+   * broadcasts the values, errors, checkpoints and connection status of the
+   * subscriptions *it* holds; there is no frame with which a follower can ask
+   * the leader for anything.
+   *
+   * `subscribe` works on a follower and is how the relay delivers: the
+   * registration is what the leader's broadcast key is matched against, so a
+   * follower sees a value while the leader independently holds the same
+   * `(fn, args, shardKey)`.
+   *
+   * Nothing else is served, because the leader broadcasts nothing for it and a
+   * follower cannot ask. `subscribeShape` and `acquireConnectionContext` are
+   * inert on a follower — framework code (`@lunora/db`'s shape sync, every
+   * `usePresence` adapter) calls them from an effect the app cannot opt out
+   * of, so throwing would unwind the tab rather than degrade one feature.
+   * `whisper`, `whisperSubscribe`, `setConnectionContext` and `stream` are
+   * only ever called by app code, which can handle a failure, so those throw
+   * `NOT_IMPLEMENTED` rather than returning a handle that never fires. (The
+   * brief window every tab spends claiming leadership at startup is not a
+   * follower state: a lone tab self-promotes and its registered subscriptions
+   * are sent then.) HTTP surfaces — `query`, `mutation`, `action`, the offline
+   * queue's replay — are unaffected on every tab.
+   *
+   * So: enable this when your tabs run the SAME app views over plain
+   * `subscribe`, and leave it off if tabs can sit on different routes or you
+   * use shapes, whispers, streams, or connection context.
+   */
+  crossTabSync?: boolean;
+  fetch?: typeof fetch;
+  /**
+   * Interval (ms) between keepalive pings sent on each open subscription
+   * socket. The server answers them via the Durable Object's hibernation
+   * auto-response WITHOUT waking the DO, so an idle socket stays alive across
+   * hibernation without a billable wakeup. Defaults to 30000 (30s); set to
+   * `0` (or a negative value) to disable the heartbeat entirely.
+   */
+  heartbeatIntervalMs?: number;
+  /**
+   * When `true` and a `queryCache` is active, React's `useQuery` holds its
+   * TanStack query disabled until the durable cache has finished loading
+   * (`whenReady()`), so its first enabled render can seed the cached value
+   * instead of issuing an HTTP read that the cache would immediately
+   * overwrite. Defaults to `false`.
+   *
+   * It is ONLY React's `useQuery` that defers — the Vue, Svelte, Solid and
+   * Angular hooks subscribe at mount regardless of this flag, and so does
+   * React's own subscription registry. They do not need the gate: a
+   * subscription opened before the load completes is seeded by the load
+   * itself, so a cached value reaches the first subscriber either way.
+   *
+   * Requires `queryCache` to be set (not `false`); silently ignored otherwise.
+   */
+  hydrateOnStart?: boolean;
+  offlineQueue?: OfflineQueueOptions;
+  /**
+   * Durable outbox seam for offline writes. When supplied (the `@lunora/db`
+   * path wires `createExecutorOutboxSink`), offline mutations are delegated to
+   * the sink and the built-in {@link PersistenceAdapter}-backed `OfflineQueue`
+   * is bypassed, so a db app has exactly one durable write path. Omit for the
+   * standalone client, which keeps using {@link LunoraClientOptions.persistence}.
+   */
+  outbox?: OutboxSink;
+  /**
+   * Durable store for the offline mutation queue. Tri-state — an explicit
+   * {@link PersistenceAdapter} is used as-is; `false` opts out (the queue stays
+   * in memory, lost on reload); omitted (the default) auto-probes a durable
+   * IndexedDB store when the `indexedDB` global is present (browsers), otherwise
+   * in-memory, so SSR/Node/React-Native keep the in-memory behaviour and only
+   * environments that can persist do. Pass `createAsyncStoragePersistence()` on
+   * React Native.
+   */
+  persistence?: false | PersistenceAdapter;
+  /**
+   * App/schema version stamped onto every persisted queued write and cached
+   * read. Bump it on a breaking change to a function signature or query shape:
+   * on the next boot, persisted writes / cached reads stamped with a different
+   * version are dropped (and purged) rather than replayed / hydrated against the
+   * new schema. Omit to disable version gating (records are never invalidated by
+   * version).
+   *
+   * **Adoption is itself an invalidation event:** records written before you set
+   * `persistenceVersion` carry no version, so the first boot after enabling it
+   * purges all currently-queued offline writes (and cached reads) as stale. Adopt
+   * it on a build where that clean slate is acceptable — typically the same
+   * breaking deploy you're protecting against — not purely speculatively.
+   */
+  persistenceVersion?: string;
+  /**
+   * HTTP polling fallback for live queries on a network that refuses WebSocket
+   * upgrades (a corporate proxy, a captive portal).
+   *
+   * One-shot `query`/`mutation`/`action` calls already ride HTTP POST, so such a
+   * network does not break them — it breaks reactivity, and only that. After a
+   * run of connect attempts that never reach `open`, the client re-runs each
+   * subscribed query over the batch-RPC endpoint on an interval and reports
+   * `"polling"` from the client's `connectionStatus()`.
+   *
+   * It is a degradation, not a second transport: shapes (`@lunora/db`
+   * collections), durable streams and whispers have no request/response form to
+   * re-run and stay unavailable until a socket opens. Freshness is bounded by
+   * the interval, and each tick costs a full re-run of every subscribed query.
+   *
+   * Defaults to polling every 5s after 3 consecutive failed opens. Set
+   * `intervalMs: 0` to disable it and keep the historical behaviour (live
+   * queries simply stop moving).
+   */
+  pollingFallback?: {
+    /** Consecutive connect attempts that must fail to reach `open` first. Default 3; `0` disables. */
+    afterFailedAttempts?: number;
+    /** Poll cadence in ms. Default 5000; `0` disables. */
+    intervalMs?: number;
+  };
+  /**
+   * Durable store for the read cache (Pillar 2). When active, query results
+   * are persisted as their subscriptions advance and hydrated on construction
+   * so a reload renders cached data before the socket reconnects, then resumes
+   * the live subscription from the persisted cursor. Tri-state — an explicit
+   * {@link QueryCacheAdapter} is used as-is; `false` opts out (reads stay in
+   * memory only); omitted (the default) auto-probes IndexedDB exactly like
+   * {@link LunoraClientOptions.persistence}.
+   */
+  queryCache?: QueryCacheAdapter | false;
+  reconnect?: ReconnectOptions;
+  url: string;
+  WebSocket?: typeof WebSocket;
+  /**
+   * Credential appended to the WebSocket URL as `?token=…`. The server matches
+   * it against `LUNORA_WS_BEARER` (to clear the upgrade gate) and/or
+   * `LUNORA_ADMIN_TOKEN` (to authorize `__lunora_admin__:*` subscriptions —
+   * what the studio supplies). Browsers can't set headers on the `WebSocket`
+   * constructor, so the query parameter is the only channel; it ends up in
+   * server logs and history, so prefer a short-lived rotating token in
+   * production over a static secret.
+   *
+   * Pass a {@link WsTokenProvider} function to resolve the token fresh at
+   * every (re)connect — the channel for short-lived credentials such as the
+   * ephemeral admin sub-token minted by `POST /_lunora/admin/ws-token`: the
+   * provider re-mints on each reconnect, including the one following a `4001`
+   * token-expired drop, so a static master token never has to ride the URL.
+   */
+  wsToken?: string | WsTokenProvider;
+  wsUrl?: string;
+}
+/** Wire envelope sent on `POST /_lunora/rpc`. */
+interface RpcEnvelope {
+  args?: Record<string, unknown>;
+  /**
+   * Stable per-client identifier (custom-mutator push path). Pairs with
+   * {@link RpcEnvelope.mutationId} to form `idempotencyKey` and scope the
+   * server `__client_watermark`. Absent on plain `client.mutation` calls.
+   */
+  clientId?: string;
+  functionPath: string;
+  /**
+   * Idempotency key (`${clientId}:${mutationId}`) for the custom-mutator push
+   * path, mirrored into the `x-lunora-mutation-id` header. Absent on plain
+   * `client.mutation` calls.
+   */
+  idempotencyKey?: string;
+  /**
+   * Monotonic per-client mutation id (custom-mutator push path), backing the
+   * server-side per-client watermark: `id <= watermark` is a replay (skipped),
+   * `id == watermark + 1` runs authoritatively, `id > watermark + 1` halts the
+   * batch so the client resends from `watermark + 1`. Absent on plain
+   * `client.mutation` calls.
+   */
+  mutationId?: number;
+  shardKey?: string;
+}
+/**
+ * Wire response from the shard's `/rpc` endpoint (forwarded by the runtime). A
+ * watermarked custom-mutator push additionally carries `lastMutationId` — the
+ * highest per-client sequence the DO has applied — which the client uses to keep
+ * its `clientSeq` generator monotonic across reloads (see `LunoraClient.callMutator`).
+ * A plain mutation on a CDC shard carries `commitCursor` — the cursor the write
+ * committed at — which gates the drop of a per-call optimistic layer.
+ */
+type RpcResponseBody = {
+  error: {
+    code: string;
+    data?: unknown;
+    message: string;
+  };
+} | {
+  commitCursor?: number;
+  lastMutationId?: number;
+  result: unknown;
+};
+/** Subscription protocol — client → server. */
+interface ClientSubscribeMessage {
+  id: string;
+  /**
+   * `sinceSeq` is the persisted `cursor` high-watermark the client last saw
+   * for this shard (Pillar 1b resume). Present only when a durable
+   * {@link QueryCacheAdapter} restored a cached value with a cursor; the
+   * server replies with a lightweight `resume` frame instead of a full
+   * snapshot when nothing the query reads changed since it. Absent on a
+   * first-time subscribe.
+   */
+  query: {
+    args?: Record<string, unknown>;
+    functionPath?: string;
+    sinceEpoch?: string;
+    sinceSeq?: number;
+    table?: string;
+  };
+  type: "subscribe";
+}
+interface ClientUnsubscribeMessage {
+  id: string;
+  type: "unsubscribe";
+}
+/**
+ * One-shot control frame sent right after the socket opens. Registers the
+ * connection's app `context` (e.g. `{ roomId, sessionId }`) with the server and
+ * fires the `onConnect` lifecycle hooks; the same context is replayed to
+ * `onDisconnect` when the socket drops.
+ */
+interface ClientConnectMessage {
+  /**
+   * Wire behaviours this client can handle that an older one cannot, so the
+   * server can use them without breaking clients that can't. Currently just
+   * `"pageDelta"`; see `shared/page-result.ts` for what it promises and why it
+   * must be announced rather than assumed. Omitting it is always safe.
+   */
+  caps?: ReadonlyArray<string>;
+  /**
+   * Stable per-client id (persisted alongside the outbox). Lets the server
+   * scope this connection's `__client_watermark` so custom-mutator pokes can
+   * echo the right per-client `lastMutationId`. Omitted by clients that don't
+   * use custom mutators.
+   */
+  clientId?: string;
+  context?: Record<string, unknown>;
+  id: string;
+  type: "connect";
+}
+/**
+ * Subscribe to a declarative **shape** — server-side partial replication scoped
+ * by `shardBy` + the shape's predicate + RLS. The client sends the shape *name*
+ * + validated `args`; the server resolves the trusted `where` (identity/RLS
+ * `baseWhere` the client can't forge) and streams the matching rowset, then live
+ * {@link ServerPokePartMessage} diffs. `id` namespaces the subscription and is
+ * echoed as `shapeId` on every poke part.
+ */
+interface ClientShapeSubscribeMessage {
+  id: string;
+  shape: {
+    args?: Record<string, unknown>;
+    name: string;
+  };
+  /**
+   * Resume from this checkpoint (the `__cdc_log` cursor the client last
+   * applied for this shape). When absent or below the server's retained floor
+   * (`minCdcSeq`), the server re-seeds with a full insert-poke instead of a
+   * delta.
+   */
+  sinceCheckpoint?: number;
+  /**
+   * The CDC epoch {@link ClientShapeSubscribeMessage.sinceCheckpoint} belongs
+   * to. A mismatch (forked changelog timeline) forces a full re-seed even when
+   * the cursor is numerically in range.
+   */
+  sinceEpoch?: string;
+  type: "shape_subscribe";
+}
+/** Cancel a shape subscription started with the same `id`. */
+interface ClientShapeUnsubscribeMessage {
+  id: string;
+  type: "shape_unsubscribe";
+}
+interface ClientAckMessage {
+  id: string;
+  type: "ack";
+}
+/**
+ * Start a streaming query. The id namespaces a fresh stream and is echoed on
+ * every {@link ServerChunkMessage} the server pushes back. Cancel a running
+ * stream by sending a {@link ClientUnsubscribeMessage} with the same id —
+ * subscription and stream id-spaces share the cancel channel; the prefix
+ * (`sub_*` vs `stream_*`) keeps the local registries searchable.
+ */
+interface ClientStreamMessage {
+  /**
+   * Run generation the {@link ClientStreamMessage.sinceChunk} watermark
+   * belongs to: the `generation` stamp carried by the chunk frames this
+   * client already received, echoed back on a resume. The server refuses to
+   * splice a different run's tail onto the held prefix — a mismatch fails
+   * with `STREAM_INTERRUPTED` instead. Omitted on a first attach.
+   */
+  generation?: number;
+  id: string;
+  query: {
+    args?: Record<string, unknown>;
+    functionPath: string;
+    shardKey?: string;
+  };
+  /**
+   * Resume watermark: the highest chunk `seq` this client already received.
+   * Only meaningful for a stream the server declared `durable` — the run
+   * replays everything after it and then continues live, which is what turns
+   * a reconnect into a resume instead of a lost generation. Omitted on a
+   * first attach.
+   *
+   * Named `sinceChunk`, not `sinceSeq`, because a subscribe envelope already
+   * carries a `query.sinceSeq` meaning the CDC cursor.
+   */
+  sinceChunk?: number;
+  type: "stream";
+}
+/**
+ * Join or leave a whisper `topic` — an app-chosen ephemeral channel scoped to a
+ * shard. While joined, the client receives every {@link ServerWhisperMessage}
+ * other members broadcast to the topic.
+ */
+interface ClientWhisperSubscribeMessage {
+  topic: string;
+  type: "whisper_subscribe" | "whisper_unsubscribe";
+}
+/**
+ * Broadcast ephemeral `data` to the topic's other members on the shard. The
+ * payload is relayed verbatim with no server-side persistence (no SQLite/CDC
+ * write) — for typing indicators, live cursors, presence pings. The sender does
+ * not receive its own whisper.
+ */
+interface ClientWhisperMessage {
+  data?: unknown;
+  topic: string;
+  type: "whisper";
+}
+type ClientMessage = ClientAckMessage | ClientConnectMessage | ClientShapeSubscribeMessage | ClientShapeUnsubscribeMessage | ClientStreamMessage | ClientSubscribeMessage | ClientUnsubscribeMessage | ClientWhisperMessage | ClientWhisperSubscribeMessage;
+/** Subscription protocol — server → client. */
+interface ServerDataMessage {
+  /**
+   * The `__cdc_log` high-watermark covered by this frame (Pillar 1b). The
+   * client persists it as the query's `serverCursor` and replays it as
+   * `sinceSeq` on the next reconnect. Absent on shards that never enabled CDC.
+   */
+  cursor?: number;
+  data?: unknown;
+  delta?: unknown;
+  /** The CDC epoch this frame's cursor belongs to (see {@link CachedQuery.serverEpoch}). */
+  epoch?: string;
+  id: string;
+  /**
+   * The highest custom-mutator `mutationId` from this client the server has
+   * now applied (the per-client `__client_watermark`). Echoed so the client's
+   * outbox can drop confirmed pending mutations and let TanStack DB collapse
+   * the matching optimistic overlay. Absent on shards without custom mutators.
+   */
+  lastMutationId?: number;
+  type: "data" | "delta";
+}
+/**
+ * Lightweight resume acknowledgement (Pillar 1b): the server determined that
+ * nothing the subscription reads changed since the client's `sinceSeq`, so it
+ * skips re-sending the snapshot. The client keeps its cached value and only
+ * advances `serverCursor` to `cursor`.
+ */
+interface ServerResumeMessage {
+  cursor?: number;
+  /** The CDC epoch this resume's cursor belongs to (see {@link CachedQuery.serverEpoch}). */
+  epoch?: string;
+  id: string;
+  /** Per-client custom-mutator watermark (see {@link ServerDataMessage.lastMutationId}). */
+  lastMutationId?: number;
+  type: "resume";
+}
+/**
+ * Settled acknowledgement for a **list** subscription: a write touched one of
+ * the subscription's read tables but produced a byte-identical result, so the
+ * server suppressed the data frame. Sent ONLY to a `@lunora/db` custom-mutator
+ * client (one that announced a `clientId`, hence has a server-side
+ * `__client_watermark`) so its optimistic list overlay drops even when no data
+ * frame arrives. Plain `useQuery` subscribers never receive it, and an older
+ * client safely ignores the unknown frame.
+ */
+interface ServerSettledMessage {
+  cursor?: number;
+  /** The CDC epoch this settled frame's cursor belongs to (see {@link CachedQuery.serverEpoch}). */
+  epoch?: string;
+  id: string;
+  /**
+   * The highest custom-mutator `mutationId` from this client the server has
+   * now applied (the per-client `__client_watermark`). Forwarded to a
+   * collection's `onCheckpoint` so it can drop the overlay for the confirmed
+   * write whose result didn't change this list.
+   */
+  lastMutationId?: number;
+  type: "settled";
+}
+interface ServerErrorMessage {
+  error?: unknown;
+  id?: string;
+  message?: string;
+  type: "error";
+}
+interface ServerAckMessage {
+  id: string;
+  type: "ack";
+}
+interface ServerCompleteMessage {
+  id: string;
+  type: "complete";
+}
+/** One frame of a streaming query — `data` carries the user-yielded chunk. */
+interface ServerChunkMessage {
+  data: unknown;
+  /**
+   * Generation stamp of the **durable** run this chunk belongs to. The client
+   * stores it beside {@link ServerChunkMessage.seq} and echoes it as
+   * {@link ClientStreamMessage.generation} on a resume, so the server can
+   * tell a genuine resume from an attempt to splice onto a different run
+   * under the same key. Absent on an ephemeral stream.
+   */
+  generation?: number;
+  id: string;
+  /**
+   * Monotonic position of this chunk within a **durable** run, starting at 1.
+   * The client stores the last one it saw and replays it as
+   * {@link ClientStreamMessage.sinceChunk} when the socket comes back. Absent
+   * on an ephemeral stream, which has nothing to resume from.
+   */
+  seq?: number;
+  type: "chunk";
+}
+/**
+ * An ephemeral whisper relayed from another member of `topic` on the same shard
+ * (AnyCable-style whispering). `data` is the sender's payload verbatim; `from`
+ * is the sender's verified user id when known (absent for an anonymous sender).
+ * Never persisted server-side.
+ */
+interface ServerWhisperMessage {
+  data: unknown;
+  from?: string;
+  topic: string;
+  type: "whisper";
+}
+/**
+ * One row-level change in a shape's replication stream — the wire form of the
+ * DO's `__cdc_log` `CdcChange`. `insert`/`update` carry the post-image in
+ * `value` (projected to the shape's `columns`); `delete` omits it, identifying
+ * the removed row by `key` alone. The client applies these to its local
+ * collection; an unknown `key` on a `delete` is a safe no-op (a row the client
+ * never had in this shape).
+ */
+interface RowOp {
+  /** Row primary key (`_id`). */
+  key: string;
+  op: "delete" | "insert" | "update";
+  /** Logical table the row belongs to. */
+  table: string;
+  /** Post-image document for insert/update; absent on delete. */
+  value?: Record<string, unknown>;
+}
+/**
+ * Opens a **poke** — an atomically-applied batch of shape diffs (Zero's poke
+ * protocol). A `pokeStart` is followed by zero or more {@link ServerPokePartMessage}
+ * frames and closed by exactly one {@link ServerPokeEndMessage}; the client
+ * buffers every part and applies them in a single transaction at `pokeEnd`, so a
+ * socket that drops mid-poke simply re-seeds on reconnect (no torn view).
+ */
+interface ServerPokeStartMessage {
+  /**
+   * Poke-level fallback base, stamped by single-part senders. Per-shape
+   * {@link ServerPokePartMessage.baseCheckpoint} takes precedence; this is what
+   * a part without its own base falls back to.
+   */
+  baseCheckpoint?: number;
+  /** CDC epoch this poke belongs to; a mismatch forces the client to re-seed rather than apply. */
+  epoch?: string;
+  /** Correlates this poke's `pokeStart`/`pokePart`/`pokeEnd` frames. */
+  pokeId: string;
+  type: "pokeStart";
+}
+/** One shape's slice of an in-flight poke: the row-ops to apply for `shapeId`. */
+interface ServerPokePartMessage {
+  /**
+   * The checkpoint this shape's view must be at for `rowsPatch` to splice on
+   * cleanly. Per shape, because every shape on a socket has its own
+   * delivered-through cursor. Absent when the server cannot name a base — the
+   * gap check is then disarmed for this part, never guessed at.
+   */
+  baseCheckpoint?: number;
+  /** Per-client custom-mutator watermark carried with this slice (see {@link ServerSettledMessage.lastMutationId}). */
+  lastMutationId?: number;
+  pokeId: string;
+  /**
+   * `true` when `rowsPatch` is the shape's COMPLETE membership, not a diff (a
+   * full seed or re-seed). The client MUST drop its current view for this shape
+   * before applying: a seed is inserts-only, so merging it leaves any row that
+   * left the shape while the client was disconnected on screen forever.
+   *
+   * Never inferred from an absent {@link ServerPokePartMessage.baseCheckpoint} —
+   * most live poke paths legitimately carry no base.
+   */
+  reset?: boolean;
+  /** Ordered row-level changes for this shape, applied in sequence at `pokeEnd`. */
+  rowsPatch: RowOp[];
+  /** The {@link ClientShapeSubscribeMessage.id} these row-ops belong to. */
+  shapeId: string;
+  type: "pokePart";
+}
+/**
+ * Closes a poke: the client commits the buffered parts atomically and advances
+ * its checkpoint to {@link ServerPokeEndMessage.checkpoint} (the `__cdc_log`
+ * cursor high-watermark the view now reflects), replayed as `sinceCheckpoint` on
+ * the next reconnect.
+ */
+interface ServerPokeEndMessage {
+  /** The `__cdc_log` cursor the view is at after applying this poke. */
+  checkpoint?: number;
+  /** CDC epoch the {@link ServerPokeEndMessage.checkpoint} belongs to. */
+  epoch?: string;
+  pokeId: string;
+  type: "pokeEnd";
+}
+type ServerMessage = ServerAckMessage | ServerChunkMessage | ServerCompleteMessage | ServerDataMessage | ServerErrorMessage | ServerPokeEndMessage | ServerPokePartMessage | ServerPokeStartMessage | ServerResumeMessage | ServerSettledMessage | ServerWhisperMessage;
+/**
+ * The authenticated user as exposed client-side, mirroring better-auth's
+ * `user` row (the `user` field of the `get-session` response). Kept minimal
+ * and structural — only `id` is guaranteed; the rest are the common better-auth
+ * fields, and the index signature carries any plugin-contributed extras.
+ */
+interface User {
+  readonly createdAt?: NullableTimestamp;
+  readonly email?: null | string;
+  readonly emailVerified?: boolean | null;
+  readonly id: string;
+  readonly image?: null | string;
+  readonly name?: null | string;
+  readonly [key: string]: unknown;
+  readonly updatedAt?: NullableTimestamp;
+}
+/**
+ * Per-job retry policy carried on a {@link ScheduleRecord}. Mirrors
+ * `@lunora/scheduler`'s `RetryPolicy`; absent means the scheduler's defaults.
+ */
+interface ScheduleRetryPolicy {
+  /** Backoff growth across attempts. Default `"exponential"`. */
+  backoff?: "exponential" | "linear";
+  /** Base delay in milliseconds for the first retry. Default `30_000`. */
+  baseMs?: number;
+  /** Maximum number of dispatch attempts before dead-lettering. Default `5`. */
+  maxAttempts?: number;
+  /** Optional ceiling clamping the computed backoff delay. */
+  maxMs?: number;
+}
+/**
+ * One pending scheduled function, as returned by the worker's
+ * `GET /_lunora/admin/scheduled` endpoint. The route is a byte-for-byte proxy of
+ * the SchedulerDO's own `/list`, so this mirrors `@lunora/scheduler`'s
+ * `ScheduleRecord` field-for-field — structurally, so the client carries no
+ * dependency on it. `packages/client/__tests__/structural-mirrors.test.ts` fails
+ * when the two drift.
+ */
+interface ScheduleRecord {
+  args: Record<string, unknown>;
+  /**
+   * Dispatch attempts already made. Absent (treated as 0) until the first
+   * failure; on a dead-letter record it is the exhausted count (> the retry
+   * budget). Surfaced so the studio can show how hard a job tried before it
+   * was parked.
+   */
+  attempts?: number;
+  enqueuedAt: number;
+  /**
+   * The `ns:fn` path dispatched on fire. Absent when the job targets a durable
+   * workflow/agent instead — exactly one of `functionPath` /
+   * {@link ScheduleRecord.workflow} is set, so a view rendering a job's target
+   * must fall back to `workflow` rather than assuming a path.
+   */
+  functionPath?: string;
+  id: string;
+  /** Scheduler/workpool instance the job was enqueued through. Absent for the default instance. */
+  instanceName?: string;
+  /** Logical workpool the job is routed to (concurrency-gated), when any. */
+  pool?: string;
+  /** Per-job retry policy; absent means the scheduler's built-in defaults. */
+  retry?: ScheduleRetryPolicy;
+  scheduledFor: number;
+  shardKey?: string;
+  /**
+   * The `WORKFLOW_*`/`AGENT_*` binding a fresh durable instance is started from
+   * on fire (the {@link ScheduleRecord.args} become its `params`). Set instead
+   * of {@link ScheduleRecord.functionPath}.
+   */
+  workflow?: string;
+}
+/**
+ * One workpool's live backlog, as returned by the worker's
+ * `GET /_lunora/admin/scheduled/status` endpoint. Mirrors `@lunora/scheduler`'s
+ * `SchedulerPoolStatus` structurally so the client carries no dependency on it.
+ */
+interface SchedulerPoolStatus {
+  /** Jobs currently dispatched-but-not-yet-completed (the held concurrency slots). */
+  inFlight: number;
+  /** The pool's concurrency cap. */
+  maxConcurrency: number;
+  /** The logical workpool name. */
+  name: string;
+  /** Pending jobs routed to this pool but not yet dispatched. */
+  queued: number;
+}
+/**
+ * The app-level scheduler backlog, as returned by the worker's
+ * `GET /_lunora/admin/scheduled/status` endpoint. `pools` is the per-pool
+ * breakdown; `backlog` and `inFlight` are the app-wide sums of `queued` and
+ * `inFlight` across every pool — the headline numbers for the studio SLO
+ * view. Mirrors `@lunora/scheduler`'s `SchedulerStatus` structurally.
+ */
+interface SchedulerStatus {
+  /** Sum of every pool's `queued` count — the total pending backlog. */
+  backlog: number;
+  /** Sum of every pool's `inFlight` count — the total held concurrency slots. */
+  inFlight: number;
+  /** Per-pool backlog breakdown. */
+  pools: SchedulerPoolStatus[];
+}
+/**
+ * One shard's request volume, as returned by the worker's
+ * `POST /_lunora/admin/shard-traffic` endpoint. The cross-shard traffic feed
+ * the studio's `hot_shard` advisor lint consumes: `requests` is the shard's
+ * lifetime dispatch total, `shardKey` the DO id name (`""` for the root shard).
+ */
+interface ShardTrafficEntry {
+  requests: number;
+  shardKey: string;
+}
+/**
+ * The whole-shard-set traffic distribution returned by the worker's
+ * `POST /_lunora/admin/shard-traffic` endpoint. `shards` is one entry per live
+ * shard (a failed shard surfaces with `requests: 0`); `ok`/`failed` count the
+ * shards that returned vs. errored. Shaped to feed the advisor's `hot_shard`
+ * lint after the studio tags each entry with its sharded function `group`.
+ */
+interface ShardTrafficResult {
+  failed: number;
+  ok: number;
+  shards: ShardTrafficEntry[];
+}
+/**
+ * One object in the storage bucket, as returned by the worker's
+ * `GET /_lunora/admin/storage` endpoint. Mirrors `@lunora/storage`'s
+ * `R2ObjectLike` structurally.
+ */
+interface StorageObject {
+  customMetadata?: Record<string, string>;
+  etag: string;
+  httpMetadata?: {
+    contentType?: string;
+  };
+  key: string;
+  size: number;
+  /**
+   * When the object was stored. R2 emits a `Date`, which JSON-serializes to an
+   * ISO string over the wire; a mock may supply epoch ms — so consumers should
+   * normalise via `new Date(uploaded)`. Absent if the backend didn't report it.
+   */
+  uploaded?: number | string;
+}
+/** One page of {@link StorageObject}s plus the cursor to fetch the next, if any. */
+interface StorageListPage {
+  cursor?: string;
+  objects: StorageObject[];
+}
+/**
+ * One argument of a registered function, derived from its `v.*` validator by the
+ * worker. A compact signature shape — enough to render a function's API without
+ * the build-time codegen types.
+ */
+interface FunctionArgumentDescriptor {
+  /** Element validator kind for an `array` arg (one level), e.g. `string`. */
+  element?: string;
+  /** The (optional-unwrapped) validator kind, e.g. `string`, `id`, `object`. */
+  kind: string;
+  /** The argument name. */
+  name: string;
+  /** True when the arg is wrapped in `v.optional(...)`. */
+  optional: boolean;
+  /** Target table for an `id` arg (`v.id("table")`). */
+  table?: string;
+}
+/**
+ * One registered function, as returned by the worker's
+ * `GET /_lunora/admin/functions` endpoint: its `<file>:<function>` path, which
+ * client method (`query` / `mutation` / `action`) invokes it, and its argument
+ * signature. `args` is absent on responses from an older worker.
+ */
+interface FunctionDescriptor {
+  args?: FunctionArgumentDescriptor[];
+  kind: "action" | "mutation" | "query";
+  path: string;
+}
+/** A `.global()` (D1-backed) table plus its row count, from `/_lunora/admin/global/tables`. */
+interface GlobalTableInfo {
+  name: string;
+  rowCount: number;
+}
+/** A window of rows from one global table, from `/_lunora/admin/global/table`. */
+interface GlobalTablePage {
+  columns: string[];
+  /** FK columns (local column → referenced table) for external tables with real `REFERENCES` constraints, from `PRAGMA foreign_key_list`. */
+  refs?: Record<string, string>;
+  rows: Record<string, unknown>[];
+  total: number;
+}
+/**
+ * One equality constraint a facet-value click adds to the global browser's view
+ * (`column = value`). `value` is the raw stored scalar the facet returned, sent
+ * as-is and bound server-side, so it never injects SQL.
+ */
+interface GlobalFilterClause {
+  column: string;
+  value: unknown;
+}
+/** One distinct value of a faceted global column with its row count, from `/_lunora/admin/global/facet`. */
+interface GlobalFacetValue {
+  count: number;
+  value: unknown;
+}
+/** Per-column distinct-value summary for the global browser, from `/_lunora/admin/global/facet`. */
+interface GlobalFacetResult {
+  truncated: boolean;
+  values: GlobalFacetValue[];
+}
+/** A nullable timestamp field as better-auth serializes it: epoch-ms, ISO string, or null. */
+type NullableTimestamp = null | number | string;
+/** A workflow instance's lifecycle status. Mirrors Cloudflare's `InstanceStatus`. */
+type WorkflowInstanceStatus = "complete" | "errored" | "paused" | "queued" | "running" | "terminated" | "unknown" | "waiting" | "waitingForPause";
+/** The lifecycle mutations the status endpoint accepts. */
+type WorkflowInstanceAction = "pause" | "resume" | "terminate";
+/** One row of the workflow-instances list. */
+interface WorkflowInstanceSummary {
+  createdOn?: string;
+  endedOn?: string;
+  id: string;
+  startedOn?: string;
+  status: WorkflowInstanceStatus;
+}
+/** One durable step of an instance's execution timeline. */
+interface WorkflowStepDetail {
+  /** 1-based attempt count (`> 1` means the step retried). */
+  attempts?: number;
+  end?: string;
+  error?: unknown;
+  name: string;
+  output?: unknown;
+  start?: string;
+  success?: boolean;
+  /** `step` / `sleep` / `waitForEvent` / … (Cloudflare's step `type`). */
+  type?: string;
+}
+/** A workflow instance's full detail: summary plus params/output/error and the step timeline. */
+interface WorkflowInstanceDetail extends WorkflowInstanceSummary {
+  error?: unknown;
+  output?: unknown;
+  params?: unknown;
+  steps: WorkflowStepDetail[];
+}
+/** A page of workflow instances. */
+interface WorkflowInstancePage {
+  /**
+   * Whether workflow inspection is configured on the worker (a Cloudflare
+   * account id + API token). `false` when the admin proxy reports it can't
+   * inspect instances; omitted (treated as configured) otherwise. Lets a
+   * caller render a "set credentials" state without a failed request.
+   */
+  configured?: boolean;
+  instances: WorkflowInstanceSummary[];
+  page: number;
+  perPage: number;
+  totalCount?: number;
+}
+type SubscriptionCallback = (data: 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;
+  /**
+   * `true` only on the checkpoint a `data`/`delta` frame fires immediately
+   * before that same frame's rowset callback — i.e. the one checkpoint whose
+   * `mutationId` describes rows that are about to arrive.
+   *
+   * A `settled` frame (and a cross-tab `subscription-settled` relay) fires a
+   * checkpoint with NO matching rowset, because the server suppressed a data
+   * frame whose value didn't change. A consumer that stashes `mutationId` for
+   * the next rowset to consume — `@lunora/db`'s `pendingFrameWatermark` — must
+   * not stash those, or the value sits until some later unstamped frame eats
+   * it and the checkpoint gate resolves at a stale watermark instead of
+   * falling back to the RPC-ack compensator.
+   */
+  rowsFollow?: boolean;
+}
+/** A subscription-scoped error the server pushed for this subscription id. */
+interface SubscriptionError {
+  /**
+   * The coded reason, when the frame carried one. `LunoraErrorCodeInput`, not
+   * `LunoraErrorCode`: the catalog codes autocomplete for a consumer branching
+   * on this (the shard sends `BAD_SUBSCRIPTION_ARGS`, `TOO_MANY_SUBSCRIPTIONS`,
+   * `SUBSCRIPTION_PERSIST_FAILED`, …; the client itself adds
+   * `WIRE_DECODE_FAILED` for a frame `decodeWire` refuses), but this value is
+   * read verbatim off the wire and nothing validates it against the catalog,
+   * so narrowing it to `LunoraErrorCode` would be a lie a newer server tells.
+   */
+  code?: LunoraErrorCodeInput;
+  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: SyncWatermark) => 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;
+  /**
+   * The wire-encoded form of `args`, computed once at `subscribe` time (so an
+   * unsupported value fails loud at the call site, not inside a reconnect's
+   * open handler). Sent on every `subscribe` frame — identical to `args` for
+   * pure JSON, tagged tokens for `bigint`/`Date`/bytes/… (the shard
+   * `decodeWire`s them at its subscribe entry point).
+   *
+   * A SNAPSHOT, not a view: `args` is the caller's own object, retained by
+   * reference and never copied, so a caller that mutates it after subscribing
+   * would otherwise poison every later resubscribe. `encodeWire` rebuilds
+   * every container, so this copy is immune to that.
+   */
+  readonly wireArgs: Record<string, unknown>;
+}
+/**
+ * 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;
+  /**
+   * The registry key of an already-registered state, from its cached
+   * {@link SubscriptionState.argsKey}. Re-deriving it from `state.args` would
+   * re-read the caller's own (mutable) args object, so a caller that mutated
+   * its args after subscribing would compute a DIFFERENT key on unsubscribe
+   * and leak the registration forever.
+   */
+  static keyOf(state: SubscriptionState): 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[];
+  /**
+   * Drop every registration. Terminal — used by `LunoraClient.close()`, whose
+   * whole point is to release the callback closures each {@link SubscriptionState}
+   * holds (`callbacks`, `errorCallbacks`, `checkpointCallbacks` — React state
+   * setters and `@lunora/db` collection closures), which otherwise outlive the
+   * closed client for as long as the client object is reachable.
+   */
+  clear(): void;
+}
+/**
+ * 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;
+ * `polling` = no socket would open, so live queries are being refreshed over HTTP
+ * instead (see {@link file://./polling-fallback.ts} — live but slower, and shapes
+ * / streams / whispers are dark); `offline` = sockets exist but all are down
+ * (between reconnect attempts).
+ *
+ * `polling` outranks `connecting`: while the fallback is running a reconnect is
+ * still armed in the background, and reporting that attempt would flicker the
+ * indicator between two states while data is in fact arriving on the slow path.
+ */
+type ConnectionStatus = "connected" | "connecting" | "idle" | "offline" | "polling";
+/** 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;
+  /**
+   * Single-query shortcut: the transform is layered onto the subscription
+   * registered under **this write's own** `(functionPath, args, shardKey)`, and
+   * nothing else. A client cannot know which queries a write affects, so the
+   * targeting rule is "same reference, same args" — which makes this the
+   * shorthand for a query and a mutation that share a path (a counter, a
+   * document by id), and a silent no-op for anything else.
+   *
+   * **The general case — a `messages:send` mutation patching a `messages:list`
+   * query — is {@link MutationCallOptions.optimisticUpdate}**, whose store names
+   * its targets. Reach for that whenever the mutation and the query are
+   * different functions, which is nearly always.
+   *
+   * The transform must be pure: it re-runs on every server frame while the write
+   * is pending, so derive from `current` rather than closing over a value.
+   */
+  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;
+  /**
+   * Pin this call's `.dropStalePatches()` baseline instead of sampling the
+   * client's current view — the durable-replay counterpart to
+   * {@link MutationCallOptions.mutationId}. See
+   * {@link import("./types").OutboxMutation.baselineSeq} for why a replay must
+   * hand back the cursor it was composed at.
+   *
+   * Tri-state, the same shape (and for the same reason) as the `identity` stamp
+   * a queued write carries: `undefined` samples the current cursor, `null` pins
+   * "composed with no baseline", and a number pins that cursor. A plain
+   * `number | undefined` could not express the middle case, so every write
+   * queued without a live subscription would have re-derived.
+   *
+   * Omit for normal calls.
+   */
+  replayBaseline?: null | number;
+  shardKey?: string;
+}
+/** Callback a shape subscription invokes with its materialized rowset on every applied poke. */
+type ShapeCallback = (rows: Record<string, unknown>[]) => void;
+/**
+ * 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;
+  /** Failed-open run that engages the HTTP polling fallback; `0` disables it. */
+  private readonly pollingFallbackAfterFailedAttempts;
+  /** Polling-fallback cadence (ms); `0` disables it. See {@link LunoraClientOptions.pollingFallback}. */
+  private readonly pollingFallbackIntervalMs;
+  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;
+  /**
+   * The read-cache entries currently ON DISPLAY in a live subscription, by the
+   * same key — every entry consumed out of `hydratedQueryCache` and not yet
+   * overwritten by a server frame.
+   *
+   * Gating the cache at read time only protects a value not handed over YET.
+   * A credential can change while a cached value is already on screen (the
+   * account-switch shape: an established subject, a token it was never checked
+   * against), and the fingerprint does not move with it — so nothing else
+   * would notice. `revokeCacheSeededValues` takes those values back off
+   * screen and returns the entries to `hydratedQueryCache`, where the ordinary
+   * identity gate decides whether they may ever be shown again.
+   */
+  private readonly cacheSeededQueries;
+  /**
+   * 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;
+  /**
+   * The bearer token `authSubject` was last asserted against. A subject
+   * is a claim about WHO a specific credential belongs to; once the token
+   * rotates, the sticky label is carried forward on the assumption it is the
+   * same user — but nothing has confirmed that yet, and the alternative (an
+   * account switch) would replay one user's queued writes as another. While
+   * this is out of step with `authToken` the identity counts as unconfirmed
+   * and every replay verdict is `"unknown"` (hold), until the next session
+   * resolve re-asserts the subject. Only used when a subject is established;
+   * a token-hash identity is self-confirming.
+   */
+  private subjectToken;
+  /**
+   * How many `getCurrentUser()` round trips are in flight.
+   *
+   * The identity gates need to tell two `null` fingerprints apart. For an app
+   * with no auth at all, and for a client the server has answered "no
+   * session" to, `null` is a real and stable identity — nobody else holds it,
+   * so a `null`-stamped queued write or cached read is this client's own and
+   * may be used. While a resolve is IN FLIGHT it is neither: the fingerprint
+   * may be one round trip away from `subj:<id>`, which is the window a cookie
+   * app spends every page load in, and where `null === null` handed one
+   * browser user's durable state to the next. Counted rather than flagged so
+   * two overlapping resolves (a token change during a probe) both have to
+   * finish before the gates reopen.
+   */
+  private sessionProbesInFlight;
+  /**
+   * Monotonic id stamped on each `/get-session` round trip, so only the
+   * NEWEST one may write the shared identity.
+   *
+   * `adoptResolvedSubject`'s token check asks whether the credential the
+   * answer is about is still the one in hand. On a cookie app there is no
+   * credential to ask about: every probe captures `requestToken === null`, so
+   * two overlapping probes both pass it and whichever lands LAST wins —
+   * including an older one, which then replaces the subject a newer answer
+   * already established. Comparing the generation instead asks the question
+   * the token cannot: is this still the current question?
+   */
+  private sessionProbeGeneration;
+  /**
+   * Whether anything resolves this client's identity at all.
+   *
+   * The gates need to tell an app with NO AUTH — whose `null` fingerprint is
+   * settled forever and shared with nobody — from a cookie app that simply
+   * has not asked yet. Nothing in the client's own configuration says which
+   * it is (`authBasePath` has a default), so the answer is declared: a
+   * `getCurrentUser()` call, or `@lunora/client/auth`'s identity store
+   * attaching itself, is what makes `null` provisional. An app that does
+   * neither keeps its read cache and its offline queue exactly as before.
+   */
+  private identityResolutionExpected;
+  /**
+   * Whether a `/get-session` round trip has ever produced an ANSWER — a user,
+   * or an explicit "no session". Distinct from `sessionProbesInFlight`, which
+   * only covers the request's own lifetime and so reopened the gates both
+   * before the first probe started and after one failed to answer, leaving a
+   * `null` fingerprint free to match the previous cookie user's cached rows
+   * and queued writes in exactly the window the probe count was added to
+   * close. A transport or parse failure never sets this: it learned nothing.
+   */
+  private identitySettled;
+  /**
+   * 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;
+  /** Token hash the last durable-replay auth refusal fired `onTokenExpired` for — see `shouldRequeueReplayFailure`. */
+  private authRefusalNotifiedFor;
+  /** 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. */
+  /**
+   * Teardown callbacks for the admin sockets {@link LunoraClient.subscribeScheduledJobs}
+   * opens. Those run their own reconnect loop off a closure-local `closed`
+   * flag rather than `this.closed` (they predate `ensureSocket`'s guard), so
+   * without this registry a `close()` left every one of them reconnecting on
+   * its backoff forever — re-minting an ephemeral admin sub-token on each
+   * attempt when a `WsTokenProvider` is wired.
+   */
+  private readonly adminSocketTeardowns;
+  /**
+   * The in-flight offline-queue replay per shard (`connectionKey`), while one
+   * is running. Two jobs:
+   *
+   * 1. It serializes overlapping flushes for the same shard — two reconnect
+   *    events in quick succession used to drain and replay concurrently.
+   * 2. It is the barrier {@link LunoraClient.mutation} waits on before sending a FRESH
+   *    write directly. The socket's `open` handler flips `wsState` to `"open"`
+   *    first and calls the flush last, so from that instant `mutation()`'s
+   *    offline gate is false and a new write raced straight to `/rpc` against
+   *    the replay of the older, queued write for the same document — the newer
+   *    one could land first and then be overwritten by the older. Ordering
+   *    inside the replay (`replaySequential`) never covered this, because the
+   *    racing write was never in the queue.
+   */
+  private readonly offlineFlushes;
+  /**
+   * Per-shard replay backoff, keyed by {@link connectionKey} exactly as the
+   * flushes and their timers are: `delayMs` is the longest hint the CURRENT
+   * flush of that key was given (written by
+   * {@link LunoraClient.noteReplayRetryDelay}, consumed once by
+   * {@link LunoraClient.scheduleRateLimitedRetry} at the end of the drain), and
+   * `attempts` counts its consecutive failed flushes, which is what the
+   * hintless backoff ramps on.
+   *
+   * Keyed, not a single field: flushes are per shard key and run concurrently,
+   * so one field means one limited shard sets the wait for every other shard
+   * and two flushes overwrite — then consume — each other's delay, leaving one
+   * of them with nothing scheduled at all. Evicted by
+   * {@link LunoraClient.scheduleRateLimitedRetry} the moment a key has nothing
+   * left to retry, so an app that shards per document does not accumulate an
+   * entry per document it ever wrote.
+   */
+  private readonly replayRetryState;
+  /** Pending rate-limit retry flushes, keyed by {@link connectionKey}, so `close()` can cancel them. */
+  private readonly replayRetryTimers;
+  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. Clearing the token
+   * clears it too — a credential-less subject would let the NEXT sign-in
+   * inherit the previous user's identity (and their queue and read cache).
+   * Establishing the subject on an UNCHANGED token (e.g. the user id resolves a
+   * tick after the token was set — see {@link getCurrentUser}, which does this
+   * for every adapter) re-stamps any in-flight queued writes rather than
+   * dropping them: same credential, just a more stable label. A real user
+   * switch still drops the previous user's writes.
+   *
+   * A sticky subject carried across a token change is not re-confirmed until
+   * the next session resolve says which user the NEW credential belongs to.
+   * Queued writes are HELD (never sent, never dropped) for that window — see
+   * {@link replayIdentityVerdict} — so a refresh can't replay them and an
+   * account switch can't replay the previous user's writes as the new one.
+   *
+   * 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;
+  /**
+   * Declare that this client's identity is resolved by something — call it
+   * before the first `getCurrentUser()`, not after.
+   *
+   * `@lunora/client/auth`'s identity store calls this when it attaches, which
+   * is the moment an app becomes one that HAS auth. Until something says so,
+   * a `null` fingerprint is taken to be the settled, unshared identity of an
+   * app with no auth at all, because nothing else distinguishes the two: both
+   * hold no token, both have never been answered, and `authBasePath` has a
+   * default. That reading is right for the no-auth app and wrong for a cookie
+   * app whose first `/get-session` has not started — the window where
+   * `null === null` matched the PREVIOUS browser user's cached rows and
+   * queued writes, before any probe was in flight to mark the fingerprint
+   * provisional.
+   *
+   * Idempotent, and one-way: a client that resolves an identity keeps its
+   * gates armed until a probe actually answers.
+   */
+  expectIdentityResolution(): void;
+  /**
+   * This client's current CDC baseline for `shardKey` — the cursor its live
+   * queries have reached, which is what a write composed right now should be
+   * judged against.
+   *
+   * Exposed for the same reason {@link currentIdentity} is: a durable
+   * {@link OutboxSink} owns its own at-least-once replay outside the built-in
+   * `OfflineQueue`, so it has to capture this at COMPOSE time and hand it back
+   * through {@link MutationCallOptions.replayBaseline}. Sampling it inside the
+   * replay instead reads the cursor this client has advanced to in the
+   * meantime, which is the newer state the write must be judged against.
+   *
+   * `undefined` when no subscription on the shard carries a cursor yet.
+   */
+  currentBaseline(shardKey?: string): number | undefined;
+  /**
+   * Verdict on whether a durable write stamped with `stamped` may be replayed
+   * now. The comparison a replay handler must NOT hand-roll.
+   *
+   * `"match"` is the same identity, or the same credential under a token hash
+   * — which a late-resolving subject would otherwise make look different.
+   *
+   * `"unknown"` is nobody signed in *yet*. A durable replay starts when the
+   * executor is constructed, before the app has resolved its session and
+   * called {@link setAuthToken}, so this is the normal state on every reload.
+   * There is no other identity to replay as, so such a write must be HELD,
+   * never dropped — dropping here destroys the queuing user's own offline
+   * writes. It is indistinguishable from an explicit sign-out (the fingerprint
+   * is `null` for both), which is the safe conflation: holding a write for a
+   * signed-out app costs a retry, dropping it costs the write.
+   *
+   * It also covers a `null` stamp against a `null` fingerprint — but only
+   * while {@link identityUnresolved} says a session resolve is in flight.
+   * Two `null`s are the same identity for an app with no auth at all (nobody
+   * else shares that fingerprint, because nobody else exists) and for a
+   * client the server has told there is no session; they are NOT the same
+   * identity in the window where the fingerprint is about to become
+   * `subj:<id>`, which is where one browser user's queued write went out on
+   * the next one's cookie.
+   *
+   * A held write is not stranded: the hold ends when the resolve settles, and
+   * both {@link setAuthToken} and {@link getCurrentUser} re-flush there. If
+   * the identity that arrives is not the one that queued the write, the
+   * verdict is then `"mismatch"` and the write is settled terminally.
+   *
+   * A sticky subject carried across a token change is `"unknown"` for the same
+   * reason: the label says user A, the credential in hand has not been checked
+   * against it, and the two answers (a refresh vs an account switch) call for
+   * opposite verdicts. Hold until the next session resolve settles it.
+   *
+   * `"mismatch"` is a different identity signed in, and is the one that must be
+   * terminal: replaying would attribute one user's write to another and pass
+   * THEIR row-level security.
+   */
+  replayIdentityVerdict(stamped: null | string | undefined): "match" | "mismatch" | "unknown";
+  /** 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.
+   *
+   * `null` means the **server answered** that there is no session — an empty
+   * body, no `user` field, or a non-OK status such as 401. A network or parse
+   * failure **rejects** instead, because "the endpoint was unreachable" is not
+   * the same answer as "you are signed out": collapsing the two made an
+   * offline reload with a valid stored token read as a sign-out in every
+   * adapter's auth gate. Callers that cannot act on the difference can still
+   * `.catch(() => null)`; `@lunora/client/auth`'s identity store maps the
+   * rejection to the `"unreachable"` status instead.
+   *
+   * Framework-agnostic: pair it with {@link onAuthTokenChange} to refetch when
+   * the token changes (that's what `@lunora/react`'s `useAuth` does).
+   *
+   * A resolved user also ESTABLISHES the identity subject for the credential
+   * that resolved it ({@link setAuthToken}'s second argument). This is the one
+   * call every adapter's identity store already makes, and the only place that
+   * knows the answer — leaving it to each adapter is what left the sticky-subject
+   * contract unreached in every shipped one, so a routine JWT refresh read as a
+   * user switch and discarded the user's own queued writes and read cache.
+   */
+  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.
+   *
+   * Not available on a `crossTabSync` FOLLOWER tab — the context rides the
+   * `connect` envelope of a socket a follower does not own, so it would be
+   * stored and never sent. Throws `NOT_IMPLEMENTED` there.
+   */
+  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: a whisper topic is access-controlled only if the app declares an
+   * `onWhisper` authorizer server-side (`@lunora/server`). Without one, the
+   * topic's only boundary is the shard — any client that can open a socket to it
+   * can join, read, and inject on any topic name. `from` is server-stamped and
+   * unforgeable either way, but never trust a whisper's `data` as authorization,
+   * and remember that even an authorized topic is transient awareness with no
+   * durable trace: anything privileged belongs behind a query/mutation with RLS.
+   *
+   * A denied join is silent — whispers are never acked, so nothing distinguishes
+   * "denied" from "nobody is whispering". Gate the UI on a query you can read a
+   * verdict from, not on whether whispers arrive.
+   *
+   * Not available on a `crossTabSync` FOLLOWER tab — whisper frames are not
+   * relayed over the cross-tab channel, so this throws `NOT_IMPLEMENTED`
+   * there rather than registering a handler nothing can ever reach. See
+   * {@link LunoraClientOptions.crossTabSync}.
+   */
+  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`).
+   *
+   * That best-effort drop is for a socket that is momentarily down. A
+   * `crossTabSync` FOLLOWER tab has no socket and never will (see
+   * {@link LunoraClientOptions.crossTabSync}), so every whisper from it would
+   * be dropped forever — it throws `NOT_IMPLEMENTED` instead.
+   *
+   * A send the app's `onWhisper` authorizer denies is dropped the same silent
+   * way, for the same reason: there is no ack frame to report it on. See
+   * {@link whisperSubscribe} for the security model.
+   */
+  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`.
+   *
+   * **Return-value caveat — the queued paths do not carry the server's result.**
+   * The declared `Promise<ReturnOf<F>>` only holds when the write goes straight
+   * to the server. Once a write is queued:
+   *
+   * - with a durable `outbox` configured, this resolves **immediately with
+   *   `undefined`** (typed as `ReturnOf<F>`) the moment the write is handed to
+   *   the outbox — the replay happens later, out of band, with no awaiter;
+   * - with the built-in offline queue, it stays pending until the replay lands
+   *   and then resolves with the replayed call's value.
+   *
+   * So `const id = await client.mutation(api.todos.create, …)` is `undefined`
+   * for every write issued while offline under an outbox. Generate ids
+   * client-side (or read them back from a subscription) rather than depending
+   * on a mutation's return value in an offline-capable app —
+   * {@link LunoraClient.importRows} documents the same caveat for its counts.
+   */
+  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 }`.
+   *
+   * An absent `deleted` field reads as `false`, matching every sibling admin
+   * verb (`runCronJob`'s `ran`, …): the studio renders this value as the row's
+   * outcome, so defaulting a missing field to success would report a delete
+   * that a mismatched/older worker never performed.
+   */
+  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 wire-encoded, JSON-encoded into the
+   * `filters` query param, and the values are bound server-side.
+   *
+   * The response is `decodeWire`d. The worker encodes it (`readGlobalTablePage`
+   * in `@lunora/d1`) because JSON cannot carry a `v.bigint()` column at all and
+   * silently flattens a `v.bytes()` one to `{}` — so without the decode here the
+   * grid renders the raw 3-element tagged array instead of the value. The shard
+   * browser's twin already pairs the same way through `rpc`; this is the global
+   * half of that symmetry.
+   */
+  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.
+   *
+   * Wire-encoded/decoded on both legs for the same reason
+   * {@link LunoraClient.readGlobalTablePage} is: a facet over a BLOB column
+   * returns bytes, which `Response.json` flattens to `{}` — and since a facet
+   * value is exactly what a click sends back as a `filters` clause, that is a
+   * broken drill-down rather than a display glitch.
+   */
+  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>>>;
+  /**
+   * List sign-up invitations, newest first (requires the `inviteOnly` plugin).
+   * Unfiltered: a row is pending when `acceptedAt` is null and `expiresAt` is in
+   * the future, and the caller labels it — filtering server-side after the page
+   * would let page 1 come back empty while pending rows sat on page 2.
+   */
+  listAuthSignUpInvitations(options?: {
+    limit?: number;
+    offset?: number;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** Invite an address to sign up, or refresh an existing invitation for it. */
+  createAuthSignUpInvitation(input: {
+    email: string;
+    expiresInSeconds?: number;
+    invitedBy?: string;
+  }): Promise<Record<string, unknown>>;
+  /** Withdraw a sign-up invitation. Not retroactive — an account already created keeps existing. */
+  revokeAuthSignUpInvitation(input: {
+    email: string;
+  }): Promise<void>;
+  /** 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 to a live query. The callback fires with the current value (from
+   * the durable read cache, when one is hydrated) and again on every server
+   * frame; the returned function unsubscribes.
+   *
+   * Subscriptions are deduped by `(functionPath, args, shardKey)` — a second
+   * `subscribe` for the same triple joins the existing registration and shares
+   * its value, cursor and optimistic layers.
+   *
+   * Available on a `crossTabSync` FOLLOWER tab, unlike the other socket-backed
+   * surfaces: registering here is exactly what lets the cross-tab relay deliver
+   * the leader's broadcasts (see the note in the body). The caveat is that the
+   * channel only carries the LEADER's own subscriptions outward, so a follower
+   * sees this query's frames only while the leader holds it too — see
+   * {@link LunoraClientOptions.crossTabSync}.
+   */
+  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.
+   *
+   * Not available on a `crossTabSync` FOLLOWER tab: shape pokes are not part of
+   * the leader→follower broadcast set, so a follower's shape could never
+   * resolve. The returned handle is inert there, and `options.onError` is
+   * invoked with `NOT_IMPLEMENTED` — see
+   * {@link LunoraClientOptions.crossTabSync}. Reporting rather than throwing is
+   * deliberate: `@lunora/db`'s shape-backed `createCollection` calls this from
+   * its sync path, where a throw takes the collection out entirely, while
+   * `onError` is the seam it already routes to `markReady()`.
+   */
+  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;
+  /**
+   * `true` when this tab is a cross-tab FOLLOWER of a live leader — i.e. it
+   * will not open a socket of its own and another tab is known to hold one.
+   *
+   * Deliberately NOT just `!isLeader()`. Every `crossTabSync` client is a
+   * non-leader for the first `leaderTimeout` of its life, while its
+   * claim-leadership probe is outstanding; a lone tab self-promotes at the end
+   * of that window and `onBecomeLeader` opens the sockets and replays every
+   * registered subscription. That window is a legitimate, self-healing defer,
+   * not a failure. A KNOWN leader on another tab is the state that never heals.
+   */
+  private followsAnotherTab;
+  /**
+   * Reject a call that needs a socket this tab will never have.
+   *
+   * The cross-tab protocol is one-directional: a leader broadcasts
+   * `subscription-data` / `-error` / `-settled` / `connection-status` to
+   * followers, and a follower has no frame with which to tell the leader what
+   * it needs (see `cross-tab.ts`'s `WsFollowerMessage`, which is exactly
+   * heartbeat / claim-leadership / yield-leadership). `subscribeShape` /
+   * `whisper*` / `setConnectionContext` / `acquireConnectionContext` — none of
+   * which the leader broadcasts at all — therefore never worked on a follower
+   * under any circumstances: each returned a handle that looked live, fired no
+   * callback, raised no error, and reported `connectionStatus() ===
+   * "connected"` (mirrored from the leader).
+   *
+   * `subscribe` is deliberately NOT in that set. A follower's `subscribe`
+   * registers the key the leader's broadcast is matched against, so it is the
+   * mechanism the relay is built on rather than a surface that silently fails.
+   * A follower sees a query only while the leader holds the same
+   * `(fn, args, shardKey)` — that is the documented shape of the option, not a
+   * defect.
+   *
+   * `subscribeShape` and `stream()` reach the same outcome by a different
+   * route: they fail the handle they return rather than throwing at the call,
+   * because both are driven from a sync/render path where a throw destroys the
+   * caller instead of degrading it. See
+   * {@link LunoraClientOptions.crossTabSync} for what the option does and does
+   * not cover.
+   */
+  private assertLeaderOwnedSurface;
+  /**
+   * Clear every timer a {@link ShardConnection} can have armed.
+   *
+   * One function because both teardown paths must clear all three and a fourth
+   * timer would otherwise have to be remembered in two places — which is how a
+   * leak gets added rather than written.
+   */
+  private clearConnectionTimers;
+  /**
+   * 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.
+   *
+   * Settles this shard's in-flight streams first. The teardown clears
+   * `conn.socket` BEFORE the real `close` event fires, so that event trips
+   * `openManagedSocket`'s identity guard (`conn.socket !== socket`) and
+   * returns — meaning `handleDisconnect`, the only other place that settles a
+   * shard's streams, never runs for this connection again. `close()` already
+   * failed and cleared `this.streams` before it gets here, so this is a no-op
+   * on that path; the cross-tab demotion path is the one where a consumer's
+   * `for await` used to block forever with no error and no completion.
+   */
+  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;
+  /**
+   * Is a write for this shard still sitting in the durable path, waiting to
+   * replay? Drives the FIFO gate in {@link mutation}: a live write must never
+   * overtake one that is queued (or held) ahead of it.
+   *
+   * Whichever durable path is wired answers: the built-in {@link OfflineQueue}
+   * knows its entries' shard keys, while an {@link OutboxSink} reports only a
+   * process-wide depth (the executor's pending count is not shard-scoped) —
+   * over-inclusion there costs a write a trip through the outbox it could have
+   * skipped, which is the same trip the writes ahead of it are taking anyway.
+   * A sink that reports nothing keeps the previous behaviour.
+   */
+  private hasPendingWriteAhead;
+  /**
+   * 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 so a `subscribe()` for the key seeds its initial
+   * value off disk.
+   *
+   * The load is asynchronous but every framework adapter subscribes
+   * SYNCHRONOUSLY at mount, so the subscriptions that most want the cache
+   * already exist by the time it lands. Those are seeded here and their entry
+   * is dropped: an entry that stayed in {@link hydratedQueryCache} behind a
+   * live subscription would be consumed by the NEXT subscribe of the same key
+   * (a remount after navigating away) and replay the previous session's value
+   * over whatever the socket had since delivered. A cache entry therefore
+   * never outlives a live subscription for its key — it is either handed to
+   * that subscription or discarded.
+   *
+   * Only keys with no live subscription are held for a later `subscribe()`;
+   * the identity gate applies to both paths, so a signed-out cache never leaks
+   * into a new session.
+   */
+  private hydrateQueryCache;
+  /**
+   * Hand a loaded read-cache entry to a subscription that was opened before
+   * the load resolved — the same value, cursor and epoch {@link subscribe}
+   * would have taken from {@link takeHydratedCache} had the load finished
+   * first, so the cursor still rides the `subscribe` frame as `sinceSeq` (that
+   * frame only goes out once the socket opens, well after this microtask).
+   *
+   * A no-op once the socket has delivered anything for this key: a live value
+   * always beats the cache. Identity-gated exactly like `takeHydratedCache`.
+   */
+  private seedSubscriptionFromCache;
+  /**
+   * Move the durable read cache in or out of view as the CREDENTIAL changes —
+   * which the identity fingerprint does not track: a sticky subject rides
+   * across a token change (the account-switch shape), leaving the label
+   * unmoved, so `setAuthToken`'s identity-change block never runs for it.
+   * Revoke while that pairing is unchecked, and hand the values back once the
+   * next session resolve confirms the credential really is that subject's.
+   */
+  private syncReadCacheToCredential;
+  /**
+   * A server frame owns this key now, so the read cache may neither take its
+   * seeded value back ({@link revokeCacheSeededValues}) nor hold an entry for
+   * a later `subscribe()` of the same key to replay a stale session over.
+   */
+  private dropCacheSeed;
+  /**
+   * Hand a cache-seeded entry back to {@link hydratedQueryCache} when its last
+   * subscriber detaches, so the NEXT `subscribe()` of the same key can seed
+   * from it again.
+   *
+   * Without this the hydrated cache was one-shot per key: {@link takeHydratedCache}
+   * consumes the entry, the final unsubscribe drops the state that held its
+   * value, and nothing re-seeds. Navigating away from a route and back while
+   * offline therefore rendered `undefined` for the rest of the offline
+   * session even though the durable store still held the rows. React hid it
+   * behind TanStack's `gcTime`; every other adapter showed it immediately.
+   *
+   * Only a seed still listed in {@link cacheSeededQueries} moves — a server
+   * frame calls {@link dropCacheSeed}, which clears both maps, so an entry
+   * that is still here has not been superseded and is the freshest value this
+   * client has for the key. That is the same map-to-map move
+   * {@link revokeCacheSeededValues} makes, and it keeps the two maps disjoint:
+   * an entry is either on display or waiting, never both.
+   */
+  private returnCacheSeed;
+  /**
+   * Take every value the durable read cache is currently displaying back off
+   * screen, and return its entry to {@link hydratedQueryCache} so the identity
+   * gate — not this call — decides whether it is ever shown again. A
+   * same-credential refresh gets its offline-first value back the moment the
+   * next session resolve re-confirms the subject; a genuine account switch
+   * never does, and {@link clearQueryCacheForIdentityChange} wipes it.
+   *
+   * Only cache-seeded values: a server frame has been delivered under a socket
+   * whose own identity is pinned and checked ({@link persistQueryValue}), and
+   * dropping those would blank a live query on every token refresh.
+   */
+  private revokeCacheSeededValues;
+  /**
+   * Consume the hydrated read-cache entry for a key (if any), gated on
+   * identity ({@link cachedQueryMatchesIdentity}). A mismatch yields
+   * `undefined`, so a cache written under a different identity never leaks
+   * into a new session.
+   *
+   * Only a MATCH is removed. The cache seeds a subscription's first value
+   * once, so consuming a match is right — but destroying a mismatch is what
+   * made a late-resolving identity unrecoverable: the subject typically lands
+   * a `/get-session` after the first `subscribe()`, and by then the entry that
+   * would have matched was gone. Left in place, {@link reseedFromHydratedCache}
+   * can still hand it over when the identity settles.
+   */
+  private takeHydratedCache;
+  /**
+   * Hand every still-held read-cache entry to the subscription that is open on
+   * its key, now that the identity has settled onto a resolved subject.
+   *
+   * `subscribe()` runs long before `/get-session` answers, so on a reload the
+   * gate is asked its question with only a raw token in hand. When the token
+   * itself matches, {@link cachedQueryMatchesIdentity} already says yes there
+   * and then; when it has been refreshed since the value was cached, the only
+   * honest answer at that moment is "unknown" — and this is where it becomes
+   * knowable. {@link seedSubscriptionFromCache} is a no-op for any subscription
+   * the socket has already fed, so a live value always wins.
+   */
+  private reseedFromHydratedCache;
+  /**
+   * 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;
+  /**
+   * The CDC cursor this client's view of `shardKey` is at — the highest
+   * `serverCursor` any live subscription on that shard has advanced to.
+   *
+   * This is the baseline a `.dropStalePatches()` table judges a write against,
+   * and the "highest" is what makes it sound: a cursor the client has reached on
+   * ANY subscription means the shard's changelog up to that point has been
+   * delivered here, so anything later is by definition something this client had
+   * not seen when it composed the write.
+   *
+   * `undefined` when no subscription on the shard carries a cursor yet — a
+   * client that has only ever issued one-shot RPCs, or a server with CDC off.
+   * That is reported honestly rather than defaulted to `0`: a `0` baseline would
+   * claim the client had seen NOTHING, which makes every field look changed and
+   * would have the shard discard every patch it sends.
+   */
+  private baselineCursorFor;
+  /**
+   * One polling-fallback pass for a shard: re-run every live query bound to it
+   * over the batch-RPC endpoint and feed each result into the same frame-apply
+   * path a server `data` frame takes.
+   *
+   * Reusing {@link LunoraClient.batch} and {@link LunoraClient.handleDataMessage}
+   * rather than forking either is the whole point. The apply path is where
+   * optimistic layers rebase, the durable read cache is seeded, and subscriber
+   * callbacks fan out; a second implementation of that would drift, and it would
+   * drift into exactly the bugs the live path has already had fixed.
+   *
+   * The result is re-encoded on the way in because `batch` hands back a decoded
+   * value while the frame path expects the wire form. `encodeWire` is identity
+   * for JSON-safe data and lossless for the rest (that is the codec's contract),
+   * so the round trip costs an allocation and changes nothing.
+   *
+   * **No cursor rides this path.** A poll is a full snapshot, so the frames it
+   * synthesizes carry no `cursor`/`epoch` and cannot advance a subscription's
+   * resume watermark — which is correct: the watermark describes what the CDC
+   * log has delivered, and this delivered none of it. When the socket comes
+   * back, the resubscribe resumes from the last cursor the SOCKET saw, and the
+   * server re-snapshots whatever it needs to.
+   *
+   * A slot that failed is fanned to the subscription's error callbacks rather
+   * than being swallowed: the whole point of the fallback is that the app keeps
+   * working, and a query that is now failing (a permission change, a bad arg)
+   * has to be visible.
+   */
+  private pollSubscriptions;
+  /** 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;
+  /**
+   * Send the stream-start frames queued while the socket was (re)connecting,
+   * marking each one that lands as started on the server.
+   */
+  private flushPendingStreams;
+  /**
+   * Tear down a stream the consumer cancelled, telling the server when the
+   * server is the one still holding it.
+   */
+  private cancelStream;
+  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;
+  /**
+   * Re-send `state`'s `subscribe` frame, but only once fewer than
+   * {@link RESUBSCRIBE_CONCURRENCY} frames on this shard are still awaiting a
+   * reply. Used by every path that resends MANY subscriptions at once — the
+   * socket-open resubscribe and the cross-tab leader handover, which replays
+   * every tab's subscriptions combined. A first subscribe (one frame, caller
+   * paced) still goes straight out through {@link sendSubscribeIfOpen}.
+   */
+  private queueResubscribe;
+  /**
+   * Send queued `subscribe` frames until the in-flight window is full.
+   *
+   * Cannot wedge: a queued subscription whose frame does not actually go out
+   * (socket closed, already acked, unsubscribed while queued) takes no slot,
+   * every sent frame is released by the first server frame carrying its id
+   * (see {@link handleServerMessage}) or by its own watchdog, and a disconnect
+   * drops the queue wholesale — the next `open` re-queues every subscription
+   * on the shard, because `markShardPendingAck` un-acked them all.
+   */
+  private drainResubscribeQueue;
+  /** Free the in-flight slot `id` holds on `conn` (if any) and let the next queued subscribe go out. */
+  private releaseResubscribeSlot;
+  /**
+   * Abandon this connection's paced resubscribe: clear every watchdog and
+   * forget both the in-flight and the waiting entries. Called wherever the
+   * socket they were sent on goes away — the server drops that socket's
+   * subscriptions anyway, and the next `open` re-queues all of them.
+   */
+  private clearResubscribeQueue;
+  /** Send `state`'s `subscribe` frame when the shard's socket can carry it; `true` when a frame actually went out. */
+  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` never matches a bearer-token fingerprint — but it is only an
+   * IDENTITY of its own once this client knows no subject is coming. An app
+   * with no auth at all, and a client the server has answered "no session"
+   * to, both hold a `null` nobody else shares. A client mid-`/get-session`
+   * holds a `null` that may be one round trip from `subj:<id>`, which is
+   * every cookie app's page load: ask {@link identityUnresolved} before
+   * treating it as an identity, or `null === null` matches two different
+   * people. 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;
+  /**
+   * The `credential` field a read-cache write carries: the token hash of the
+   * bearer currently held, or nothing at all when signed out (there is no
+   * credential to match against, and the `null` identity already covers it).
+   */
+  private credentialStamp;
+  /**
+   * Whether a read-cache entry belongs to the identity in effect right now —
+   * the ONE gate the hydrated peek, the subscribe-time take and the late seed
+   * all share.
+   *
+   * Three ways to be the same identity, because the label and the credential
+   * resolve at different times:
+   *
+   * 1. The fingerprints are equal — the plain case.
+   * 2. The entry is stamped under a token hash and the live identity has since
+   * been relabelled to the subject that credential resolved to
+   * ({@link isSameCredentialUnderTokenHash}).
+   * 3. The entry is stamped under a subject and THIS session has only the raw
+   * token so far, but it is byte-for-byte the credential the entry was written
+   * under. This is the direction the strict comparison missed entirely, and it
+   * is the normal shape of every reload: every adapter calls
+   * `setAuthToken(token)` from storage and only learns the subject a
+   * `/get-session` round trip later — which offline never completes at all.
+   * Without it the durable read cache never seeded for a bearer-token app.
+   *
+   * All three want a credential this client actually HOLDS, which is why a
+   * **cookie session seeds nothing on an offline cold start** — a documented
+   * limitation, not a gap. The cookie is `HttpOnly`: the client can neither
+   * read it nor prove it still has it, and offline the `/get-session` that
+   * would resolve the subject never answers, so such entries (stamped
+   * `subj:<id>`, no credential) have nothing to match. Seeding them on the
+   * remembered subject LABEL would hand the rows to whoever opens the browser
+   * profile with nothing evidencing they are that subject, and revoking on a
+   * later mismatch does not repair it: that check can only run once
+   * connectivity returns, which is exactly the state where the offline seed
+   * was not needed. Offline-first reads require a bearer token.
+   *
+   * Case 1 is suspended while the subject awaits re-confirmation
+   * ({@link subjectAwaitingReconfirm}): the fingerprint then labels a
+   * credential nothing has checked it against, which is precisely the
+   * account-switch shape — `setAuthToken(otherAccountsToken)` with no subject,
+   * what every adapter does on a reload, still reading `subj:<previous user>`.
+   * Matching on that label alone hands the new account the previous account's
+   * cached rows. Cases 2 and 3 both PROVE the credential, so the reload this
+   * gate exists for still seeds.
+   */
+  private cachedQueryMatchesIdentity;
+  /**
+   * 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;
+  /**
+   * Release one {@link sessionProbesInFlight} hold and re-flush the writes
+   * that hold alone was holding.
+   *
+   * A resolve that names a user re-flushes through {@link setAuthToken} (the
+   * identity changed). One that does not — signed out, or unreachable —
+   * changes no identity and so fires no listener, and a write held only
+   * because {@link identityUnresolved} said so would sit queued until the
+   * next reconnect. Same connected-only gate as `setAuthToken`'s, so this
+   * stays a re-flush of a live connection rather than a reason to replay an
+   * offline queue.
+   *
+   * Only for a `null` fingerprint, which is the ONLY hold this probe owns:
+   * {@link replayIdentityVerdict}'s unresolved-identity hold tests
+   * `current === null`, while its other hold — a sticky subject awaiting
+   * re-confirmation — requires an established subject and so a
+   * `subj:<id>` fingerprint. That one is already on the `noteHeldRetryDelay`
+   * backoff and must stay there.
+   *
+   * Re-flushing it from here instead was an unbounded loop, not a slow
+   * backoff: `drainOfflineQueue` answers a subject-awaiting hold by probing
+   * `getCurrentUser()` itself, whose release re-flushed, which drained, which
+   * probed again — hundreds of round trips without a millisecond passing,
+   * until the heap gave out. Narrowing to the `null` fingerprint makes the
+   * cycle unreachable rather than merely rare: the branch that starts a probe
+   * cannot be entered by a flush this guard lets through.
+   */
+  private releaseSessionProbe;
+  /**
+   * Whether this client's `null` identity fingerprint is still provisional —
+   * a {@link getCurrentUser} resolve is in flight and may be about to name a
+   * subject. The one question every identity gate asks before it is willing
+   * to treat `null` as an identity rather than as an absence of one.
+   */
+  private identityUnresolved;
+  /**
+   * Key the offline-queue identity on the resolved user id rather than the
+   * token bytes, so the NEXT token refresh keeps the same identity.
+   *
+   * Only a resolved user labels anything. A 401, a network failure or an
+   * empty session resolves `null` for reasons that say nothing about who is
+   * signed in, and a token that rotated mid-flight belongs to a session this
+   * answer predates — both leave the established label alone rather than
+   * clearing it (which would look like an identity change and drop the queue).
+   *
+   * A superseded probe is the same case, and the one the token check cannot
+   * see: on a cookie app both `requestToken`s are `null`, so a slow answer
+   * from an OLDER probe passed that check and overwrote the subject a newer
+   * one had already established. `requestGeneration` is the question's id —
+   * it must still be the current one at the moment of the write.
+   */
+  private adoptResolvedSubject;
+  /**
+   * True while an established subject labels a credential it was never checked
+   * against — see the `subjectToken` field. Every replay verdict is
+   * `"unknown"` (hold) until the next session resolve re-asserts the subject.
+   */
+  private subjectAwaitingReconfirm;
+  /**
+   * The identity a queued write is stamped with. The live `queuedIdentities`
+   * map is the source of truth for this session; a hydrated write whose id
+   * isn't in it falls back to the stamp persisted with the record. `Map.get`
+   * returns `undefined` for unstamped/hydrated ids and `item.identity` is
+   * `undefined` for legacy records (persisted before stamps were durable),
+   * while a persisted `null` (queued while signed out) is a real value that
+   * must not collapse into `undefined` — hence `=== undefined`, not `??`.
+   */
+  private stampOf;
+  /**
+   * Reject the in-memory offline writes that can no longer replay under the
+   * identity now signed in, dropping their durable records so a later
+   * `hydrate` can't resurrect another user's writes.
+   *
+   * Per item, not wholesale: this runs on a plain sign-in too (`null` → a
+   * signed-in identity is a credential change like any other), where the
+   * queue is the *signing-in user's own* restored writes. Every stamp goes
+   * through {@link replayIdentityVerdict}, the one comparison, and only
+   * `"mismatch"` is terminal — `"match"` and `"unknown"` stay queued.
+   *
+   * The durable read cache is cleared only when there WAS a previous identity
+   * to protect. Wiping it on a sign-in from signed-out would destroy the
+   * offline-first cache on every cold boot, and buys nothing: cache entries
+   * are identity-stamped and gated at every read.
+   */
+  private rejectQueuedForIdentityChange;
+  /**
+   * Move the identity stamp of every open shard socket from `from` to `to` —
+   * the sibling of {@link restampQueuedIdentity} for the read cache. A socket
+   * pins the identity it was upgraded under (see `ShardConnection.identity`)
+   * and {@link persistQueryValue} stamps cached reads with it, deliberately,
+   * so a still-open previous-user socket can't file frames under the new
+   * user's stamp. A same-credential relabel is the one case where that pin is
+   * stale rather than protective: without this, every read cached for the rest
+   * of the session is filed under a fingerprint the next session's identity
+   * gate rejects, and the durable read cache silently yields nothing.
+   */
+  private restampConnectionIdentity;
+  /**
+   * Migrate every 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.
+   *
+   * That map alone was not enough: it is consumed and DELETED on the first
+   * flush attempt (`replayIdentityVerdict`), while the queue entry and its
+   * persisted record keep the original stamp. So a reload, or a requeue after a
+   * transient failure, fell back to the old token hash — and once the token had
+   * been refreshed, `isSameCredentialUnderTokenHash` no longer recognised it
+   * and the write was rejected `OFFLINE_IDENTITY_CHANGED` for the very user
+   * `setAuthToken`'s sticky-`subject` contract promises to protect. The queue's
+   * own re-stamp covers both the entry and its durable record.
+   */
+  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;
+  /**
+   * Retire everything the PREVIOUS identity left live on a genuine identity
+   * change: the sockets it is authenticated on, and the rows they delivered.
+   *
+   * A WebSocket credential is pinned in its upgrade URL and cannot be rotated
+   * in place, so `setAuthToken` alone left the previous user's socket open and
+   * delivering — the consequence `ShardConnection.identity`'s docblock already
+   * described, with "nothing" as the thing that closes it on a client without
+   * `crossTabSync`. And each `SubscriptionState` keeps the last value that
+   * socket delivered, which `subscribe()` replays synchronously to every new
+   * subscriber, so the incoming user's first render was the outgoing user's
+   * rows even after the socket did go.
+   *
+   * Both halves are needed: closing the socket without clearing the values
+   * leaves them on screen until a frame replaces them (which never comes for a
+   * query the new user cannot read), and clearing the values without closing
+   * the socket lets the next frame put them straight back.
+   */
+  private evictPreviousIdentitySession;
+  /**
+   * Move this tab's cross-tab coordinator onto the channel the new identity
+   * derives, after an identity change.
+   *
+   * The channel name embeds the identity fingerprint (see
+   * {@link createTabCoordinator}), so without this the tab keeps
+   * leading/following the PREVIOUS identity's group. BroadcastChannel names
+   * are immutable, so a stop-old+construct-new is the only way to move
+   * channels — but that means the fresh coordinator would otherwise sit
+   * through the full claim-then-`leaderTimeout` dance (3s default) before any
+   * tab opens a socket again, freezing every live query for that long on
+   * EVERY identity change (including a routine JWT refresh for an app that
+   * doesn't pass a stable `subject` — the documented reason to pass one). If
+   * this tab was already the leader, it's overwhelmingly likely to remain the
+   * sole tab on the new channel too, so promote it immediately instead of
+   * waiting — `promoteImmediately`'s docblock covers the (self-healing) rare
+   * case where another tab does the same at once.
+   */
+  private restartTabCoordinatorForIdentity;
+  /**
+   * Close every open shard socket so each reconnects carrying the credential
+   * in effect now.
+   *
+   * Non-terminal, unlike {@link close}: the `ShardConnection` records and the
+   * subscriptions riding them survive, and the registered `close` handler
+   * (`handleDisconnect`) schedules the retry and replays the subscribes. This
+   * is the only way to move a WS credential — it lives in the upgrade URL.
+   */
+  private bounceShardSockets;
+  /**
+   * 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 `onOpen`
+   * callback that calls `flushOfflineQueue(shardKey)`), 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;
+  /**
+   * Replay a shard's queued writes, serialized per shard and published as
+   * {@link offlineFlushes} so a concurrent `mutation()` can wait behind it.
+   * Never rejects: every entry's outcome is settled individually inside
+   * {@link drainOfflineQueue}, and a poisoned chain would strand every later
+   * flush AND every write waiting on the barrier.
+   */
+  private flushOfflineQueue;
+  private drainOfflineQueue;
+  /**
+   * Ask for another flush of this shard after a backoff, because every entry it
+   * drained was HELD for an identity that is not re-confirmed yet.
+   *
+   * Same state and same timer as a rate-limited replay
+   * ({@link LunoraClient.noteReplayRetryDelay}) — one pending flush per shard
+   * key either way — only the reason differs: there is no error to read a
+   * `Retry-After` off, so the hintless {@link defaultReplayRetryDelayMs} ramp
+   * (1s doubling to a 60s ceiling, jittered) is the whole policy. It is a
+   * ceiling on the rate, not a budget of attempts: a durable write is never
+   * dropped for having waited too long, so a subject that never resolves leaves
+   * the queue re-probing at ≤ 60s intervals with the writes intact and
+   * {@link LunoraClient.pendingCount} non-zero for the app to surface. The
+   * retries stop when the hold lifts (the queue drains), when the shard has
+   * nothing queued, or at `close()`.
+   *
+   * Identity is re-read by the flush, never carried across the timer: the
+   * retry re-enters {@link LunoraClient.drainOfflineQueue}, which re-runs
+   * {@link LunoraClient.replayGateVerdict} per entry against the identity in
+   * effect when it runs. A retry therefore cannot replay a write under an
+   * identity that changed while the timer was pending — it re-holds it, or
+   * rejects it as a mismatch, exactly as a reconnect-driven flush would.
+   */
+  private noteHeldRetryDelay;
+  /**
+   * Remember the longest delay this shard's flush was told (or worked out) to
+   * wait, so the drain can honour it before trying again
+   * ({@link LunoraClient.replayRetryState}). Counts the attempt either way:
+   * that is what a hintless refusal backs off on.
+   */
+  private noteReplayRetryDelay;
+  /**
+   * Consume this shard's retry delay and re-flush it once the delay has
+   * elapsed.
+   *
+   * Two things record a delay for it to consume: a failure the server or an
+   * edge ANSWERED (see {@link replayRetryDelayMs}) and a flush that HELD every
+   * entry it drained (see {@link LunoraClient.noteHeldRetryDelay}). Both happen
+   * over a socket that stays open, so without this the writes sit queued
+   * indefinitely; a `fetch` that never landed records nothing, because the
+   * reconnect that follows flushes the queue anyway. One pending timer per
+   * shard; a second delay replaces it rather than stacking flushes.
+   *
+   * Nothing left to retry on this key (drained, closed, or no delay) drops its
+   * backoff state, which is both the reset after progress and what bounds the
+   * map.
+   */
+  private scheduleRateLimitedRetry;
+  /**
+   * 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 gate for one queued write about to replay: a write stamped under
+   * one identity must never replay under another, and must never be DESTROYED
+   * because the identity isn't known yet.
+   *
+   * The three-way verdict is {@link replayIdentityVerdict}'s, not a second
+   * hand-rolled comparison — `@lunora/db`'s durable outbox holds on `"unknown"`
+   * through the same call, and this path (the default for the standalone
+   * client) used to drop there instead, purging the queuing user's own write
+   * on every reload that opened its socket before the session resolved.
+   *
+   * `"send"` replays it and consumes the live stamp. `"hold"` leaves it queued
+   * and persisted, stamp intact, for a later flush once an identity is
+   * established (see `setAuthToken`). `"reject"` means a different identity is
+   * signed in: settle it terminally `OFFLINE_IDENTITY_CHANGED` and purge the
+   * durable record.
+   */
+  private replayGateVerdict;
+  /** 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;
+  /**
+   * Whether a replay failure leaves the durable write queued rather than
+   * settling it terminally — the ONE classification the single-call, per-slot
+   * and whole-batch paths share, so a write's fate never depends on how many
+   * siblings rode along.
+   *
+   * {@link isTransientReplayFailure} answers the "no verdict was reached" half.
+   * The other half is a refused CREDENTIAL ({@link isAuthReplayFailure}): the
+   * queue flushes on the shard's `open` handler with whatever bearer survived
+   * the offline window, so an expired token is the expected outcome of a long
+   * disconnect, not a verdict on the write. Notifying {@link onTokenExpired}
+   * here is what closes the loop — the HTTP replay path has no equivalent of
+   * the WS `4001` close frame, so without this nothing tells the app to
+   * refresh, and `setAuthToken` (which re-flushes) is never called.
+   *
+   * Notified once per credential, not once per write: a flush of a hundred
+   * queued writes earns a hundred identical refusals, and firing the hook for
+   * each would put a hundred token refreshes on the app. The stamp re-arms as
+   * soon as the credential moves, which is the only thing that can change the
+   * answer.
+   */
+  private shouldRequeueReplayFailure;
+  /** 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 server verdict
+   * drops the write; a transient failure ({@link isTransientReplayFailure} — a
+   * transport error, a shard the worker couldn't reach, a rate-limit refusal, or a
+   * non-2xx carrying no `{ error }` envelope) 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. The batch path classifies a slot by the same rule, so a durable write's
+   * fate never depends on how many siblings happened to be queued alongside it.
+   */
+  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 failure
+   * {@link shouldRequeueReplayFailure} keeps, 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 (a bad request the server reached a
+   * verdict on) is terminal for every entry.
+   *
+   * The body is also held under {@link MAX_BATCH_BODY_BYTES}: the worker caps a
+   * batch body at 1 MiB and answers `413`, which is ONE refusal covering every
+   * write in the chunk. An over-budget chunk is halved before it is sent, and a
+   * `413` for a chunk of more than one write halves it and retries rather than
+   * settling the whole chunk terminally — so a backlog of large writes still
+   * commits, one bisection deeper.
+   *
+   * 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;
+  /**
+   * Classify a `/_lunora/rpc-batch` reply that carried no per-slot results — one
+   * outcome covering every entry in the chunk. A code
+   * {@link shouldRequeueReplayFailure} keeps (an unreachable shard, a
+   * rate-limit refusal, a refused credential) or a {@link TransportError} (an
+   * edge reply with no verdict in it) leaves every write durable for the next
+   * attempt; anything else is a verdict reached on the request itself, and
+   * settles all of them.
+   */
+  private settleWholeBatchError;
+  /**
+   * Split an over-large batch chunk in half and replay each half, preserving
+   * FIFO order. Recurses through {@link replayBatched}, so a chunk keeps halving
+   * until it fits (or reaches one write, which is then the server's verdict to
+   * give). A `stop` on the first half leaves the second unsent and queued.
+   */
+  private replayBatchedHalves;
+  /**
+   * 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 failure {@link shouldRequeueReplayFailure} keeps, or a slot the server
+   * never returned, is returned for the caller to re-queue.
+   *
+   * A slot whose `error` key holds no readable envelope is in the same position
+   * as one the server never returned — nothing came back about that entry that
+   * can be read as a verdict — so it is kept, not settled.
+   * @returns the writes that must be re-queued (kept slots), in input order
+   */
+  private settleReplayBatchSlots;
+}
+export { ServerPokePartMessage as $, ActionCallOptions as A, BookmarkStorage as B, ConnectionStatus as C, DEFAULT_MAX_BUFFER as D, OutboxMutation as E, FunctionArgumentDescriptor as F, GlobalFacetResult as G, HttpStreamRef as H, OutboxSink as I, PersistedMutation as J, RowOp as K, LunoraClient as L, MutationCallOptions as M, RpcEnvelope as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReconnectOptions as R, SubscriptionError as S, RpcResponseBody as T, User as U, ScheduleRecord as V, ScheduleRetryPolicy as W, SchedulerPoolStatus as X, SchedulerStatus as Y, ServerMessage as Z, ServerPokeEndMessage as _, Unsubscribe as a, ServerPokeStartMessage as a0, ShardTrafficEntry as a1, ShardTrafficResult as a2, StorageListPage as a3, StorageObject as a4, StoredQuery as a5, StreamHandle as a6, SubscriptionCallback as a7, SubscriptionRegistry as a8, SubscriptionState as a9, SyncWatermark as aa, WorkflowInstanceAction as ab, WorkflowInstanceDetail as ac, WorkflowInstancePage as ad, WorkflowInstanceStatus as ae, WorkflowInstanceSummary as af, WorkflowStepDetail as ag, WsTokenProvider as ah, createClientQuery as ai, createLocalStore as aj, createStream as ak, SubscriptionErrorCallback as b, PersistenceAdapter as c, HttpStreamArgsOf as d, HttpStreamChunkOf as e, StreamIterable as f, BatchSlot as g, CachedQuery as h, ClientDebugShard as i, ClientDebugSnapshot as j, ClientDebugSubscription as k, ClientMessage as l, ClientQueryRef as m, ClientShapeSubscribeMessage as n, ClientShapeUnsubscribeMessage as o, FunctionDescriptor as p, GlobalFacetValue as q, GlobalFilterClause as r, GlobalTableInfo as s, GlobalTablePage as t, HttpStreamCallArgs as u, LunoraClientError as v, LunoraClientOptions as w, MutationSettledEvent as x, OptimisticLocalStore as y, OptimisticUpdate as z };