@lunora/client 1.0.0-alpha.7 → 1.0.0-alpha.9

package/dist/auth/index.d.mts

@@ -1,4 +1,4 @@
-import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-DLbxPGH9.mjs";
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-CfwxuJo8.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-DLbxPGH9.js";
+import { U as User, L as LunoraClient } from "../packem_shared/lunora-client.d-CfwxuJo8.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-DLbxPGH9.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-DLbxPGH9.mjs";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-BAT6GeSD.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-CfwxuJo8.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-CfwxuJo8.mjs";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-Bbn8plix.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 —
@@ -199,6 +199,20 @@ 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. */
@@ -206,6 +220,15 @@ interface QueuedMutation<T = unknown> {
   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;
+/**
 * 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
@@ -215,6 +238,7 @@ interface QueuedMutation<T = unknown> {
 * 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
@@ -233,8 +257,9 @@ declare class OfflineQueue {
   private readonly maxItems;
   private readonly onPersistenceError;
   private readonly persistence;
+  private readonly onEvict;
   private readonly items;
-  constructor(options?: OfflineQueueOptions, persistence?: PersistenceAdapter);
+  constructor(options?: OfflineQueueOptions, persistence?: PersistenceAdapter, onEvict?: EvictHandler);
   get size(): number;
   enqueue<T>(entry: QueuedMutation<T>): void;
   /**

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-DLbxPGH9.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 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-DLbxPGH9.js";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-CSkjbfEq.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-CfwxuJo8.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-CfwxuJo8.js";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-DuMetDdU.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 —
@@ -199,6 +199,20 @@ 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. */
@@ -206,6 +220,15 @@ interface QueuedMutation<T = unknown> {
   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;
+/**
 * 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
@@ -215,6 +238,7 @@ interface QueuedMutation<T = unknown> {
 * 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
@@ -233,8 +257,9 @@ declare class OfflineQueue {
   private readonly maxItems;
   private readonly onPersistenceError;
   private readonly persistence;
+  private readonly onEvict;
   private readonly items;
-  constructor(options?: OfflineQueueOptions, persistence?: PersistenceAdapter);
+  constructor(options?: OfflineQueueOptions, persistence?: PersistenceAdapter, onEvict?: EvictHandler);
   get size(): number;
   enqueue<T>(entry: QueuedMutation<T>): void;
   /**

package/dist/index.mjs

@@ -2,11 +2,11 @@ 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-Bsv8immC.mjs';
+export { c as createLocalStore } from './packem_shared/local-store-BNgN3Dw3.mjs';
+export { LunoraClient } from './packem_shared/LunoraClient-C4eFp92b.mjs';
 export { createMutationRunner } from './packem_shared/createMutationRunner-BqsavzvG.mjs';
 export { createMutatorRunner } from './packem_shared/createMutatorRunner-BETvCd0p.mjs';
-export { OfflineQueue } from './packem_shared/OfflineQueue-D-ASeqL7.mjs';
+export { OfflineQueue } from './packem_shared/OfflineQueue-eJBiWPfg.mjs';
 export { createInMemoryPersistence, createIndexedDbPersistence } from './packem_shared/createInMemoryPersistence-CW82inU5.mjs';
 export { preloadQuery, preloadedQueryResult } from './packem_shared/preloadQuery-lobFkD2Z.mjs';
 export { createInMemoryQueryCache, createIndexedDbQueryCache, queryCacheKey } from './packem_shared/createInMemoryQueryCache-B1PQ9Twl.mjs';

package/dist/packem_shared/{LunoraClient-Bsv8immC.mjs → LunoraClient-C4eFp92b.mjs}

@@ -1,12 +1,37 @@
 import { S as SubscriptionRegistry, s as stableStringify } from './subscription-C1Jy7HiF.mjs';
 import createInMemoryBookmarkStorage from './createInMemoryBookmarkStorage-BoN7a7TH.mjs';
 import { isMutationDelta, applyDelta } from './applyDelta-4jFGTPA3.mjs';
-import { createLocalStore } from './createLocalStore-DSUfoLqY.mjs';
-import { OfflineQueue, nextId, reportPersistenceError } from './OfflineQueue-D-ASeqL7.mjs';
+import { a as applyOptimisticLayer, d as dropConfirmedLayers, n as notifySubscription, f as foldOptimistic, c as createLocalStore } from './local-store-BNgN3Dw3.mjs';
+import { OfflineQueue, nextId, reportPersistenceError } from './OfflineQueue-eJBiWPfg.mjs';
 import { queryCacheKey } from './createInMemoryQueryCache-B1PQ9Twl.mjs';
 import { createReconnect } from './createReconnect-Di_-oHH7.mjs';
 import { createStream } from './DEFAULT_MAX_BUFFER-BDkqO5PW.mjs';
 
+class Listeners {
+  listeners = /* @__PURE__ */ new Set();
+  add(listener) {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  // The conditional rest tuple makes `emit()` argument-free for a
+  // `Listeners<void>` and one-argument for every other payload.
+  // eslint-disable-next-line @typescript-eslint/no-invalid-void-type -- `[T] extends [void]` is the discriminant for the payload-free overload, not a value-position void
+  emit(...args) {
+    const [value] = args;
+    for (const listener of this.listeners) {
+      try {
+        listener(value);
+      } catch {
+      }
+    }
+  }
+  clear() {
+    this.listeners.clear();
+  }
+}
+
 const RPC_PATH = "/_lunora/rpc";
 const WS_PATH = "/_lunora/ws";
 const bucketQuery = (bucket) => bucket === void 0 || bucket === "" ? "" : `&bucket=${encodeURIComponent(bucket)}`;
@@ -102,41 +127,6 @@ const withQuery = (path, params) => {
   return query === "" ? path : `${path}?${query}`;
 };
 const connectionKey = (shardKey) => shardKey ?? "";
-const writeOptimisticToState = (state, next) => {
-  const previous = state.lastValue;
-  const versionAtApply = state.serverVersion;
-  state.lastValue = next;
-  for (const callback of state.callbacks) {
-    try {
-      callback(next);
-    } catch {
-    }
-  }
-  return () => {
-    if (state.serverVersion > versionAtApply) {
-      return;
-    }
-    if (state.lastValue !== next) {
-      return;
-    }
-    state.lastValue = previous;
-    for (const callback of state.callbacks) {
-      try {
-        callback(previous);
-      } catch {
-      }
-    }
-  };
-};
-const applyOptimisticToState = (state, optimistic) => {
-  let next;
-  try {
-    next = optimistic(state.lastValue);
-  } catch {
-    return void 0;
-  }
-  return writeOptimisticToState(state, next);
-};
 const buildStreamError = (message) => {
   const errorEnvelope = message.error;
   const code = typeof errorEnvelope?.code === "string" ? errorEnvelope.code : void 0;
@@ -273,11 +263,13 @@ class LunoraClient {
   queuedIdentities = /* @__PURE__ */ new Map();
   closed = false;
   /** Subscribers to auth-token changes (see `onAuthTokenChange`). */
-  authTokenListeners = /* @__PURE__ */ new Set();
+  authTokenListeners = new Listeners();
   /** Subscribers to aggregate connection-status changes (see `onConnectionStatus`). */
-  statusListeners = /* @__PURE__ */ new Set();
+  statusListeners = new Listeners();
   /** Subscribers notified when the server drops a socket for an expired token (see `onTokenExpired`). */
-  tokenExpiredListeners = /* @__PURE__ */ new Set();
+  tokenExpiredListeners = new Listeners();
+  /** Subscribers to offline-queued mutation verdicts (see `onMutationSettled`). */
+  mutationSettledListeners = new Listeners();
   /**
    * Whisper-topic handlers, keyed by `connectionKey(shardKey)` → topic → set
    * of callbacks. Membership doubles as the resubscribe set replayed on every
@@ -316,7 +308,9 @@ class LunoraClient {
     this.persistence = options.persistence;
     this.queryCache = options.queryCache === false ? void 0 : options.queryCache;
     this.onPersistenceError = options.offlineQueue?.onPersistenceError;
-    this.offlineQueue = new OfflineQueue(options.offlineQueue, options.persistence);
+    this.offlineQueue = new OfflineQueue(options.offlineQueue, options.persistence, (entry, error) => {
+      this.emitItemSettled(entry, "rejected", error);
+    });
     this.outbox = options.outbox;
     this.clientId = options.clientId ?? `client-${nextId()}`;
     if (this.persistence) {
@@ -347,12 +341,7 @@ class LunoraClient {
     }
     this.authToken = token;
     this.rejectQueuedForIdentityChange();
-    for (const listener of this.authTokenListeners) {
-      try {
-        listener(token);
-      } catch {
-      }
-    }
+    this.authTokenListeners.emit(token);
   }
   getAuthToken() {
     return this.authToken;
@@ -424,10 +413,7 @@ class LunoraClient {
    * the current value.
    */
   onAuthTokenChange(listener) {
-    this.authTokenListeners.add(listener);
-    return () => {
-      this.authTokenListeners.delete(listener);
-    };
+    return this.authTokenListeners.add(listener);
   }
   /**
    * Fetch the currently authenticated user from better-auth's `get-session`
@@ -630,10 +616,7 @@ class LunoraClient {
    * with a freshly minted one. Returns an unsubscribe function.
    */
   onTokenExpired(listener) {
-    this.tokenExpiredListeners.add(listener);
-    return () => {
-      this.tokenExpiredListeners.delete(listener);
-    };
+    return this.tokenExpiredListeners.add(listener);
   }
   // --- Connection status --------------------------------------------------
   /**
@@ -649,11 +632,23 @@ class LunoraClient {
    * unsubscribe function.
    */
   onConnectionStatus(listener) {
-    this.statusListeners.add(listener);
+    const unsubscribe = this.statusListeners.add(listener);
     listener(this.computeStatus());
-    return () => {
-      this.statusListeners.delete(listener);
-    };
+    return unsubscribe;
+  }
+  /**
+   * Subscribe to terminal verdicts for offline-queued mutations. The listener
+   * fires once per queued write that commits or is rejected — including a write
+   * restored from durable storage after a reload, whose original `mutation()`
+   * Promise no longer exists (`hadAwaiter: false`), and a write the queue
+   * evicts on overflow or discards on an identity change. This is the durable
+   * channel for surfacing a rolled-back optimistic write to the UI; an online
+   * mutation that never queued still surfaces through the Promise `mutation()`
+   * returns. The listener is NOT invoked on registration. Returns an
+   * unsubscribe function. See {@link MutationSettledEvent}.
+   */
+  onMutationSettled(listener) {
+    return this.mutationSettledListeners.add(listener);
   }
   // --- RPC ---------------------------------------------------------------
   async query(function_, args, options = {}) {
@@ -678,9 +673,14 @@ class LunoraClient {
     }
     const argsRecord = args;
     const mutationId = options.mutationId ?? nextId();
-    const optimisticRollbacks = this.applyOptimisticUpdates(function_.__lunoraRef, argsRecord, options.shardKey, options.optimistic);
+    const { confirms: optimisticConfirms, rollbacks: optimisticRollbacks } = this.applyOptimisticUpdates(
+      function_.__lunoraRef,
+      argsRecord,
+      options.shardKey,
+      options.optimistic
+    );
     if (options.optimisticUpdate) {
-      this.applyOptimisticUpdate(options.optimisticUpdate, args, options.shardKey, optimisticRollbacks);
+      this.applyOptimisticUpdate(options.optimisticUpdate, args, options.shardKey, optimisticRollbacks, optimisticConfirms);
     }
     const conn = this.getConnection(options.shardKey);
     const wsState = conn?.wsState ?? "idle";
@@ -691,10 +691,21 @@ class LunoraClient {
     const shouldQueueOffline = this.WebSocketImpl !== void 0 && connectedGate;
     const midReconnect = wsState === "connecting" && connectedGate;
     if (wsState !== "open" && !hasSocket && shouldQueueOffline || midReconnect) {
-      return this.enqueueOfflineMutation(function_, argsRecord, options.shardKey, mutationId, optimisticRollbacks);
+      return this.enqueueOfflineMutation(function_, argsRecord, options.shardKey, mutationId, optimisticRollbacks, optimisticConfirms);
     }
     try {
-      return await this.rpc(function_.__lunoraRef, argsRecord, options.shardKey, { captureBookmark: true, mutationId });
+      let commitCursor;
+      const result = await this.rpc(function_.__lunoraRef, argsRecord, options.shardKey, {
+        captureBookmark: true,
+        mutationId,
+        onCommitCursor: (cursor) => {
+          commitCursor = cursor;
+        }
+      });
+      for (const confirm of optimisticConfirms) {
+        confirm(commitCursor);
+      }
+      return result;
     } catch (error) {
       rollbackOptimistic(optimisticRollbacks);
       throw error;
@@ -1346,8 +1357,9 @@ class LunoraClient {
         fn: function_,
         id,
         lastValue: cached?.value,
+        optimisticLayers: [],
+        serverBase: cached?.value,
         serverCursor: cached?.serverCursor,
-        serverVersion: 0,
         shardKey: options.shardKey,
         ...cached?.serverEpoch === void 0 ? {} : { serverEpoch: cached.serverEpoch }
       };
@@ -1529,6 +1541,7 @@ class LunoraClient {
     this.authTokenListeners.clear();
     this.statusListeners.clear();
     this.tokenExpiredListeners.clear();
+    this.mutationSettledListeners.clear();
     this.whisperHandlers.clear();
     this.shapeSubscriptions.clear();
     this.pokeBuffers.clear();
@@ -1545,7 +1558,7 @@ class LunoraClient {
    * optimistically (confirmation rides the synced view). Otherwise the
    * built-in `OfflineQueue` resolves/rejects the returned promise on replay.
    */
-  async enqueueOfflineMutation(function_, argsRecord, shardKey, mutationId, optimisticRollbacks) {
+  async enqueueOfflineMutation(function_, argsRecord, shardKey, mutationId, optimisticRollbacks, optimisticConfirms) {
     const issuingIdentity = this.identityFingerprint();
     if (this.outbox) {
       this.outboxMutationCounter += 1;
@@ -1564,18 +1577,32 @@ class LunoraClient {
         rollbackOptimistic(optimisticRollbacks);
         throw error instanceof Error ? error : new Error(String(error));
       }
+      for (const confirm of optimisticConfirms) {
+        confirm(void 0);
+      }
       return void 0;
     }
     return new Promise((resolve, reject) => {
       const entry = {
         args: argsRecord,
         functionPath: function_.__lunoraRef,
+        // A live caller is awaiting this Promise, so a terminal verdict
+        // reaches them directly; the observer event carries
+        // `hadAwaiter: true`. Hydrated replays leave this unset.
+        liveAwaiter: true,
         // Reuse the call's idempotency key as the queue id so the replay
         // carries the same `x-lunora-mutation-id` the server dedups on.
         id: mutationId,
         // Persist the stamp alongside the record so a hydrated write can
         // only replay under the identity that queued it.
         identity: issuingIdentity,
+        // Confirm the per-call optimistic layer(s) against the commit cursor
+        // the flush replay echoes (see flushOfflineQueue).
+        onCommit: (commitCursor) => {
+          for (const confirm of optimisticConfirms) {
+            confirm(commitCursor);
+          }
+        },
         reject: (error) => {
           this.queuedIdentities.delete(mutationId);
           rollbackOptimistic(optimisticRollbacks);
@@ -1646,7 +1673,8 @@ class LunoraClient {
    * (nothing to render offline).
    */
   persistQueryValue(state) {
-    if (!this.queryCache || state.lastValue === void 0) {
+    const authoritative = state.serverBase;
+    if (!this.queryCache || authoritative === void 0) {
       return;
     }
     const key = queryCacheKey(state.fn.__lunoraRef, state.argsKey, state.shardKey);
@@ -1654,7 +1682,7 @@ class LunoraClient {
       identity: this.identityFingerprint(),
       serverCursor: state.serverCursor,
       ts: Date.now(),
-      value: state.lastValue,
+      value: authoritative,
       ...state.serverEpoch === void 0 ? {} : { serverEpoch: state.serverEpoch }
     });
     this.cacheFlushTimer ??= setTimeout(() => {
@@ -1694,12 +1722,25 @@ class LunoraClient {
       return;
     }
     this.lastStatus = next;
-    for (const listener of this.statusListeners) {
-      try {
-        listener(next);
-      } catch {
-      }
-    }
+    this.statusListeners.emit(next);
+  }
+  /**
+   * Build a {@link MutationSettledEvent} from a queued entry and emit it on the
+   * {@link onMutationSettled} channel. `item.id` is always assigned by the time
+   * a write settles (`enqueue`/`hydrate` guarantee it), so the `?? ""` fallback
+   * is unreachable — present only to satisfy the optional queue-id type.
+   */
+  emitItemSettled(item, status, error) {
+    this.mutationSettledListeners.emit({
+      args: item.args,
+      code: error === void 0 ? void 0 : error.code,
+      error,
+      functionPath: item.functionPath,
+      hadAwaiter: item.liveAwaiter ?? false,
+      id: item.id ?? "",
+      shardKey: item.shardKey,
+      status
+    });
   }
   /**
    * Apply an optimistic update to the subscription that matches the mutation's
@@ -1716,31 +1757,35 @@ class LunoraClient {
    * of whether the caller passed `undefined` or omitted the field.
    */
   applyOptimisticUpdates(functionRef, argsRecord, mutationShardKey, optimistic) {
-    const optimisticRollbacks = [];
+    const confirms = [];
+    const rollbacks = [];
     if (!optimistic) {
-      return optimisticRollbacks;
+      return { confirms, rollbacks };
     }
     const matchKey = SubscriptionRegistry.key(functionRef, argsRecord, mutationShardKey);
     const state = this.subscriptions.get(matchKey);
     if (state) {
-      const rollback = applyOptimisticToState(state, optimistic);
-      if (rollback) {
-        optimisticRollbacks.push(rollback);
+      const handle = applyOptimisticLayer(state, optimistic);
+      if (handle) {
+        confirms.push(handle.confirm);
+        rollbacks.push(handle.rollback);
       }
     }
-    return optimisticRollbacks;
+    return { confirms, rollbacks };
   }
   /**
    * Run a Convex-parity `optimisticUpdate` callback against a localStore bound
-   * to the live subscription registry, appending each `setQuery` write's
-   * rollback to `optimisticRollbacks` (the same LIFO list the legacy path uses,
-   * unwound on settle/error). A throwing callback unwinds its own partial
-   * writes — LIFO over just the rollbacks it produced — and is swallowed, so a
-   * buggy optimistic update can never fail the mutation or leave a partial
-   * patch live, mirroring the legacy transform's throw handling.
-   */
-  applyOptimisticUpdate(optimisticUpdate, args, shardKey, optimisticRollbacks) {
-    const { rollbacks, store } = createLocalStore(this.subscriptions, shardKey, writeOptimisticToState, stableStringify);
+   * to the live subscription registry. Each `setQuery` registers a constant
+   * optimistic LAYER on its target subscription (via the same engine the
+   * per-call `optimistic` path uses), so the multi-query patch rebases onto
+   * incoming deltas and drops gaplessly on its commit cursor — its `confirm` /
+   * `rollback` closures are appended to the mutation's settle lists. A throwing
+   * callback unwinds its own partial writes — LIFO over just the rollbacks it
+   * produced — and is swallowed, so a buggy optimistic update can never fail the
+   * mutation or leave a partial patch live.
+   */
+  applyOptimisticUpdate(optimisticUpdate, args, shardKey, optimisticRollbacks, optimisticConfirms) {
+    const { confirms, rollbacks, store } = createLocalStore(this.subscriptions, shardKey, stableStringify);
     try {
       optimisticUpdate(store, args);
     } catch {
@@ -1750,6 +1795,7 @@ class LunoraClient {
       return;
     }
     optimisticRollbacks.push(...rollbacks);
+    optimisticConfirms.push(...confirms);
   }
   getConnection(shardKey) {
     return this.connections.get(connectionKey(shardKey));
@@ -1850,6 +1896,7 @@ class LunoraClient {
       throw new Error(`LunoraClient: request failed (status ${response.status.toString()}${statusText})`);
     }
     flags.onMutationAck?.(body.lastMutationId);
+    flags.onCommitCursor?.(body.commitCursor);
     return body.result;
   }
   /**
@@ -2312,8 +2359,7 @@ class LunoraClient {
       return;
     }
     const payload = this.resolveDataPayload(message, state);
-    state.lastValue = payload;
-    state.serverVersion += 1;
+    state.serverBase = payload;
     if (message.cursor !== void 0) {
       state.serverCursor = message.cursor;
     }
@@ -2321,12 +2367,8 @@ class LunoraClient {
       state.serverEpoch = message.epoch;
     }
     this.persistQueryValue(state);
-    for (const callback of state.callbacks) {
-      try {
-        callback(payload);
-      } catch {
-      }
-    }
+    dropConfirmedLayers(state, state.serverCursor);
+    notifySubscription(state, state.optimisticLayers.length === 0 ? payload : foldOptimistic(payload, state.optimisticLayers));
   }
   /**
    * Handle a `resume` frame (Pillar 1b): the server proved nothing the
@@ -2383,6 +2425,9 @@ class LunoraClient {
         state.serverEpoch = epoch;
       }
       this.persistQueryValue(state);
+      if (dropConfirmedLayers(state, state.serverCursor)) {
+        notifySubscription(state, foldOptimistic(state.serverBase, state.optimisticLayers));
+      }
     }
   }
   /**
@@ -2403,8 +2448,8 @@ class LunoraClient {
       return message.data;
     }
     const { delta } = message;
-    if (isMutationDelta(delta) && state.lastValue !== void 0) {
-      const merged = applyDelta(state.lastValue, delta);
+    if (isMutationDelta(delta) && state.serverBase !== void 0) {
+      const merged = applyDelta(state.serverBase, delta);
       if (merged !== void 0) {
         return merged;
       }
@@ -2426,12 +2471,7 @@ class LunoraClient {
   }
   /** Notify every {@link onTokenExpired} listener (best-effort, listener throws swallowed). */
   notifyTokenExpired() {
-    for (const listener of this.tokenExpiredListeners) {
-      try {
-        listener();
-      } catch {
-      }
-    }
+    this.tokenExpiredListeners.emit();
   }
   handleCompleteMessage(id) {
     const stream = this.streams.get(id);
@@ -2488,6 +2528,7 @@ class LunoraClient {
       const error = new Error("offline mutation discarded: auth identity changed before replay");
       error.code = "OFFLINE_IDENTITY_CHANGED";
       item.reject(error);
+      this.emitItemSettled(item, "rejected", error);
     }
     this.clearQueryCacheForIdentityChange();
   }
@@ -2523,17 +2564,28 @@ class LunoraClient {
         const error = new Error("offline mutation skipped: auth identity changed before replay");
         error.code = "OFFLINE_IDENTITY_CHANGED";
         item.reject(error);
+        this.emitItemSettled(item, "rejected", error);
         continue;
       }
       this.queuedIdentities.delete(item.id ?? "");
       try {
-        const value = await this.rpc(item.functionPath, item.args, item.shardKey, { captureBookmark: true, mutationId: item.id });
+        let commitCursor;
+        const value = await this.rpc(item.functionPath, item.args, item.shardKey, {
+          captureBookmark: true,
+          mutationId: item.id,
+          onCommitCursor: (cursor) => {
+            commitCursor = cursor;
+          }
+        });
         this.unpersist(item.id);
+        item.onCommit?.(commitCursor);
         item.resolve(value);
+        this.emitItemSettled(item, "committed");
       } catch (error) {
         if (error.code !== void 0) {
           this.unpersist(item.id);
           item.reject(error);
+          this.emitItemSettled(item, "rejected", error);
           continue;
         }
         this.offlineQueue.requeue(drained.slice(index));