@lunora/client 1.0.0-alpha.1 → 1.0.0-alpha.11

package/dist/auth/index.d.mts

@@ -1,4 +1,4 @@
-import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-DGvyuJ_p.mjs";
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-Dm1BYq19.mjs";
 import '@lunora/runtime';
 interface IdentityStore {
   /** Read the current resolved user, or `null` when signed out / not yet resolved. */

package/dist/auth/index.d.ts

@@ -1,4 +1,4 @@
-import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-DGvyuJ_p.js";
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-Dm1BYq19.js";
 import '@lunora/runtime';
 interface IdentityStore {
   /** Read the current resolved user, or `null` when signed out / not yet resolved. */

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-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-DGvyuJ_p.mjs";
-export { type C as CachedQuery, type e as ClientMessage, type f as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type g as FunctionArgumentDescriptor, type h as FunctionDescriptor, type G as GlobalFacetResult, type i as GlobalFacetValue, type j as GlobalFilterClause, type k as GlobalTableInfo, type l as GlobalTablePage, L as LunoraClient, type m as LunoraClientOptions, type n as OptimisticLocalStore, type o as OptimisticUpdate, type p as PersistedMutation, type P as Preloaded, type q as RpcEnvelope, type r as RpcResponseBody, type s as ScheduleRecord, type t as SchedulerPoolStatus, type u as SchedulerStatus, type v as ServerMessage, type w as ShardTrafficEntry, type x as ShardTrafficResult, type y as StorageListPage, type z as StorageObject, type E as StreamHandle, type H as StreamIterable, type I as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, J as SubscriptionRegistry, type K as SubscriptionState, type a as Unsubscribe, type U as User, type W as WorkflowInstanceAction, type N as WorkflowInstanceDetail, type T as WorkflowInstancePage, type V as WorkflowInstanceStatus, type X as WorkflowInstanceSummary, type Y as WorkflowStepDetail, Z as createLocalStore, _ as createStream } from "./packem_shared/lunora-client.d-DGvyuJ_p.mjs";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-dSaRMuhL.mjs";
+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-Dm1BYq19.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 MutationSettledEvent, type q as OptimisticLocalStore, type r as OptimisticUpdate, type s as OutboxMutation, type t as OutboxSink, type u as PersistedMutation, type P as Preloaded, type v as RowOp, type w as RpcEnvelope, type x as RpcResponseBody, type y as ScheduleRecord, type z as SchedulerPoolStatus, type E as SchedulerStatus, type H as ServerMessage, type I as ServerPokeEndMessage, type J as ServerPokePartMessage, type K as ServerPokeStartMessage, type N as ShardTrafficEntry, type T as ShardTrafficResult, type V as StorageListPage, type W as StorageObject, type X as StreamHandle, type Y as StreamIterable, type Z as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, _ as SubscriptionRegistry, type $ as SubscriptionState, type a0 as SyncWatermark, type a as Unsubscribe, type U as User, type a1 as WorkflowInstanceAction, type a2 as WorkflowInstanceDetail, type a3 as WorkflowInstancePage, type a4 as WorkflowInstanceStatus, type a5 as WorkflowInstanceSummary, type a6 as WorkflowStepDetail, a7 as createLocalStore, a8 as createStream } from "./packem_shared/lunora-client.d-Dm1BYq19.mjs";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-BfWzGJWV.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 —
@@ -136,6 +136,59 @@ interface MutationRunnerSinks<R> {
 * 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`).
+*/
+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.
+*/
+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.
+*/
+interface MutatorRunnerSinks {
+  /** Receives the normalized {@link Error} when an invocation rejects, or `undefined` on success / reset. */
+  setError: (error: Error | undefined) => void;
+  /** Receives `true` while at least one invocation is in flight (ref-counted across overlapping calls), else `false`. */
+  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).
+*/
+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>;
   readonly functionPath: string;
@@ -146,12 +199,57 @@ interface QueuedMutation<T = unknown> {
   * 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;
   /** Rejects if the mutation can no longer be replayed. */
   readonly reject: (error: unknown) => void;
   /** Resolves once the mutation has been replayed against the server. */
   readonly resolve: (value: T) => void;
   readonly shardKey?: string;
 }
+/**
+* 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.
+*/
+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;
+}
+/**
+* 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
@@ -170,8 +268,12 @@ declare class OfflineQueue {
   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;
   /**
@@ -198,6 +300,8 @@ declare class OfflineQueue {
   */
   requeue(items: QueuedMutation[]): void;
   clear(): void;
+  /** 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
@@ -225,6 +329,24 @@ interface IndexedDbPersistenceOptions {
 */
 declare const createIndexedDbPersistence: (options?: IndexedDbPersistenceOptions) => PersistenceAdapter;
 /**
+* Resolve the effective offline-queue persistence from the user option,
+* defaulting to a durable IndexedDB store when the environment supports one.
+*
+* An explicit adapter is used as-is; `false` opts out (the caller keeps an
+* in-memory queue, lost on reload); `undefined` (the default) auto-probes
+* IndexedDB when the global is present (browsers) and `autoProbe` is set,
+* otherwise `undefined` — so SSR/Node/React-Native keep today's in-memory
+* behaviour and only environments that can persist do.
+*
+* `autoProbe` is `false` when the `@lunora/db` outbox is wired: that sink is the
+* single durable write path, so the built-in queue must stay in memory rather
+* than persist a second, never-flushed copy. An explicit adapter is still
+* honoured (the caller asked for it); only the implicit default is suppressed.
+*
+* The IndexedDB adapter opens its connection lazily, so constructing it here is
+* cheap and never throws (the `indexedDB` global is verified present first).
+*/
+/**
 * 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
@@ -265,6 +387,15 @@ interface IndexedDbQueryCacheOptions {
 */
 declare const createIndexedDbQueryCache: (options?: IndexedDbQueryCacheOptions) => QueryCacheAdapter;
 /**
+* Resolve the effective read-cache from the user option, defaulting to a durable
+* IndexedDB store when the environment supports one. Same tri-state semantics as
+* `resolvePersistenceAdapter` in `./persistence`:
+*
+* - an explicit adapter is used as-is;
+* - `false` opts out — reads stay in memory only;
+* - `undefined` (the default) auto-probes IndexedDB (browsers), else `undefined`.
+*/
+/**
 * Exponential backoff calculator with optional jitter.
 *
 * `next()` doubles the delay each call up to `maxDelayMs`. When `jitter` is
@@ -278,4 +409,4 @@ 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, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createReconnect, isConflictError, isMutationDelta, queryCacheKey };
+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 };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-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-DGvyuJ_p.js";
-export { type C as CachedQuery, type e as ClientMessage, type f as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type g as FunctionArgumentDescriptor, type h as FunctionDescriptor, type G as GlobalFacetResult, type i as GlobalFacetValue, type j as GlobalFilterClause, type k as GlobalTableInfo, type l as GlobalTablePage, L as LunoraClient, type m as LunoraClientOptions, type n as OptimisticLocalStore, type o as OptimisticUpdate, type p as PersistedMutation, type P as Preloaded, type q as RpcEnvelope, type r as RpcResponseBody, type s as ScheduleRecord, type t as SchedulerPoolStatus, type u as SchedulerStatus, type v as ServerMessage, type w as ShardTrafficEntry, type x as ShardTrafficResult, type y as StorageListPage, type z as StorageObject, type E as StreamHandle, type H as StreamIterable, type I as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, J as SubscriptionRegistry, type K as SubscriptionState, type a as Unsubscribe, type U as User, type W as WorkflowInstanceAction, type N as WorkflowInstanceDetail, type T as WorkflowInstancePage, type V as WorkflowInstanceStatus, type X as WorkflowInstanceSummary, type Y as WorkflowStepDetail, Z as createLocalStore, _ as createStream } from "./packem_shared/lunora-client.d-DGvyuJ_p.js";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-BoDmFqSG.js";
+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-Dm1BYq19.js";
+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 MutationSettledEvent, type q as OptimisticLocalStore, type r as OptimisticUpdate, type s as OutboxMutation, type t as OutboxSink, type u as PersistedMutation, type P as Preloaded, type v as RowOp, type w as RpcEnvelope, type x as RpcResponseBody, type y as ScheduleRecord, type z as SchedulerPoolStatus, type E as SchedulerStatus, type H as ServerMessage, type I as ServerPokeEndMessage, type J as ServerPokePartMessage, type K as ServerPokeStartMessage, type N as ShardTrafficEntry, type T as ShardTrafficResult, type V as StorageListPage, type W as StorageObject, type X as StreamHandle, type Y as StreamIterable, type Z as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, _ as SubscriptionRegistry, type $ as SubscriptionState, type a0 as SyncWatermark, type a as Unsubscribe, type U as User, type a1 as WorkflowInstanceAction, type a2 as WorkflowInstanceDetail, type a3 as WorkflowInstancePage, type a4 as WorkflowInstanceStatus, type a5 as WorkflowInstanceSummary, type a6 as WorkflowStepDetail, a7 as createLocalStore, a8 as createStream } from "./packem_shared/lunora-client.d-Dm1BYq19.js";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-Sp_Ef-_u.js";
 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 —
@@ -136,6 +136,59 @@ interface MutationRunnerSinks<R> {
 * 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`).
+*/
+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.
+*/
+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.
+*/
+interface MutatorRunnerSinks {
+  /** Receives the normalized {@link Error} when an invocation rejects, or `undefined` on success / reset. */
+  setError: (error: Error | undefined) => void;
+  /** Receives `true` while at least one invocation is in flight (ref-counted across overlapping calls), else `false`. */
+  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).
+*/
+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>;
   readonly functionPath: string;
@@ -146,12 +199,57 @@ interface QueuedMutation<T = unknown> {
   * 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;
   /** Rejects if the mutation can no longer be replayed. */
   readonly reject: (error: unknown) => void;
   /** Resolves once the mutation has been replayed against the server. */
   readonly resolve: (value: T) => void;
   readonly shardKey?: string;
 }
+/**
+* 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.
+*/
+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;
+}
+/**
+* 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
@@ -170,8 +268,12 @@ declare class OfflineQueue {
   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;
   /**
@@ -198,6 +300,8 @@ declare class OfflineQueue {
   */
   requeue(items: QueuedMutation[]): void;
   clear(): void;
