@lunora/client 1.0.0-alpha.25 → 1.0.0-alpha.250

package/dist/index.d.mts

@@ -1,7 +1,193 @@
-import { c as PersistenceAdapter, B as BookmarkStorage, S as SubscriptionError, H as HttpStreamRef, d as HttpStreamArgsOf, e as HttpStreamChunkOf, f as StreamIterable, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, g as ReconnectOptions, L as LunoraClient } from "./packem_shared/lunora-client.d-C4ud8bej.mjs";
-export { type h as BatchSlot, C as CONFLICT_ERROR_CODE, type i as CachedQuery, type j as ClientMessage, type k as ClientQueryRef, type l as ClientShapeSubscribeMessage, type m as ClientShapeUnsubscribeMessage, type n as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type o as FunctionArgumentDescriptor, type p as FunctionDescriptor, type G as GlobalFacetResult, type q as GlobalFacetValue, type r as GlobalFilterClause, type s as GlobalTableInfo, type t as GlobalTablePage, type u as HttpStreamCallArgs, type v as LunoraClientError, type w as LunoraClientOptions, type x as LunoraErrorCode, type y as MutationSettledEvent, type z as OptimisticLocalStore, type E as OptimisticUpdate, type I as OutboxMutation, type J as OutboxSink, type K as PersistedMutation, type P as Preloaded, type N as RowOp, type T as RpcEnvelope, type V as RpcResponseBody, type W as ScheduleRecord, type X as SchedulerPoolStatus, type Y as SchedulerStatus, type Z as ServerMessage, type _ as ServerPokeEndMessage, type $ as ServerPokePartMessage, type a0 as ServerPokeStartMessage, type a1 as ShardTrafficEntry, type a2 as ShardTrafficResult, type a3 as StorageListPage, type a4 as StorageObject, type a5 as StreamHandle, type a6 as SubscriptionCallback, type b as SubscriptionErrorCallback, a7 as SubscriptionRegistry, type a8 as SubscriptionState, type a9 as SyncWatermark, type a as Unsubscribe, type U as User, type aa as WorkflowInstanceAction, type ab as WorkflowInstanceDetail, type ac as WorkflowInstancePage, type ad as WorkflowInstanceStatus, type ae as WorkflowInstanceSummary, type af as WorkflowStepDetail, type ag as WsTokenProvider, ah as createClientQuery, ai as createLocalStore, aj as createStream, ak as getErrorCode, al as getRetryAfterMs, am as isConflictError, an as isForbiddenError, ao as isRateLimitedError, ap as isUnauthorizedError } from "./packem_shared/lunora-client.d-C4ud8bej.mjs";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-Dvk8zg6m.mjs";
-export type { AuthCapabilities, AuthConfigInfo, AuthImpersonation, AuthPage, AuthSession, AuthUser, AuthUserFieldSpec, CronJobInfo, KvKeyEntry, KvKeyListResult, KvNamespaceSummary, KvValueResult, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
+import { R as ReconnectOptions, c as PersistenceAdapter, Q as QueryCacheAdapter, B as BookmarkStorage, C as ConnectionStatus, S as SubscriptionError, H as HttpStreamRef, d as HttpStreamArgsOf, e as HttpStreamChunkOf, f as StreamIterable, O as OfflineQueueOptions, L as LunoraClient } from "./packem_shared/lunora-client.d-DtTKDhtw.mjs";
+export { type A as ActionCallOptions, type g as BatchSlot, type h as CachedQuery, type i as ClientDebugShard, type j as ClientDebugSnapshot, type k as ClientDebugSubscription, type l as ClientMessage, type m as ClientQueryRef, type n as ClientShapeSubscribeMessage, type o as ClientShapeUnsubscribeMessage, D as DEFAULT_MAX_BUFFER, type F as FunctionArgumentDescriptor, type p as FunctionDescriptor, type G as GlobalFacetResult, type q as GlobalFacetValue, type r as GlobalFilterClause, type s as GlobalTableInfo, type t as GlobalTablePage, type u as HttpStreamCallArgs, type v as LunoraClientError, type w as LunoraClientOptions, type M as MutationCallOptions, type x as MutationSettledEvent, type y as OnlineOnlyOption, type z as OptimisticLocalStore, type E as OptimisticUpdate, type I as OutboxMutation, type J as OutboxSink, type K as PersistedMutation, type P as Preloaded, type N as ReplayCredential, type T as ReplayIdentityVerdict, type V as RoomRef, type W as RowOp, type X as RpcEnvelope, type Y as RpcResponseBody, type Z as ScheduleRecord, type _ as ScheduleRetryPolicy, type $ as SchedulerPoolStatus, type a0 as SchedulerStatus, type a1 as ServerMessage, type a2 as ServerPokeEndMessage, type a3 as ServerPokePartMessage, type a4 as ServerPokeStartMessage, type a5 as ShardTrafficEntry, type a6 as ShardTrafficResult, type a7 as StorageListPage, type a8 as StorageObject, type a9 as StoredQuery, type aa as StreamHandle, type ab as SubscriptionCallback, type b as SubscriptionErrorCallback, ac as SubscriptionRegistry, type ad as SubscriptionState, type ae as SyncStatus, type af as SyncWatermark, type a as Unsubscribe, type U as User, type ag as WorkflowInstanceAction, type ah as WorkflowInstanceDetail, type ai as WorkflowInstancePage, type aj as WorkflowInstanceStatus, type ak as WorkflowInstanceSummary, type al as WorkflowStepDetail, type am as WsTokenProvider, an as createClientQuery, ao as createLocalStore, ap as createStream } from "./packem_shared/lunora-client.d-DtTKDhtw.mjs";
+import { LunoraError, LunoraErrorCode } from '@lunora/errors';
+export type { LunoraErrorCode } from '@lunora/errors';
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-CT_9YaL9.mjs";
+import { F as FunctionReference } from "./packem_shared/function-reference.d-Br_hsKje.mjs";
+export type { A as ArgsOf, R as ReturnOf } from "./packem_shared/function-reference.d-Br_hsKje.mjs";
+export type { AuthCapabilities, AuthConfigInfo, AuthImpersonation, AuthPage, AuthSession, AuthUser, AuthUserFieldSpec, CronJobInfo, KvKeyEntry, KvKeyListResult, KvNamespaceSummary, KvValueResult, PipelineLogColumnMap, PipelineLogCursor, PipelineLogField, PipelineLogPage, PipelineLogQuery, PipelineLogRow, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
+/**
+ * A failure the SERVER reached no verdict on: the response carried no
+ * `{ error }` envelope at all — no `fetch` implementation, a non-JSON body from
+ * a proxy, a bare 5xx gateway page.
+ *
+ * The distinction matters because a durable write must be re-queued rather than
+ * dropped, and `code` cannot carry it: these arrive as `INTERNAL`, which is also
+ * what a server that DID reach a verdict sends. It used to be a `Symbol` stamped
+ * on with `Object.assign` and read back through a `Record<symbol, unknown>`
+ * cast, so the one classifier that knew the convention was the only reader that
+ * could ever see it. As a kind, every reader can: `error instanceof
+ * TransportError`.
+ *
+ * Still `INTERNAL` on the wire, so nothing that switches on `code` changes.
+ *
+ * `data` carries the structured payload such an error can still have — the
+ * `{ retryAfterMs }` a `Retry-After` on the unreadable response named, which
+ * {@link getRetryAfterMs} reads back and the outbox paces its retry on.
+ */
+declare class TransportError extends LunoraError {
+  constructor(message: string, data?: unknown);
+}
+/** 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 a code string absent from the catalog (an app-minted code
+ * passed to `LunoraError` reads 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;
+/**
+ * Whether a durable replay's failure refused the credential rather than the
+ * write (see {@link AUTH_REPLAY_ERROR_CODES}) — a durable outbox holds such a
+ * write for the next attempt instead of dropping it.
+ */
+declare const isAuthReplayFailure: (error: unknown) => boolean;
+/**
+ * Exponential backoff calculator with optional jitter.
+ *
+ * `next()` doubles the delay each call up to `maxDelayMs`. When `jitter` is
+ * enabled the returned value is randomized in `[delay/2, delay]` so a fleet
+ * of clients reconnecting at the same time spread out their retries.
+ */
+interface ReconnectCalculator {
+  /** Returns the delay to wait before the next reconnect attempt. */
+  next: () => number;
+  /** Resets the backoff to the initial delay (call on successful reconnect). */
+  reset: () => void;
+}
+declare const createReconnect: (options?: ReconnectOptions, random?: () => number) => ReconnectCalculator;
+/**
+ * Optimistic-reconcile logic shared by every `@lunora/*` framework adapter's
+ * agent-chat surface (`@lunora/react` `useAgentChat`, plus the `@lunora/vue`,
+ * `@lunora/solid`, `@lunora/svelte`, and `@lunora/angular` counterparts). The
+ * adapters keep only their framework-specific state plumbing
+ * (`useState` / `.value` / `.set()` / a store) and delegate the pure merge decision
+ * here, so the heuristic lives — and is tested — in exactly one place.
+ */
+/**
+ * The durable-message shape the reconcile reads: a structural subset of each
+ * adapter's `AgentChatMessage` (itself a client-safe mirror of `@lunora/agent`'s
+ * `AgentMessageRow`). Only `content`, `role`, and the per-thread-monotonic `seq` are
+ * consulted; adapters pass their fuller row type, which is assignable to this.
+ */
+interface ReconcileDurableMessage {
+  content: string;
+  role: "assistant" | "system" | "tool" | "user";
+  seq: number;
+}
+/**
+ * A local optimistic user turn awaiting server acknowledgement. `id` is a
+ * client-generated handle the adapter uses to roll the row back on a failed send;
+ * the reconcile itself reads only `content` and `maxDurableSeqAtSend`.
+ */
+interface OptimisticMessage {
+  content: string;
+  id: number;
+  /**
+   * The highest durable `seq` present when this row was sent. The reconcile
+   * retires the row when a durable `user` row with matching `content` lands at a
+   * STRICTLY GREATER `seq` (i.e. after the send) — window-independent because
+   * `seq` is monotonic, not a positional count. Also the age baseline for the
+   * {@link RETIRE_AFTER_DURABLE_SEQ_ADVANCE} fallback.
+   *
+   * `seq` is monotonic PER THREAD, not globally (`@lunora/agent` assigns it from
+   * the thread's own message count), so a baseline captured in one thread is
+   * meaningless in another: an optimistic row carried across a thread switch can
+   * never be retired by the new thread's history until its `seq` happens to pass
+   * the old thread's. Adapters therefore drop their optimistic rows whenever the
+   * resolved thread key changes.
+   */
+  maxDurableSeqAtSend: number;
+}
+/**
+ * The highest `seq` across `messages`, or `-1` when empty. Used both to capture an
+ * optimistic row's `maxDurableSeqAtSend` at send time and to base the synthetic
+ * seqs of rendered optimistic rows above the highest real durable seq (not just
+ * `messages.length`, which under-counts when durable rows have gaps), so a
+ * placeholder seq never collides with a real one.
+ */
+declare const maxSeq: (messages: ReadonlyArray<{
+  seq: number;
+}>) => number;
+/**
+ * Secondary, windowed fallback: retire a pending optimistic row once the durable
+ * history's highest `seq` has advanced at least this far past the value seen at
+ * send, even though no matching-content user row is currently visible to claim it.
+ * This covers the pathological "identical content already present at send time"
+ * case, where no user row with a STRICTLY GREATER `seq` than the send-time max will
+ * ever appear for the primary content match to consume (e.g. the acknowledging row
+ * was evicted by a bounded `limit` before reconcile could see it). `seq` is monotonic
+ * within the thread, so it keeps climbing even when the visible user-row COUNT does not.
+ *
+ * The `2` is a heuristic threshold, NOT an invariant about turn shape. It is
+ * tempting to read it as "one turn == a user row and an assistant row (+2)", but
+ * `@lunora/agent`'s tool-loop turns can persist MANY rows, and an ERRORED turn
+ * persists only the user row (+1). Those non-(+2) turns are retired by the PRIMARY
+ * seq-based content match below (which sees the user row land at a greater `seq`),
+ * never by this count-based fallback. The fully robust fix is a server-echoed
+ * correlation id on each persisted user row (deferred; no plan filed).
+ *
+ * KNOWN LIMITATION (inherent to a client-only heuristic): on an ownerless /
+ * `instanceId`-less thread a FOREIGN writer that advances `seq` by >= 2 between this
+ * row's send and its own acknowledgement can trip this fallback and retire the row a
+ * beat early. The correlation id closes that gap; until then it is the accepted
+ * residual edge.
+ */
+declare const RETIRE_AFTER_DURABLE_SEQ_ADVANCE = 2;
+/**
+ * Drop the optimistic user turns the durable history has now caught up on. Pure —
+ * it reads only the two arrays plus values captured on each pending row at send
+ * time (no clock, no state mutation), so it is safe to run in render.
+ *
+ * The primary retire condition: a durable `user` row with the same `content` exists
+ * whose `seq` is STRICTLY GREATER than the row's `maxDurableSeqAtSend` — i.e. a user
+ * row that landed AFTER the send. This is window-independent (it matches on monotonic
+ * `seq`, not a positional count), so it retires the normal turn AND an errored
+ * single-row (+1) turn even under a saturated, sliding `limit`. Each durable row is
+ * consumed at most once (the `consumed` set), so repeated identical prompts sent
+ * back-to-back each wait for their OWN durable row instead of collapsing onto one.
+ *
+ * Failing that, the {@link RETIRE_AFTER_DURABLE_SEQ_ADVANCE} windowed fallback fires
+ * (see its doc) for the "identical content already present" pathological case.
+ */
+declare const reconcileOptimistic: (optimistic: ReadonlyArray<OptimisticMessage>, durable: ReadonlyArray<ReconcileDurableMessage>) => OptimisticMessage[];
 /**
  * The slice of React Native's `AsyncStorage` (or any async key/value store —
  * Expo `SecureStore`, a wrapped `localForage`, an in-memory map in tests) this
@@ -22,17 +208,90 @@ interface AsyncStoragePersistenceOptions {
 /**
  * Builds a {@link PersistenceAdapter} over an async key/value store — the React
  * Native / Expo counterpart to the IndexedDB adapter (`createIndexedDbPersistence`).
- * The whole FIFO mutation log is serialized to JSON under a single key (`key`),
- * so enqueue order is preserved and `load()` returns freshly-parsed records that
- * callers can't alias.
+ * The whole FIFO mutation log is stored under a single key (`key`), so enqueue
+ * order is preserved and `load()` returns freshly-parsed records that callers
+ * can't alias.
+ *
+ * Records round-trip through {@link singleBlobStore}'s wire codec. Args it
+ * cannot carry (a `RegExp`, a class instance) reject at `append`/`replace` — the
+ * flush path rejects them terminally anyway. A blob that exists but can't be
+ * decoded loads as empty, and every write rejects rather than overwrite it and
+ * lose the queued writes it may still hold; `clear()` discards it.
  *
- * AsyncStorage has no transactions, so every read-modify-write is funnelled
- * through a single promise chain — concurrent `append`/`remove` calls run one at
- * a time and can't clobber each other's writes.
+ * AsyncStorage has no transactions, so every read-modify-write runs through
+ * {@link singleBlobStore}'s serialized chain — concurrent `append`/`remove`
+ * calls run one at a time and can't clobber each other's writes.
  */
 declare const createAsyncStoragePersistence: (options: AsyncStoragePersistenceOptions) => PersistenceAdapter;
+interface AsyncStorageQueryCacheOptions {
+  /** Storage key the cache is serialized under; defaults to `"lunora:query-cache"`. */
+  key?: string;
+  /** LRU row cap; defaults to 50 (see {@link DEFAULT_MAX_ENTRIES}). Must be a positive integer. The oldest rows by `ts` are pruned on `put` once exceeded. */
+  maxEntries?: number;
+  /** The async key/value store the cache is read from and written to (e.g. React Native `AsyncStorage`). */
+  storage: AsyncStorageLike;
+}
+/**
+ * Builds a {@link QueryCacheAdapter} over an async key/value store — the React
+ * Native / Expo counterpart to `createIndexedDbQueryCache`. The whole cache is
+ * serialized under a single key (`key`).
+ *
+ * Values round-trip through {@link singleBlobStore}'s wire codec (a `bigint`,
+ * `Date`, or bytes survives a reload); a corrupt blob reads as an empty cache.
+ *
+ * AsyncStorage has no transactions, so every read-modify-write runs through
+ * {@link singleBlobStore}'s serialized chain — concurrent `put`/`remove` calls
+ * run one at a time and can't clobber each other's writes.
+ *
+ * Single-blob storage rewrites the whole cache per `put` (bounded by
+ * `maxEntries` — see the cap's note on Android's row and shared-budget limits);
+ * if that ever shows up in profiles, per-key storage entries are the upgrade
+ * path.
+ */
+declare const createAsyncStorageQueryCache: (options: AsyncStorageQueryCacheOptions) => QueryCacheAdapter;
 /** Default in-memory bookmark store. Survives the lifetime of the client. */
 declare const createInMemoryBookmarkStorage: () => BookmarkStorage;
+/**
+ * Reactive sinks an adapter binds to its own primitive's setters (a React
+ * `useState`, a Solid signal, a Vue ref, a Svelte store). The runner pushes into
+ * them; how they store the value is the adapter's concern (e.g. Solid and React
+ * wrap function-valued results in a thunk so the setter stores them rather than
+ * invoking them).
+ */
+interface CallRunnerSinks<R> {
+  /** Receives the normalized {@link Error} when the latest invocation rejects. */
+  setError: (error: Error) => void;
+  /** Receives `true` while at least one invocation is in flight (ref-counted across overlapping calls), else `false`. */
+  setPending: (pending: boolean) => void;
+  /** Receives the resolved value when the latest invocation succeeds. */
+  setResult: (result: R) => void;
+}
+/**
+ * Build the framework-neutral half of an adapter's write primitive — the `mutate`
+ * of `useMutation`/`createMutation`/`mutation`, and the `call` of
+ * `useAction`/`createAction`/`action`.
+ *
+ * It owns the orchestration every adapter otherwise copy-pastes: ref-counting
+ * overlapping invocations into `setPending` (so the flag clears only once the
+ * last settles), normalizing a thrown non-`Error`, and routing success/failure to
+ * `setResult`/`setError` before re-throwing the SAME instance (so a typed error's
+ * `.code`/`.data` survive for both the `catch` and the template).
+ *
+ * `invoke` is a pre-bound thunk — `(args, options) => client.mutation(fn, args, options)`
+ * or `(args, options) => client.action(fn, args, options)`. Binding at the call
+ * site is what keeps this one function: the runner never inspects `options`, it
+ * only forwards them, so the option type is inferred from the closure rather
+ * than hard-coded per procedure kind. What actually keeps `optimisticUpdate` off
+ * an action is the adapter's exported handle type, not this file.
+ *
+ * `data`/`error` track the LATEST invocation, not the last to settle: overlapping
+ * calls can resolve out of order, so an earlier call that finishes later must not
+ * clobber a newer call's outcome. Each invocation takes a monotonic token and
+ * writes the value sinks only while it is still the most recent one — otherwise a
+ * double-click could leave the UI showing the first click's result, or an error
+ * for a call that succeeded.
+ */
+declare const createCallRunner: <A, O, R>(invoke: (args: A, options?: O) => Promise<R>, sinks: CallRunnerSinks<R>) => ((args: A, options?: O) => Promise<R>);
 interface TabCoordinatorOptions {
   /**
    * BroadcastChannel name. Defaults to `"lunora-bridge"`.
@@ -51,18 +310,71 @@ interface TabCoordinatorOptions {
    * Called when this tab becomes the leader (should open WS connections).
    */
   onBecomeLeader?: () => void;
+  /**
+   * Called when the leader broadcasts its aggregate `ConnectionStatus`
+   * (see `LunoraClient.emitConnectionStatus`) — a follower owns no socket
+   * of its own, so this is its only truthful signal for a status indicator
+   * or the offline-queue gate. Sent on every leader-side status change and
+   * once more right after a new leader takes over, so a follower already
+   * mid-mirroring isn't stuck on a stale value from the PREVIOUS leader.
+   *
+   * `identity` is the leader's own `identityFingerprint()` (`null` = signed
+   * out) — the channel-name scoping (see `LunoraClient.createTabCoordinator`)
+   * is the primary defence against a stale frame from a since-changed
+   * identity, but `setAuthToken` in one tab can move it to a new channel
+   * while this frame is already queued in another tab's message task queue.
+   * A follower drops the frame when `identity` is present and doesn't match
+   * its own; an **absent** `identity` (mixed-version leader) is accepted —
+   * today's behavior, and the channel split already separates version groups.
+   */
+  onConnectionStatus?: (status: ConnectionStatus, identity?: string | null) => void;
+  /**
+   * Called when the leader broadcasts a subscription error.
+   */
+  /** Fired on the LEADER when it answers another tab's leadership claim — the moment a new follower is known to be listening. */
+  onLeaderClaimAnswered?: () => void;
   /**
    * Called when this tab loses leadership (should close WS connections).
    */
   onStopBeingLeader?: () => void;
   /**
-   * Called when the leader broadcasts subscription data.
+   * Called when the leader broadcasts subscription data. `cursor`/`epoch`
+   * ride along when the leader is CLIENT-01-aware, so the follower can drop
+   * its own confirmed optimistic layers instead of just displaying the raw
+   * value; both are absent on a mixed-version leader that hasn't shipped the
+   * cursor yet (the follower falls back to its historical behavior — see
+   * the follower data handler in `tab-leadership.ts`).
+   *
+   * `identity` is the leader's `identityFingerprint()` (see
+   * `onConnectionStatus`'s docblock for the full rationale and the
+   * absent-field mixed-version rule — identical here).
    */
-  onSubscriptionData?: (key: string, data: unknown) => void;
+  onSubscriptionData?: (key: string, data: unknown, cursor?: number, epoch?: string, identity?: string | null) => void;
+  onSubscriptionError?: (key: string, error: SubscriptionError, identity?: string | null) => void;
   /**
-   * Called when the leader broadcasts a subscription error.
+   * Called when the leader broadcasts a `settled` frame's checkpoint advance
+   * (no value change, but the resume cursor moved). A follower needs this
+   * too — otherwise a `setQuery`/per-call optimistic overlay that a
+   * byte-identical write just confirmed stays masked on follower tabs until
+   * the next VISIBLE data frame arrives, even though the leader already
+   * dropped it.
+   *
+   * `lastMutationId` is the LEADER's own per-client `__client_watermark` —
+   * scoped server-side to the socket's announced `clientId` — so it only
+   * means anything to a follower whose `clientId` matches the leader's
+   * (`clientId` rides along for exactly that comparison; see
+   * `LunoraClient`'s wiring). An **absent** `clientId` (a mixed-version
+   * leader that hasn't shipped this field yet) also skips the
+   * `mutationId` half — safe, because the follower's own gates still
+   * resolve via its own RPC-ack watermark path and the `CheckpointRegistry`
+   * bounded fallback. The checkpoint (cursor) half of this callback fires
+   * unconditionally regardless of `clientId` — only the `mutationId` half
+   * is scoped.
+   *
+   * `identity` is the leader's `identityFingerprint()` — see
+   * `onConnectionStatus`'s docblock for the drop rule (identical here).
    */
-  onSubscriptionError?: (key: string, error: SubscriptionError) => void;
+  onSubscriptionSettled?: (key: string, cursor?: number, epoch?: string, lastMutationId?: number, clientId?: string, identity?: string | null) => void;
 }
 declare class TabCoordinator {
   private readonly bc;
@@ -75,15 +387,31 @@ declare class TabCoordinator {
   private leader;
   /** `true` once `start()` has been called. */
   private running;
+  /**
+   * `true` while a `claimAndPromote()` claim window is open. Guards the yield
+   * handler and `checkLeaderHealth`'s belt-and-braces else-branch so the two
+   * promotion paths can't both arm a `becomeLeader` timeout for the same gap.
+   */
+  private promotionPending;
   /** Timestamp of the most recent leader heartbeat. */
   private lastHeartbeat;
+  /**
+   * Snapshots waiting for the end of the current tick, latest per key. A
+   * `subscription-data` frame is a full snapshot, so a burst for one key within
+   * a tick only needs its last frame posted — each post structured-clones the
+   * whole value for every tab on the channel.
+   */
+  private readonly pendingData;
   private heartbeatTimer;
   private leaderCheckTimer;
   /** Callbacks set via constructor options. */
   private readonly onBecomeLeader;
   private readonly onStopBeingLeader;
+  private readonly onConnectionStatus;
   private readonly onSubscriptionData;
+  private readonly onLeaderClaimAnswered;
   private readonly onSubscriptionError;
+  private readonly onSubscriptionSettled;
   constructor(options?: TabCoordinatorOptions);
   /**
    * Start the coordinator: attempt to claim leadership and begin the
@@ -97,6 +425,23 @@ declare class TabCoordinator {
   stop(): void;
   /** `true` when this tab is the current WebSocket leader. */
   isLeader(): boolean;
+  /**
+   * Force this (freshly `start()`-ed) tab to become leader immediately,
+   * skipping the normal claim-then-`leaderTimeout` dance. Safe to call
+   * right after `start()` when the caller already knows this tab was the
+   * SOLE leader of the group it's replacing (e.g. `LunoraClient`'s
+   * identity-change coordinator restart — waiting out the full
+   * `leaderTimeout` there would freeze every live query for no reason,
+   * since this tab is overwhelmingly likely to be alone on the freshly
+   * derived channel). A sibling tab going through the normal `start()`
+   * dance for the SAME transition observes this tab's `becomeLeader`
+   * heartbeat and defers before its own claim-timeout fires; if another
+   * tab ALSO force-promotes at the same moment (e.g. two tabs both
+   * transitioning to the same new identity), the existing
+   * `resolveLeaderVsLeaderTieBreak` resolves the rare double-promotion
+   * the same way it resolves any other split-brain.
+   */
+  promoteImmediately(): void;
   /** The tab id of the current leader, or `undefined` if unknown / no leader. */
   get leaderTabId(): string | undefined;
   /** The id of this tab. */
@@ -105,15 +450,53 @@ declare class TabCoordinator {
   get isRunning(): boolean;
   /**
    * Broadcast subscription data to all follower tabs. Only the leader should
-   * call this.
+   * call this. `cursor`/`epoch` are omitted from the wire frame when
+   * `undefined` (e.g. a CDC-off shard) — a follower on ANY version treats a
+   * missing `cursor` as "no confirmed-layer drop this frame", so omitting it
+   * here is equivalent to sending it as `undefined`. `identity` is this
+   * (leader) tab's own `identityFingerprint()` (`null` = signed out) —
+   * stamped so a follower can drop a frame from a since-changed identity
+   * (see the `onSubscriptionData` docblock); spread-included whenever
+   * supplied, since a fixed leader always knows its own identity (never
+   * omits it) and `null` must round-trip distinctly from "field absent".
    */
-  broadcastSubscriptionData(key: string, data: unknown): void;
+  broadcastSubscriptionData(key: string, data: unknown, cursor?: number, epoch?: string, identity?: string | null): void;
   /**
    * Broadcast a subscription error to all follower tabs. Only the leader
    * should call this.
+   *
+   * `identity` is this tab's own `identityFingerprint()`, stamped so a
+   * follower can drop a frame minted under a different credential — the same
+   * guard `broadcastSubscriptionData` and `broadcastSubscriptionSettled`
+   * carry. This one lacked it, which was harmless only because nothing called
+   * it; once the leader started fanning errors, an unstamped frame could
+   * deliver one caller's rejection to a tab that had since signed in as
+   * someone else.
    */
-  broadcastSubscriptionError(key: string, error: SubscriptionError): void;
+  broadcastSubscriptionError(key: string, error: SubscriptionError, identity?: string | null): void;
+  /**
+   * Broadcast a `settled` frame's checkpoint advance to all follower tabs
+   * (no value change, but the resume cursor/epoch moved — see
+   * `LunoraClient.handleSettledMessage`). `clientId` is this (leader) tab's
+   * own client id, stamped so a follower can tell whether the echoed
+   * `lastMutationId` watermark is genuinely its own (see the
+   * `onSubscriptionSettled` docblock). `identity` is this tab's own
+   * `identityFingerprint()` — see `broadcastSubscriptionData`'s docblock for
+   * the same round-tripping rule. Only the leader should call this.
+   */
+  broadcastSubscriptionSettled(key: string, cursor?: number, epoch?: string, lastMutationId?: number, clientId?: string, identity?: string | null): void;
+  /**
+   * Broadcast this tab's aggregate `ConnectionStatus` to follower tabs, so
+   * they can mirror a truthful status without a socket of their own (see
+   * `LunoraClient.computeStatus`/`emitConnectionStatus`). `identity` is this
+   * tab's own `identityFingerprint()` — see `broadcastSubscriptionData`'s
+   * docblock for the same round-tripping rule. Only the leader should call
+   * this.
+   */
+  broadcastConnectionStatus(status: ConnectionStatus, identity?: string | null): void;
   private broadcast;
+  /** Post the snapshots queued this tick — unless leadership was lost meanwhile, when the new leader's own snapshots supersede them. */
+  private flushPendingData;
   private handleMessage;
   private handleClaimLeadership;
   private handleHeartbeat;
@@ -133,28 +516,15 @@ declare class TabCoordinator {
   private becomeLeader;
   private sendHeartbeat;
   private checkLeaderHealth;
+  /**
+   * Broadcast a leadership claim and arm a `becomeLeader` fallback: if no
+   * other tab has asserted itself as leader by the time the window elapses,
+   * self-promote. Shared by `checkLeaderHealth`'s stale-leader path and the
+   * `yield-leadership` handler so both promotion triggers use one claim
+   * window instead of each arming its own timeout.
+   */
+  private claimAndPromote;
 }
-/**
- * Client-side incremental merging of structured mutation deltas.
- *
- * Lunora's live-query fan-out has two server paths:
- *
- * 1. Server re-execution (subscriptions carrying a `functionPath`) pushes a
- * full `data` snapshot whenever a write touches a table the query reads. These
- * already carry the authoritative result and are applied wholesale.
- * 2. Legacy delta fan-out (`broadcastDelta`) pushes a structured `MutationDelta`
- * as a `delta` frame to subscribers matched by table + args. The delta describes
- * a single row change (`insert` / `update` / `delete`) keyed by row id, so the
- * client can splice it into the cached list result without a full re-send.
- *
- * Historically the client treated the `delta` field as an opaque blob and
- * replaced the whole cached value with it on every message — which only made
- * sense for the rare delta payloads that already carried the full result. This
- * module lets the client recognise a structured delta and merge it into the
- * existing array (preserving order, no dup/loss), falling back to full
- * replacement when the payload isn't a recognisable row delta or can't be
- * applied cleanly against the current cached shape.
- */
 /**
  * One row change as emitted by `@lunora/do`'s `broadcastDelta`. Mirrors
  * `MutationDelta` in `@lunora/do` structurally so the client carries no
@@ -177,28 +547,21 @@ interface MutationDelta {
  */
 declare const isMutationDelta: (value: unknown) => value is MutationDelta;
 /**
- * Apply a structured `MutationDelta` to a cached array result, returning a new
- * array (never mutating the input). Returns `undefined` when the delta can't be
+ * Apply a structured `MutationDelta` to a cached list result, returning a new
+ * value (never mutating the input). Returns `undefined` when the delta can't be
  * applied cleanly — the caller should then fall back to the existing
  * full-replacement behaviour (or trust the next snapshot to reconcile).
  *
- * Mergeable shape: a plain array of id-bearing row objects, e.g. the result of
- * `db.query().collect()`.
- *
- * Insert / update / delete are matched by row `_id`:
- * - `insert`: appended (or placed by `_creationTime` order) if absent; treated
- * as an update if a row with the same id already exists (idempotent — guards
- * against a delta replayed after a snapshot already included it).
- * - `update`: replaces the matching row in place, preserving its position.
- * - `delete`: removes the matching row.
- *
- * Returns `undefined` when `current` isn't an array of id-keyable objects, or
- * when an `insert`/`update` delta carries no `row` to splice in.
+ * Mergeable shapes: an array of id-bearing row objects, or a `.paginate()`
+ * result wrapping one in `page` (see `rowListOf`). A paginated value keeps its
+ * other fields and comes back as a new object with a new `page` — the server
+ * only sends row deltas for that shape when everything outside the page is
+ * unchanged, so the merged value matches the snapshot it chose not to send.
+ * @returns the merged value, or `undefined` when the delta cannot be applied
  */
-declare const applyDelta: (current: unknown, delta: MutationDelta) => undefined | unknown[];
+declare const applyDelta: (current: unknown, delta: MutationDelta) => Record<string, unknown> | undefined | unknown[];
 /**
  * Options accepted by {@link httpStream}.
- * @experimental Part of the HTTP-SSE stream surface.
  */
 interface HttpStreamOptions {
   /**
@@ -211,8 +574,43 @@ interface HttpStreamOptions {
   fetch?: typeof fetch;
   /** Extra request headers (e.g. `authorization`). `accept: text/event-stream` is always sent. */
   headers?: Record<string, string>;
+  /**
+   * Treat a connection that delivers nothing — no chunk, no keepalive comment —
+   * for this many milliseconds as dead: it is cancelled, then reconnected with
+   * {@link HttpStreamOptions.reconnect} or failed with `STREAM_IDLE`. Off by
+   * default, because a route may be silent for as long as its handler works
+   * (a model thinking); set it to a few multiples of the route's keepalive
+   * interval when the route sends one.
+   *
+   * Measured per streamed read, so it needs a `fetch` that exposes
+   * `response.body`. A runtime whose `fetch` delivers no body stream (React
+   * Native) reads the whole payload with one `text()` call that resolves only
+   * at the end — no per-frame progress exists to measure silence against, so
+   * this bound does not apply there and a stalled read waits for
+   * `.cancel()` or {@link HttpStreamOptions.signal} instead.
+   */
+  idleTimeoutMs?: number;
+  /**
+   * Seed the first request's `Last-Event-ID` header, resuming a stream from a
+   * position a previous consumer persisted. Once frames arrive this is
+   * superseded by their `id:`, and a reconnecting stream always sends the
+   * latest id it saw.
+   */
+  lastEventId?: string;
   /** Caps the in-flight chunk buffer (see `createStream`); exceeding it fails the stream. */
   maxBuffer?: number;
+  /** Called with each frame's `id:` as it is seen (the value that will be replayed on reconnect). */
+  onEventId?: (id: string) => void;
+  /** Called when the server advertises a `retry:` reconnect delay, in milliseconds. */
+  onRetry?: (ms: number) => void;
+  /**
+   * Reopen the request after a transport interruption — a bare EOF or a
+   * read/transport error — replaying the last seen id as `Last-Event-ID`.
+   * Defaults to `false`, which surfaces the interruption as
+   * `HTTP_STREAM_INTERRUPTED` exactly as before. A terminal `complete`/`error`
+   * frame, a non-2xx status, and a consumer cancel never reconnect.
+   */
+  reconnect?: boolean;
   /** External abort signal — aborting it cancels the fetch (→ the server handler's `signal`). */
   signal?: AbortSignal;
 }
@@ -230,39 +628,132 @@ interface HttpStreamOptions {
  * an `event: error` frame (or a transport failure) surfaces as a coded
  * rejection on the next `next()`. `.cancel()` — or aborting `options.signal` —
  * aborts the underlying fetch, which the server observes via `request.signal`.
- * @experimental Reconnect/POST-body/wire-fidelity design questions are still open, so the shape may change.
  */
 declare const httpStream: <Ref extends HttpStreamRef>(route: Ref, args?: HttpStreamArgsOf<Ref>, options?: HttpStreamOptions) => StreamIterable<HttpStreamChunkOf<Ref>>;
-/** The single transport method a mutation runner needs — narrowed so adapters can test against a stub. */
-interface MutationCapableClient<F extends FunctionReference> {
-  mutation: (function_: F, args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>;
+/** Options for {@link connectLiveStream}. */
+interface ConnectLiveStreamOptions {
+  /** `fetch` override (a test seam, or a custom transport). */
+  fetch?: typeof fetch;
+  /** Extra headers sent on both the stream and the control requests. */
+  headers?: Record<string, string>;
+  /**
+   * Treat a connection that delivers nothing — not even a keepalive — for this many milliseconds as
+   * dead, and reconnect. Every target that serves live streams (Cloudflare Workers, the Node host
+   * and celld) runs the same `ShardDO` live handlers, and they write a `:ka` comment every 25s
+   * while a stream is open, so the default is `75000`. Set `0` to disable the bound when a proxy
+   * or a server of your own in front of the shard does not forward comment frames.
+   */
+  idleTimeoutMs?: number;
+  /** Ceiling for the reconnect backoff, in ms. Defaults to `30000`. */
+  maxDelayMs?: number;
+  /** Base reconnect delay in ms. Defaults to `1000`. */
+  retryDelay?: number;
+  /** Send cookies / credentials on the stream and control requests. */
+  withCredentials?: boolean;
+}
+/** A delivered live event. */
+interface LiveStreamEvent {
+  /** The decoded payload the publisher sent. */
+  payload: unknown;
+  /** The topic the event was published on. */
+  topic: string;
+}
+/** Options for {@link LiveStream.subscribe}. */
+/** A subscribe the shard refused for good: a reconnect would only be refused again. */
+interface LiveStreamSubscribeError {
+  /** The HTTP status of the refusal, e.g. 403, 409 or 429. */
+  status: number;
+  subscriptionId: string;
+  topic: string;
+}
+interface LiveStreamSubscribeOptions {
+  /** Stable caller id; a generated one is used when omitted. */
+  id?: string;
+  /**
+   * Called when the shard refuses this subscription (403, 409, 429 and similar). The subscription is dropped
+   * first, so a later subscribe with the same id is accepted. A 401 is not reported: the stream reconnects,
+   * which re-authenticates and registers the subscription again.
+   */
+  onError?: (error: LiveStreamSubscribeError) => void;
+  /** Called for every event on `topic`. */
+  onEvent?: (payload: unknown) => void;
+  /** The topic to follow. */
+  topic: string;
+}
+/** A live stream connection. */
+interface LiveStream {
+  /** Close the stream and stop reconnecting. */
+  close: () => void;
+  /** The server-minted connection id, or `undefined` before the first connect and while reconnecting. */
+  readonly connectionId: string | undefined;
+  /** Observe every event on the connection; returns an unsubscribe handle. */
+  onEvent: (handler: (event: LiveStreamEvent) => void) => () => void;
+  /** Resolves once the first connection is established (rejects only if `close`d first). */
+  readonly ready: Promise<void>;
+  /** Follow a topic; returns an unsubscribe handle. */
+  subscribe: (options: LiveStreamSubscribeOptions) => () => void;
 }
 /**
- * Reactive sinks an adapter binds to its own primitive's setters (a Solid
- * signal, a Vue ref, a Svelte store). The runner pushes into them; how they
- * store the value is the adapter's concern (e.g. Solid wraps function-valued
- * results in a thunk).
+ * Connect to a live topic stream. See the module docblock.
+ * @param url the `connect` route URL (its sibling `control` route is derived)
  */
-interface MutationRunnerSinks<R> {
-  /** Receives the normalized {@link Error} when an invocation rejects. */
-  setError: (error: Error) => void;
-  /** Receives `true` while at least one invocation is in flight (ref-counted across overlapping calls), else `false`. */
-  setPending: (pending: boolean) => void;
-  /** Receives the resolved value when an invocation succeeds. */
-  setResult: (result: R) => void;
+declare const connectLiveStream: (url: string, options?: ConnectLiveStreamOptions) => LiveStream;
+/**
+ * A reference to one declared live topic, as `_generated/live.ts` hands it out. Plain data
+ * (no server code), so a client bundle can hold it; the phantom `Payload` is what lets
+ * `ctx.live.publish` and the framework hooks type the event.
+ */
+interface LiveTopicRef<Payload = unknown> {
+  /** Phantom: carries the declared payload type. Never present at runtime. */
+  readonly __payload?: Payload;
+  /** The `id` of the `defineLiveStream` that declares and authorizes this topic. */
+  readonly __lunoraLive: string;
+  /** The encoded wire topic (see {@link encodeLiveTopic}). */
+  readonly topic: string;
+}
+/** Options for {@link subscribeLiveTopic}. */
+interface SubscribeLiveTopicOptions extends Omit<ConnectLiveStreamOptions, "fetch"> {
+  /** Called when the shard refuses this subscription (403, 409, 429 and similar). */
+  onError?: (error: LiveStreamSubscribeError) => void;
+  /** Called for every event on `topic`. */
+  onEvent?: (payload: unknown) => void;
+  /**
+   * Partitions the shared connection. A cookie-authenticated stream is bound to the session that opened it, so
+   * pass something that changes when the signed-in user does (a user id): a new value opens a new connection
+   * and the old one closes once its subscribers have moved. It is never sent to the server.
+   */
+  sessionKey?: string;
+  /** The topic to follow. */
+  topic: string;
+  /** The `connect` route URL of a `defineLiveStream`. */
+  url: string;
 }
 /**
- * Build the framework-neutral `mutate` half of an adapter's mutation hook.
- *
- * Owns the orchestration every adapter otherwise copy-pastes: ref-counts
- * overlapping invocations into `setPending` (so it only clears once the last
- * settles), normalizes a thrown non-`Error`, and routes success/failure to
- * `setResult`/`setError` before re-throwing. Each adapter (`@lunora/react`,
- * `/solid`, `/svelte`, `/vue`) binds the three sinks to its own reactive
- * setters, so this logic lives in exactly one place. Optimistic-update options
- * pass straight through to `client.mutation`.
+ * Follow `topic` on the shared connection for `url`.
+ * @returns an unsubscribe handle; the last one out closes the connection
+ */
+declare const subscribeLiveTopic: (options: SubscribeLiveTopicOptions) => (() => void);
+/**
+ * What a framework hook takes besides the topic reference: the transport tuning of
+ * {@link SubscribeLiveTopicOptions}, with `onEvent` typed by the topic's declared payload.
+ */
+interface LiveTopicOptions<Payload = unknown> extends Omit<SubscribeLiveTopicOptions, "onEvent" | "topic" | "url"> {
+  /** Called for every event on the topic. The payload is the type the topic declares. */
+  onEvent?: (payload: Payload) => void;
+  /**
+   * Follow the topic on this shard: the connect URL gets `?shard=<key>`, and the control calls carry it too. Omit it
+   * for the default shard. Publish to the same shard with `{ shardKey }`, since delivery never crosses shards.
+   */
+  shardKey?: string;
+}
+/**
+ * Resolve a topic reference to the string-based options {@link subscribeLiveTopic} takes: the connect URL is the
+ * stream's route under the client's base URL, and the topic is the reference's encoded wire topic. Every framework
+ * hook goes through this, so they all build the same connection (and so share it).
  */
-declare const createMutationRunner: <F extends FunctionReference>(client: MutationCapableClient<F>, function_: F, sinks: MutationRunnerSinks<ReturnOf<F>>) => ((args: ArgsOf<F>, options?: MutationCallOptions<unknown, unknown, ArgsOf<F>>) => Promise<ReturnOf<F>>);
+declare const liveTopicSubscription: <Payload>(client: {
+  readonly url: string;
+}, ref: LiveTopicRef<Payload>, options?: LiveTopicOptions<Payload>) => SubscribeLiveTopicOptions;
 /**
  * The structural surface of a TanStack `Transaction` a bound custom mutator
  * returns — its `isPersisted.promise` resolves once the write is persisted and
@@ -317,15 +808,48 @@ declare const createMutatorRunner: <TArgs>(handle: MutatorHandle<TArgs>, sinks:
   reset: () => void;
 };
 interface QueuedMutation<T = unknown> {
+  /**
+   * Set on a write that was queued because its direct send failed in a way that
+   * says nothing about its fate (see `LunoraClient.mutation`). Its caller is still
+   * waiting and was never told it failed, so the replay counts its transient
+   * failures and rejects it after a few, rather than retrying for ever.
+   */
+  readonly ambiguousSend?: boolean;
   readonly args: Record<string, unknown>;
+  /**
+   * CDC cursor this write was composed against (see
+   * {@link PersistedMutation.baselineSeq}). Persisted and restored so a replay is
+   * judged against what its author could see, not against what the client has
+   * since caught up to.
+   */
+  readonly baselineSeq?: number;
+  /**
+   * The client id that queued this write (see {@link PersistedMutation.clientId}).
+   * Persisted and restored, so a replay namespaces by the id that issued the
+   * write rather than whatever the current session minted.
+   */
+  clientId?: string;
   readonly functionPath: string;
   /** Stable id used to remove the entry from durable storage once replayed; assigned by the queue when absent. */
   id?: string;
   /**
    * Issuing identity fingerprint carried through to durable storage (`null` =
    * signed out). Absent on hydrated legacy records, which replay ambiently.
+   *
+   * Mutable so {@link OfflineQueue.restampIdentity} can relabel a still-queued
+   * write when the identity's LABEL changes but the credential does not (the
+   * `setAuthToken(token, userId)` case where the subject resolves a tick after
+   * the token). The value is re-persisted alongside, so the new label survives
+   * a reload and a requeue.
+   */
+  identity?: string | null;
+  /**
+   * Position in the order this session ISSUED its writes, taken before the first send. A write whose
+   * direct send failed ambiguously is queued only once that send gives up, behind writes issued (and
+   * queued) while it was in flight; this puts it back ahead of them. Absent on hydrated records,
+   * which are older than anything issued this session.
    */
-  readonly identity?: string | null;
+  readonly issueSeq?: number;
   /**
    * `true` when a live caller is still awaiting this write's `mutation()`
    * Promise; `false`/absent for a write restored from durable storage after a
@@ -359,6 +883,14 @@ interface QueuedMutation<T = unknown> {
  * eviction), so the client can surface the dropped write on its
  * terminal-verdict observer even when the entry has no live awaiter (a hydrated
  * record). The `error` carries the `OFFLINE_QUEUE_OVERFLOW` code.
+ *
+ * The `sdks/*` ports deliberately do NOT mirror this shape — they return the
+ * discarded entry from `enqueue`/`hydrate`/`drainConflict`/`clear` instead,
+ * because they call the queue with a real lock held and settling a write needs
+ * that same lock, which self-deadlocks a non-reentrant one. Keep the callback
+ * here: this client is single-threaded, so the hazard does not exist, and an
+ * observer the queue fires itself is what covers the case a return value's
+ * consumer can quietly miss — a hydrated entry whose `reject` is a no-op.
  */
 type EvictHandler = (entry: QueuedMutation, error: Error & {
   code?: string;
@@ -367,6 +899,8 @@ type EvictHandler = (entry: QueuedMutation, error: Error & {
 interface OfflineQueueDeps {
   /** Invoked when an entry is discarded on capacity overflow (carries `OFFLINE_QUEUE_OVERFLOW`). */
   onEvict?: EvictHandler;
+  /** Invoked when a write that was out for replay settles, which `onSizeChange` does not cover: the queue was already shorter. */
+  onReplayingChange?: () => void;
   /** Invoked with the new depth after any size change (drives the client's pending-sync count). */
   onSizeChange?: (size: number) => void;
   /** Durable store; when present, writes are mirrored and restored across reloads. */
@@ -394,12 +928,44 @@ declare class OfflineQueue {
   private readonly persistence;
   private readonly onEvict;
   private readonly onSizeChange;
+  private readonly onReplayingChange;
   /** App/schema version stamped on persisted writes; mismatched records are purged on hydrate. */
   private readonly version;
   private readonly items;
+  /** Ids of writes a flush has {@link OfflineQueue.drain}ed and neither requeued nor discarded yet, which are on the wire or about to be. */
+  private readonly replayingIds;
+  /** Appends still in flight, by write id, each resolving to whether the record landed. Anything that touches a record durably waits on its append first. */
+  private readonly appending;
+  /**
+   * Writes enqueued this session and not yet settled (see {@link OfflineQueue.discard}). Unlike `items`
+   * this survives a replay temporarily draining the queue, so a failed append is tracked for as long as
+   * the write is unsettled, and a retry derives its record from the entry as it is NOW.
+   */
+  private readonly unsettled;
+  /** Ids whose append was rejected (a quota error, a closed connection), kept to be tried again — see {@link OfflineQueue.flushUnpersisted}. */
+  private readonly unpersisted;
   constructor(options?: OfflineQueueOptions, deps?: OfflineQueueDeps);
   get size(): number;
+  /** Writes drained for replay and not yet settled or requeued: out of {@link OfflineQueue.size}, but still unsettled. */
+  get replaying(): number;
   enqueue<T>(entry: QueuedMutation<T>): void;
+  /**
+   * Remove a settled write's durable record — after its append, if that is
+   * still in flight. A write that replays quickly can settle before its append
+   * has landed; a `remove` that overtook it found nothing, and the record then
+   * landed behind it and replayed in the next session.
+   */
+  discard(id: string): void;
+  /**
+   * Try again to persist every write whose append was rejected. Called when the
+   * page is being hidden: the last chance to get a still-queued write into
+   * durable storage before a reload or a discard of the tab loses it.
+   *
+   * A write whose append is still in flight is skipped: `visibilitychange` and `pagehide` fire
+   * back to back, and a second append for the same id would hit a unique-id constraint (or store
+   * the record twice) and leave the write wrongly tracked as unpersisted.
+   */
+  flushUnpersisted(): void;
   /**
    * Restore mutations persisted in a prior session and re-queue them in FIFO
    * order. Restored entries already live in durable storage, so they are not
@@ -419,6 +985,33 @@ declare class OfflineQueue {
    * silently clobber the newer data with the stale one.
    */
   hydrate(): Promise<(string | undefined)[]>;
+  /**
+   * Relabel every queued write stamped `from` to `to`, in memory AND in durable
+   * storage.
+   *
+   * Used when the auth identity's LABEL changes while the credential does not —
+   * `setAuthToken(token, userId)` where the user id resolves a tick after the
+   * token was set. `setAuthToken` documents that this re-stamps in-flight
+   * queued writes rather than dropping them, and that promise only held for the
+   * caller's live in-memory stamp map, which is consumed and deleted on the
+   * first flush attempt. Everything durable still carried the old token hash,
+   * so a reload — or a transient-failure requeue after the token had since been
+   * refreshed — fell back to it, failed the replay identity gate, and rejected
+   * the SAME user's offline write with `OFFLINE_IDENTITY_CHANGED`.
+   *
+   * The durable rewrite goes through `PersistenceAdapter.replace`, the one
+   * operation on the contract that is required to be atomic — see
+   * {@link OfflineQueue.rewriteStamp}.
+   */
+  restampIdentity(from: string | null, to: string | null): void;
+  /**
+   * Whether any queued mutation matches — the cheap "is there a write ahead of
+   * me on this shard?" question, answered without draining. A write held at
+   * flush time (an identity not yet re-confirmed) sits here with no barrier
+   * published for a later `mutation()` to wait on, so this is what keeps a
+   * live write from overtaking it.
+   */
+  hasPending(predicate: (item: QueuedMutation) => boolean): boolean;
   /**
    * Remove and return queued mutations. With no `predicate`, drains the whole
    * queue. With one, drains only matching entries (preserving FIFO order) and
@@ -444,6 +1037,41 @@ declare class OfflineQueue {
    */
   drainConflict(): QueuedMutation[];
   clear(): void;
+  /** The durable form of a queued write. */
+  private recordOf;
+  /** Append `record`, remembering it as unpersisted if the append is rejected. */
+  private persist;
+  /**
+   * The durable half of {@link OfflineQueue.restampIdentity}: rewrite the
+   * persisted record under the new identity stamp.
+   *
+   * This used to be `remove` then `append` (because `append` is an insert, not
+   * an upsert) with a compensating re-append on failure, and no arrangement of
+   * those two calls is safe. A process stop between a committed `remove` and
+   * the `append` leaves the mutation in NO durable store while the in-memory
+   * entry has already advanced, so a reload loses the write outright — and
+   * compensation cannot cover a crash, only a rejection. The re-append also
+   * moved the record to the tail, replaying it out of issue order.
+   *
+   * `PersistenceAdapter.replace` is the single atomic operation that removes
+   * both: the swap lands whole or not at all, and the record keeps its place
+   * in FIFO order. A rejection means nothing changed durably — the record
+   * stands under its OLD stamp, which is the documented outcome (a replay
+   * under a stale stamp is refused with `OFFLINE_IDENTITY_CHANGED`, visible
+   * and recoverable, unlike a silent loss) — so there is nothing to
+   * compensate, only to report.
+   */
+  private rewriteStamp;
+  /**
+   * Evict entries from the FRONT of `items` (the oldest — FIFO order) until
+   * the queue is at or under `maxItems`, rejecting each with
+   * `OFFLINE_QUEUE_OVERFLOW`, un-persisting it, and firing `onEvict`. Shared
+   * by `enqueue` (a live write pushes past capacity) and `hydrate` (a durable
+   * store restored more than `maxItems` records — CLIENT-03) so an overflow
+   * always drops the same way regardless of which caller triggered it.
+   */
+  private evictOverflow;
+  private markReplaying;
   /** Notify the size observer (the client's pending-sync count) after any change. */
   private notifySize;
 }
@@ -494,7 +1122,7 @@ interface IndexedDbQueryCacheOptions {
   databaseName?: string;
   /** Injectable `IDBFactory` (e.g. `fake-indexeddb` in tests); defaults to the global `indexedDB`. */
   indexedDB?: IDBFactory;
-  /** LRU row cap; defaults to 500. The oldest rows by `ts` are pruned on `put` once exceeded. */
+  /** LRU row cap; defaults to 500. Must be a positive integer. The oldest rows by `ts` are pruned on `put` once exceeded. */
   maxEntries?: number;
   /** Object-store name; defaults to `"query-cache"`. */
   storeName?: string;
@@ -512,28 +1140,22 @@ interface IndexedDbQueryCacheOptions {
  * environments should use {@link createInMemoryQueryCache}.
  */
 declare const createIndexedDbQueryCache: (options?: IndexedDbQueryCacheOptions) => QueryCacheAdapter;
-/**
- * Exponential backoff calculator with optional jitter.
- *
- * `next()` doubles the delay each call up to `maxDelayMs`. When `jitter` is
- * enabled the returned value is randomized in `[delay/2, delay]` so a fleet
- * of clients reconnecting at the same time spread out their retries.
- */
-interface ReconnectCalculator {
-  /** Returns the delay to wait before the next reconnect attempt. */
-  next: () => number;
-  /** Resets the backoff to the initial delay (call on successful reconnect). */
-  reset: () => void;
-}
-declare const createReconnect: (options?: ReconnectOptions, random?: () => number) => ReconnectCalculator;
 /**
  * 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.
  *
  * When the precondition is checked (on queue drain / reconnect) it re-reads the
- * query's current value via {@link LunoraClient.peekActiveQueryValue}. If the
- * value differs from what was captured at call time the precondition returns
- * `false` and the offline mutation is dropped as stale.
+ * query's current state via {@link LunoraClient.peekActiveQuerySnapshot}. The
+ * comparison only runs when a live subscription backed **both** reads; if either
+ * read found no active subscription (e.g. the originating component unmounted
+ * before replay, or a reconnect blanked it and it has not been answered again),
+ * the precondition returns `true` (not stale) because absence of a subscription
+ * is not evidence the value changed — the read simply cannot see it. When both reads did have a live subscription and the value differs, the
+ * precondition returns `false` and the offline mutation is dropped as stale.
+ *
+ * The offline queue does not evaluate it while the subscription is still waiting
+ * for its answer on a reconnected socket: the value it holds then is the previous
+ * socket's (or blank), so the write stays queued until the answer lands.
  * @example
  * ```ts
  * client.mutation(api.todos.update, { id, text }, {
@@ -542,92 +1164,4 @@ declare const createReconnect: (options?: ReconnectOptions, random?: () => numbe
  * ```
  */
 declare const createSnapshotPrecondition: (client: LunoraClient, functionRef: FunctionReference, args: Record<string, unknown>, shardKey?: string) => (() => boolean);
-/**
- * Client-side service-worker registration and lifecycle management.
- *
- * Usage:
- * ```ts
- * const sw = new ClientServiceWorker({ swUrl: "/sw.js" });
- * await sw.register();
- *
- * if (sw.active) {
- *   sw.postMessage({ type: "sync" });
- * }
- * ```
- */
-type ServiceWorkerStatus = "unsupported" | "unregistered" | "registering" | "active" | "error";
-interface ClientSwOptions {
-  /** Called when the status changes. */
-  onStatusChange?: (status: ServiceWorkerStatus) => void;
-  /** Optional registration scope. Defaults to `/`. */
-  scope?: string;
-  /** URL of the service worker script (relative to origin). */
-  swUrl: string;
-}
-/**
- * Manages service-worker registration and provides a simple API for
- * sending messages and listening for responses.
- */
-declare class ClientServiceWorker {
-  #private;
-  readonly swUrl: string;
-  readonly scope: string;
-  constructor(options: ClientSwOptions);
-  /** Current registration status. */
-  get status(): ServiceWorkerStatus;
-  /** The underlying `ServiceWorkerRegistration`, if registered. */
-  get registration(): ServiceWorkerRegistration | undefined;
-  /** Whether the SW is currently controlling this page. */
-  get active(): boolean;
-  /**
-   * Register the service worker.
-   *
-   * Returns `false` when the browser does not support service workers.
-   */
-  register(): Promise<boolean>;
-  /**
-   * Remove the active service worker registration and clear listeners.
-   *
-   * Returns `false` when no registration is currently held.
-   */
-  unregister(): Promise<boolean>;
-  /**
-   * Send a message to the active service worker.
-   */
-  postMessage(message: unknown): void;
-  /**
-   * Register a handler for messages **from** the service worker.
-   * @returns Unsubscribe function.
-   */
-  onMessage(handler: (event: MessageEvent) => void): () => void;
-}
-/**
- * Outbound message from the client to the SW.
- */
-interface ClientToSwMessage {
-  /** Opaque correlation ID for request/response patterns. */
-  correlationId?: string;
-  payload?: unknown;
-  type: string;
-}
-/**
- * Inbound message from the SW to the client.
- */
-interface SwToClientMessage {
-  /** Echoes the correlation ID from the client request, if any. */
-  correlationId?: string;
-  payload?: unknown;
-  type: string;
-}
-/**
- * Send a typed message to the service worker and optionally await a
- * matching response.
- * @returns A promise that resolves when the SW sends a reply with the
- * same `correlationId` (if `expectResponse` is true).
- */
-declare const sendToSw: (sw: ServiceWorker | null, message: ClientToSwMessage, expectResponse?: boolean) => Promise<unknown>;
-/**
- * Create a reply for a client message (call from inside the SW).
- */
-declare const createReply: (original: ClientToSwMessage, payload?: unknown) => SwToClientMessage;
-export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, ClientServiceWorker, type ClientSwOptions, type ClientToSwMessage, type FunctionReference, type HttpStreamArgsOf, type HttpStreamChunkOf, type HttpStreamOptions, type HttpStreamRef, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, LunoraClient, type MutationCallOptions, type MutationDelta, type MutationRunnerSinks, type MutatorHandle, type MutatorRunnerSinks, type MutatorTransaction, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, type ServiceWorkerStatus, type StreamIterable, type SubscriptionError, type SwToClientMessage, TabCoordinator, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createMutatorRunner, createReconnect, createReply, createSnapshotPrecondition, httpStream, isMutationDelta, queryCacheKey, sendToSw };
+export { type AsyncStorageLike, type AsyncStoragePersistenceOptions, type AsyncStorageQueryCacheOptions, type BookmarkStorage, CONFLICT_ERROR_CODE, type ConnectLiveStreamOptions, type ConnectionStatus, type FunctionReference, type HttpStreamArgsOf, type HttpStreamChunkOf, type HttpStreamOptions, type HttpStreamRef, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, type LiveStream, type LiveStreamEvent, type LiveStreamSubscribeError, type LiveStreamSubscribeOptions, type LiveTopicOptions, type LiveTopicRef, LunoraClient, type MutationDelta, type MutatorHandle, type MutatorRunnerSinks, type MutatorTransaction, OfflineQueue, type OfflineQueueOptions, type OptimisticMessage, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, RETIRE_AFTER_DURABLE_SEQ_ADVANCE, type ReconcileDurableMessage, type ReconnectCalculator, type ReconnectOptions, type StreamIterable, type SubscribeLiveTopicOptions, type SubscriptionError, TabCoordinator, TransportError, applyDelta, connectLiveStream, createAsyncStoragePersistence, createAsyncStorageQueryCache, createCallRunner, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutatorRunner, createReconnect, createSnapshotPrecondition, getErrorCode, getRetryAfterMs, httpStream, isAuthReplayFailure, isConflictError, isForbiddenError, isMutationDelta, isRateLimitedError, isUnauthorizedError, liveTopicSubscription, maxSeq, queryCacheKey, reconcileOptimistic, subscribeLiveTopic };