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

package/dist/packem_shared/{OfflineQueue-D-ASeqL7.mjs → OfflineQueue-eJBiWPfg.mjs}

@@ -23,12 +23,14 @@ class OfflineQueue {
   maxItems;
   onPersistenceError;
   persistence;
+  onEvict;
   items = [];
-  constructor(options = {}, persistence) {
+  constructor(options = {}, persistence, onEvict) {
     this.maxItems = options.maxItems ?? 1e3;
     this.queueBeforeFirstConnect = options.queueBeforeFirstConnect ?? false;
     this.onPersistenceError = options.onPersistenceError;
     this.persistence = persistence;
+    this.onEvict = onEvict;
   }
   get size() {
     return this.items.length;
@@ -51,6 +53,7 @@ class OfflineQueue {
         const error = new Error("offline queue overflow");
         error.code = "OFFLINE_QUEUE_OVERFLOW";
         dropped.reject(error);
+        this.onEvict?.(dropped, error);
       }
     }
   }

package/dist/packem_shared/createLocalStore-IOur0jHF.mjs

@@ -0,0 +1 @@
+export { c as createLocalStore } from './local-store-BNgN3Dw3.mjs';

package/dist/packem_shared/{createServerClient-DucOyOz3.mjs → createServerClient-PHoMdNGJ.mjs}

@@ -1,4 +1,4 @@
-import { LunoraClient } from './LunoraClient-Bsv8immC.mjs';
+import { LunoraClient } from './LunoraClient-C4eFp92b.mjs';
 
 const createServerClient = (options) => {
   const client = new LunoraClient({ fetch: options.fetch, url: options.url });

package/dist/packem_shared/local-store-BNgN3Dw3.mjs

@@ -0,0 +1,111 @@
+const foldOptimistic = (base, layers) => {
+  let value = base;
+  for (const layer of layers) {
+    try {
+      value = layer.transform(value);
+    } catch {
+    }
+  }
+  return value;
+};
+const notifySubscription = (state, value) => {
+  if (value === state.lastValue) {
+    return;
+  }
+  state.lastValue = value;
+  for (const callback of state.callbacks) {
+    try {
+      callback(value);
+    } catch {
+    }
+  }
+};
+const applyOptimisticLayer = (state, optimistic) => {
+  let next;
+  try {
+    next = optimistic(state.lastValue);
+  } catch {
+    return void 0;
+  }
+  const layer = { id: /* @__PURE__ */ Symbol("optimistic"), transform: optimistic };
+  state.optimisticLayers.push(layer);
+  notifySubscription(state, next);
+  const remove = () => {
+    const index = state.optimisticLayers.findIndex((entry) => entry.id === layer.id);
+    if (index === -1) {
+      return false;
+    }
+    state.optimisticLayers.splice(index, 1);
+    return true;
+  };
+  const refold = () => {
+    notifySubscription(state, foldOptimistic(state.serverBase, state.optimisticLayers));
+  };
+  return {
+    confirm: (commitCursor) => {
+      if (commitCursor === void 0) {
+        remove();
+        return;
+      }
+      layer.commitCursor = commitCursor;
+      if (state.serverCursor !== void 0 && state.serverCursor >= commitCursor && remove()) {
+        refold();
+      }
+    },
+    rollback: () => {
+      if (remove()) {
+        refold();
+      }
+    }
+  };
+};
+const dropConfirmedLayers = (state, cursor) => {
+  if (cursor === void 0 || state.optimisticLayers.length === 0) {
+    return false;
+  }
+  const before = state.optimisticLayers.length;
+  state.optimisticLayers = state.optimisticLayers.filter((layer) => layer.commitCursor === void 0 || layer.commitCursor > cursor);
+  return state.optimisticLayers.length !== before;
+};
+
+const createLocalStore = (subscriptions, shardKey, stableStringify) => {
+  const confirms = [];
+  const rollbacks = [];
+  const findState = (functionRef, argsKey) => {
+    for (const state of subscriptions.all()) {
+      if (state.fn.__lunoraRef === functionRef && state.shardKey === shardKey && state.argsKey === argsKey) {
+        return state;
+      }
+    }
+    return void 0;
+  };
+  const store = {
+    getAllQueries: (function_) => {
+      const matches = [];
+      for (const state of subscriptions.all()) {
+        if (state.fn.__lunoraRef === function_.__lunoraRef && state.shardKey === shardKey) {
+          matches.push({ args: state.args, value: state.lastValue });
+        }
+      }
+      return matches;
+    },
+    getQuery: (function_, args) => {
+      const state = findState(function_.__lunoraRef, stableStringify(args ?? {}));
+      return state?.lastValue;
+    },
+    setQuery: (function_, args, value) => {
+      const state = findState(function_.__lunoraRef, stableStringify(args ?? {}));
+      if (!state) {
+        return;
+      }
+      const handle = applyOptimisticLayer(state, () => value);
+      if (handle) {
+        confirms.push(handle.confirm);
+        rollbacks.push(handle.rollback);
+      }
+    }
+  };
+  return { confirms, rollbacks, store };
+};
+
+export { applyOptimisticLayer as a, createLocalStore as c, dropConfirmedLayers as d, foldOptimistic as f, notifySubscription as n };

package/dist/packem_shared/{lunora-client.d-CeUZ8lE1.d.mts → lunora-client.d-CfwxuJo8.d.mts}

@@ -312,6 +312,8 @@ interface RpcEnvelope {
 * watermarked custom-mutator push additionally carries `lastMutationId` — the
 * highest per-client sequence the DO has applied — which the client uses to keep
 * its `clientSeq` generator monotonic across reloads (see `LunoraClient.callMutator`).
+* A plain mutation on a CDC shard carries `commitCursor` — the cursor the write
+* committed at — which gates the drop of a per-call optimistic layer.
 */
 type RpcResponseBody = {
   error: {
@@ -319,6 +321,7 @@ type RpcResponseBody = {
     message: string;
   };
 } | {
+  commitCursor?: number;
   lastMutationId?: number;
   result: unknown;
 };
@@ -820,6 +823,23 @@ interface SubscriptionError {
   message: string;
 }
 type SubscriptionErrorCallback = (error: SubscriptionError) => void;
+/**
+* One active per-call optimistic transform layered onto a subscription. The
+* displayed value is the authoritative {@link SubscriptionState.serverBase}
+* folded through every layer's `transform`, in order — so an incoming server
+* frame re-folds the still-pending layers onto the new base (rebasing) instead
+* of clobbering them. A layer is dropped — gaplessly — once a `data`/`delta`
+* frame whose `cursor >= commitCursor` arrives (its write is now reflected in
+* `serverBase`); `commitCursor` is the CDC cursor the server echoed on the
+* mutation's response, and stays `undefined` while the write is still queued/
+* in-flight (so the overlay survives unrelated deltas until confirmed).
+*/
+interface OptimisticLayer {
+  /** The committed CDC cursor (from the mutation response); `undefined` until confirmed. */
+  commitCursor?: number;
+  readonly id: symbol;
+  readonly transform: (current: unknown) => unknown;
+}
 interface SubscriptionState {
   /** True once the server has acked the subscription on the current socket. */
   acked: boolean;
@@ -862,6 +882,21 @@ interface SubscriptionState {
   /** Last known value, used to short-circuit `useQuery`-style consumers. */
   lastValue: unknown;
   /**
+  * Active per-call optimistic layers, in application order (see
+  * {@link OptimisticLayer}). Empty for subscriptions with no pending per-call
+  * optimistic write — the common case, where `lastValue` tracks `serverBase`
+  * exactly and behaviour is identical to a plain server-value assignment.
+  */
+  optimisticLayers: OptimisticLayer[];
+  /**
+  * The authoritative server value the optimistic layers fold onto — the value
+  * with NO optimistic overlay. Tracks `lastValue` exactly whenever no layers
+  * are active; diverges only while a per-call optimistic write is pending. A
+  * server frame updates this (and re-folds the layers); the durable read cache
+  * persists this, never the optimistic overlay.
+  */
+  serverBase: unknown;
+  /**
   * The `__cdc_log` high-watermark (`cursor`) the `lastValue` reflects,
   * captured from the last `data`/`delta`/`resume` frame. Persisted to the
   * durable read cache and replayed as `sinceSeq` on reconnect so the server
@@ -877,12 +912,6 @@ interface SubscriptionState {
   * until the first epoch-stamped frame arrives.
   */
   serverEpoch?: string;
-  /**
-  * Monotonic counter incremented on every server-pushed delta or data.
-  * Used by optimistic-update rollback to detect whether the server has
-  * already moved past the value we'd otherwise restore.
-  */
-  serverVersion: number;
   readonly shardKey?: string;
 }
 /**
@@ -909,10 +938,10 @@ declare class SubscriptionRegistry {
 * many subscribed queries at once (Convex's `OptimisticLocalStore` model).
 *
 * `getQuery` reads the current value (server value or any still-pending
-* optimistic override) of a subscribed query; `setQuery` writes an optimistic
-* override on top. Every write is collected as a rollback closure so the whole
-* batch unwinds atomically when the mutation settles or the server advances
-* past it — the same per-subscription rollback machinery the legacy
+* optimistic override) of a subscribed query; `setQuery` registers a constant
+* optimistic layer on top. The whole batch rebases onto incoming deltas and
+* settles together — confirmed on the mutation's commit cursor, or rolled back
+* on failure — the same per-subscription layer machinery the single-query
 * per-call `optimistic` transform uses, generalized to N queries.
 */
 interface OptimisticLocalStore {
@@ -942,13 +971,17 @@ interface OptimisticLocalStore {
 /** A mutation's multi-query optimistic update: read/write the cache via `localStore`. */
 type OptimisticUpdate<Args> = (localStore: OptimisticLocalStore, args: Args) => void;
 /**
-* Build an {@link OptimisticLocalStore} bound to a subscription registry, the
-* mutation's shard key, and the `writeOptimisticToState` primitive. Returns the
-* store plus the ordered rollback closures every `setQuery` produced, so the
-* caller can unwind the whole batch (LIFO) if the mutation later fails — and
-* leave them in place to be GC'd alongside the subscription on success.
+* Build an {@link OptimisticLocalStore} bound to a subscription registry and the
+* mutation's shard key. Each `setQuery(value)` registers a constant-value layer
+* on its target subscription (via `applyOptimisticLayer`): the predicted value
+* survives incoming server deltas (re-clamped, masking concurrent changes to that
+* query — not merged) and drops gaplessly on the mutation's commit cursor, like
+* the single-query per-call `optimistic` path. Returns the store plus the ordered
+* `confirm` (success) and `rollback` (failure) closures every `setQuery` produced,
+* so the caller settles the whole batch when the mutation does.
 */
-declare const createLocalStore: (subscriptions: SubscriptionRegistry, shardKey: string | undefined, write: (state: SubscriptionState, next: unknown) => () => void, stableStringify: (value: unknown) => string) => {
+declare const createLocalStore: (subscriptions: SubscriptionRegistry, shardKey: string | undefined, stableStringify: (value: unknown) => string) => {
+  confirms: ((commitCursor: number | undefined) => void)[];
   rollbacks: (() => void)[];
   store: OptimisticLocalStore;
 };
@@ -1006,6 +1039,41 @@ declare const createStream: <T>(options: {
 */
 type ConnectionStatus = "connected" | "connecting" | "idle" | "offline";
 /**
+* Terminal verdict for a mutation that passed through the offline queue,
+* delivered to {@link LunoraClient.onMutationSettled}.
+*
+* Unlike the Promise returned by {@link LunoraClient.mutation} — which only the
+* original caller can await, and which no longer exists after a reload — this
+* fires for *every* queued write the server (or the queue) reaches a verdict on,
+* including writes restored from durable storage in a later session. It is the
+* channel a UI uses to tell the user "your queued change couldn't be saved"
+* instead of silently dropping a rolled-back optimistic row.
+*
+* `status: "rejected"` carries the failure `code` (e.g. `CONFLICT`,
+* `OFFLINE_QUEUE_OVERFLOW`, `OFFLINE_IDENTITY_CHANGED`) and the `error`.
+* `hadAwaiter` is `false` for a write whose original `mutation()` Promise is
+* gone (a hydrated/post-reload replay or an eviction), so a listener can tell
+* "the caller already saw this" apart from "nothing else will report this".
+*/
+interface MutationSettledEvent {
+  /** The write's args, so a listener can describe or re-offer the change. */
+  readonly args: Record<string, unknown>;
+  /** Server/queue error code on `rejected` (e.g. `CONFLICT`), when present. */
+  readonly code?: string;
+  /** The rejection error on `status: "rejected"`. */
+  readonly error?: unknown;
+  /** The `&lt;file>:&lt;function>` reference of the mutation. */
+  readonly functionPath: string;
+  /** Whether a live caller was still awaiting this write's `mutation()` Promise. */
+  readonly hadAwaiter: boolean;
+  /** The write's stable id (idempotency key / queue id). */
+  readonly id: string;
+  /** Shard the write targeted, if any. */
+  readonly shardKey?: string;
+  /** Terminal outcome. */
+  readonly status: "committed" | "rejected";
+}
+/**
 * Per-call options for {@link LunoraClient.mutation} — the optimistic-update
 * machinery plus `shardKey`. Exported (at the end of this file) so the framework
 * adapters (`@lunora/react`, `/solid`, `/svelte`, `/vue`) can type their
@@ -1145,6 +1213,8 @@ declare class LunoraClient {
   private readonly statusListeners;
   /** Subscribers notified when the server drops a socket for an expired token (see `onTokenExpired`). */
   private readonly tokenExpiredListeners;
+  /** Subscribers to offline-queued mutation verdicts (see `onMutationSettled`). */
+  private readonly mutationSettledListeners;
   /**
   * Whisper-topic handlers, keyed by `connectionKey(shardKey)` → topic → set
   * of callbacks. Membership doubles as the resubscribe set replayed on every
@@ -1332,6 +1402,18 @@ declare class LunoraClient {
   * unsubscribe function.
   */
   onConnectionStatus(listener: (status: ConnectionStatus) => void): Unsubscribe;
+  /**
+  * Subscribe to terminal verdicts for offline-queued mutations. The listener
+  * fires once per queued write that commits or is rejected — including a write
+  * restored from durable storage after a reload, whose original `mutation()`
+  * Promise no longer exists (`hadAwaiter: false`), and a write the queue
+  * evicts on overflow or discards on an identity change. This is the durable
+  * channel for surfacing a rolled-back optimistic write to the UI; an online
+  * mutation that never queued still surfaces through the Promise `mutation()`
+  * returns. The listener is NOT invoked on registration. Returns an
+  * unsubscribe function. See {@link MutationSettledEvent}.
+  */
+  onMutationSettled(listener: (event: MutationSettledEvent) => void): Unsubscribe;
   query<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: {
     shardKey?: string;
   }): Promise<ReturnOf<F>>;
@@ -1841,6 +1923,13 @@ declare class LunoraClient {
   /** Recompute the aggregate status and notify listeners if it changed. */
   private emitConnectionStatus;
   /**
+  * Build a {@link MutationSettledEvent} from a queued entry and emit it on the
+  * {@link onMutationSettled} channel. `item.id` is always assigned by the time
+  * a write settles (`enqueue`/`hydrate` guarantee it), so the `?? ""` fallback
+  * is unreachable — present only to satisfy the optional queue-id type.
+  */
+  private emitItemSettled;
+  /**
   * Apply an optimistic update to the subscription that matches the mutation's
   * `(functionRef, args, shardKey)` triple, returning the rollback callbacks to
   * invoke if the mutation later fails.
@@ -1857,12 +1946,14 @@ declare class LunoraClient {
   private applyOptimisticUpdates;
   /**
   * 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.
+  * to the live subscription registry. Each `setQuery` registers a constant
+  * optimistic LAYER on its target subscription (via the same engine the
+  * per-call `optimistic` path uses), so the multi-query patch rebases onto
+  * incoming deltas and drops gaplessly on its commit cursor — its `confirm` /
+  * `rollback` closures are appended to the mutation's settle lists. A throwing
+  * callback unwinds its own partial writes — LIFO over just the rollbacks it
+  * produced — and is swallowed, so a buggy optimistic update can never fail the
+  * mutation or leave a partial patch live.
   */
   private applyOptimisticUpdate;
   private getConnection;
@@ -2012,4 +2103,4 @@ declare class LunoraClient {
   private clearQueryCacheForIdentityChange;
   private flushOfflineQueue;
 }
-export { SyncWatermark as $, ArgsOf as A, BookmarkStorage as B, CachedQuery as C, DEFAULT_MAX_BUFFER as D, ServerMessage as E, FunctionReference as F, GlobalFacetResult as G, ServerPokeEndMessage as H, ServerPokePartMessage as I, ServerPokeStartMessage as J, ShardTrafficEntry as K, LunoraClient as L, MutationCallOptions as M, ShardTrafficResult as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, StorageListPage as T, User as U, StorageObject as V, StreamHandle as W, StreamIterable as X, SubscriptionCallback as Y, SubscriptionRegistry as Z, SubscriptionState as _, Unsubscribe as a, WorkflowInstanceAction as a0, WorkflowInstanceDetail as a1, WorkflowInstancePage as a2, WorkflowInstanceStatus as a3, WorkflowInstanceSummary as a4, WorkflowStepDetail as a5, createLocalStore as a6, createStream as a7, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, ClientMessage as e, ClientShapeSubscribeMessage as f, ClientShapeUnsubscribeMessage as g, ConnectionStatus as h, FunctionArgumentDescriptor as i, FunctionDescriptor as j, GlobalFacetValue as k, GlobalFilterClause as l, GlobalTableInfo as m, GlobalTablePage as n, LunoraClientOptions as o, OptimisticLocalStore as p, OptimisticUpdate as q, OutboxMutation as r, OutboxSink as s, PersistedMutation as t, RowOp as u, RpcEnvelope as v, RpcResponseBody as w, ScheduleRecord as x, SchedulerPoolStatus as y, SchedulerStatus as z };
+export { SubscriptionState as $, ArgsOf as A, BookmarkStorage as B, CachedQuery as C, DEFAULT_MAX_BUFFER as D, SchedulerStatus as E, FunctionReference as F, GlobalFacetResult as G, ServerMessage as H, ServerPokeEndMessage as I, ServerPokePartMessage as J, ServerPokeStartMessage as K, LunoraClient as L, MutationCallOptions as M, ShardTrafficEntry as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, ShardTrafficResult as T, User as U, StorageListPage as V, StorageObject as W, StreamHandle as X, StreamIterable as Y, SubscriptionCallback as Z, SubscriptionRegistry as _, Unsubscribe as a, SyncWatermark as a0, WorkflowInstanceAction as a1, WorkflowInstanceDetail as a2, WorkflowInstancePage as a3, WorkflowInstanceStatus as a4, WorkflowInstanceSummary as a5, WorkflowStepDetail as a6, createLocalStore as a7, createStream as a8, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, ClientMessage as e, ClientShapeSubscribeMessage as f, ClientShapeUnsubscribeMessage as g, ConnectionStatus as h, FunctionArgumentDescriptor as i, FunctionDescriptor as j, GlobalFacetValue as k, GlobalFilterClause as l, GlobalTableInfo as m, GlobalTablePage as n, LunoraClientOptions as o, MutationSettledEvent as p, OptimisticLocalStore as q, OptimisticUpdate as r, OutboxMutation as s, OutboxSink as t, PersistedMutation as u, RowOp as v, RpcEnvelope as w, RpcResponseBody as x, ScheduleRecord as y, SchedulerPoolStatus as z };

package/dist/packem_shared/{lunora-client.d-CeUZ8lE1.d.ts → lunora-client.d-CfwxuJo8.d.ts}

@@ -312,6 +312,8 @@ interface RpcEnvelope {
 * watermarked custom-mutator push additionally carries `lastMutationId` — the
 * highest per-client sequence the DO has applied — which the client uses to keep
 * its `clientSeq` generator monotonic across reloads (see `LunoraClient.callMutator`).
+* A plain mutation on a CDC shard carries `commitCursor` — the cursor the write
+* committed at — which gates the drop of a per-call optimistic layer.
 */
 type RpcResponseBody = {
   error: {
@@ -319,6 +321,7 @@ type RpcResponseBody = {
     message: string;
   };
 } | {
+  commitCursor?: number;
   lastMutationId?: number;
   result: unknown;
 };
@@ -820,6 +823,23 @@ interface SubscriptionError {
   message: string;
 }
 type SubscriptionErrorCallback = (error: SubscriptionError) => void;
+/**
+* One active per-call optimistic transform layered onto a subscription. The
+* displayed value is the authoritative {@link SubscriptionState.serverBase}
+* folded through every layer's `transform`, in order — so an incoming server
+* frame re-folds the still-pending layers onto the new base (rebasing) instead
+* of clobbering them. A layer is dropped — gaplessly — once a `data`/`delta`
+* frame whose `cursor >= commitCursor` arrives (its write is now reflected in
+* `serverBase`); `commitCursor` is the CDC cursor the server echoed on the
+* mutation's response, and stays `undefined` while the write is still queued/
+* in-flight (so the overlay survives unrelated deltas until confirmed).
+*/
+interface OptimisticLayer {
+  /** The committed CDC cursor (from the mutation response); `undefined` until confirmed. */
+  commitCursor?: number;
+  readonly id: symbol;
+  readonly transform: (current: unknown) => unknown;
+}
 interface SubscriptionState {
   /** True once the server has acked the subscription on the current socket. */
   acked: boolean;
@@ -862,6 +882,21 @@ interface SubscriptionState {
   /** Last known value, used to short-circuit `useQuery`-style consumers. */
   lastValue: unknown;
   /**
+  * Active per-call optimistic layers, in application order (see
+  * {@link OptimisticLayer}). Empty for subscriptions with no pending per-call
+  * optimistic write — the common case, where `lastValue` tracks `serverBase`
+  * exactly and behaviour is identical to a plain server-value assignment.
+  */
+  optimisticLayers: OptimisticLayer[];
+  /**
+  * The authoritative server value the optimistic layers fold onto — the value
+  * with NO optimistic overlay. Tracks `lastValue` exactly whenever no layers
+  * are active; diverges only while a per-call optimistic write is pending. A
+  * server frame updates this (and re-folds the layers); the durable read cache
+  * persists this, never the optimistic overlay.
+  */
+  serverBase: unknown;
+  /**
   * The `__cdc_log` high-watermark (`cursor`) the `lastValue` reflects,
   * captured from the last `data`/`delta`/`resume` frame. Persisted to the
   * durable read cache and replayed as `sinceSeq` on reconnect so the server
@@ -877,12 +912,6 @@ interface SubscriptionState {
   * until the first epoch-stamped frame arrives.
   */
   serverEpoch?: string;
-  /**
-  * Monotonic counter incremented on every server-pushed delta or data.
-  * Used by optimistic-update rollback to detect whether the server has
-  * already moved past the value we'd otherwise restore.
-  */
-  serverVersion: number;
   readonly shardKey?: string;
 }
 /**
@@ -909,10 +938,10 @@ declare class SubscriptionRegistry {
 * many subscribed queries at once (Convex's `OptimisticLocalStore` model).
 *
 * `getQuery` reads the current value (server value or any still-pending
-* optimistic override) of a subscribed query; `setQuery` writes an optimistic
-* override on top. Every write is collected as a rollback closure so the whole
-* batch unwinds atomically when the mutation settles or the server advances
-* past it — the same per-subscription rollback machinery the legacy
+* optimistic override) of a subscribed query; `setQuery` registers a constant
+* optimistic layer on top. The whole batch rebases onto incoming deltas and
+* settles together — confirmed on the mutation's commit cursor, or rolled back
+* on failure — the same per-subscription layer machinery the single-query
 * per-call `optimistic` transform uses, generalized to N queries.
 */
 interface OptimisticLocalStore {
@@ -942,13 +971,17 @@ interface OptimisticLocalStore {
 /** A mutation's multi-query optimistic update: read/write the cache via `localStore`. */
 type OptimisticUpdate<Args> = (localStore: OptimisticLocalStore, args: Args) => void;
 /**
-* Build an {@link OptimisticLocalStore} bound to a subscription registry, the
-* mutation's shard key, and the `writeOptimisticToState` primitive. Returns the
-* store plus the ordered rollback closures every `setQuery` produced, so the
-* caller can unwind the whole batch (LIFO) if the mutation later fails — and
-* leave them in place to be GC'd alongside the subscription on success.
+* Build an {@link OptimisticLocalStore} bound to a subscription registry and the
+* mutation's shard key. Each `setQuery(value)` registers a constant-value layer
+* on its target subscription (via `applyOptimisticLayer`): the predicted value
+* survives incoming server deltas (re-clamped, masking concurrent changes to that
+* query — not merged) and drops gaplessly on the mutation's commit cursor, like
+* the single-query per-call `optimistic` path. Returns the store plus the ordered
+* `confirm` (success) and `rollback` (failure) closures every `setQuery` produced,
+* so the caller settles the whole batch when the mutation does.
 */
-declare const createLocalStore: (subscriptions: SubscriptionRegistry, shardKey: string | undefined, write: (state: SubscriptionState, next: unknown) => () => void, stableStringify: (value: unknown) => string) => {
+declare const createLocalStore: (subscriptions: SubscriptionRegistry, shardKey: string | undefined, stableStringify: (value: unknown) => string) => {
+  confirms: ((commitCursor: number | undefined) => void)[];
   rollbacks: (() => void)[];
   store: OptimisticLocalStore;
 };
@@ -1006,6 +1039,41 @@ declare const createStream: <T>(options: {
 */
 type ConnectionStatus = "connected" | "connecting" | "idle" | "offline";
 /**
+* Terminal verdict for a mutation that passed through the offline queue,
+* delivered to {@link LunoraClient.onMutationSettled}.
+*
+* Unlike the Promise returned by {@link LunoraClient.mutation} — which only the
+* original caller can await, and which no longer exists after a reload — this
+* fires for *every* queued write the server (or the queue) reaches a verdict on,
+* including writes restored from durable storage in a later session. It is the
+* channel a UI uses to tell the user "your queued change couldn't be saved"
+* instead of silently dropping a rolled-back optimistic row.
+*
+* `status: "rejected"` carries the failure `code` (e.g. `CONFLICT`,
+* `OFFLINE_QUEUE_OVERFLOW`, `OFFLINE_IDENTITY_CHANGED`) and the `error`.
+* `hadAwaiter` is `false` for a write whose original `mutation()` Promise is
+* gone (a hydrated/post-reload replay or an eviction), so a listener can tell
+* "the caller already saw this" apart from "nothing else will report this".
+*/
+interface MutationSettledEvent {
+  /** The write's args, so a listener can describe or re-offer the change. */
+  readonly args: Record<string, unknown>;
+  /** Server/queue error code on `rejected` (e.g. `CONFLICT`), when present. */
+  readonly code?: string;
+  /** The rejection error on `status: "rejected"`. */
+  readonly error?: unknown;
+  /** The `&lt;file>:&lt;function>` reference of the mutation. */
+  readonly functionPath: string;
+  /** Whether a live caller was still awaiting this write's `mutation()` Promise. */
+  readonly hadAwaiter: boolean;
+  /** The write's stable id (idempotency key / queue id). */
+  readonly id: string;
+  /** Shard the write targeted, if any. */
+  readonly shardKey?: string;
+  /** Terminal outcome. */
+  readonly status: "committed" | "rejected";
+}
+/**
 * Per-call options for {@link LunoraClient.mutation} — the optimistic-update
 * machinery plus `shardKey`. Exported (at the end of this file) so the framework
 * adapters (`@lunora/react`, `/solid`, `/svelte`, `/vue`) can type their
@@ -1145,6 +1213,8 @@ declare class LunoraClient {
   private readonly statusListeners;
   /** Subscribers notified when the server drops a socket for an expired token (see `onTokenExpired`). */
   private readonly tokenExpiredListeners;
+  /** Subscribers to offline-queued mutation verdicts (see `onMutationSettled`). */
+  private readonly mutationSettledListeners;
   /**
   * Whisper-topic handlers, keyed by `connectionKey(shardKey)` → topic → set
   * of callbacks. Membership doubles as the resubscribe set replayed on every
@@ -1332,6 +1402,18 @@ declare class LunoraClient {
   * unsubscribe function.
   */
   onConnectionStatus(listener: (status: ConnectionStatus) => void): Unsubscribe;
+  /**
+  * Subscribe to terminal verdicts for offline-queued mutations. The listener
+  * fires once per queued write that commits or is rejected — including a write
+  * restored from durable storage after a reload, whose original `mutation()`
+  * Promise no longer exists (`hadAwaiter: false`), and a write the queue
+  * evicts on overflow or discards on an identity change. This is the durable
+  * channel for surfacing a rolled-back optimistic write to the UI; an online
+  * mutation that never queued still surfaces through the Promise `mutation()`
+  * returns. The listener is NOT invoked on registration. Returns an
+  * unsubscribe function. See {@link MutationSettledEvent}.
+  */
+  onMutationSettled(listener: (event: MutationSettledEvent) => void): Unsubscribe;
   query<F extends FunctionReference>(function_: F, args: ArgsOf<F>, options?: {
     shardKey?: string;
   }): Promise<ReturnOf<F>>;
@@ -1841,6 +1923,13 @@ declare class LunoraClient {
   /** Recompute the aggregate status and notify listeners if it changed. */
   private emitConnectionStatus;
   /**
+  * Build a {@link MutationSettledEvent} from a queued entry and emit it on the
+  * {@link onMutationSettled} channel. `item.id` is always assigned by the time
+  * a write settles (`enqueue`/`hydrate` guarantee it), so the `?? ""` fallback
+  * is unreachable — present only to satisfy the optional queue-id type.
+  */
+  private emitItemSettled;
+  /**
   * Apply an optimistic update to the subscription that matches the mutation's
   * `(functionRef, args, shardKey)` triple, returning the rollback callbacks to
   * invoke if the mutation later fails.
@@ -1857,12 +1946,14 @@ declare class LunoraClient {
   private applyOptimisticUpdates;
   /**
   * 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.
+  * to the live subscription registry. Each `setQuery` registers a constant
+  * optimistic LAYER on its target subscription (via the same engine the
+  * per-call `optimistic` path uses), so the multi-query patch rebases onto
+  * incoming deltas and drops gaplessly on its commit cursor — its `confirm` /
+  * `rollback` closures are appended to the mutation's settle lists. A throwing
+  * callback unwinds its own partial writes — LIFO over just the rollbacks it
+  * produced — and is swallowed, so a buggy optimistic update can never fail the
+  * mutation or leave a partial patch live.
   */
   private applyOptimisticUpdate;
   private getConnection;
@@ -2012,4 +2103,4 @@ declare class LunoraClient {
   private clearQueryCacheForIdentityChange;
   private flushOfflineQueue;
 }
-export { SyncWatermark as $, ArgsOf as A, BookmarkStorage as B, CachedQuery as C, DEFAULT_MAX_BUFFER as D, ServerMessage as E, FunctionReference as F, GlobalFacetResult as G, ServerPokeEndMessage as H, ServerPokePartMessage as I, ServerPokeStartMessage as J, ShardTrafficEntry as K, LunoraClient as L, MutationCallOptions as M, ShardTrafficResult as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, StorageListPage as T, User as U, StorageObject as V, StreamHandle as W, StreamIterable as X, SubscriptionCallback as Y, SubscriptionRegistry as Z, SubscriptionState as _, Unsubscribe as a, WorkflowInstanceAction as a0, WorkflowInstanceDetail as a1, WorkflowInstancePage as a2, WorkflowInstanceStatus as a3, WorkflowInstanceSummary as a4, WorkflowStepDetail as a5, createLocalStore as a6, createStream as a7, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, ClientMessage as e, ClientShapeSubscribeMessage as f, ClientShapeUnsubscribeMessage as g, ConnectionStatus as h, FunctionArgumentDescriptor as i, FunctionDescriptor as j, GlobalFacetValue as k, GlobalFilterClause as l, GlobalTableInfo as m, GlobalTablePage as n, LunoraClientOptions as o, OptimisticLocalStore as p, OptimisticUpdate as q, OutboxMutation as r, OutboxSink as s, PersistedMutation as t, RowOp as u, RpcEnvelope as v, RpcResponseBody as w, ScheduleRecord as x, SchedulerPoolStatus as y, SchedulerStatus as z };
+export { SubscriptionState as $, ArgsOf as A, BookmarkStorage as B, CachedQuery as C, DEFAULT_MAX_BUFFER as D, SchedulerStatus as E, FunctionReference as F, GlobalFacetResult as G, ServerMessage as H, ServerPokeEndMessage as I, ServerPokePartMessage as J, ServerPokeStartMessage as K, LunoraClient as L, MutationCallOptions as M, ShardTrafficEntry as N, OfflineQueueOptions as O, Preloaded as P, QueryCacheAdapter as Q, ReturnOf as R, SubscriptionError as S, ShardTrafficResult as T, User as U, StorageListPage as V, StorageObject as W, StreamHandle as X, StreamIterable as Y, SubscriptionCallback as Z, SubscriptionRegistry as _, Unsubscribe as a, SyncWatermark as a0, WorkflowInstanceAction as a1, WorkflowInstanceDetail as a2, WorkflowInstancePage as a3, WorkflowInstanceStatus as a4, WorkflowInstanceSummary as a5, WorkflowStepDetail as a6, createLocalStore as a7, createStream as a8, SubscriptionErrorCallback as b, PersistenceAdapter as c, ReconnectOptions as d, ClientMessage as e, ClientShapeSubscribeMessage as f, ClientShapeUnsubscribeMessage as g, ConnectionStatus as h, FunctionArgumentDescriptor as i, FunctionDescriptor as j, GlobalFacetValue as k, GlobalFilterClause as l, GlobalTableInfo as m, GlobalTablePage as n, LunoraClientOptions as o, MutationSettledEvent as p, OptimisticLocalStore as q, OptimisticUpdate as r, OutboxMutation as s, OutboxSink as t, PersistedMutation as u, RowOp as v, RpcEnvelope as w, RpcResponseBody as x, ScheduleRecord as y, SchedulerPoolStatus as z };

package/dist/packem_shared/{preload.d-DipqU0PI.d.mts → preload.d-Bbn8plix.d.mts}

@@ -1,4 +1,4 @@
-import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-CeUZ8lE1.mjs";
+import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-CfwxuJo8.mjs";
 /**
 * Run a query once on the server (during SSR) and capture its result in a
 * serializable {@link Preloaded} token. Embed the token in the rendered HTML and

package/dist/packem_shared/{preload.d-CzHLgVfw.d.ts → preload.d-DuMetDdU.d.ts}

@@ -1,4 +1,4 @@
-import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-CeUZ8lE1.js";
+import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-CfwxuJo8.js";
 /**
 * Run a query once on the server (during SSR) and capture its result in a
 * serializable {@link Preloaded} token. Embed the token in the rendered HTML and

package/dist/query/index.d.mts

@@ -1,5 +1,5 @@
-import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-CeUZ8lE1.mjs";
-export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-CeUZ8lE1.mjs";
+import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-CfwxuJo8.mjs";
+export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-CfwxuJo8.mjs";
 import '@lunora/runtime';
 /**
 * The sentinel a framework adapter resolves its reactive args to when it wants

package/dist/query/index.d.ts

@@ -1,5 +1,5 @@
-import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-CeUZ8lE1.js";
-export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-CeUZ8lE1.js";
+import { S as SubscriptionError, F as FunctionReference, A as ArgsOf, R as ReturnOf, L as LunoraClient, a as Unsubscribe } from "../packem_shared/lunora-client.d-CfwxuJo8.js";
+export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-CfwxuJo8.js";
 import '@lunora/runtime';
 /**
 * The sentinel a framework adapter resolves its reactive args to when it wants

package/dist/ssr/index.d.mts

@@ -1,6 +1,6 @@
-import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-CeUZ8lE1.mjs";
-export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-CeUZ8lE1.mjs";
-export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-DipqU0PI.mjs";
+import { P as Preloaded, L as LunoraClient } from "../packem_shared/lunora-client.d-CfwxuJo8.mjs";
+export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-CfwxuJo8.mjs";
+export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-Bbn8plix.mjs";
 import '@lunora/runtime';
 /**
 * Structural shape of a better-auth `getSession` call's resolved value.