+  /** 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
@@ -225,6 +329,24 @@ interface IndexedDbPersistenceOptions {
 */
 declare const createIndexedDbPersistence: (options?: IndexedDbPersistenceOptions) => PersistenceAdapter;
 /**
+* Resolve the effective offline-queue persistence from the user option,
+* defaulting to a durable IndexedDB store when the environment supports one.
+*
+* An explicit adapter is used as-is; `false` opts out (the caller keeps an
+* in-memory queue, lost on reload); `undefined` (the default) auto-probes
+* IndexedDB when the global is present (browsers) and `autoProbe` is set,
+* otherwise `undefined` — so SSR/Node/React-Native keep today's in-memory
+* behaviour and only environments that can persist do.
+*
+* `autoProbe` is `false` when the `@lunora/db` outbox is wired: that sink is the
+* single durable write path, so the built-in queue must stay in memory rather
+* than persist a second, never-flushed copy. An explicit adapter is still
+* honoured (the caller asked for it); only the implicit default is suppressed.
+*
+* The IndexedDB adapter opens its connection lazily, so constructing it here is
+* cheap and never throws (the `indexedDB` global is verified present first).
+*/
+/**
 * 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
@@ -265,6 +387,15 @@ interface IndexedDbQueryCacheOptions {
 */
 declare const createIndexedDbQueryCache: (options?: IndexedDbQueryCacheOptions) => QueryCacheAdapter;
 /**
+* Resolve the effective read-cache from the user option, defaulting to a durable
+* IndexedDB store when the environment supports one. Same tri-state semantics as
+* `resolvePersistenceAdapter` in `./persistence`:
+*
+* - an explicit adapter is used as-is;
+* - `false` opts out — reads stay in memory only;
+* - `undefined` (the default) auto-probes IndexedDB (browsers), else `undefined`.
+*/
+/**
 * Exponential backoff calculator with optional jitter.
 *
 * `next()` doubles the delay each call up to `maxDelayMs`. When `jitter` is
@@ -278,4 +409,4 @@ 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, OfflineQueue, type OfflineQueueOptions, type PersistenceAdapter, type QueryCacheAdapter, type QueuedMutation, type ReconnectCalculator, type ReconnectOptions, type ReturnOf, applyDelta, createAsyncStoragePersistence, createInMemoryBookmarkStorage, createInMemoryPersistence, createInMemoryQueryCache, createIndexedDbPersistence, createIndexedDbQueryCache, createMutationRunner, createReconnect, isConflictError, isMutationDelta, queryCacheKey };
+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 };

package/dist/index.mjs

@@ -2,13 +2,14 @@ export { createAsyncStoragePersistence } from './packem_shared/createAsyncStorag
 export { default as createInMemoryBookmarkStorage } from './packem_shared/createInMemoryBookmarkStorage-BoN7a7TH.mjs';
 export { applyDelta, isMutationDelta } from './packem_shared/applyDelta-4jFGTPA3.mjs';
 export { CONFLICT_ERROR_CODE, isConflictError } from './packem_shared/CONFLICT_ERROR_CODE-aUdVbEDw.mjs';
-export { createLocalStore } from './packem_shared/createLocalStore-DSUfoLqY.mjs';
-export { LunoraClient } from './packem_shared/LunoraClient-B00f7VUM.mjs';
+export { c as createLocalStore } from './packem_shared/local-store-BNgN3Dw3.mjs';
+export { LunoraClient } from './packem_shared/LunoraClient-6J-4BGWK.mjs';
 export { createMutationRunner } from './packem_shared/createMutationRunner-BqsavzvG.mjs';
-export { OfflineQueue } from './packem_shared/OfflineQueue-D5p_QgF_.mjs';
-export { createInMemoryPersistence, createIndexedDbPersistence } from './packem_shared/createIndexedDbPersistence-CW82inU5.mjs';
+export { createMutatorRunner } from './packem_shared/createMutatorRunner-BETvCd0p.mjs';
+export { O as OfflineQueue } from './packem_shared/offline-queue-7Wc4onA0.mjs';
+export { createInMemoryPersistence, createIndexedDbPersistence } from './packem_shared/createInMemoryPersistence-DlFjWtOm.mjs';
 export { preloadQuery, preloadedQueryResult } from './packem_shared/preloadQuery-lobFkD2Z.mjs';
-export { createInMemoryQueryCache, createIndexedDbQueryCache, queryCacheKey } from './packem_shared/createIndexedDbQueryCache-B1PQ9Twl.mjs';
+export { createInMemoryQueryCache, createIndexedDbQueryCache, queryCacheKey } from './packem_shared/createInMemoryQueryCache-4AkTV38-.mjs';
 export { createReconnect } from './packem_shared/createReconnect-Di_-oHH7.mjs';
-export { DEFAULT_MAX_BUFFER, createStream } from './packem_shared/createStream-BDkqO5PW.mjs';
-export { SubscriptionRegistry } from './packem_shared/SubscriptionRegistry-B-Qx_Gux.mjs';
+export { DEFAULT_MAX_BUFFER, createStream } from './packem_shared/DEFAULT_MAX_BUFFER-BDkqO5PW.mjs';
+export { S as SubscriptionRegistry } from './packem_shared/subscription-C1Jy7HiF.mjs';