@lunora/client 1.0.0-alpha.3 → 1.0.0-alpha.31

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

@@ -0,0 +1,2987 @@
+import { CronJobInfo, VectorIndexSummary, VectorQueryMatch, PipelineLogQuery, PipelineLogPage, KvNamespaceSummary, KvKeyListResult, KvValueResult, AuthUser, AuthPage, AuthImpersonation, AuthCapabilities, AuthConfigInfo, AuthSession } from '@lunora/runtime';
+/**
+ * Reactive key-value store for local-only client state.
+ *
+ * Unlike a server {@link SubscriptionState} (which tracks a live WS connection,
+ * an `acked` flag, `serverBase`, optimistic layers, and the full subscription
+ * machinery), a `ClientQueryRef` is purely local — no server round-trip, no
+ * WebSocket, no persistence. It exists so framework adapters can offer a
+ * `useClientQuery` hook whose values survive component remounts and are shared
+ * across every consumer of the same ref, with none of the ceremony or coupling
+ * of a dedicated context provider.
+ *
+ * The store lives inside `LunoraClient` (a private field) and is surfaced through
+ * `client.getClientQuery(ref)` / `setClientQuery(ref, value)` /
+ * `subscribeClientQuery(ref, callback)`.
+ */
+/** Opaque handle for a typed client-local query slot. */
+interface ClientQueryRef<T = unknown> {
+  /** Default value when no value has been set explicitly. */
+  readonly defaultValue: T;
+  /** Stable identity for the slot. Must be unique within a client instance. */
+  readonly key: string;
+}
+/**
+ * Create a typed {@link ClientQueryRef}. Call once per slot at module scope
+ * (or inside a component module) — the ref object is the stable identity.
+ * @example
+ * ```ts
+ * // lunora/client-queries.ts
+ * import { createClientQuery } from "@lunora/client";
+ *
+ * export const sidebarOpen = createClientQuery("sidebarOpen", true);
+ * export const selectedMessageId = createClientQuery("selectedMessageId", undefined as string | undefined);
+ * ```
+ */
+declare const createClientQuery: <T>(key: string, defaultValue: T) => ClientQueryRef<T>;
+/**
+ * The machine-readable error codes a client can observe on a failed
+ * RPC/batch/subscription. Mirrors the server's `CODE_STATUS` keys
+ * (`@lunora/server`'s `error.ts`) by hand — the client is framework-neutral and
+ * must never import the server package (wrong dependency direction / would pull
+ * the server into the browser bundle). Keep this list in sync when a server code
+ * is added or removed (see the drift-guard note in the plan/maintenance docs).
+ */
+declare const LUNORA_ERROR_CODES: readonly ["BAD_REQUEST", "CONFLICT", "COUNT_RLS_UNSUPPORTED", "FORBIDDEN", "INTERNAL_SERVER_ERROR", "MASK_UNSUPPORTED", "NOT_FOUND", "NOT_IMPLEMENTED", "RELATION_PREDICATE_UNSUPPORTED", "TOO_MANY_REQUESTS", "UNAUTHORIZED", "UNPROCESSABLE"];
+/** A machine-readable error `code` the client may observe. Mirror of the server's `LunoraErrorCode`. */
+type LunoraErrorCode = (typeof LUNORA_ERROR_CODES)[number];
+/** Error code the server uses for optimistic-concurrency conflicts (HTTP 409). */
+declare const CONFLICT_ERROR_CODE = "CONFLICT";
+/**
+ * Whether an unknown rejection is an optimistic-concurrency conflict — the
+ * server lost a write race and the caller should refetch and retry (or surface
+ * the conflict). Structural check on the `code` property the client attaches
+ * when decoding the worker's `{ error: { code, message } }` envelope.
+ */
+declare const isConflictError: (error: unknown) => error is Error & {
+  code: "CONFLICT";
+};
+/**
+ * Whether a rejection is an RLS/policy denial (`FORBIDDEN`, HTTP 403) — the
+ * caller is authenticated but not permitted to read/write the row. The most
+ * common per-call error a UI must handle in an RLS-first app.
+ */
+declare const isForbiddenError: (error: unknown) => error is Error & {
+  code: "FORBIDDEN";
+};
+/** Whether a rejection is an authentication failure (`UNAUTHORIZED`, HTTP 401) — no/invalid identity. */
+declare const isUnauthorizedError: (error: unknown) => error is Error & {
+  code: "UNAUTHORIZED";
+};
+/**
+ * Whether a rejection is a rate-limit denial (`TOO_MANY_REQUESTS`, HTTP 429).
+ * The retry hint (if the server sent one) is read with {@link getRetryAfterMs}.
+ */
+declare const isRateLimitedError: (error: unknown) => error is Error & {
+  code: "TOO_MANY_REQUESTS";
+};
+/**
+ * Read the server's machine-readable `code` off a rejection, narrowed to the
+ * known {@link LunoraErrorCode} union. Returns `undefined` for a non-`Error`, a
+ * missing code, or an unrecognized code string (forward-compat server codes read
+ * as `undefined` here rather than being falsely narrowed).
+ */
+declare const getErrorCode: (error: unknown) => LunoraErrorCode | undefined;
+/**
+ * Read the rate-limit retry hint (`data.retryAfterMs`) off a
+ * `TOO_MANY_REQUESTS` rejection without hand-casting the `unknown` `data`
+ * payload. Returns the finite millisecond value the server sent, or `undefined`
+ * when absent/non-numeric. Pair with {@link isRateLimitedError}.
+ */
+declare const getRetryAfterMs: (error: unknown) => number | undefined;
+/** The registered function kinds a {@link FunctionReference} can describe. `stream` is a query that yields multiple frames over the WS. */
+type FunctionKind = "action" | "mutation" | "query" | "stream";
+/**
+ * Opaque reference to a registered function emitted by `@lunora/codegen`.
+ *
+ * At runtime it carries the `&lt;file>:&lt;function>` identifier in `__lunoraRef`.
+ * Generated declarations decorate this with phantom type parameters so the
+ * client can infer args / return values per call site.
+ */
+interface FunctionReference<Kind extends FunctionKind = FunctionKind, Args = unknown, Return = unknown> {
+  /**
+   * Phantom marker carrying the `Kind`/`Args`/`Return` type parameters for
+   * inference. Never present at runtime; declared as a covariant (output)
+   * position so a concrete reference stays assignable to a widened one.
+   */
+  readonly __lunoraPhantom?: {
+    args: Args;
+    kind: Kind;
+    returns: Return;
+  };
+  readonly __lunoraRef: string;
+}
+/** Extract the args type from a {@link FunctionReference}. */
+type ArgsOf<F> = F extends FunctionReference<infer _K, infer A, infer _R> ? A : never;
+/** Extract the return type from a {@link FunctionReference}. */
+type ReturnOf<F> = F extends FunctionReference<infer _K, infer _A, infer R> ? R : never;
+/**
+ * Typed reference to an HTTP-SSE stream route (`httpRoute.&lt;verb>(path).stream()`)
+ * emitted by `@lunora/codegen` as `httpStreams.&lt;namespace>.&lt;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";
+/** 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>;
+  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>;
+}
+/**
+ * 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>;
+  /** 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;
+  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>;
+}
+/**
+ * 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 {
+  /**
+   * 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 while
+   * signed out.
+   */
+  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;
+}
+/**
+ * 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<(CachedQuery & {
+    key: string;
+  })[]>;
+  /** 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 coordinate via BroadcastChannel
+   * so only one tab (the "leader") opens WebSocket connections to the server.
+   * Follower tabs receive subscription data through the channel instead.
+   *
+   * Reduces simultaneous WS connections, bandwidth, and cross-tab state drift.
+   * Requires `BroadcastChannel` (browser-only); silently ignored otherwise.
+   * Defaults to `false`.
+   */
+  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, framework hooks (React, Vue, …)
+   * wait for the durable cache to finish hydrating before their first render
+   * with an enabled subscription, so users see cached data instead of an
+   * undefined flash before the socket round-trip. Defaults to `false`.
+   *
+   * 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;
+  /**
+   * 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 &lt;= 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 {
+  /**
+   * 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 {
+  id: string;
+  query: {
+    args?: Record<string, unknown>;
+    functionPath: string;
+    shardKey?: string;
+  };
+  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;
+  id: string;
+  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 {
+  /** The checkpoint the client's view is expected to be at before this poke applies (for ordering/gap detection). */
+  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 {
+  /** Per-client custom-mutator watermark carried with this slice (see {@link ServerSettledMessage.lastMutationId}). */
+  lastMutationId?: number;
+  pokeId: string;
+  /** 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;
+}
+/**
+ * One pending scheduled function, as returned by the worker's
+ * `GET /_lunora/admin/scheduled` endpoint. Mirrors `@lunora/scheduler`'s
+ * `ScheduleRecord` structurally so the client carries no dependency on it.
+ */
+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;
+  functionPath: string;
+  id: string;
+  /** Logical workpool the job is routed to (concurrency-gated), when any. */
+  pool?: string;
+  scheduledFor: number;
+  shardKey?: 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 `&lt;file>:&lt;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;
+/** A subscription-scoped error the server pushed for this subscription id. */
+interface SubscriptionError {
+  code?: string;
+  message: string;
+}
+type SubscriptionErrorCallback = (error: SubscriptionError) => void;
+/**
+ * One active per-call optimistic transform layered onto a subscription. The
+ * displayed value is the authoritative {@link SubscriptionState.serverBase}
+ * folded through every layer's `transform`, in order — so an incoming server
+ * frame re-folds the still-pending layers onto the new base (rebasing) instead
+ * of clobbering them. A layer is dropped — gaplessly — once a `data`/`delta`
+ * frame whose `cursor >= commitCursor` arrives (its write is now reflected in
+ * `serverBase`); `commitCursor` is the CDC cursor the server echoed on the
+ * mutation's response, and stays `undefined` while the write is still queued/
+ * in-flight (so the overlay survives unrelated deltas until confirmed).
+ */
+interface OptimisticLayer {
+  /** The committed CDC cursor (from the mutation response); `undefined` until confirmed. */
+  commitCursor?: number;
+  readonly id: symbol;
+  readonly transform: (current: unknown) => unknown;
+}
+interface SubscriptionState {
+  /** True once the server has acked the subscription on the current socket. */
+  acked: boolean;
+  readonly args: Record<string, unknown>;
+  /**
+   * Stable wire-key of `args` (`stableWireKey`), computed once at subscribe
+   * time. Cached so the optimistic-update fan-out can compare against a
+   * mutation's args key without re-serializing every subscription's args on
+   * every mutation.
+   */
+  readonly argsKey: string;
+  readonly callbacks: Set<SubscriptionCallback>;
+  /**
+   * Notified when a `settled` frame advances this subscription's watermark — a
+   * write touched the subscription's tables but the result was byte-identical,
+   * so the server suppressed the data frame. A `@lunora/db` list collection
+   * uses this to drop the optimistic overlay for the confirmed write.
+   *
+   * A SET (not a single slot) because `SubscriptionState` is SHARED across
+   * every subscriber to the same `(fn, args, shardKey)`: a `@lunora/db`
+   * collection may subscribe to a query a plain `useQuery` already opened, so
+   * each subscriber registers its own callback (mirroring `callbacks` /
+   * `errorCallbacks`) and a `settled` frame fans out to all of them. Plain
+   * `useQuery` consumers register nothing, leaving the set empty.
+   */
+  readonly checkpointCallbacks: Set<(watermark: {
+    checkpoint?: number;
+    mutationId?: number;
+  }) => void>;
+  /** Notified when the server rejects this subscription (e.g. admin auth). */
+  readonly errorCallbacks: Set<SubscriptionErrorCallback>;
+  readonly fn: FunctionReference;
+  readonly id: string;
+  /**
+   * The highest custom-mutator `mutationId` from this client the server has
+   * applied, captured from the last `settled` frame (the suppressed-list-frame
+   * watermark). Forwarded to {@link SubscriptionState.checkpointCallbacks}.
+   * Absent until a `settled` frame arrives.
+   */
+  lastMutationId?: number;
+  /** Last known value, used to short-circuit `useQuery`-style consumers. */
+  lastValue: unknown;
+  /**
+   * Active per-call optimistic layers, in application order (see
+   * {@link OptimisticLayer}). Empty for subscriptions with no pending per-call
+   * optimistic write — the common case, where `lastValue` tracks `serverBase`
+   * exactly and behaviour is identical to a plain server-value assignment.
+   */
+  optimisticLayers: OptimisticLayer[];
+  /**
+   * The authoritative server value the optimistic layers fold onto — the value
+   * with NO optimistic overlay. Tracks `lastValue` exactly whenever no layers
+   * are active; diverges only while a per-call optimistic write is pending. A
+   * server frame updates this (and re-folds the layers); the durable read cache
+   * persists this, never the optimistic overlay.
+   */
+  serverBase: unknown;
+  /**
+   * The `__cdc_log` high-watermark (`cursor`) the `lastValue` reflects,
+   * captured from the last `data`/`delta`/`resume` frame. Persisted to the
+   * durable read cache and replayed as `sinceSeq` on reconnect so the server
+   * can resume instead of re-snapshotting (Pillar 1b/2). Absent until the
+   * first cursor-stamped frame arrives.
+   */
+  serverCursor?: number;
+  /**
+   * The CDC `epoch` token the `serverCursor` belongs to, captured from the
+   * same frame. Replayed as `sinceEpoch` on reconnect so the server resumes
+   * only when the client is still on the same changelog timeline — a reset or
+   * recycled shard advertises a new epoch, forcing a fresh snapshot. Absent
+   * until the first epoch-stamped frame arrives.
+   */
+  serverEpoch?: string;
+  readonly shardKey?: string;
+}
+/**
+ * Active subscription registry. The client keys subscriptions by
+ * `(functionPath, stableWireKey(args), shardKey)` so duplicate calls share a
+ * single server-side registration. Args are stably encoded (keys sorted at every
+ * depth) so two structurally-equal arg records constructed with a different key
+ * order (`{ a, b }` vs `{ b, a }`) collapse to the same key instead of leaking a
+ * duplicate subscription. Encoding the args' **wire form** keeps the key
+ * byte-identical for pure-JSON args while giving wire-typed args (`bigint`,
+ * `Date`, bytes, …) distinct stable tokens instead of a throw.
+ */
+declare class SubscriptionRegistry {
+  static key(functionPath: string, args: Record<string, unknown>, shardKey?: string): string;
+  private readonly byKey;
+  private readonly byId;
+  get(key: string): SubscriptionState | undefined;
+  getById(id: string): SubscriptionState | undefined;
+  add(state: SubscriptionState): void;
+  remove(state: SubscriptionState): void;
+  all(): SubscriptionState[];
+}
+/**
+ * Read/write handle over the client's live query cache, handed to a mutation's
+ * `withOptimisticUpdate` callback so a single mutation can optimistically patch
+ * many subscribed queries at once (Convex's `OptimisticLocalStore` model).
+ *
+ * `getQuery` reads the current value (server value or any still-pending
+ * optimistic override) of a subscribed query; `setQuery` registers a constant
+ * optimistic layer on top. The whole batch rebases onto incoming deltas and
+ * settles together — confirmed on the mutation's commit cursor, or rolled back
+ * on failure — the same per-subscription layer machinery the single-query
+ * per-call `optimistic` transform uses, generalized to N queries.
+ */
+interface OptimisticLocalStore {
+  /**
+   * Every loaded subscription on `function_`, regardless of args, paired with
+   * the args it was subscribed under. Mirrors Convex's `getAllQueries` — handy
+   * when a write must patch every variant of a list query (all channels,
+   * all filters) without enumerating their args up front.
+   */
+  getAllQueries: <F extends FunctionReference>(function_: F) => {
+    args: ArgsOf<F>;
+    value: ReturnOf<F> | undefined;
+  }[];
+  /**
+   * Current cached value for the subscribed `(function_, args)` query, or
+   * `undefined` when nothing is subscribed/loaded for it. Reflects any
+   * optimistic override already written in this batch.
+   */
+  getQuery: <F extends FunctionReference>(function_: F, args: ArgsOf<F>) => ReturnOf<F> | undefined;
+  /**
+   * Write an optimistic override for the subscribed `(function_, args)`
+   * query. A no-op (returns without effect) when no subscription matches —
+   * mirroring Convex, where you only patch queries the page is watching.
+   */
+  setQuery: <F extends FunctionReference>(function_: F, args: ArgsOf<F>, value: ReturnOf<F> | undefined) => void;
+}
+/** A mutation's multi-query optimistic update: read/write the cache via `localStore`. */
+type OptimisticUpdate<Args> = (localStore: OptimisticLocalStore, args: Args) => void;
+/**
+ * Build an {@link OptimisticLocalStore} bound to a subscription registry and the
+ * mutation's shard key. Each `setQuery(value)` registers a constant-value layer
+ * on its target subscription (via `applyOptimisticLayer`): the predicted value
+ * survives incoming server deltas (re-clamped, masking concurrent changes to that
+ * query — not merged) and drops gaplessly on the mutation's commit cursor, like
+ * the single-query per-call `optimistic` path. Returns the store plus the ordered
+ * `confirm` (success) and `rollback` (failure) closures every `setQuery` produced,
+ * so the caller settles the whole batch when the mutation does.
+ */
+declare const createLocalStore: (subscriptions: SubscriptionRegistry, shardKey: string | undefined) => {
+  confirms: ((commitCursor: number | undefined) => void)[];
+  rollbacks: (() => void)[];
+  store: OptimisticLocalStore;
+};
+declare const DEFAULT_MAX_BUFFER = 1024;
+interface StreamHandle<T = unknown> {
+  /** Mark the stream complete (no more chunks); resolves any pending consumer to `done:true`. */
+  readonly complete: () => void;
+  /** Surface an error to any pending consumer; subsequent pushes are dropped. */
+  readonly fail: (error: Error) => void;
+  /**
+   * Push one chunk. Silent no-op once the stream is `complete`, `fail`-ed,
+   * or `cancel`-ed. When the buffer is already at `maxBuffer`, the stream
+   * is failed with a `STREAM_BACKPRESSURE` error and the push is dropped —
+   * the producer never sees a thrown exception.
+   */
+  readonly push: (value: T) => void;
+}
+interface StreamIterable<T> extends AsyncIterable<T> {
+  /** Cancel the stream from the consumer side: closes the iterator and notifies the registered canceller. */
+  cancel: () => void;
+}
+/**
+ * Build a stream handle paired with an async-iterable. The handle is the
+ * server-driven side (the WS dispatcher pushes chunks / completes / errors);
+ * the iterable is what the user awaits. `onCancel` is invoked exactly once
+ * when the consumer calls `.cancel()` (or `.return()`) so the client can
+ * send a `{type:"unsubscribe"}` frame to the server.
+ */
+declare const createStream: <T>(options: {
+  maxBuffer?: number;
+  onCancel: () => void;
+}) => {
+  handle: StreamHandle<T>;
+  iterable: StreamIterable<T>;
+};
+type WSState = "idle" | "connecting" | "open" | "closed";
+/**
+ * Aggregate live-socket health across every shard connection, for a UI status
+ * indicator. `idle` = no socket opened yet; `connecting` = at least one socket
+ * is (re)connecting and none is open; `connected` = at least one socket is open;
+ * `offline` = sockets exist but all are down (between reconnect attempts).
+ */
+type ConnectionStatus = "connected" | "connecting" | "idle" | "offline";
+/** One shard's socket + watermark state in a {@link LunoraClient.debug} snapshot. */
+interface ClientDebugShard {
+  /**
+   * Highest custom-mutator watermark the server has echoed for this client on this
+   * shard. A write whose `clientSeq` is above this has been sent but not confirmed
+   * — the first thing to check when an optimistic overlay won't clear.
+   */
+  confirmedMutationWatermark: number;
+  /** Whether a `WebSocket` object currently exists (distinct from it being open). */
+  hasSocket: boolean;
+  /** `undefined` for the default (unsharded) connection. */
+  shardKey: string | undefined;
+  /** Whether this shard's socket has ever completed a handshake — gates offline queueing. */
+  wasEverConnected: boolean;
+  wsState: WSState;
+}
+/** One live query or shape subscription in a {@link LunoraClient.debug} snapshot. */
+interface ClientDebugSubscription {
+  /** Whether the server has acknowledged the subscription on the current socket. */
+  acked: boolean;
+  /** `namespace:fn` for a query, `shape:&lt;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 `&lt;file>:&lt;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.mutation} — the optimistic-update
+ * machinery plus `shardKey`. Exported (at the end of this file) so the framework
+ * adapters (`@lunora/react`, `/solid`, `/svelte`, `/vue`) can type their
+ * `mutate(args, options?)` against one canonical definition instead of
+ * re-declaring it.
+ */
+interface MutationCallOptions<TCurrent = unknown, TValue = unknown, TArgs = unknown> {
+  /**
+   * Override the auto-generated idempotency key (`x-lunora-mutation-id`). Lets a
+   * durable outbox replay a committed-but-unacked write under its *original* key
+   * so the server dedups it instead of applying it twice. Omit for normal calls —
+   * each then gets a fresh key.
+   */
+  mutationId?: string;
+  optimistic?: (current: TCurrent | undefined) => TValue;
+  /**
+   * Convex-parity multi-query optimistic update. Receives an
+   * `OptimisticLocalStore` over the live subscription cache plus the
+   * mutation's args, so one mutation can patch many subscribed queries at
+   * once; every write is rolled back atomically if the mutation fails.
+   */
+  optimisticUpdate?: OptimisticUpdate<TArgs>;
+  /**
+   * Sync predicate evaluated just before the offline queue replays this
+   * write on reconnect. When it returns `false` the mutation is dropped
+   * instead of replayed — use it to guard against replaying writes whose
+   * assumptions are no longer valid (e.g. the document it referred to was
+   * deleted by another client while this tab was offline).
+   */
+  precondition?: () => boolean;
+  shardKey?: string;
+}
+/** Callback a shape subscription invokes with its materialized rowset on every applied poke. */
+type ShapeCallback = (rows: Record<string, unknown>[]) => void;
+/**
+ * The high-water marks a shape poke has now synced to the client: `checkpoint`
+ * is the op-log cursor and `mutationId` the highest custom-mutator id the server
+ * echoed for this client. A `@lunora/db` collection feeds these into its
+ * checkpoint registry to drop optimistic overlays once the server's authoritative
+ * rows have landed.
+ */
+interface SyncWatermark {
+  checkpoint?: number;
+  mutationId?: number;
+}
+/**
+ * An `Error` carrying the server's machine-readable `code` and (for a
+ * `LunoraError`) structured `data`, plus an optional actionable `hint` (Markdown)
+ * and `docsUrl` resolved from the central error catalog. The client's public
+ * error contract for RPC/batch failures — a UI can render `hint`/`docsUrl` to
+ * tell the user how to fix the error. The `(string & {})` arm keeps
+ * forward-compat/unknown server codes assignable without losing autocomplete on
+ * the known {@link LunoraErrorCode} union.
+ */
+type LunoraClientError = Error & {
+  code?: LunoraErrorCode | (string & {});
+  data?: unknown;
+  docsUrl?: string;
+  hint?: string | string[];
+};
+/** One demuxed result slot of a {@link LunoraClient.batch} call (plan 088). */
+type BatchSlot = {
+  error: LunoraClientError;
+  ok: false;
+} | {
+  ok: true;
+  value: unknown;
+};
+/**
+ * Lunora browser/edge client. Talks RPC over HTTP and real-time deltas over
+ * a single multiplexed WebSocket.
+ *
+ * Reconnect, offline queueing, and optimistic updates are all handled here;
+ * see the package README for the wire protocol.
+ */
+declare class LunoraClient {
+  /** Hard cap on concurrently-buffered pokes — a backstop that reclaims buffers abandoned by a mid-poke disconnect (no `pokeEnd`). Far above any real concurrent-in-flight count. */
+  private static readonly MAX_POKE_BUFFERS;
+  /**
+   * Create a typed {@link ClientQueryRef}. Convenience wrapper around
+   * {@link createClientQuery} so you don't need a separate import.
+   * @example
+   * ```ts
+   * const sidebarOpen = LunoraClient.createClientQuery("sidebarOpen", true);
+   * ```
+   */
+  static createClientQuery<T>(key: string, defaultValue: T): ClientQueryRef<T>;
+  readonly url: string;
+  readonly wsUrl: string;
+  /** Local reactive store for {@link ClientQueryRef} values — no server round-trip. Private; reach it via `getClientQuery` / `setClientQuery` / `subscribeClientQuery`. */
+  private readonly clientQueryStore;
+  private wsToken;
+  /** Better-auth base path (trailing slash stripped) for the `get-session` lookup. */
+  private readonly authBasePath;
+  private readonly fetchImpl;
+  private readonly WebSocketImpl;
+  private readonly bookmark;
+  private readonly reconnectOptions;
+  /** WS connect timeout (ms); `0` disables it. See {@link LunoraClientOptions.connectTimeoutMs}. */
+  private readonly connectTimeoutMs;
+  /** Keepalive cadence (ms); `0` disables the heartbeat. See {@link LunoraClientOptions.heartbeatIntervalMs}. */
+  private readonly heartbeatIntervalMs;
+  private readonly offlineQueue;
+  /**
+   * Durable outbox seam (the `@lunora/db` `createExecutorOutboxSink`). When
+   * set, offline writes are delegated here and the built-in {@link OfflineQueue}
+   * is bypassed, so a db app has exactly one durable write path.
+   */
+  private readonly outbox;
+  /** Stable per-client id stamped onto every `OutboxMutation` (custom-mutator watermark). */
+  private readonly clientId;
+  /**
+   * `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,
+   * keyed by shard bucket (`shardKey ?? ""`) since the DO tracks one
+   * `__client_watermark` per shard. `callMutator` bumps it from every
+   * ack; the `@lunora/db` mutator runtime seeds its `clientSeq` generator from
+   * it so a reload (which resets the in-memory counter) never reissues a stale
+   * sequence the server would silently swallow as a replay.
+   */
+  private readonly clientWatermarks;
+  /** Monotonic per-client mutation counter backing the server `__client_watermark`. */
+  private outboxMutationCounter;
+  private readonly onPersistenceError;
+  private readonly persistence;
+  /** App/schema version stamped on persisted writes + cached reads; mismatches are purged. */
+  private readonly persistenceVersion;
+  /** Releases the multi-tab outbox-leader Web Lock on close (see `hydrateAsOutboxLeader`). */
+  private outboxLeaderRelease;
+  /** Durable read cache (Pillar 2); `undefined` when `queryCache` is omitted or `false`. */
+  private readonly queryCache;
+  /**
+   * Values restored from the `queryCache` at construction, keyed by the
+   * read-cache key, awaiting the `subscribe()` that will consume them. A
+   * key is consumed (deleted) the first time its subscription is created, so
+   * the cache only ever seeds the initial value — live frames take over after.
+   */
+  private readonly hydratedQueryCache;
+  /**
+   * Coalesced read-cache writes: the latest value per key, flushed to
+   * the `queryCache` on a short debounce so a burst of deltas persists once.
+   */
+  private readonly pendingCacheWrites;
+  private cacheFlushTimer;
+  private readonly subscriptions;
+  /**
+   * Cross-tab coordinator; created only when `crossTabSync: true`. When the
+   * client is not the elected leader, all WebSocket operations are skipped.
+   * Not `readonly` — `close()` clears it (mirrors `outboxLeaderRelease`).
+   */
+  private tabCoordinator;
+  /** One {@link ShardConnection} per shard key (keyed by `shardKey ?? ""`). */
+  private readonly connections;
+  /** Default `connect`-envelope context applied to a shard with no explicit override. */
+  private readonly defaultConnectionContext;
+  /**
+   * Per-shard `connect`-envelope context registered via `setConnectionContext`
+   * (keyed by `shardKey ?? ""`), overriding `defaultConnectionContext`. Sent
+   * on every socket open so it replays across reconnects, and forwarded to the
+   * server's `onConnect`/`onDisconnect` lifecycle hooks. This holds only the
+   * imperative (last-writer-wins) override; refcounted holders registered via
+   * `acquireConnectionContext` live in `connectionContextHolders` and take
+   * precedence — see `effectiveConnectionContext`.
+   */
+  private readonly connectionContexts;
+  /**
+   * Per-shard stack of refcounted connection-context holders (keyed by
+   * `shardKey ?? ""`), registered via `acquireConnectionContext`. Each holder
+   * is an opaque token carrying its `context`; the most-recently acquired
+   * holder wins (last-writer-wins among live holders), and the context is only
+   * cleared for a shard once its last holder releases — so two concurrently
+   * mounted presence hooks on the same shard can't stomp each other's context
+   * on cleanup. A holder is identified by reference identity so a release
+   * removes exactly the right one regardless of stack position.
+   */
+  private readonly connectionContextHolders;
+  private authToken;
+  /**
+   * Optional STABLE identity subject (a user id), the basis of the offline-queue
+   * identity stamp when supplied. Keeps a same-user token *refresh* from looking
+   * like an identity change (which would discard queued writes). `undefined` =
+   * not supplied, so identity falls back to a hash of the raw token. See
+   * `setAuthToken` / `identityFingerprint`.
+   */
+  private authSubject;
+  /**
+   * Identity stamp recorded against each queued offline mutation, keyed by
+   * the queue-assigned mutation id. Captured at enqueue from the auth token
+   * in effect at the time, and re-checked at flush so a queued write can
+   * never replay under a different identity than the one that issued it.
+   * See `identityFingerprint` for the fingerprint shape.
+   */
+  private readonly queuedIdentities;
+  private closed;
+  /** Subscribers to auth-token changes (see `onAuthTokenChange`). */
+  private readonly authTokenListeners;
+  /** Subscribers to aggregate connection-status changes (see `onConnectionStatus`). */
+  private readonly statusListeners;
+  /** Subscribers notified when the server drops a socket for an expired token (see `onTokenExpired`). */
+  private readonly tokenExpiredListeners;
+  /** Subscribers to offline-queued mutation verdicts (see `onMutationSettled`). */
+  private readonly mutationSettledListeners;
+  /** Subscribers to the offline-queue pending-count (see `onPendingChange`). */
+  private readonly pendingChangeListeners;
+  /**
+   * Whisper-topic handlers, keyed by `connectionKey(shardKey)` → topic → set
+   * of callbacks. Membership doubles as the resubscribe set replayed on every
+   * (re)connect so a topic survives a socket bounce.
+   */
+  private readonly whisperHandlers;
+  /** Last status broadcast, so we only notify listeners on an actual change. */
+  private lastStatus;
+  private nextSubId;
+  private nextStreamId;
+  /**
+   * In-flight client-side stream readers, keyed by the stream id sent on the
+   * wire. The handle drives the underlying iterator queue and `shardKey`
+   * tells us which socket to push the cancel frame onto when the consumer
+   * calls `.cancel()` or the iterator is garbage-collected.
+   */
+  private readonly streams;
+  /** Live shape subscriptions (partial replication), keyed by their wire id. */
+  private readonly shapeSubscriptions;
+  /** In-flight pokes being assembled between `pokeStart` and `pokeEnd`, keyed by `pokeId`. */
+  private readonly pokeBuffers;
+  private nextShapeId;
+  constructor(options: LunoraClientOptions);
+  /**
+   * Set (or clear) the bearer token sent on every HTTP RPC. Notifies any
+   * {@link onAuthTokenChange} listeners so React hooks like `useAuth` stay in
+   * sync across all mounted instances.
+   *
+   * Pass a STABLE `subject` (the user id) to key the offline-queue identity on
+   * it instead of the token bytes, so a token *refresh* (same user, new JWT)
+   * doesn't read as an identity change and discard queued writes. The subject is
+   * **sticky**: a later call that omits it (or passes `undefined`) keeps the
+   * established subject — so `setAuthToken(refreshedToken)` after a prior
+   * `setAuthToken(token, user.id)` retains the identity. Pass `null` to clear it
+   * (an explicit sign-out). Establishing the subject for the first time on an
+   * UNCHANGED token (e.g. the user id resolves a tick after the token was set)
+   * re-stamps any in-flight queued writes rather than dropping them — same
+   * credential, just a more stable label. A real user switch (the token AND
+   * subject both change) still drops the previous user's writes.
+   *
+   * Does NOT update the WebSocket auth — the WS token is fixed at upgrade
+   * time and lives in the URL. To refresh live WS auth, call
+   * {@link setWsToken} explicitly, which closes existing shard sockets to
+   * force a reconnect with the new credential.
+   */
+  setAuthToken(token: string | null, subject?: string | null): void;
+  getAuthToken(): string | null;
+  /**
+   * The current identity fingerprint (the same stamp queued offline writes
+   * carry). Exposed so a durable {@link OutboxSink}'s replay handler — which
+   * owns its own at-least-once replay outside the built-in `OfflineQueue` —
+   * can drop a persisted write whose captured `identity` no longer matches the
+   * signed-in user, the guard the queue path applies in `flushOfflineQueue`.
+   */
+  currentIdentity(): string | null;
+  /** This client's stable identifier — the watermark key the server's custom-mutator protocol advances per `clientSeq`. */
+  clientIdentifier(): string;
+  /**
+   * The highest custom-mutator watermark the server has echoed for this client
+   * on the given shard (0 if none yet). The `@lunora/db` mutator runtime seeds
+   * its `clientSeq` generator from this so a reload never reissues a sequence
+   * the server has already applied (which it would swallow as a replay, silently
+   * dropping the write).
+   */
+  confirmedMutationWatermark(shardKey?: string): number;
+  /**
+   * Push a custom mutator to its authoritative server impl over the watermark
+   * protocol (Phase 4): the request carries `x-lunora-client-id` + a monotonic
+   * `x-lunora-client-seq`, so the DO runs it exactly once and advances this
+   * client's `__client_watermark`.
+   *
+   * Returns the server `result` plus `applied`: `true` when the DO ran this push
+   * as the next-in-order mutation, `false` when it was a replay ack (`clientSeq`
+   * was at or below the stored watermark — e.g. a stale sequence after a reload).
+   * A `false` verdict tells the caller to reissue above the now-known watermark
+   * (echoed into {@link confirmedMutationWatermark}) rather than treat the benign
+   * ack as a confirmed write. Every ack — applied or not — bumps the watermark.
+   *
+   * This is the online transport for `@lunora/db`'s client-mutator runtime; the
+   * optimistic overlay + durable-outbox concerns live in that runtime, not here.
+   */
+  callMutator(functionPath: string, args: Record<string, unknown>, options?: {
+    clientSeq?: number;
+    shardKey?: string;
+  }): Promise<{
+    applied: boolean;
+    result: unknown;
+  }>;
+  /**
+   * Subscribe to auth-token changes. Returns an unsubscribe function. The
+   * listener is NOT invoked on registration — use {@link getAuthToken} for
+   * the current value.
+   */
+  onAuthTokenChange(listener: (token: string | null) => void): Unsubscribe;
+  /**
+   * Fetch the currently authenticated user from better-auth's `get-session`
+   * endpoint, returning the `user` record or `null` when signed out. Sends
+   * the stored bearer token (if any) and `credentials: "include"` so a
+   * cookie-session is also honoured. A network/parse failure or a non-OK
+   * response resolves to `null` rather than throwing — callers treat "couldn't
+   * resolve identity" as "signed out".
+   *
+   * Framework-agnostic: pair it with {@link onAuthTokenChange} to refetch when
+   * the token changes (that's what `@lunora/react`'s `useAuth` does).
+   */
+  getCurrentUser(): Promise<User | null>;
+  /**
+   * Replace the token appended to WS upgrade URLs as `?token=…` and close
+   * every open shard socket so the reconnect picks up the new value. Call
+   * this whenever the user's WS credential changes (rotating the admin token
+   * in the studio, switching workspaces, etc.). Accepts a static string or a
+   * {@link WsTokenProvider} resolved fresh at every (re)connect — the channel
+   * for short-lived credentials like the minted ephemeral admin sub-token.
+   * Bearer tokens for HTTP RPC are independent — see {@link setAuthToken}.
+   */
+  setWsToken(token: string | undefined | WsTokenProvider): void;
+  /**
+   * Register (or clear, with `undefined`) the app context sent in the `connect`
+   * envelope for a shard's socket, overriding the client-wide
+   * {@link LunoraClientOptions.connectionContext}. The server forwards it to the
+   * `onConnect`/`onDisconnect` lifecycle hooks as `event.context` — e.g.
+   * `@lunora/react`'s `usePresence` registers `{ roomId, sessionId }` so the
+   * presence row is removed the instant the socket drops, with no TTL lag.
+   *
+   * Stored per shard and replayed on every (re)connect. When a socket for the
+   * shard is already open, a fresh `connect` envelope is sent immediately so the
+   * server sees the new context without waiting for a reconnect.
+   */
+  setConnectionContext(context: Record<string, unknown> | undefined, options?: {
+    shardKey?: string;
+  }): void;
+  /**
+   * Refcounted variant of {@link setConnectionContext}: register a connection
+   * `context` for a shard and get back a release function. Unlike the imperative
+   * setter, the context is only cleared once the *last* acquired holder releases
+   * it — so two components (e.g. two mounted `usePresence` hooks) on the same
+   * shard no longer clobber each other's context when one of them unmounts. The
+   * most-recently acquired live holder wins (last-writer-wins), and releasing
+   * the top holder falls back to the previous one rather than clearing.
+   *
+   * With a single holder the behaviour is identical to a
+   * `setConnectionContext(context)` / `setConnectionContext(undefined)` pair.
+   * Releasing more than once is a no-op (the holder is matched by reference, so
+   * a double release can't drop a different holder).
+   */
+  acquireConnectionContext(context: Record<string, unknown>, options?: {
+    shardKey?: string;
+  }): Unsubscribe;
+  /**
+   * Join a whisper `topic` and receive every ephemeral message other members
+   * broadcast to it on the same shard (typing indicators, live cursors,
+   * presence pings). Whispers never touch the server's durable state — there's
+   * no query, no row, no CDC entry. Returns an unsubscribe function; the topic
+   * is left on the server once its last local handler unsubscribes.
+   *
+   * `handler` receives the raw `data` and the sender's verified `from` user id
+   * (omitted for an anonymous sender). The topic is scoped to `options.shardKey`
+   * (the default shard when omitted) — use the same shard you target with the
+   * matching queries/mutations so members land on the same Durable Object.
+   *
+   * Security: whisper topics are NOT access-controlled beyond the shard
+   * boundary — any client that can open a socket to the shard can join, read,
+   * and inject on any topic name. `from` is server-stamped and unforgeable, but
+   * do not put data on a whisper topic that some shard members shouldn't see,
+   * and don't trust a whisper's `data` as authorization. Use a query/mutation
+   * (with RLS) for anything privileged; whispers are for transient awareness.
+   */
+  whisperSubscribe(topic: string, handler: (data: unknown, from?: string) => void, options?: {
+    shardKey?: string;
+  }): Unsubscribe;
+  /**
+   * Broadcast an ephemeral `data` payload to the other members of a whisper
+   * `topic` on `options.shardKey`'s shard. Fire-and-forget: the frame is
+   * dropped when the shard socket isn't open (whispers are transient, never
+   * queued), and the server silently drops it if the sender exceeds its
+   * whisper rate budget. The sender never receives its own whisper. Omitting
+   * `data` delivers JSON `null` to receivers (not `undefined`).
+   */
+  whisper(topic: string, data?: unknown, options?: {
+    shardKey?: string;
+  }): void;
+  /**
+   * Subscribe to token-expiry events: invoked whenever the server drops a
+   * shard socket because the connection's credential lapsed (close code
+   * `4001`). The client already reconnects automatically (re-resolving
+   * identity from the cookie/token in effect); use this to refresh a
+   * short-lived token first — e.g. call {@link setWsToken} / {@link setAuthToken}
+   * with a freshly minted one. Returns an unsubscribe function.
+   */
+  onTokenExpired(listener: () => void): Unsubscribe;
+  /**
+   * Current aggregate live-socket status across all shard connections. See
+   * {@link ConnectionStatus}.
+   */
+  connectionStatus(): ConnectionStatus;
+  /**
+   * Subscribe to aggregate connection-status changes. Invokes `listener`
+   * immediately with the current status, then on every transition. Returns an
+   * unsubscribe function.
+   */
+  onConnectionStatus(listener: (status: ConnectionStatus) => void): Unsubscribe;
+  /**
+   * Number of offline writes waiting in the built-in queue to be sent — the
+   * depth for a "N changes waiting to sync" indicator. Counts writes that are
+   * queued (offline / mid-reconnect), not ones already in flight on the wire.
+   * A `@lunora/db` app whose writes ride the unified outbox should read
+   * `LunoraDb.pendingCount()` instead (this counts only the built-in queue).
+   */
+  pendingCount(): number;
+  /**
+   * A point-in-time snapshot of everything the sync engine believes right now:
+   * per-shard sockets and watermarks, every live query and shape subscription with
+   * its cursor and ack state, and the offline-queue depth.
+   *
+   * This exists because the alternative is `console.log`. When an optimistic
+   * overlay doesn't clear, the questions are always the same — *is the socket open?
+   * what watermark has the server confirmed for this shard? has this shape been
+   * poked since my write? is anything stuck in the queue?* — and none of them were
+   * answerable from outside the client, so every adopter ends up instrumenting the
+   * library by hand or building a bespoke policy layer around a symptom.
+   *
+   * Read it from a devtools console, log it next to a bug report, or render it in a
+   * debug panel. Pull-only and allocation-cheap; nothing here is reactive, so poll
+   * it or read it on demand.
+   *
+   * ```ts
+   * const { shards, subscriptions } = client.debug();
+   * // shards: [{ shardKey: "user-1", wsState: "open", confirmedMutationWatermark: 42, … }]
+   * ```
+   */
+  debug(): ClientDebugSnapshot;
+  /**
+   * Subscribe to changes in {@link pendingCount}. Invokes `listener` immediately
+   * with the current count, then whenever the queue depth changes (a write is
+   * enqueued, flushed, or discarded). Returns an unsubscribe function.
+   */
+  onPendingChange(listener: (pending: number) => void): Unsubscribe;
+  /**
+   * Subscribe to terminal verdicts for offline-queued mutations. The listener
+   * fires once per queued write that commits or is rejected — including a write
+   * restored from durable storage after a reload, whose original `mutation()`
+   * Promise no longer exists (`hadAwaiter: false`), and a write the queue
+   * evicts on overflow or discards on an identity change. This is the durable
+   * channel for surfacing a rolled-back optimistic write to the UI; an online
+   * mutation that never queued still surfaces through the Promise `mutation()`
+   * returns. The listener is NOT invoked on registration. Returns an
+   * unsubscribe function. See {@link MutationSettledEvent}.
+   */
+  onMutationSettled(listener: (event: MutationSettledEvent) => void): Unsubscribe;
+  /**
+   * The `WebSocket` implementation this client was constructed with (an
+   * explicit `options.WebSocket`, or the ambient global on platforms that have
+   * one) — `undefined` if neither is available. This is the seam a feature
+   * that opens its OWN socket outside the client's multiplexed connection
+   * (e.g. a voice-agent hook) should default to, instead of reaching for
+   * `globalThis.WebSocket` directly: on React Native the client wraps this
+   * constructor to inject the auth-headers factory's credential onto the
+   * upgrade request (`createLunoraClient`'s `withAuthWebSocket`), which a raw
+   * `new globalThis.WebSocket(url)` would silently bypass.
+   */
+  getWebSocketImpl(): typeof WebSocket | undefined;
+  /**
+   * Read the current value for a {@link ClientQueryRef}. Returns
+   * `ref.defaultValue` when no value has been explicitly set.
+   */
+  getClientQuery<T>(ref: ClientQueryRef<T>): T;
+  /**
+   * Set a new value for `ref` and notify every subscriber. Pass `undefined`
+   * to reset the slot to `ref.defaultValue`.
+   */
+  setClientQuery<T>(ref: ClientQueryRef<T>, value: T): void;
+  /**
+   * Subscribe to changes for `ref`. The callback is NOT invoked on
+   * registration — call {@link getClientQuery} for the current value.
+   * Returns an unsubscribe function.
+   */
+  subscribeClientQuery(ref: ClientQueryRef, callback: (value: unknown) => void): Unsubscribe;
+  /**
+   * Reset a {@link ClientQueryRef} to its default value, notifying every
+   * subscriber. Equivalent to `setClientQuery(ref, ref.defaultValue)` but
+   * removes the stored entry so a future {@link getClientQuery} returns
+   * the default rather than an explicitly-set value.
+   */
+  resetClientQuery(ref: ClientQueryRef): void;
+  /**
+   * Capture a snapshot of the current live query value at call time and
+   * produce a `() => boolean` precondition that compares it against the
+   * value at replay time (on queue drain / reconnect).
+   *
+   * When the precondition is checked it re-reads the query's current value
+   * via `peekActiveQueryValue`. If the value differs from what was
+   * captured at call time the precondition returns `false` and the offline
+   * mutation is dropped as stale.
+   *
+   * This is a method wrapper around `createSnapshotPrecondition` that
+   * binds the client instance for you — no need to pass `client` explicitly.
+   * @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, if one
+   * exists. Returns the subscription's `lastValue` (which includes any
+   * optimistic overlay) or `undefined` if no subscription is active for the
+   * given `(functionPath, args, shardKey)`.
+   *
+   * Unlike {@link peekHydratedQuery} (which reads from the durable read cache
+   * and is independent of active subscriptions), this method reflects the
+   * current in-memory state of an already-opened subscription — useful for
+   * offline mutation preconditions that need to snapshot the value at call time
+   * and compare it at replay time.
+   */
+  peekActiveQueryValue(functionPath: string, args: Record<string, unknown>, shardKey?: string): unknown;
+  query<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: {
+    shardKey?: string;
+  }): Promise<ReturnOf<F>>;
+  /**
+   * Batch several independent calls into ONE round trip (plan 088). Each call is
+   * dispatched server-side exactly as an individual RPC — per-shard
+   * authorization, `(identity, mutationId)` idempotency, and custom-mutator
+   * watermark ordering are all preserved — and the worker splits the batch by
+   * shard so calls to different shards fan out to their own DOs. Results are
+   * demuxed back in input order; a failing call does NOT fail the batch (its
+   * slot carries `{ ok: false, error }`, with `.code`/`.data` reconstructed like
+   * a single call). Args/results ride the value codec (bytes/bigint survive).
+   *
+   * No promise pipelining and no capability passing — a call's args cannot
+   * reference another call's result (see plan 088 §fence; capabilities are
+   * incompatible with DO hibernation).
+   */
+  batch(calls: ReadonlyArray<{
+    args?: Record<string, unknown>;
+    fn: FunctionReference;
+    shardKey?: string;
+  }>): Promise<BatchSlot[]>;
+  /**
+   * Invoke a mutation. Errors propagate as rejections.
+   *
+   * Offline-queue semantics: a mutation is queued (and replayed on reconnect)
+   * only when the targeted shard's socket was open at least once already
+   * (`wasEverConnected`), so the registry / resubscribe handshake has run.
+   * Mutations issued before the very first WS connect to a shard fail fast.
+   * Opt into queueing-before-first-connect via
+   * `OfflineQueueOptions.queueBeforeFirstConnect`.
+   */
+  mutation<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>): Promise<ReturnOf<F>>;
+  action<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: {
+    shardKey?: string;
+  }): Promise<ReturnOf<F>>;
+  /**
+   * Bulk-import `rows` through a mutation that accepts a batch, chunked so a large
+   * dataset lands in a bounded number of round-trips.
+   *
+   * **Offline caveat:** each chunk is sent with {@link LunoraClient.mutation}, which
+   * resolves once the write is durably queued rather than once the server has applied
+   * it. So an import run while offline resolves `{ chunks, imported }` with nothing
+   * committed yet — the counts describe what was *handed over*, and the outbox
+   * replays them on reconnect. Don't report "migration complete" on this alone.
+   *
+   * This is the one-shot migration / seed path: "I have 20k rows client-side and a
+   * server mutation that inserts many at once". Doing it by hand goes wrong in two
+   * predictable ways — a serial per-row loop pays one round-trip *and* one watermark
+   * wait per row (a 200-row import becomes 200 sequential hops), while a single
+   * giant call blows the DO's batch limit. So: chunk, send sequentially, and give
+   * each chunk a stable idempotency key derived from `importId` + its index, so a
+   * resumed or retried import doesn't double-insert the chunks that already landed.
+   *
+   * The server mutation is yours (Lunora can't guess the table or the row shape);
+   * back it with `ctx.db.insertMany(...)`, or `insertManyUnsafe(...)` for data you
+   * vouch for. `chunkSize` defaults to 500, matching the DO's default batch cap.
+   *
+   * ```ts
+   * await client.importRows(api.migrate.importNodes, nodes, {
+   *     importId: `migrate-${userId}`,
+   *     onProgress: ({ done, total }) => setProgress(done / total),
+   *     shardKey: userId,
+   *     toArgs: (chunk) => ({ nodes: chunk }),
+   * });
+   * ```
+   */
+  importRows(function_: FunctionReference, rows: ReadonlyArray<unknown>, options?: {
+    /** Rows per call. Defaults to 500 — the DO's default batch cap. */
+    chunkSize?: number;
+    /**
+     * Stable id for this import run. Each chunk is sent under
+     * `${importId}:${chunkIndex}` as its mutation id, so re-running an import
+     * that uses the SAME `chunkSize` re-sends each chunk under its prior key
+     * and the server dedupes it instead of inserting twice.
+     *
+     * CAVEAT — the key is POSITIONAL, not content-based: it pins on the chunk
+     * INDEX, not on the rows inside it. Resume or retry with a DIFFERENT
+     * `chunkSize` (or a changed row ordering) and index N now covers different
+     * rows than the first run's index N; the server sees a duplicate key and
+     * SILENTLY DROPS those rows. Keep `chunkSize` (and the row order) identical
+     * across resumes of the same `importId`. Omit `importId` only for a
+     * throwaway import where double-insertion is acceptable.
+     */
+    importId?: string;
+    /**
+     * Called after each chunk is accepted — for a progress bar.
+     *
+     * "Accepted" is not always "committed": while offline (or mid-reconnect) a
+     * `mutation` resolves as soon as the write is durably **queued**, so a fully
+     * offline import reports completion with nothing yet applied server-side.
+     * Gate a migration's "done" state on connectivity, not just on this.
+     */
+    onProgress?: (progress: {
+      done: number;
+      total: number;
+    }) => void;
+    /** Routes every chunk to one shard's DO. */
+    shardKey?: string;
+    /** Build the mutation args for one chunk. Defaults to `{ rows: chunk }`. */
+    toArgs?: (chunk: ReadonlyArray<unknown>) => Record<string, unknown>;
+  }): Promise<{
+    chunks: number;
+    imported: number;
+  }>;
+  /**
+   * Read the cross-shard request distribution for a `.shardBy(...)` table —
+   * the feed the studio's `hot_shard` advisor lint consumes. Hits the
+   * admin-gated `POST /_lunora/admin/shard-traffic` endpoint, which fans the
+   * cheap per-shard `getMetrics` read out across every live shard and returns
+   * each shard's `{ shardKey, requests }` total (a failed shard surfaces with
+   * `requests: 0`). Requires the worker to be built with a `queryCoordinator`
+   * and `adminToken`, and this client's auth token to match; defaults any
+   * absent field so an older worker yields an empty-but-valid shape.
+   */
+  shardTraffic(table: string): Promise<ShardTrafficResult>;
+  /**
+   * List the functions queued via `runAfter` / `runAt`, soonest-due last
+   * (the worker returns them in storage order). Hits the admin-gated
+   * `/_lunora/admin/scheduled` endpoint, so the worker must be built with a
+   * `schedulerDO` namespace and `adminToken`, and this client's auth token
+   * must match. Powers `@lunora/studio`'s scheduled-jobs panel.
+   */
+  listScheduledJobs(): Promise<ScheduleRecord[]>;
+  /**
+   * Read the app-level workpool backlog that powers `@lunora/studio`'s SLO
+   * view: per-pool `{ name, queued, inFlight, maxConcurrency }` plus the
+   * app-wide `backlog` (total queued) and `inFlight` (total held slots) sums.
+   * Hits the admin-gated `GET /_lunora/admin/scheduled/status` endpoint, so the
+   * same preconditions as {@link listScheduledJobs} apply (a `schedulerDO`
+   * namespace + `adminToken` on the worker and a matching auth token here).
+   * Defaults any absent field so an older worker still yields a valid shape.
+   */
+  schedulerStatus(): Promise<SchedulerStatus>;
+  /** Cancel a pending scheduled job by id. Returns whether a job was removed. */
+  cancelScheduledJob(id: string): Promise<{
+    cancelled: boolean;
+  }>;
+  /**
+   * List the dead-letter jobs: schedules that exhausted their retry budget
+   * and were parked instead of dropped. These never appear in
+   * {@link listScheduledJobs} (their live header is gone), so this is the only
+   * way the studio surfaces a permanently-failed job. Hits the admin-gated
+   * `GET /_lunora/admin/scheduled/dead`; same preconditions as
+   * {@link listScheduledJobs}. Powers `@lunora/studio`'s dead-letter panel.
+   */
+  listDeadJobs(): Promise<ScheduleRecord[]>;
+  /**
+   * Resurrect a dead-letter job by id: it re-enters the schedule with a fresh
+   * retry budget and fires on the next drain. Returns whether a parked record
+   * matched. Hits the admin-gated `POST /_lunora/admin/scheduled/dead/retry`.
+   */
+  retryDeadJob(id: string): Promise<{
+    retried: boolean;
+  }>;
+  /**
+   * Permanently drop a dead-letter job by id (the operator has decided not to
+   * recover it). Returns whether a parked record was removed. Hits the
+   * admin-gated `POST /_lunora/admin/scheduled/dead/cancel`.
+   */
+  removeDeadJob(id: string): Promise<{
+    removed: boolean;
+  }>;
+  /**
+   * List a workflow's instances via the admin Workflows proxy
+   * (`/_lunora/admin/workflows/instances`) — the Cloudflare control-plane data
+   * the `Workflow` binding can't expose. Requires the worker to be built with a
+   * `workflowsClient` (Cloudflare account id + API token). When one isn't
+   * configured this does NOT reject: the proxy returns a `200 { configured:
+   * false }` sentinel, so the result resolves with `configured === false` and an
+   * empty `instances` list — callers should branch on that flag rather than
+   * try/catch. (The instance-detail / status endpoints still reject with 501.)
+   * `name` is the deployed workflow name.
+   */
+  listWorkflowInstances(options: {
+    name: string;
+    page?: number;
+    perPage?: number;
+    status?: WorkflowInstanceStatus;
+  }): Promise<WorkflowInstancePage>;
+  /** Read one workflow instance with its step timeline (`/_lunora/admin/workflows/instance`). */
+  getWorkflowInstance(options: {
+    id: string;
+    name: string;
+  }): Promise<WorkflowInstanceDetail>;
+  /** Pause / resume / terminate a workflow instance (`/_lunora/admin/workflows/status`). Needs an Edit-scoped Cloudflare token. */
+  setWorkflowInstanceStatus(options: {
+    action: WorkflowInstanceAction;
+    id: string;
+    name: string;
+  }): Promise<{
+    status: WorkflowInstanceStatus;
+  }>;
+  /**
+   * Subscribe to the live scheduled-jobs list over the SchedulerDO's admin
+   * WebSocket. `onJobs` fires with the full list on connect and on every
+   * change (schedule / cancel / alarm-fire). Reconnects with the client's
+   * configured backoff. Requires `wsToken` to be set to an admin credential
+   * (the browser can't send an `Authorization` header on a WS) — the master
+   * token, or preferably a {@link WsTokenProvider} minting the ephemeral
+   * sub-token so the master credential stays out of the URL. Returns an
+   * unsubscribe function that closes the socket and stops reconnecting.
+   */
+  subscribeScheduledJobs(onJobs: (jobs: ScheduleRecord[]) => void): Unsubscribe;
+  /**
+   * List the registered public functions (queries / mutations / actions) with
+   * their kinds. Hits the admin-gated `GET /_lunora/admin/functions` endpoint —
+   * the worker must be built with a `functions` registry and `adminToken`, and
+   * this client's auth token must match. Powers `@lunora/studio`'s function
+   * runner auto-discovery.
+   */
+  listFunctions(): Promise<FunctionDescriptor[]>;
+  /**
+   * List the code-defined cron triggers (the `cronJobs()` map injected on the
+   * worker), each flattened to its firing `cron` expression. Hits the
+   * admin-gated `GET /_lunora/admin/cron-jobs` endpoint — the worker must be
+   * built with a `cronJobs` map and `adminToken`, and this client's auth token
+   * must match. These are static (Cloudflare exposes no runtime cron
+   * introspection), so the studio renders them read-only alongside the dynamic
+   * scheduler jobs.
+   */
+  getCronJobs(): Promise<CronJobInfo[]>;
+  /**
+   * Manually fire one code-defined cron job by name — the same dispatch the
+   * scheduled trigger runs (dispatch the function, or start the durable
+   * workflow), on demand. Hits the admin-gated `POST /_lunora/admin/cron-jobs/run`
+   * endpoint; the worker must be built with a `cronJobs` map and `adminToken`,
+   * and this client's auth token must match. Resolves when the job has run (a
+   * function job's shard response is 2xx, or the workflow instance was created)
+   * and rejects with the dispatch error otherwise.
+   */
+  runCronJob(name: string): Promise<{
+    name: string;
+    ran: boolean;
+  }>;
+  /**
+   * Fetch the generated OpenAPI 3.1 document. Hits the admin-gated
+   * `GET /_lunora/admin/openapi` endpoint — the worker must be built with an
+   * `openApiSpec` and `adminToken`, and this client's auth token must match.
+   * Powers `@lunora/studio`'s API-reference (Scalar) view. When the worker has
+   * no spec wired, the endpoint still resolves with an empty-but-valid OpenAPI
+   * document (no `paths`), so callers can render a "not configured" state.
+   */
+  fetchOpenApi(): Promise<Record<string, unknown>>;
+  /**
+   * Fetch the generated OpenRPC 1.x document. Hits the admin-gated
+   * `GET /_lunora/admin/openrpc` endpoint — the worker must be built with an
+   * `openRpcSpec` and `adminToken`, and this client's auth token must match.
+   * OpenRPC is the RPC-native spec (a `methods` array over the JSON-RPC-shaped
+   * `POST /_lunora/rpc` transport); it documents the RPC functions only.
+   * Powers `@lunora/studio`'s OpenRPC API-reference view. When the worker has
+   * no spec wired, the endpoint still resolves with an empty-but-valid OpenRPC
+   * document (no `methods`), so callers can render a "not configured" state.
+   */
+  fetchOpenRpc(): Promise<Record<string, unknown>>;
+  /**
+   * List objects in the storage bucket, optionally under a `prefix` and from a
+   * pagination `cursor`. Hits the admin-gated `GET /_lunora/admin/storage`
+   * endpoint — the worker must be built with a `storageList` function and
+   * `adminToken`, and this client's auth token must match. Powers
+   * `@lunora/studio`'s file browser.
+   */
+  listStorageObjects(options?: {
+    bucket?: string;
+    cursor?: string;
+    limit?: number;
+    prefix?: string;
+  }): Promise<StorageListPage>;
+  /**
+   * Delete one object from the storage bucket by key. Hits the admin-gated
+   * `DELETE /_lunora/admin/storage?key=…` endpoint — the worker must be built
+   * with a `storageDelete` function and `adminToken`. Powers the studio file
+   * browser's per-row delete; resolves `{ deleted, key }`.
+   */
+  deleteStorageObject(key: string, options?: {
+    bucket?: string;
+  }): Promise<{
+    deleted: boolean;
+    key: string;
+  }>;
+  /**
+   * List the storage bucket names the worker exposes, for the studio file
+   * browser's bucket picker. Hits the admin-gated
+   * `GET /_lunora/admin/storage/buckets` endpoint — always resolves (an empty
+   * array when the worker configures no `storageBuckets`, i.e. single-bucket).
+   */
+  listStorageBuckets(): Promise<string[]>;
+  /**
+   * Upload one object to the storage bucket. Hits the admin-gated
+   * `PUT /_lunora/admin/storage?key=…` endpoint with the raw body and an
+   * optional `contentType` header — the worker must be built with a
+   * `storageUpload` function and `adminToken`. Powers the studio file
+   * browser's upload control; resolves `{ etag?, key }`.
+   */
+  uploadStorageObject(options: {
+    body: ArrayBuffer | Blob;
+    bucket?: string;
+    contentType?: string;
+    key: string;
+  }): Promise<{
+    etag?: string;
+    key: string;
+  }>;
+  /**
+   * Build a (signed or public) URL for one object. Hits the admin-gated
+   * `GET /_lunora/admin/storage/url?key=…` endpoint — the worker must be built
+   * with a `storageSignedUrl` function and `adminToken`. Powers the studio
+   * file browser's copy-URL action; resolves the URL string.
+   *
+   * `options.expiresInSeconds` requests a share-link lifetime, which is
+   * validated/clamped server-side. The options object mirrors the worker's
+   * `StorageSignedUrlFunction` options (a `password` / download-limit are noted
+   * as future fields there).
+   */
+  signedStorageUrl(key: string, options?: {
+    bucket?: string;
+    expiresInSeconds?: number;
+  }): Promise<string>;
+  /**
+   * List the `.global()` (D1-backed) tables with their row counts. Hits the
+   * admin-gated `GET /_lunora/admin/global/tables` endpoint — the worker must
+   * be built with a `globalIntrospector` and `adminToken`. Powers the data
+   * browser's global mode.
+   */
+  listGlobalTables(): Promise<GlobalTableInfo[]>;
+  /**
+   * Read a page of rows from one `.global()` table. `filters` AND-narrows the
+   * page to rows matching each `column = value` eq constraint — the drill-down a
+   * facet-value click applies; the array is JSON-encoded into the `filters`
+   * query param and the values are bound server-side.
+   */
+  readGlobalTablePage(options: {
+    filters?: GlobalFilterClause[];
+    limit?: number;
+    offset?: number;
+    table: string;
+  }): Promise<GlobalTablePage>;
+  /**
+   * Summarise the distinct values of one column in a `.global()` table over the
+   * active view (the same eq `filters` the browser is previewing) — the global
+   * twin of the shard browser's facet. Hits the admin-gated
+   * `GET /_lunora/admin/global/facet` endpoint; `column` is validated + bound
+   * server-side. Powers the global data browser's facet sidebar.
+   */
+  facetGlobalColumn(options: {
+    column: string;
+    filters?: GlobalFilterClause[];
+    limit?: number;
+    table: string;
+  }): Promise<GlobalFacetResult>;
+  /**
+   * List the schema's Vectorize indexes with their declared shape (table,
+   * field, dimensions, metric, metadata) and live stats (vector count,
+   * processing watermark) when the binding is reachable. Hits the admin-gated
+   * `GET /_lunora/admin/vector/indexes` endpoint — the worker must be built
+   * with a `vectorIntrospector` and `adminToken`. Powers the studio's vector
+   * browser. Vectorize can't enumerate indexes at runtime, so this list comes
+   * from the generated `LUNORA_VECTOR_INDEXES` registry.
+   */
+  listVectorIndexes(): Promise<VectorIndexSummary[]>;
+  /**
+   * Run a nearest-neighbour similarity query against one vector index: the
+   * worker embeds `text` via the index's embedder and returns the top matches.
+   * Hits the admin-gated `POST /_lunora/admin/vector/query` endpoint. Throws
+   * `VECTOR_QUERY_UNSUPPORTED` when the worker's introspector has no embedder
+   * wired (the index lists read-only).
+   */
+  queryVectorIndex(options: {
+    name: string;
+    text: string;
+    topK?: number;
+  }): Promise<VectorQueryMatch[]>;
+  /**
+   * Read one keyset-paginated page of the durable `ctx.log` archive that
+   * `pipelineLogSink` writes to R2. Server-side only — the worker holds the R2
+   * SQL credentials and runs the reader; the browser only sees the decoded
+   * `{ rows, nextCursor }`. Pass the previous page's `nextCursor` as
+   * `query.cursor` to page. Admin-gated. When the operator hasn't wired the
+   * archive, `adminFetch` throws a `LunoraClientError` with `.code ===
+   * "LOG_ARCHIVE_NOT_CONFIGURED"`, so a caller can render a "not configured"
+   * state rather than an error.
+   */
+  queryLogArchive(query?: PipelineLogQuery): Promise<PipelineLogPage>;
+  /**
+   * List the worker's registered Workers KV namespaces (binding names). Hits
+   * the admin-gated `GET /_lunora/admin/kv/namespaces` endpoint — the worker
+   * must be built with a `kvIntrospector` and `adminToken`. Powers the
+   * studio's KV browser.
+   */
+  listKvNamespaces(): Promise<KvNamespaceSummary[]>;
+  /**
+   * List keys in a KV namespace, optionally filtered by `prefix` and
+   * paginated via `cursor`. Hits the admin-gated
+   * `GET /_lunora/admin/kv/keys` endpoint.
+   */
+  listKvKeys(options: {
+    cursor?: string;
+    limit?: number;
+    namespace: string;
+    prefix?: string;
+  }): Promise<KvKeyListResult>;
+  /**
+   * Read a KV value (as text) and its metadata. Hits the admin-gated
+   * `GET /_lunora/admin/kv/value` endpoint. Returns `{ value: null, metadata: null }`
+   * when the key is absent.
+   */
+  getKvValue(options: {
+    key: string;
+    namespace: string;
+  }): Promise<KvValueResult>;
+  /**
+   * Write a string value to a KV namespace. Accepts an absolute `expiration`
+   * (Unix seconds) or a relative `expirationTtl`, plus optional `metadata` —
+   * re-send the loaded values on edit so a save preserves rather than clears
+   * them. Hits the admin-gated `PUT /_lunora/admin/kv/value` endpoint.
+   */
+  putKvValue(options: {
+    expiration?: number;
+    expirationTtl?: number;
+    key: string;
+    metadata?: unknown;
+    namespace: string;
+    value: string;
+  }): Promise<void>;
+  /**
+   * Delete a key from a KV namespace. No-op when the key is absent. Hits the
+   * admin-gated `DELETE /_lunora/admin/kv/value` endpoint.
+   */
+  deleteKvKey(options: {
+    key: string;
+    namespace: string;
+  }): Promise<void>;
+  /**
+   * List authenticated users, paged and optionally searched / filtered / sorted.
+   * Hits the admin-gated `GET /_lunora/admin/auth/users` endpoint — the worker
+   * must be built with an `authAdmin` and `adminToken`. Powers the studio's
+   * users dashboard.
+   */
+  listAuthUsers(options?: {
+    filterField?: string;
+    filterValue?: string;
+    limit?: number;
+    offset?: number;
+    search?: string;
+    searchField?: string;
+    sortBy?: string;
+    sortDirection?: "asc" | "desc";
+  }): Promise<AuthPage<AuthUser>>;
+  /**
+   * Create a user. Hits the admin-gated `POST /_lunora/admin/auth/users/create`
+   * endpoint (requires the worker's `authAdmin` to implement `createUser`).
+   * `data` carries any app-defined `user.additionalFields`.
+   */
+  createAuthUser(input: {
+    data?: Record<string, unknown>;
+    email: string;
+    name: string;
+    password?: string;
+    role?: string | string[];
+  }): Promise<AuthUser>;
+  /** Set a user's role (string, or array joined comma-wise server-side). */
+  setAuthUserRole(input: {
+    role: string | string[];
+    userId: string;
+  }): Promise<AuthUser>;
+  /** Ban a user. `expiresInSeconds` sets a temporary ban; omit it for a permanent one. Revokes the user's live sessions. */
+  banAuthUser(input: {
+    expiresInSeconds?: number;
+    reason?: string;
+    userId: string;
+  }): Promise<AuthUser>;
+  /** Lift a user's ban. */
+  unbanAuthUser(input: {
+    userId: string;
+  }): Promise<AuthUser>;
+  /** Set a user's password (admin override — no current-password challenge). */
+  setAuthUserPassword(input: {
+    newPassword: string;
+    userId: string;
+  }): Promise<void>;
+  /** Permanently delete a user and revoke their sessions. */
+  removeAuthUser(input: {
+    userId: string;
+  }): Promise<void>;
+  /**
+   * Mint an impersonation session for a user, returning its bearer `token`.
+   * The caller is responsible for using the token (e.g. setting the session
+   * cookie); the server performs no cookie round-trip.
+   */
+  impersonateAuthUser(input: {
+    userId: string;
+  }): Promise<AuthImpersonation>;
+  /** Revoke a single session by its id (force sign-out of one device). */
+  revokeAuthSession(input: {
+    sessionId: string;
+  }): Promise<void>;
+  /** Revoke every session for a user (force sign-out everywhere). */
+  revokeAuthUserSessions(input: {
+    userId: string;
+  }): Promise<void>;
+  /**
+   * Report which auth dashboard surfaces are available — derived server-side
+   * from the enabled better-auth plugins. The studio renders only the panels
+   * whose capability is `true`.
+   */
+  getAuthCapabilities(): Promise<AuthCapabilities>;
+  /** Update a user's fields (name/email/app-defined `additionalFields`). */
+  updateAuthUser(input: {
+    data: Record<string, unknown>;
+    userId: string;
+  }): Promise<AuthUser>;
+  /** List a user's linked accounts (credential / OAuth providers). Token material is stripped server-side. */
+  listAuthAccounts(input: {
+    userId: string;
+  }): Promise<Record<string, unknown>[]>;
+  /** Unlink a linked account from a user. */
+  unlinkAuthAccount(input: {
+    accountId: string;
+    userId: string;
+  }): Promise<void>;
+  /** List a user's registered passkeys (requires the passkey plugin). */
+  listAuthPasskeys(input: {
+    userId: string;
+  }): Promise<Record<string, unknown>[]>;
+  /** Delete a passkey by id (requires the passkey plugin). */
+  deleteAuthPasskey(input: {
+    passkeyId: string;
+  }): Promise<void>;
+  /** Disable two-factor auth for a user (requires the two-factor plugin). */
+  disableAuthTwoFactor(input: {
+    userId: string;
+  }): Promise<void>;
+  /** List organizations, paged (requires the organization plugin). */
+  listAuthOrganizations(options?: {
+    limit?: number;
+    offset?: number;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** List the members of an organization (requires the organization plugin). */
+  listAuthOrgMembers(input: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** List an organization's pending invitations (requires the organization plugin). */
+  listAuthOrgInvitations(input: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** Remove a member from an organization. */
+  removeAuthOrgMember(input: {
+    memberId: string;
+  }): Promise<void>;
+  /** Cancel a pending organization invitation. */
+  cancelAuthOrgInvitation(input: {
+    invitationId: string;
+  }): Promise<void>;
+  /**
+   * Report the deployment's auth configuration — enabled plugins, sign-in
+   * methods, user-settable create-user fields, organization sub-features
+   * (teams / roles), and session / rate-limit policy. Drives the config panel
+   * and the dynamic create-user form. Never carries a secret.
+   */
+  getAuthConfig(): Promise<AuthConfigInfo>;
+  /** Create an organization; optionally seed an `owner` member for `ownerId`. */
+  createAuthOrganization(input: {
+    logo?: string;
+    metadata?: Record<string, unknown>;
+    name: string;
+    ownerId?: string;
+    slug?: string;
+  }): Promise<Record<string, unknown>>;
+  /** Update an organization's name/slug/logo/metadata. */
+  updateAuthOrganization(input: {
+    logo?: string;
+    metadata?: Record<string, unknown>;
+    name?: string;
+    organizationId: string;
+    slug?: string;
+  }): Promise<Record<string, unknown>>;
+  /** Delete an organization and cascade its members, invitations, teams, and custom roles. */
+  deleteAuthOrganization(input: {
+    organizationId: string;
+  }): Promise<void>;
+  /** Directly add an existing user to an organization (no invitation/acceptance). */
+  addAuthOrgMember(input: {
+    organizationId: string;
+    role?: string;
+    userId: string;
+  }): Promise<Record<string, unknown>>;
+  /** Create a pending email invitation to an organization. */
+  inviteAuthOrgMember(input: {
+    email: string;
+    inviterId?: string;
+    organizationId: string;
+    role?: string;
+  }): Promise<Record<string, unknown>>;
+  /** Change a member's role. */
+  setAuthOrgMemberRole(input: {
+    memberId: string;
+    role: string | string[];
+  }): Promise<Record<string, unknown>>;
+  /** List an organization's teams (requires the organization plugin with teams enabled). */
+  listAuthOrgTeams(input: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** Create a team under an organization. */
+  createAuthOrgTeam(input: {
+    name: string;
+    organizationId: string;
+  }): Promise<Record<string, unknown>>;
+  /** Rename a team. */
+  updateAuthOrgTeam(input: {
+    name: string;
+    teamId: string;
+  }): Promise<Record<string, unknown>>;
+  /** Delete a team and its memberships. */
+  removeAuthOrgTeam(input: {
+    teamId: string;
+  }): Promise<void>;
+  /** List a team's members. */
+  listAuthOrgTeamMembers(input: {
+    limit?: number;
+    offset?: number;
+    teamId: string;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** Add a user to a team. */
+  addAuthOrgTeamMember(input: {
+    teamId: string;
+    userId: string;
+  }): Promise<Record<string, unknown>>;
+  /** Remove a member from a team. */
+  removeAuthOrgTeamMember(input: {
+    teamMemberId: string;
+  }): Promise<void>;
+  /** List an organization's custom roles (requires the organization plugin with dynamic access control). */
+  listAuthOrgRoles(input: {
+    limit?: number;
+    offset?: number;
+    organizationId: string;
+  }): Promise<AuthPage<Record<string, unknown>>>;
+  /** Create a custom org role with a permission grant (a `resource -> actions[]` map). */
+  createAuthOrgRole(input: {
+    organizationId: string;
+    permission: Record<string, string[]>;
+    role: string;
+  }): Promise<Record<string, unknown>>;
+  /** Replace a custom org role's permission grant. */
+  updateAuthOrgRole(input: {
+    permission: Record<string, string[]>;
+    roleId: string;
+  }): Promise<Record<string, unknown>>;
+  /** Delete a custom org role. */
+  deleteAuthOrgRole(input: {
+    roleId: string;
+  }): Promise<void>;
+  /** List auth sessions, paged and optionally filtered to one user. */
+  listAuthSessions(options?: {
+    limit?: number;
+    offset?: number;
+    userId?: string;
+  }): Promise<AuthPage<AuthSession>>;
+  subscribe<F extends FunctionReference>(function_: F, args: ArgsOf<F>, callback: (data: ReturnOf<F>) => void, options?: {
+    onCheckpoint?: (watermark: SyncWatermark) => void;
+    onError?: SubscriptionErrorCallback;
+    shardKey?: string;
+  }): Unsubscribe;
+  /**
+   * Subscribe to a declarative **shape** — server-side partial replication
+   * scoped by `shardBy` + the shape's predicate + RLS. The parallel to
+   * {@link subscribe} for the poke protocol: the client sends the shape *name* +
+   * validated `args` (never a `where` the client could forge), the server seeds
+   * the current membership as an insert-poke and streams live membership diffs.
+   * Each applied poke materializes the shape's rowset and invokes `callback`.
+   *
+   * Unlike {@link subscribe}, shape subscriptions are NOT deduped by
+   * (name, args): the server resolves them under the socket's verified identity,
+   * so every call gets its own id + view. The returned function unsubscribes.
+   */
+  subscribeShape(shape: {
+    args?: Record<string, unknown>;
+    name: string;
+  }, callback: ShapeCallback, options?: {
+    onCheckpoint?: (watermark: SyncWatermark) => void;
+    onError?: SubscriptionErrorCallback;
+    shardKey?: string;
+  }): Unsubscribe;
+  /**
+   * Open a streaming query. The function reference must be a
+   * `kind:"stream"` registration (built with `c.query.input(...).stream(...)`);
+   * the type constraint catches accidental use of a query/mutation/action
+   * reference at compile time. The returned iterable yields one element per
+   * chunk frame the server pushes, terminating when the server sends
+   * `complete` or the consumer calls `.cancel()`. Errors arrive as a
+   * rejection on the next `next()`.
+   *
+   * Streams ride the same WS as subscriptions and share the unsubscribe
+   * channel: cancelling sends `{type:"unsubscribe", id}` with the stream id,
+   * which the DO recognises as an abort signal for the in-flight iterator.
+   *
+   * Stream-start frames buffered while the socket is (re)connecting are
+   * capped at {@link MAX_PENDING_STREAMS} per connection — overflowing the
+   * cap drops the oldest queued frame (and fails its consumer) so a stuck
+   * reconnect can't OOM the page.
+   */
+  stream<F extends FunctionReference<"stream">>(function_: F, args: ArgsOf<F>, options?: {
+    maxBuffer?: number;
+    shardKey?: string;
+  }): StreamIterable<ReturnOf<F>>;
+  /**
+   * Open a typed **HTTP-SSE route stream** (`httpRoute.&lt;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;
+  /**
+   * Persist a mutation that can't go out on the wire right now (offline, or
+   * mid-reconnect after a prior connect). The optimistic update has already
+   * been applied by `mutation`; this only chooses the durable write path and
+   * rolls the optimistic write back if persistence is rejected.
+   *
+   * Two paths: when an `outbox` sink is wired (the `@lunora/db` executor) it
+   * owns persistence + at-least-once replay, so we delegate and return
+   * optimistically (confirmation rides the synced view). Otherwise the
+   * built-in `OfflineQueue` resolves/rejects the returned promise on replay.
+   */
+  private enqueueOfflineMutation;
+  /**
+   * Restore offline mutations persisted in a prior session and open a socket
+   * for each shard they target so they flush once the WS reconnects. Failures
+   * are swallowed — a broken durable store must not stop the client booting.
+   */
+  private hydratePersistedQueue;
+  /**
+   * Re-queue the durable offline writes — but only as the multi-tab LEADER. The
+   * persisted queue is shared across a profile's tabs; without coordination
+   * every tab would re-queue and replay the same writes (correct only because
+   * the server dedups by idempotency key, but wasteful + racy). A Web Lock makes
+   * exactly one tab hydrate; it holds the lock for its lifetime, so when it
+   * closes another tab acquires the lock and takes over. Falls back to
+   * unconditional hydration where Web Locks are unavailable (React Native, older
+   * browsers, SSR) — single-context there, so no coordination is needed.
+   */
+  private hydrateAsOutboxLeader;
+  /**
+   * Load every cached query into {@link hydratedQueryCache} so the next
+   * `subscribe()` for each key seeds its initial value off disk. A
+   * subscription created before this resolves simply misses the cache (it
+   * gets a live snapshot as before); the gate at seed time also drops any
+   * entry whose stamped identity no longer matches the current one.
+   */
+  private hydrateQueryCache;
+  /**
+   * Consume the hydrated read-cache entry for a key (if any), gated on
+   * identity. The entry is removed whether or not it matches — the cache only
+   * ever seeds a subscription's first value. A mismatch (the cache was written
+   * under a different identity) yields `undefined` so a signed-out cache never
+   * leaks into a new session.
+   */
+  private takeHydratedCache;
+  /**
+   * Queue a coalesced read-cache write for a subscription's current value.
+   * Latest-wins per key; flushed on a short debounce so a delta burst writes
+   * once. No-op when the read cache is disabled or the value is undefined
+   * (nothing to render offline).
+   */
+  private persistQueryValue;
+  /** Drain {@link pendingCacheWrites} to the durable store. */
+  private flushQueryCacheWrites;
+  /** Derive the aggregate status from the per-shard socket states. */
+  private computeStatus;
+  /** Recompute the aggregate status and notify listeners if it changed. */
+  private emitConnectionStatus;
+  /**
+   * Build a {@link MutationSettledEvent} from a queued entry and emit it on the
+   * {@link onMutationSettled} channel. `item.id` is always assigned by the time
+   * a write settles (`enqueue`/`hydrate` guarantee it), so the `?? ""` fallback
+   * is unreachable — present only to satisfy the optional queue-id type.
+   */
+  private emitItemSettled;
+  /**
+   * Apply an optimistic update to the subscription that matches the mutation's
+   * `(functionRef, args, shardKey)` triple, returning the rollback callbacks to
+   * invoke if the mutation later fails.
+   *
+   * The registry is already indexed by exactly this triple via
+   * `SubscriptionRegistry.key`, so at most one subscription can match. A direct
+   * O(1) keyed lookup replaces the former O(N) linear scan over all subscriptions.
+   *
+   * `shardKey` normalization: both `undefined` and `""` map to the empty string
+   * inside `SubscriptionRegistry.key` (via `?? ""`), so a mutation fired without
+   * a shardKey correctly matches a subscription registered without one regardless
+   * of whether the caller passed `undefined` or omitted the field.
+   */
+  private applyOptimisticUpdates;
+  /**
+   * Run a Convex-parity `optimisticUpdate` callback against a localStore bound
+   * to the live subscription registry. Each `setQuery` registers a constant
+   * optimistic LAYER on its target subscription (via the same engine the
+   * per-call `optimistic` path uses), so the multi-query patch rebases onto
+   * incoming deltas and drops gaplessly on its commit cursor — its `confirm` /
+   * `rollback` closures are appended to the mutation's settle lists. A throwing
+   * callback unwinds its own partial writes — LIFO over just the rollbacks it
+   * produced — and is swallowed, so a buggy optimistic update can never fail the
+   * mutation or leave a partial patch live.
+   */
+  private applyOptimisticUpdate;
+  private getConnection;
+  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 the shard socket and wire its lifecycle handlers. The connection must already be in the `connecting` state. */
+  private openSocket;
+  private handleDisconnect;
+  /**
+   * Begin the keepalive heartbeat on an open connection. Each tick sends a
+   * {@link WS_KEEPALIVE_PING} text frame the server answers from its
+   * hibernation auto-response without waking the DO. A no-op when the
+   * heartbeat is disabled (an interval of zero or less); idempotent — any
+   * existing timer is cleared first so a reconnect can't leak intervals.
+   */
+  private startHeartbeat;
+  /** Clear a connection's keepalive timer, if any. Safe to call repeatedly. */
+  private stopHeartbeat;
+  /** Mark every subscription bound to `shardKey` as needing a fresh ack. */
+  private markShardPendingAck;
+  private sendSubscribeIfOpen;
+  private sendShapeSubscribeIfOpen;
+  private handleServerMessage;
+  private handleErrorMessage;
+  private handlePokeStart;
+  private handlePokePart;
+  private handlePokeEnd;
+  /** 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;
+  private handleCompleteMessage;
+  private unpersist;
+  /**
+   * Stable, non-reversible fingerprint of the current auth identity used to
+   * stamp queued offline writes. `null` (signed out) is its own identity and
+   * never matches a bearer-token fingerprint. The raw token is never stored;
+   * a length-prefixed FNV-1a hash is enough to detect an identity *change*
+   * without keeping the credential around in the queue map.
+   */
+  private identityFingerprint;
+  /**
+   * Stable token-hash fingerprint of a bearer token (the `&lt;len>:&lt;fnv>:&lt;djb2>`
+   * format a token-stamped queued write carries). Extracted so the replay gate
+   * can recompute the hash of the current credential and recognise a write
+   * stamped under it — even after the fingerprint was relabelled to a subject.
+   *
+   * Two independent 32-bit passes (FNV-1a + djb2) give a ~64-bit digest, so
+   * two distinct equal-length tokens are astronomically unlikely to share a
+   * fingerprint. A single 32-bit hash collides ~1-in-4e9 per equal-length
+   * pair — enough that, on a shared device, user B could hydrate A's cached
+   * reads. Different algorithms (not the same FNV with a different seed, which
+   * would be affine-related) keep the two passes genuinely independent.
+   * Still synchronous (no crypto) and stable across surrogate pairs.
+   */
+  private hashToken;
+  /**
+   * True when `stamped` is a token-hash of the SAME credential still held now,
+   * even though the live identity has since been relabelled to a subject. Covers
+   * `setAuthToken(token, userId)` where the subject resolved a tick after the
+   * token was set: a write persisted (or requeued) under the token hash must
+   * still replay — the credential never changed, only its label — instead of
+   * being dropped as an identity mismatch. This is the durable counterpart to
+   * {@link restampQueuedIdentity}, which only relabels the in-memory live stamp
+   * (consumed on the first flush) and never touches `item.identity` or the
+   * persisted record, so a reload or a transient-failure requeue would otherwise
+   * fall back to the stale token-hash and wrongly reject the same user's write.
+   */
+  private isSameCredentialUnderTokenHash;
+  /**
+   * Drain every in-memory offline write and reject it because the auth
+   * identity changed. Durable entries are also dropped from persistence so a
+   * later `hydrate` can't resurrect another user's writes. Stamps are cleared
+   * alongside. Persisted entries restored without a live awaiter still get
+   * unpersisted here.
+   */
+  private rejectQueuedForIdentityChange;
+  /**
+   * Migrate every live identity stamp from `from` to `to` — used when the auth
+   * identity label changes but the underlying credential (token) does NOT, e.g.
+   * the user id resolves a tick after the token was set. The in-memory
+   * `queuedIdentities` map is the flush-time source of truth, so re-stamping it
+   * keeps the in-flight writes replayable under the new (more stable) identity
+   * instead of the flush guard discarding them as a mismatch.
+   */
+  private restampQueuedIdentity;
+  /**
+   * 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;
+  private flushOfflineQueue;
+  /**
+   * Partition already-gated writes into the encodable ones (returned) and reject
+   * the rest terminally. A write whose args can't be wire-encoded (e.g. a RegExp
+   * or class instance in a `v.any()` field) can NEVER replay — the codec failure
+   * is deterministic, not transient. Rejecting here is essential: otherwise
+   * `encodeWire` throws mid-flush, is classified as transient (a codec error has
+   * no `.code`), and re-queues forever — a silent hang where the caller's Promise
+   * never settles and the optimistic write never rolls back. Encoding is cheap;
+   * the flush is the slow reconnect path.
+   */
+  private encodableOrSettleTerminal;
+  /**
+   * Identity guard for one queued write about to replay: a write stamped under
+   * one identity must never replay under another. The live `queuedIdentities`
+   * map is the source of truth for the current session; a hydrated write whose
+   * id isn't in the map falls back to the stamp persisted with the record
+   * (`item.identity`), so a reload can't replay another user's queued writes.
+   * Only legacy records (persisted before stamps were durable —
+   * `item.identity === undefined`) replay under whatever identity is current.
+   *
+   * `Map.get` returns `undefined` for unstamped/hydrated ids and `item.identity`
+   * is `undefined` for legacy records; a persisted `null` (queued while signed
+   * out) is a real value that must not collapse into `undefined` — hence the
+   * explicit `=== undefined` check rather than `??`. Returns `true` when the
+   * write may replay; otherwise settles it `OFFLINE_IDENTITY_CHANGED` and returns
+   * `false`. Either way the live stamp is consumed.
+   */
+  private passesReplayIdentityGate;
+  /** Settle a write that replayed successfully: confirm its optimistic layer against the echoed commit cursor BEFORE resolving, so the gapless drop is in place when the awaiter (and any confirming frame) observes the settle. */
+  private settleReplaySuccess;
+  /** Settle a write the server reached a coded verdict on: replaying would re-trigger the same failure (a poison-message loop), so drop it. */
+  private settleReplayTerminal;
+  /**
+   * Replay already-identity-gated writes one at a time on the single-call `/rpc`
+   * path, preserving FIFO order (parallel `.then()` chains would race the
+   * ordering callers depend on). Each replays under its stable `mutationId` so
+   * the server dedups a write it already committed (exactly-once). A coded error
+   * is a server verdict (drop it); a codeless (transport/transient) failure stops
+   * the flush and re-queues this write and every unreplayed one for the next
+   * reconnect — their callers stay pending, and the identity guard re-applies on
+   * retry via each record's persisted stamp.
+   */
+  private replaySequential;
+  /**
+   * Coalesce already-identity-gated writes for a single shard into ONE
+   * `/_lunora/rpc-batch` round trip (plan 088 follow-on). The worker forwards
+   * them to the shard DO, which replays each through its single-call dispatch, so
+   * per-entry `mutationId` idempotency and in-order application are inherited from
+   * the proven path. Per-slot demux mirrors {@link replaySequential}'s
+   * classification: success confirms the optimistic layer against the echoed
+   * `commitCursor`; a coded application verdict is terminal; a transient shard
+   * failure (`SHARD_UNAVAILABLE`/`SHARD_ERROR`), a missing slot, or a whole-batch
+   * transport failure re-queues for the next reconnect (never dropping a durable
+   * write). A whole-batch coded rejection (bad request / authorization denial the
+   * server reached a verdict on) is terminal for every entry.
+   *
+   * Returns the writes that must be re-queued and `stop` — `true` when the whole
+   * chunk failed at the transport level, so the caller leaves later chunks queued
+   * rather than sending on. The caller re-queues once, in order, so requeuing is
+   * NOT done here.
+   */
+  private replayBatched;
+  /**
+   * Demux a `/_lunora/rpc-batch` reply back onto the queued writes it replayed,
+   * in input order. Each slot's envelope classifies its write the same way
+   * {@link replaySequential} does: a success confirms the optimistic layer
+   * against the echoed `commitCursor`; a coded application verdict is terminal;
+   * a transient shard failure ({@link TRANSIENT_BATCH_ERROR_CODES}) or a slot the
+   * server never returned is returned for the caller to re-queue.
+   * @returns the writes that must be re-queued (transient slots), in input order
+   */
+  private settleReplayBatchSlots;
+}
+export { SchedulerStatus as $, ArgsOf as A, BookmarkStorage as B, CONFLICT_ERROR_CODE as C, DEFAULT_MAX_BUFFER as D, LunoraErrorCode as E, FunctionReference as F, GlobalFacetResult as G, HttpStreamRef as H, MutationSettledEvent as I, OptimisticLocalStore as J, OptimisticUpdate as K, LunoraClient as L, MutationCallOptions as M, OutboxMutation as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, OutboxSink as T, User as U, PersistedMutation as V, RowOp as W, RpcEnvelope as X, RpcResponseBody as Y, ScheduleRecord as Z, SchedulerPoolStatus as _, Unsubscribe as a, ServerMessage as a0, ServerPokeEndMessage as a1, ServerPokePartMessage as a2, ServerPokeStartMessage as a3, ShardTrafficEntry as a4, ShardTrafficResult as a5, StorageListPage as a6, StorageObject as a7, StreamHandle as a8, SubscriptionCallback as a9, SubscriptionRegistry as aa, SubscriptionState as ab, SyncWatermark as ac, WorkflowInstanceAction as ad, WorkflowInstanceDetail as ae, WorkflowInstancePage as af, WorkflowInstanceStatus as ag, WorkflowInstanceSummary as ah, WorkflowStepDetail as ai, WsTokenProvider as aj, createClientQuery as ak, createLocalStore as al, createStream as am, getErrorCode as an, getRetryAfterMs as ao, isConflictError as ap, isForbiddenError as aq, isRateLimitedError as ar, isUnauthorizedError as as, SubscriptionErrorCallback as b, PersistenceAdapter as c, HttpStreamArgsOf as d, HttpStreamChunkOf as e, StreamIterable as f, ReconnectOptions as g, BatchSlot as h, CachedQuery as i, ClientDebugShard as j, ClientDebugSnapshot as k, ClientDebugSubscription as l, ClientMessage as m, ClientQueryRef as n, ClientShapeSubscribeMessage as o, ClientShapeUnsubscribeMessage as p, ConnectionStatus as q, FunctionArgumentDescriptor as r, FunctionDescriptor as s, GlobalFacetValue as t, GlobalFilterClause as u, GlobalTableInfo as v, GlobalTablePage as w, HttpStreamCallArgs as x, LunoraClientError as y, LunoraClientOptions as z };