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

package/dist/index.d.mts

@@ -1,13 +1,104 @@
-import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-DzEWBYeP.mjs";
-export { type C as CachedQuery, type e as ClientMessage, type f as ClientShapeSubscribeMessage, type g as ClientShapeUnsubscribeMessage, type h as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type i as FunctionArgumentDescriptor, type j as FunctionDescriptor, type G as GlobalFacetResult, type k as GlobalFacetValue, type l as GlobalFilterClause, type m as GlobalTableInfo, type n as GlobalTablePage, L as LunoraClient, type o as LunoraClientOptions, type p as OptimisticLocalStore, type q as OptimisticUpdate, type r as OutboxMutation, type s as OutboxSink, type t as PersistedMutation, type P as Preloaded, type u as RowOp, type v as RpcEnvelope, type w as RpcResponseBody, type x as ScheduleRecord, type y as SchedulerPoolStatus, type z as SchedulerStatus, type E as ServerMessage, type H as ServerPokeEndMessage, type I as ServerPokePartMessage, type J as ServerPokeStartMessage, type K as ShardTrafficEntry, type N as ShardTrafficResult, type T as StorageListPage, type V as StorageObject, type W as StreamHandle, type X as StreamIterable, type Y as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, Z as SubscriptionRegistry, type _ as SubscriptionState, type $ as SyncWatermark, type a as Unsubscribe, type U as User, type a0 as WorkflowInstanceAction, type a1 as WorkflowInstanceDetail, type a2 as WorkflowInstancePage, type a3 as WorkflowInstanceStatus, type a4 as WorkflowInstanceSummary, type a5 as WorkflowStepDetail, a6 as createLocalStore, a7 as createStream } from "./packem_shared/lunora-client.d-DzEWBYeP.mjs";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-DuYqEQ5J.mjs";
-export type { AuthCapabilities, AuthImpersonation, AuthPage, AuthSession, AuthUser, CronJobInfo, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
-/**
-* 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
-* adapter needs. Matches `@react-native-async-storage/async-storage`'s core
-* surface, so you can pass the module straight in.
-*/
+import { o as PersistenceAdapter, Q as QueryCacheAdapter, B as BookmarkStorage, H as HttpStreamRef, m as HttpStreamArgsOf, n as HttpStreamChunkOf, O as OfflineQueueOptions, p as ReconnectOptions, F as FunctionReference } from "./packem_shared/types.d-BOB755CV.mjs";
+export type { A as ArgsOf, C as CachedQuery, q as ClientMessage, r as ClientShapeSubscribeMessage, s as ClientShapeUnsubscribeMessage, t as FunctionArgumentDescriptor, h as FunctionDescriptor, l as GlobalFacetResult, u as GlobalFacetValue, j as GlobalFilterClause, G as GlobalTableInfo, k as GlobalTablePage, v as HttpStreamCallArgs, L as LunoraClientOptions, w as OutboxMutation, x as OutboxSink, y as PersistedMutation, P as Preloaded, R as ReturnOf, z as RowOp, D as RpcEnvelope, E as RpcResponseBody, b as ScheduleRecord, I as SchedulerPoolStatus, c as SchedulerStatus, J as ServerMessage, K as ServerPokeEndMessage, M as ServerPokePartMessage, N as ServerPokeStartMessage, T as ShardTrafficEntry, S as ShardTrafficResult, i as StorageListPage, V as StorageObject, X as StoredQuery, a as Unsubscribe, U as User, g as WorkflowInstanceAction, f as WorkflowInstanceDetail, e as WorkflowInstancePage, d as WorkflowInstanceStatus, Y as WorkflowInstanceSummary, Z as WorkflowStepDetail, W as WsTokenProvider } from "./packem_shared/types.d-BOB755CV.mjs";
+import { C as ConnectionStatus, S as SubscriptionError, b as StreamIterable, L as LunoraClient } from "./packem_shared/lunora-client.d-CEJvJAXn.mjs";
+export { type A as ActionCallOptions, type B as BatchSlot, c as CONFLICT_ERROR_CODE, type d as ClientDebugShard, type e as ClientDebugSnapshot, type f as ClientDebugSubscription, type g as ClientQueryRef, D as DEFAULT_MAX_BUFFER, type h as LunoraClientError, type i as LunoraErrorCode, type M as MutationCallOptions, type j as MutationSettledEvent, type O as OptimisticLocalStore, type k as OptimisticUpdate, type l as StreamHandle, type m as SubscriptionCallback, type a as SubscriptionErrorCallback, n as SubscriptionRegistry, type o as SubscriptionState, type p as SyncWatermark, q as createClientQuery, r as createLocalStore, s as createStream, t as getErrorCode, u as getRetryAfterMs, v as isConflictError, w as isForbiddenError, x as isRateLimitedError, y as isUnauthorizedError } from "./packem_shared/lunora-client.d-CEJvJAXn.mjs";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-7lAyp-Ky.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';
+declare const anyApi: Record<string, Record<string, unknown>>;
+/**
+ * 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 globally-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 globally monotonic, not a positional count. Also the age baseline for
+   * the {@link RETIRE_AFTER_DURABLE_SEQ_ADVANCE} fallback.
+   */
+  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 globally
+ * monotonic, 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 — see plan 188).
+ *
+ * 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
+ * adapter needs. Matches `@react-native-async-storage/async-storage`'s core
+ * surface, so you can pass the module straight in.
+ */
 interface AsyncStorageLike {
   getItem: (key: string) => Promise<string | null>;
   removeItem: (key: string) => Promise<void>;
@@ -20,46 +111,325 @@ interface AsyncStoragePersistenceOptions {
   storage: AsyncStorageLike;
 }
 /**
-* 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.
-*
-* 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.
-*/
+ * 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.
+ *
+ * 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 pass through the transport's {@link encodeWire}/{@link decodeWire}
+ * codec, NOT raw `JSON.stringify`. What this cache holds is a decoded SERVER
+ * value — whatever the query returned, including the `bigint`, `Date`, `Map`,
+ * `Set`, `ArrayBuffer`/typed-array, and `NaN`/`Infinity` leaves `decodeWire`
+ * just reconstructed on the way in. Raw JSON would mangle every one of them
+ * (`Date` to a string, bytes to `{}`, `NaN` to `null`) or throw outright on a
+ * `bigint`, and nothing would ever repair it: a `resume` frame keeps the
+ * hydrated value as-is, so the damage would survive every reconnect and every
+ * delta merged onto it. The IndexedDB sibling gets this for free via structured
+ * clone; here it is explicit. (This is what separates the read cache from the
+ * outbox, which stores JSON-safe args the caller chose.)
+ *
+ * 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;
 /**
-* 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
-* dependency on it. `row` is absent on `delete` events (and may be absent on
-* older servers for any op).
-*/
+ * 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"`.
+   */
+  channelName?: string;
+  /**
+   * Interval (ms) between leader heartbeats. Defaults to 1000.
+   */
+  heartbeatInterval?: number;
+  /**
+   * Milliseconds without a heartbeat to consider the leader dead. Must be
+   * larger than `heartbeatInterval`. Defaults to 3000.
+   */
+  leaderTimeout?: number;
+  /**
+   * 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. `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
+   * `lunora-client.ts`'s `onSubscriptionData` wiring).
+   *
+   * `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, cursor?: number, epoch?: string, identity?: string | null) => void;
+  onSubscriptionError?: (key: string, error: SubscriptionError, identity?: string | null) => void;
+  /**
+   * 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).
+   */
+  onSubscriptionSettled?: (key: string, cursor?: number, epoch?: string, lastMutationId?: number, clientId?: string, identity?: string | null) => void;
+}
+declare class TabCoordinator {
+  private readonly bc;
+  private readonly tabId;
+  private readonly heartbeatInterval;
+  private readonly leaderTimeout;
+  /** The tab id of the current known leader, or `undefined` if no leader. */
+  private knownLeader;
+  /** `true` when this tab believes it is the leader. */
+  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;
+  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
+   * heartbeat/leader-check cycle. Safe to call multiple times.
+   */
+  start(): void;
+  /**
+   * Stop the coordinator: yield leadership (if held), close the channel, and
+   * clear all timers. Safe to call multiple times.
+   */
+  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. */
+  get id(): string;
+  /** `true` when the coordinator has been started and is not yet stopped. */
+  get isRunning(): boolean;
+  /**
+   * Broadcast subscription data to all follower tabs. Only the leader should
+   * 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, 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, 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;
+  private handleMessage;
+  private handleClaimLeadership;
+  private handleHeartbeat;
+  /**
+   * Resolve two leaders existing at once — e.g. this tab was backgrounded
+   * and its heartbeat/health timers were throttled while a foreground
+   * follower's were not, so the follower's `checkLeaderHealth` timed out
+   * the (still-alive) leader and self-promoted. `BroadcastChannel` message
+   * delivery isn't subject to the same timer-throttling clamp, so even a
+   * backgrounded leader eventually observes the pretender's heartbeat here
+   * — resolve the split-brain deterministically with the same
+   * lexicographically-smaller-tabId rule used at claim-adoption. If the
+   * other tab wins, step down; if we win, reassert immediately so the
+   * pretender demotes itself the moment it processes our heartbeat.
+   */
+  private resolveLeaderVsLeaderTieBreak;
+  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;
+}
+/**
+ * One row change as emitted by `@lunora/do`'s `broadcastDelta`. Mirrors
+ * `MutationDelta` in `@lunora/do` structurally so the client carries no
+ * dependency on it. `row` is absent on `delete` events (and may be absent on
+ * older servers for any op).
+ */
 interface MutationDelta {
   /** Row id (`_id`) the change applies to. */
   key: string;
@@ -68,98 +438,88 @@ interface MutationDelta {
   table: string;
 }
 /**
-* Structural guard: is `value` a `MutationDelta` the client knows how to merge?
-* We require `op`, `table`, and a string `key` so opaque payloads that merely
-* happen to be objects (e.g. an aggregate `{ count: 1 }` a query returns
-* verbatim) are never mistaken for a row delta and keep replacing the cached
-* value wholesale.
-*/
+ * Structural guard: is `value` a `MutationDelta` the client knows how to merge?
+ * We require `op`, `table`, and a string `key` so opaque payloads that merely
+ * happen to be objects (e.g. an aggregate `{ count: 1 }` a query returns
+ * verbatim) are never mistaken for a row delta and keep replacing the cached
+ * value wholesale.
+ */
 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
-* 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.
-*/
-declare const applyDelta: (current: unknown, delta: MutationDelta) => undefined | 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";
-};
-/** 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>>;
-}
+ * 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 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) => Record<string, unknown> | undefined | unknown[];
 /**
-* 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).
-*/
-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;
+ * Options accepted by {@link httpStream}.
+ * @experimental Part of the HTTP-SSE stream surface.
+ */
+interface HttpStreamOptions {
+  /**
+   * Origin (or origin + prefix) the route path is appended to, e.g.
+   * `https://my-app.example.com`. Defaults to `""` — a relative URL, which
+   * resolves against the page origin in a browser.
+   */
+  baseUrl?: string;
+  /** `fetch` implementation override; defaults to the global `fetch`. */
+  fetch?: typeof fetch;
+  /** Extra request headers (e.g. `authorization`). `accept: text/event-stream` is always sent. */
+  headers?: Record<string, string>;
+  /** Caps the in-flight chunk buffer (see `createStream`); exceeding it fails the stream. */
+  maxBuffer?: number;
+  /** External abort signal — aborting it cancels the fetch (→ the server handler's `signal`). */
+  signal?: AbortSignal;
 }
 /**
-* 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`.
-*/
-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>>);
-/**
-* The structural surface of a TanStack `Transaction` a bound custom mutator
-* returns — its `isPersisted.promise` resolves once the write is persisted and
-* rejects on failure. Typed structurally so the framework adapters need not
-* depend on `@tanstack/db` or `@lunora/db` (the handle is created app-side by
-* `bindMutators`).
-*/
+ * Open a typed HTTP-SSE stream route and iterate its chunks:
+ *
+ * ```ts
+ * const stream = httpStream(httpStreams.http.tokens, { searchParams: { prompt } }, { baseUrl });
+ * for await (const token of stream) {
+ *     render(token); // typed as the route handler's yielded chunk
+ * }
+ * ```
+ *
+ * The returned iterable terminates when the server writes `event: complete`;
+ * 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 structural surface of a TanStack `Transaction` a bound custom mutator
+ * returns — its `isPersisted.promise` resolves once the write is persisted and
+ * rejects on failure. Typed structurally so the framework adapters need not
+ * depend on `@tanstack/db` or `@lunora/db` (the handle is created app-side by
+ * `bindMutators`).
+ */
 interface MutatorTransaction {
   isPersisted: {
     promise: Promise<unknown>;
   };
 }
 /**
-* A bound custom-mutator handle produced by `bindMutators(client, ctx, mutators)`
-* in `@lunora/db`. Calling it applies the optimistic overlay to the local
-* collections and pushes the authoritative server write; it returns the TanStack
-* transaction whose `isPersisted` promise tracks completion.
-*/
+ * A bound custom-mutator handle produced by `bindMutators(client, ctx, mutators)`
+ * in `@lunora/db`. Calling it applies the optimistic overlay to the local
+ * collections and pushes the authoritative server write; it returns the TanStack
+ * transaction whose `isPersisted` promise tracks completion.
+ */
 type MutatorHandle<TArgs> = (args: TArgs) => MutatorTransaction;
 /**
-* 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.
-*/
+ * 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.
+ */
 interface MutatorRunnerSinks {
   /** Receives the normalized {@link Error} when an invocation rejects, or `undefined` on success / reset. */
   setError: (error: Error | undefined) => void;
@@ -167,38 +527,66 @@ interface MutatorRunnerSinks {
   setPending: (pending: boolean) => void;
 }
 /**
-* Build the framework-neutral `mutate` / `reset` pair of an adapter's
-* custom-mutator hook (`useMutator` / `createMutator` / `mutator`).
-*
-* Owns the orchestration every adapter otherwise copy-pastes: ref-counts
-* overlapping invocations into `setPending` (so it only clears once the last
-* settles), awaits the bound handle's `isPersisted` promise, normalizes a thrown
-* non-`Error`, and routes failure to `setError` (clearing it on success) before
-* re-throwing. Each adapter (`@lunora/react`, `/solid`, `/svelte`, `/vue`) binds
-* the two sinks to its own reactive setters, so this logic lives in exactly one
-* place. The optimistic overlay + server push are owned by the bound handle.
-*
-* `error` tracks 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 only writes `setError` while it is still the most recent one — otherwise
-* `error`/`isError` could surface a stale success or failure (the documented
-* "latest invocation's error" contract every adapter advertises).
-*/
+ * Build the framework-neutral `mutate` / `reset` pair of an adapter's
+ * custom-mutator hook (`useMutator` / `createMutator` / `mutator`).
+ *
+ * Owns the orchestration every adapter otherwise copy-pastes: ref-counts
+ * overlapping invocations into `setPending` (so it only clears once the last
+ * settles), awaits the bound handle's `isPersisted` promise, normalizes a thrown
+ * non-`Error`, and routes failure to `setError` (clearing it on success) before
+ * re-throwing. Each adapter (`@lunora/react`, `/solid`, `/svelte`, `/vue`) binds
+ * the two sinks to its own reactive setters, so this logic lives in exactly one
+ * place. The optimistic overlay + server push are owned by the bound handle.
+ *
+ * `error` tracks 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 only writes `setError` while it is still the most recent one — otherwise
+ * `error`/`isError` could surface a stale success or failure (the documented
+ * "latest invocation's error" contract every adapter advertises).
+ */
 declare const createMutatorRunner: <TArgs>(handle: MutatorHandle<TArgs>, sinks: MutatorRunnerSinks) => {
   mutate: (args: TArgs) => Promise<void>;
   reset: () => void;
 };
 interface QueuedMutation<T = unknown> {
   readonly args: Record<string, unknown>;
+  /**
+   * 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.
-  */
+   * Issuing identity fingerprint carried through to durable storage (`null` =
+   * signed out). Absent on hydrated legacy records, which replay ambiently.
+   */
   readonly identity?: string | null;
+  /**
+   * `true` when a live caller is still awaiting this write's `mutation()`
+   * Promise; `false`/absent for a write restored from durable storage after a
+   * reload (its original awaiter is gone). Carried so terminal-verdict
+   * observers can distinguish "the caller already saw this" from "nothing else
+   * will report this". Maps to the public `MutationSettledEvent.hadAwaiter`.
+   */
+  liveAwaiter?: boolean;
+  /**
+   * Invoked on a successful replay with the server's echoed commit CDC cursor,
+   * so a live per-call optimistic layer drops gaplessly once a frame reaches it.
+   * Absent on hydrated records (the optimistic write lived in a prior session).
+   */
+  readonly onCommit?: (commitCursor: number | undefined) => void;
+  /**
+   * Optional sync predicate evaluated just before replay. When it returns
+   * `false` the write is dropped instead of replaying, handling the case
+   * where the mutation's preconditions are no longer valid (e.g. the
+   * document it referred to was deleted while offline). Absent or `true`
+   * means "ok to replay".
+   */
+  readonly precondition?: () => boolean;
   /** Rejects if the mutation can no longer be replayed. */
   readonly reject: (error: unknown) => void;
   /** Resolves once the mutation has been replayed against the server. */
@@ -206,71 +594,124 @@ interface QueuedMutation<T = unknown> {
   readonly shardKey?: string;
 }
 /**
-* A process-unique id, used both per-mutation and as the fallback `clientId`. It
-* MUST be globally unique: the server scopes a custom mutator's replay watermark
-* by `(verifiedIdentity, clientId)`, and an anonymous push has no verified
-* identity — so two anonymous clients that collide on `clientId` would share one
-* watermark namespace, letting one stall/suppress the other's ordered mutations.
-* `crypto.randomUUID` covers every modern runtime; the fallback still mixes
-* crypto-quality (or `Math.random`) entropy with the timestamp + counter so it
-* can't collide across two clients started in the same millisecond.
-*/
-/**
-* Bounded FIFO queue. Mutations issued while the client is offline are
-* enqueued and replayed in the order they were submitted once the WS
-* reconnects and identifies. If the queue exceeds `maxItems` the oldest
-* entry is rejected with `OFFLINE_QUEUE_OVERFLOW`.
-*
-* When a {@link PersistenceAdapter} is supplied, enqueued mutations are mirrored
-* to durable storage so they survive a reload — {@link OfflineQueue.hydrate} restores them on
-* the next startup and the client replays them on reconnect. Durable removal is
-* the caller's responsibility *after* a successful replay (see `LunoraClient`);
-* the queue only persists on enqueue and un-persists on overflow.
-*/
+ * Invoked when the queue itself discards an entry on overflow (capacity
+ * 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;
+}) => void;
+/** Injected dependencies for {@link OfflineQueue} (kept off the user-facing {@link OfflineQueueOptions}). */
+interface OfflineQueueDeps {
+  /** Invoked when an entry is discarded on capacity overflow (carries `OFFLINE_QUEUE_OVERFLOW`). */
+  onEvict?: EvictHandler;
+  /** 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. */
+  persistence?: PersistenceAdapter;
+  /** App/schema version stamped on persisted writes; mismatched records are purged on hydrate. */
+  version?: string;
+}
+/**
+ * Bounded FIFO queue. Mutations issued while the client is offline are
+ * enqueued and replayed in the order they were submitted once the WS
+ * reconnects and identifies. If the queue exceeds `maxItems` the oldest
+ * entry is rejected with `OFFLINE_QUEUE_OVERFLOW`.
+ *
+ * When a {@link PersistenceAdapter} is supplied, enqueued mutations are mirrored
+ * to durable storage so they survive a reload — {@link OfflineQueue.hydrate} restores them on
+ * the next startup and the client replays them on reconnect. Durable removal is
+ * the caller's responsibility *after* a successful replay (see `LunoraClient`);
+ * the queue only persists on enqueue and un-persists on overflow.
+ */
 declare class OfflineQueue {
   /** Opt-in to queueing mutations before the targeted shard's first connect. */
   readonly queueBeforeFirstConnect: boolean;
   private readonly maxItems;
   private readonly onPersistenceError;
   private readonly persistence;
+  private readonly onEvict;
+  private readonly onSizeChange;
+  /** App/schema version stamped on persisted writes; mismatched records are purged on hydrate. */
+  private readonly version;
   private readonly items;
-  constructor(options?: OfflineQueueOptions, persistence?: PersistenceAdapter);
+  constructor(options?: OfflineQueueOptions, deps?: OfflineQueueDeps);
   get size(): number;
   enqueue<T>(entry: QueuedMutation<T>): 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
-  * re-appended; they carry no-op `resolve`/`reject` (the original awaiter is
-  * gone after a reload). No-op when no persistence adapter is configured.
-  * Returns the distinct shard keys of the restored writes so the caller can
-  * open their sockets to trigger a flush.
-  */
+   * 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
+   * re-appended; they carry no-op `resolve`/`reject` (the original awaiter is
+   * gone after a reload). No-op when no persistence adapter is configured.
+   * Returns the distinct shard keys of the restored writes so the caller can
+   * open their sockets to trigger a flush.
+   *
+   * `hydrate()` runs post-construction (the caller awaits an async durable-store
+   * load), so a mutation issued while offline during that boot window is
+   * enqueued into `items` *before* this method's `await` resolves. Restored
+   * records are therefore `unshift`-ed ahead of whatever is already queued
+   * rather than `push`-ed to the end: the durable store's persist order is
+   * authoritative (a prior-session write is always older than anything from
+   * this session), so replaying a same-session boot-time write before an
+   * older restored write on the same document would let last-writer-wins
+   * silently clobber the newer data with the stale one.
+   */
   hydrate(): Promise<(string | undefined)[]>;
   /**
-  * Remove and return queued mutations. With no `predicate`, drains the whole
-  * queue. With one, drains only matching entries (preserving FIFO order) and
-  * leaves the rest queued — used to flush a single shard's writes when its
-  * socket reconnects while other shards are still down.
-  */
+   * Remove and return queued mutations. With no `predicate`, drains the whole
+   * queue. With one, drains only matching entries (preserving FIFO order) and
+   * leaves the rest queued — used to flush a single shard's writes when its
+   * socket reconnects while other shards are still down.
+   */
   drain(predicate?: (item: QueuedMutation) => boolean): QueuedMutation[];
   /**
-  * Return previously-drained mutations to the front of the queue, preserving
-  * their FIFO order, without re-persisting them — they were never unpersisted,
-  * so durable storage still holds them. Used when a flush aborts on a transient
-  * transport failure: the unreplayed writes stay queued for the next reconnect.
-  */
+   * Return previously-drained mutations to the front of the queue, preserving
+   * their FIFO order, without re-persisting them — they were never unpersisted,
+   * so durable storage still holds them. Used when a flush aborts on a transient
+   * transport failure: the unreplayed writes stay queued for the next reconnect.
+   */
   requeue(items: QueuedMutation[]): void;
+  /**
+   * Remove mutations whose precondition evaluates to `false` (stale/dirty
+   * writes that should not replay) and reject each with an
+   * `OFFLINE_PRECONDITION_FAILED` error. The valid (admitted) mutations stay
+   * queued in FIFO order. Returns the drained stale entries.
+   *
+   * Called during reconnect before the flush cycle to weed out writes whose
+   * assumptions no longer hold (e.g. a document was deleted by another client).
+   */
+  drainConflict(): QueuedMutation[];
   clear(): void;
+  /**
+   * 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;
+  /** Notify the size observer (the client's pending-sync count) after any change. */
+  private notifySize;
 }
 /**
-* In-memory {@link PersistenceAdapter}. Doesn't survive a reload — it exists so
-* the persistence wiring can be exercised without IndexedDB (tests, SSR, or as
-* a deliberate "no durable store" choice that still satisfies the interface).
-* Preserves enqueue order; `clone` keeps callers from mutating stored args.
-*/
+ * In-memory {@link PersistenceAdapter}. Doesn't survive a reload — it exists so
+ * the persistence wiring can be exercised without IndexedDB (tests, SSR, or as
+ * a deliberate "no durable store" choice that still satisfies the interface).
+ * Preserves enqueue order; `clone` keeps callers from mutating stored args.
+ */
 declare const createInMemoryPersistence: () => PersistenceAdapter;
 interface IndexedDbPersistenceOptions {
-  /** Database name; defaults to `"lunora"`. */
+  /** Database name; defaults to `"lunora-outbox"` (its own DB, separate from the read cache). */
   databaseName?: string;
   /** Injectable `IDBFactory` (e.g. `fake-indexeddb` in tests); defaults to the global `indexedDB`. */
   indexedDB?: IDBFactory;
@@ -278,62 +719,62 @@ interface IndexedDbPersistenceOptions {
   storeName?: string;
 }
 /**
-* IndexedDB-backed {@link PersistenceAdapter}. Each mutation is stored under an
-* autoincrementing key (so `load()` returns them in enqueue order regardless of
-* the string ids) with a unique secondary index on `id` for `remove()`.
-*
-* The store handle is opened lazily and the open promise is cached, so repeated
-* ops reuse one connection. Throws eagerly if no `IDBFactory` is available —
-* callers in non-browser environments should use {@link createInMemoryPersistence}.
-*/
+ * IndexedDB-backed {@link PersistenceAdapter}. Each mutation is stored under an
+ * autoincrementing key (so `load()` returns them in enqueue order regardless of
+ * the string ids) with a unique secondary index on `id` for `remove()`.
+ *
+ * The store handle is opened lazily and the open promise is cached, so repeated
+ * ops reuse one connection. Throws eagerly if no `IDBFactory` is available —
+ * callers in non-browser environments should use {@link createInMemoryPersistence}.
+ */
 declare const createIndexedDbPersistence: (options?: IndexedDbPersistenceOptions) => PersistenceAdapter;
 /**
-* Compose the read-cache key for a subscription. Mirrors how
-* `SubscriptionRegistry` keys live subscriptions so a hydrated value lines up
-* with the subscription that will consume it. `shardKey` defaults to `""` (the
-* root shard) exactly as the registry does.
-*/
+ * Compose the read-cache key for a subscription. Mirrors how
+ * `SubscriptionRegistry` keys live subscriptions so a hydrated value lines up
+ * with the subscription that will consume it. `shardKey` defaults to `""` (the
+ * root shard) exactly as the registry does.
+ */
 declare const queryCacheKey: (functionPath: string, argsKey: string, shardKey?: string) => string;
 /**
-* In-memory {@link QueryCacheAdapter}. Doesn't survive a reload — it exists so
-* the read-cache wiring can be exercised without IndexedDB (tests, SSR, or as a
-* deliberate "no durable store" choice that still satisfies the interface).
-* Enforces the same LRU row cap as the IndexedDB adapter; `clone` keeps callers
-* from mutating stored values.
-*/
+ * In-memory {@link QueryCacheAdapter}. Doesn't survive a reload — it exists so
+ * the read-cache wiring can be exercised without IndexedDB (tests, SSR, or as a
+ * deliberate "no durable store" choice that still satisfies the interface).
+ * Enforces the same LRU row cap as the IndexedDB adapter; `clone` keeps callers
+ * from mutating stored values.
+ */
 declare const createInMemoryQueryCache: (options?: {
   maxEntries?: number;
 }) => QueryCacheAdapter;
 interface IndexedDbQueryCacheOptions {
-  /** Database name; defaults to `"lunora"` (shared with the offline-mutation store). */
+  /** Database name; defaults to `"lunora-query-cache"` (its own DB, separate from the offline outbox). */
   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;
 }
 /**
-* IndexedDB-backed {@link QueryCacheAdapter}. Each query is stored under its
-* composite key (`functionPath::argsKey::shardKey`) with a `ts` index driving
-* LRU eviction. The store handle is opened lazily and cached, so repeated ops
-* reuse one connection.
-*
-* The store lives in the same `lunora` database as the offline-mutation queue
-* (bumped to schema v2). Opening it upgrades a v1 database in place, adding the
-* `query-cache` store without touching `offline-mutations`. Throws eagerly if no
-* `IDBFactory` is available — callers in non-browser environments should use
-* {@link createInMemoryQueryCache}.
-*/
+ * IndexedDB-backed {@link QueryCacheAdapter}. Each query is stored under its
+ * composite key (`functionPath::argsKey::shardKey`) with a `ts` index driving
+ * LRU eviction. The store handle is opened lazily and cached, so repeated ops
+ * reuse one connection.
+ *
+ * The store lives in its own `lunora-query-cache` database — deliberately
+ * separate from the offline-mutation outbox's `lunora-outbox` database so the two
+ * independently-toggleable adapters never share (and drift on) a schema version.
+ * Throws eagerly if no `IDBFactory` is available — callers in non-browser
+ * 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.
-*/
+ * 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;
@@ -341,4 +782,112 @@ interface ReconnectCalculator {
   reset: () => void;
 }
 declare const createReconnect: (options?: ReconnectOptions, random?: () => number) => ReconnectCalculator;
-export { type ArgsOf, type AsyncStorageLike, type AsyncStoragePersistenceOptions, type BookmarkStorage, CONFLICT_ERROR_CODE, type FunctionReference, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, 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, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createMutatorRunner, createReconnect, isConflictError, isMutationDelta, queryCacheKey };
+/**
+ * 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 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), 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.
+ * @example
+ * ```ts
+ * client.mutation(api.todos.update, { id, text }, {
+ *   precondition: createSnapshotPrecondition(client, api.todos.list, { userId }),
+ * });
+ * ```
+ */
+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 AsyncStorageLike, type AsyncStoragePersistenceOptions, type AsyncStorageQueryCacheOptions, type BookmarkStorage, ClientServiceWorker, type ClientSwOptions, type ClientToSwMessage, type ConnectionStatus, type FunctionReference, type HttpStreamArgsOf, type HttpStreamChunkOf, type HttpStreamOptions, type HttpStreamRef, type IndexedDbPersistenceOptions, type IndexedDbQueryCacheOptions, 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 ServiceWorkerStatus, type StreamIterable, type SubscriptionError, type SwToClientMessage, TabCoordinator, anyApi, applyDelta, createAsyncStoragePersistence, createAsyncStorageQueryCache, createCallRunner, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutatorRunner, createReconnect, createReply, createSnapshotPrecondition, httpStream, isMutationDelta, maxSeq, queryCacheKey, reconcileOptimistic, sendToSw };