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

package/dist/packem_shared/{LunoraClient-B00f7VUM.mjs → LunoraClient-6J-4BGWK.mjs}

@@ -1,17 +1,58 @@
+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-D5p_QgF_.mjs';
-import { queryCacheKey } from './createIndexedDbQueryCache-B1PQ9Twl.mjs';
+import { a as applyOptimisticLayer, d as dropConfirmedLayers, n as notifySubscription, f as foldOptimistic, c as createLocalStore } from './local-store-BNgN3Dw3.mjs';
+import { O as OfflineQueue, n as nextId, i as isStaleVersion, r as reportPersistenceError } from './offline-queue-7Wc4onA0.mjs';
+import { resolvePersistenceAdapter } from './createInMemoryPersistence-DlFjWtOm.mjs';
+import { resolveQueryCacheAdapter, queryCacheKey } from './createInMemoryQueryCache-4AkTV38-.mjs';
 import { createReconnect } from './createReconnect-Di_-oHH7.mjs';
-import { createStream } from './createStream-BDkqO5PW.mjs';
-import { SubscriptionRegistry } from './SubscriptionRegistry-B-Qx_Gux.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)}`;
+const rollbackOptimistic = (optimisticRollbacks) => {
+  for (let index = optimisticRollbacks.length - 1; index >= 0; index -= 1) {
+    optimisticRollbacks[index]?.();
+  }
+};
+const applyRowOpsToView = (rows, ops) => {
+  for (const op of ops) {
+    if (op.op === "delete") {
+      rows.delete(op.key);
+    } else if (op.value !== void 0) {
+      rows.set(op.key, op.value);
+    }
+  }
+};
 const WS_KEEPALIVE_PING = "lunora-ping";
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 3e4;
+const DEFAULT_CONNECT_TIMEOUT_MS = 1e4;
 const QUERY_CACHE_DEBOUNCE_MS = 250;
 const MAX_PENDING_STREAMS = 64;
 const SHARD_TRAFFIC_PATH = "/_lunora/admin/shard-traffic";
@@ -63,22 +104,6 @@ const AUTH_REMOVE_MEMBER_PATH = "/_lunora/admin/auth/organizations/members/remov
 const AUTH_CANCEL_INVITATION_PATH = "/_lunora/admin/auth/organizations/invitations/cancel";
 const DEFAULT_AUTH_BASE_PATH = "/api/auth";
 const GET_SESSION_PATH = "/get-session";
-const compareEntryKeys = ([a], [b]) => {
-  if (a < b) {
-    return -1;
-  }
-  return a > b ? 1 : 0;
-};
-const stableStringify = (value) => {
-  if (value === null || typeof value !== "object") {
-    return JSON.stringify(value);
-  }
-  if (Array.isArray(value)) {
-    return `[${value.map((entry) => stableStringify(entry)).join(",")}]`;
-  }
-  const entries = Object.entries(value).toSorted(compareEntryKeys);
-  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
-};
 const deriveWsUrl = (url) => {
   if (url.startsWith("https://")) {
     return `wss://${url.slice("https://".length)}`;
@@ -103,41 +128,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;
@@ -152,6 +142,14 @@ const buildSubscriptionError = (message) => {
   const messageText = (typeof message.message === "string" ? message.message : void 0) ?? nestedMessage ?? "subscription error";
   return { message: messageText, ...code === void 0 ? {} : { code } };
 };
+const fanSubscriptionError = (callbacks, error) => {
+  for (const errorCallback of callbacks) {
+    try {
+      errorCallback(error);
+    } catch {
+    }
+  }
+};
 const sharedDecoder = new TextDecoder();
 const decodeServerFrame = (raw) => {
   if (typeof raw === "string") {
@@ -174,6 +172,8 @@ const sendOn = (conn, message) => {
   }
 };
 class LunoraClient {
+  /** Hard cap on concurrently-buffered pokes — a backstop that reclaims buffers abandoned by a mid-poke disconnect (no `pokeEnd`). Far above any real concurrent-in-flight count. */
+  static MAX_POKE_BUFFERS = 256;
   url;
   wsUrl;
   wsToken;
@@ -183,11 +183,36 @@ class LunoraClient {
   WebSocketImpl;
   bookmark;
   reconnectOptions;
+  /** WS connect timeout (ms); `0` disables it. See {@link LunoraClientOptions.connectTimeoutMs}. */
+  connectTimeoutMs;
   /** Keepalive cadence (ms); `0` disables the heartbeat. See {@link LunoraClientOptions.heartbeatIntervalMs}. */
   heartbeatIntervalMs;
   offlineQueue;
+  /**
+   * Durable outbox seam (the `@lunora/db` `createExecutorOutboxSink`). When
+   * set, offline writes are delegated here and the built-in {@link OfflineQueue}
+   * is bypassed, so a db app has exactly one durable write path.
+   */
+  outbox;
+  /** Stable per-client id stamped onto every `OutboxMutation` (custom-mutator watermark). */
+  clientId;
+  /**
+   * Highest custom-mutator watermark the server has echoed for this client,
+   * keyed by shard bucket (`shardKey ?? ""`) since the DO tracks one
+   * `__client_watermark` per shard. `callMutator` bumps it from every
+   * ack; the `@lunora/db` mutator runtime seeds its `clientSeq` generator from
+   * it so a reload (which resets the in-memory counter) never reissues a stale
+   * sequence the server would silently swallow as a replay.
+   */
+  clientWatermarks = /* @__PURE__ */ new Map();
+  /** Monotonic per-client mutation counter backing the server `__client_watermark`. */
+  outboxMutationCounter = 0;
   onPersistenceError;
   persistence;
+  /** App/schema version stamped on persisted writes + cached reads; mismatches are purged. */
+  persistenceVersion;
+  /** Releases the multi-tab outbox-leader Web Lock on close (see `hydrateAsOutboxLeader`). */
+  outboxLeaderRelease;
   /** Durable read cache (Pillar 2); `undefined` when `queryCache` is omitted or `false`. */
   queryCache;
   /**
@@ -233,6 +258,14 @@ class LunoraClient {
   // setAuthToken / onAuthTokenChange — part of the exported API contract.
   // eslint-disable-next-line unicorn/no-null -- public auth-token contract sentinel
   authToken = null;
+  /**
+   * Optional STABLE identity subject (a user id), the basis of the offline-queue
+   * identity stamp when supplied. Keeps a same-user token *refresh* from looking
+   * like an identity change (which would discard queued writes). `undefined` =
+   * not supplied, so identity falls back to a hash of the raw token. See
+   * `setAuthToken` / `identityFingerprint`.
+   */
+  authSubject = void 0;
   /**
    * Identity stamp recorded against each queued offline mutation, keyed by
    * the queue-assigned mutation id. Captured at enqueue from the auth token
@@ -243,11 +276,15 @@ 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();
+  /** Subscribers to the offline-queue pending-count (see `onPendingChange`). */
+  pendingChangeListeners = new Listeners();
   /**
    * Whisper-topic handlers, keyed by `connectionKey(shardKey)` → topic → set
    * of callbacks. Membership doubles as the resubscribe set replayed on every
@@ -265,6 +302,11 @@ class LunoraClient {
    * calls `.cancel()` or the iterator is garbage-collected.
    */
   streams = /* @__PURE__ */ new Map();
+  /** Live shape subscriptions (partial replication), keyed by their wire id. */
+  shapeSubscriptions = /* @__PURE__ */ new Map();
+  /** In-flight pokes being assembled between `pokeStart` and `pokeEnd`, keyed by `pokeId`. */
+  pokeBuffers = /* @__PURE__ */ new Map();
+  nextShapeId = 0;
   constructor(options) {
     this.url = options.url;
     this.wsUrl = options.wsUrl ?? joinUrl(deriveWsUrl(options.url), WS_PATH);
@@ -276,14 +318,27 @@ class LunoraClient {
     this.bookmark = options.bookmarkStorage ?? createInMemoryBookmarkStorage();
     this.reconnectOptions = options.reconnect;
     this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    this.connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_CONNECT_TIMEOUT_MS;
     this.defaultConnectionContext = options.connectionContext;
-    this.persistence = options.persistence;
-    this.queryCache = options.queryCache === false ? void 0 : options.queryCache;
+    this.persistence = resolvePersistenceAdapter(options.persistence, options.outbox === void 0);
+    this.persistenceVersion = options.persistenceVersion;
+    this.queryCache = resolveQueryCacheAdapter(options.queryCache);
     this.onPersistenceError = options.offlineQueue?.onPersistenceError;
-    this.offlineQueue = new OfflineQueue(options.offlineQueue, options.persistence);
+    this.offlineQueue = new OfflineQueue(options.offlineQueue, {
+      onEvict: (entry, error) => {
+        this.emitItemSettled(entry, "rejected", error);
+      },
+      onSizeChange: (size) => {
+        this.pendingChangeListeners.emit(size);
+      },
+      persistence: this.persistence,
+      version: options.persistenceVersion
+    });
+    this.outbox = options.outbox;
+    this.clientId = options.clientId ?? `client-${nextId()}`;
     if (this.persistence) {
       queueMicrotask(() => {
-        this.hydratePersistedQueue().catch(() => void 0);
+        this.hydrateAsOutboxLeader();
       });
     }
     if (this.queryCache) {
@@ -298,37 +353,113 @@ class LunoraClient {
    * {@link onAuthTokenChange} listeners so React hooks like `useAuth` stay in
    * sync across all mounted instances.
    *
+   * Pass a STABLE `subject` (the user id) to key the offline-queue identity on
+   * it instead of the token bytes, so a token *refresh* (same user, new JWT)
+   * doesn't read as an identity change and discard queued writes. The subject is
+   * **sticky**: a later call that omits it (or passes `undefined`) keeps the
+   * established subject — so `setAuthToken(refreshedToken)` after a prior
+   * `setAuthToken(token, user.id)` retains the identity. Pass `null` to clear it
+   * (an explicit sign-out). Establishing the subject for the first time on an
+   * UNCHANGED token (e.g. the user id resolves a tick after the token was set)
+   * re-stamps any in-flight queued writes rather than dropping them — same
+   * credential, just a more stable label. A real user switch (the token AND
+   * subject both change) still drops the previous user's writes.
+   *
    * Does NOT update the WebSocket auth — the WS token is fixed at upgrade
    * time and lives in the URL. To refresh live WS auth, call
    * {@link setWsToken} explicitly, which closes existing shard sockets to
    * force a reconnect with the new credential.
    */
-  setAuthToken(token) {
-    if (this.authToken === token) {
-      return;
-    }
+  setAuthToken(token, subject) {
+    const tokenChanged = this.authToken !== token;
+    const previousIdentity = this.identityFingerprint();
     this.authToken = token;
-    this.rejectQueuedForIdentityChange();
-    for (const listener of this.authTokenListeners) {
-      try {
-        listener(token);
-      } catch {
+    if (subject !== void 0) {
+      this.authSubject = subject;
+    }
+    const newIdentity = this.identityFingerprint();
+    if (newIdentity !== previousIdentity) {
+      if (tokenChanged) {
+        this.rejectQueuedForIdentityChange();
+      } else {
+        this.restampQueuedIdentity(previousIdentity, newIdentity);
       }
     }
+    if (tokenChanged) {
+      this.authTokenListeners.emit(token);
+    }
   }
   getAuthToken() {
     return this.authToken;
   }
+  /**
+   * The current identity fingerprint (the same stamp queued offline writes
+   * carry). Exposed so a durable {@link OutboxSink}'s replay handler — which
+   * owns its own at-least-once replay outside the built-in `OfflineQueue` —
+   * can drop a persisted write whose captured `identity` no longer matches the
+   * signed-in user, the guard the queue path applies in `flushOfflineQueue`.
+   */
+  currentIdentity() {
+    return this.identityFingerprint();
+  }
+  /** This client's stable identifier — the watermark key the server's custom-mutator protocol advances per `clientSeq`. */
+  clientIdentifier() {
+    return this.clientId;
+  }
+  /**
+   * The highest custom-mutator watermark the server has echoed for this client
+   * on the given shard (0 if none yet). The `@lunora/db` mutator runtime seeds
+   * its `clientSeq` generator from this so a reload never reissues a sequence
+   * the server has already applied (which it would swallow as a replay, silently
+   * dropping the write).
+   */
+  confirmedMutationWatermark(shardKey) {
+    return this.clientWatermarks.get(shardKey ?? "") ?? 0;
+  }
+  /**
+   * Push a custom mutator to its authoritative server impl over the watermark
+   * protocol (Phase 4): the request carries `x-lunora-client-id` + a monotonic
+   * `x-lunora-client-seq`, so the DO runs it exactly once and advances this
+   * client's `__client_watermark`.
+   *
+   * Returns the server `result` plus `applied`: `true` when the DO ran this push
+   * as the next-in-order mutation, `false` when it was a replay ack (`clientSeq`
+   * was at or below the stored watermark — e.g. a stale sequence after a reload).
+   * A `false` verdict tells the caller to reissue above the now-known watermark
+   * (echoed into {@link confirmedMutationWatermark}) rather than treat the benign
+   * ack as a confirmed write. Every ack — applied or not — bumps the watermark.
+   *
+   * This is the online transport for `@lunora/db`'s client-mutator runtime; the
+   * optimistic overlay + durable-outbox concerns live in that runtime, not here.
+   */
+  async callMutator(functionPath, args, options) {
+    const clientSeq = options?.clientSeq;
+    if (clientSeq !== void 0 && (!Number.isInteger(clientSeq) || clientSeq <= 0)) {
+      throw new Error(`callMutator: clientSeq must be a positive integer, got ${String(clientSeq)}`);
+    }
+    const bucket = options?.shardKey ?? "";
+    let ackWatermark;
+    const result = await this.rpc(functionPath, args, options?.shardKey, {
+      captureBookmark: true,
+      clientId: this.clientId,
+      clientSeq,
+      onMutationAck: (lastMutationId) => {
+        ackWatermark = lastMutationId;
+      }
+    });
+    if (ackWatermark !== void 0 && ackWatermark > (this.clientWatermarks.get(bucket) ?? 0)) {
+      this.clientWatermarks.set(bucket, ackWatermark);
+    }
+    const applied = ackWatermark === void 0 || ackWatermark === clientSeq;
+    return { applied, result };
+  }
   /**
    * Subscribe to auth-token changes. Returns an unsubscribe function. The
    * listener is NOT invoked on registration — use {@link getAuthToken} for
    * 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`
@@ -531,10 +662,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 --------------------------------------------------
   /**
@@ -550,11 +678,43 @@ 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;
+  }
+  /**
+   * Number of offline writes waiting in the built-in queue to be sent — the
+   * depth for a "N changes waiting to sync" indicator. Counts writes that are
+   * queued (offline / mid-reconnect), not ones already in flight on the wire.
+   * A `@lunora/db` app whose writes ride the unified outbox should read
+   * `LunoraDb.pendingCount()` instead (this counts only the built-in queue).
+   */
+  pendingCount() {
+    return this.offlineQueue.size;
+  }
+  /**
+   * Subscribe to changes in {@link pendingCount}. Invokes `listener` immediately
+   * with the current count, then whenever the queue depth changes (a write is
+   * enqueued, flushed, or discarded). Returns an unsubscribe function.
+   */
+  onPendingChange(listener) {
+    const unsubscribe = this.pendingChangeListeners.add(listener);
+    listener(this.offlineQueue.size);
+    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 = {}) {
@@ -578,10 +738,15 @@ class LunoraClient {
       throw new Error("LunoraClient is closed");
     }
     const argsRecord = args;
-    const mutationId = nextId();
-    const optimisticRollbacks = this.applyOptimisticUpdates(function_.__lunoraRef, argsRecord, options.shardKey, options.optimistic);
+    const mutationId = options.mutationId ?? nextId();
+    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";
@@ -592,40 +757,23 @@ class LunoraClient {
     const shouldQueueOffline = this.WebSocketImpl !== void 0 && connectedGate;
     const midReconnect = wsState === "connecting" && connectedGate;
     if (wsState !== "open" && !hasSocket && shouldQueueOffline || midReconnect) {
-      const issuingIdentity = this.identityFingerprint();
-      return new Promise((resolve, reject) => {
-        const entry = {
-          args: argsRecord,
-          functionPath: function_.__lunoraRef,
-          // 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,
-          reject: (error) => {
-            this.queuedIdentities.delete(mutationId);
-            for (let index = optimisticRollbacks.length - 1; index >= 0; index -= 1) {
-              optimisticRollbacks[index]?.();
-            }
-            reject(error instanceof Error ? error : new Error(String(error)));
-          },
-          resolve,
-          shardKey: options.shardKey
-        };
-        this.offlineQueue.enqueue(entry);
-        if (entry.id !== void 0) {
-          this.queuedIdentities.set(entry.id, issuingIdentity);
-        }
-      });
+      return this.enqueueOfflineMutation(function_, argsRecord, options.shardKey, mutationId, optimisticRollbacks, optimisticConfirms);
     }
     try {
-      return await this.rpc(function_.__lunoraRef, argsRecord, options.shardKey, { captureBookmark: true, mutationId });
-    } catch (error) {
-      for (let index = optimisticRollbacks.length - 1; index >= 0; index -= 1) {
-        optimisticRollbacks[index]?.();
+      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;
     }
   }
@@ -739,8 +887,12 @@ class LunoraClient {
    * List a workflow's instances via the admin Workflows proxy
    * (`/_lunora/admin/workflows/instances`) — the Cloudflare control-plane data
    * the `Workflow` binding can't expose. Requires the worker to be built with a
-   * `workflowsClient` (Cloudflare account id + API token); otherwise the proxy
-   * responds 501 and this rejects. `name` is the deployed workflow name.
+   * `workflowsClient` (Cloudflare account id + API token). When one isn't
+   * configured this does NOT reject: the proxy returns a `200 { configured:
+   * false }` sentinel, so the result resolves with `configured === false` and an
+   * empty `instances` list — callers should branch on that flag rather than
+   * try/catch. (The instance-detail / status endpoints still reject with 501.)
+   * `name` is the deployed workflow name.
    */
   async listWorkflowInstances(options) {
     if (this.closed) {
@@ -757,7 +909,13 @@ class LunoraClient {
       query.set("perPage", String(options.perPage));
     }
     const body = await this.adminFetch(`${WORKFLOWS_INSTANCES_PATH}?${query.toString()}`, "GET");
-    return { instances: body.instances ?? [], page: body.page ?? 1, perPage: body.perPage ?? options.perPage ?? 0, totalCount: body.totalCount };
+    return {
+      configured: body.configured,
+      instances: body.instances ?? [],
+      page: body.page ?? 1,
+      perPage: body.perPage ?? options.perPage ?? 0,
+      totalCount: body.totalCount
+    };
   }
   /** Read one workflow instance with its step timeline (`/_lunora/admin/workflows/instance`). */
   async getWorkflowInstance(options) {
@@ -1260,12 +1418,14 @@ class LunoraClient {
         args: argsRecord,
         argsKey,
         callbacks: /* @__PURE__ */ new Set(),
+        checkpointCallbacks: /* @__PURE__ */ new Set(),
         errorCallbacks: /* @__PURE__ */ new Set(),
         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 }
       };
@@ -1275,6 +1435,9 @@ class LunoraClient {
     if (errorCallback) {
       state.errorCallbacks.add(errorCallback);
     }
+    if (options.onCheckpoint) {
+      state.checkpointCallbacks.add(options.onCheckpoint);
+    }
     if (state.lastValue !== void 0) {
       try {
         subscriptionCallback(state.lastValue);
@@ -1289,16 +1452,59 @@ class LunoraClient {
       if (errorCallback) {
         subscriptionState.errorCallbacks.delete(errorCallback);
       }
+      if (options.onCheckpoint) {
+        subscriptionState.checkpointCallbacks.delete(options.onCheckpoint);
+      }
       if (subscriptionState.callbacks.size === 0) {
         const conn = this.getConnection(subscriptionState.shardKey);
         const ok = conn ? sendOn(conn, { id: subscriptionState.id, type: "unsubscribe" }) : false;
         if (!ok && conn) {
-          conn.pendingUnsubscribes.push(subscriptionState.id);
+          conn.pendingUnsubscribes.push({ id: subscriptionState.id, type: "unsubscribe" });
         }
         this.subscriptions.remove(subscriptionState);
       }
     };
   }
+  /**
+   * Subscribe to a declarative **shape** — server-side partial replication
+   * scoped by `shardBy` + the shape's predicate + RLS. The parallel to
+   * {@link subscribe} for the poke protocol: the client sends the shape *name* +
+   * validated `args` (never a `where` the client could forge), the server seeds
+   * the current membership as an insert-poke and streams live membership diffs.
+   * Each applied poke materializes the shape's rowset and invokes `callback`.
+   *
+   * Unlike {@link subscribe}, shape subscriptions are NOT deduped by
+   * (name, args): the server resolves them under the socket's verified identity,
+   * so every call gets its own id + view. The returned function unsubscribes.
+   */
+  subscribeShape(shape, callback, options = {}) {
+    if (this.closed) {
+      throw new Error("LunoraClient is closed");
+    }
+    this.nextShapeId += 1;
+    const id = `shape_${this.nextShapeId.toString()}`;
+    const state = {
+      args: shape.args,
+      callbacks: /* @__PURE__ */ new Set([callback]),
+      errorCallbacks: options.onError ? /* @__PURE__ */ new Set([options.onError]) : /* @__PURE__ */ new Set(),
+      id,
+      name: shape.name,
+      onCheckpoint: options.onCheckpoint,
+      rows: /* @__PURE__ */ new Map(),
+      shardKey: options.shardKey
+    };
+    this.shapeSubscriptions.set(id, state);
+    this.ensureSocket(options.shardKey);
+    this.sendShapeSubscribeIfOpen(state);
+    return () => {
+      this.shapeSubscriptions.delete(id);
+      const conn = this.getConnection(state.shardKey);
+      const ok = conn ? sendOn(conn, { id, type: "shape_unsubscribe" }) : false;
+      if (!ok && conn) {
+        conn.pendingUnsubscribes.push({ id, type: "shape_unsubscribe" });
+      }
+    };
+  }
   /**
    * Open a streaming query. The function reference must be a
    * `kind:"stream"` registration (built with `c.query.input(...).stream(...)`);
@@ -1366,6 +1572,8 @@ class LunoraClient {
   }
   close() {
     this.closed = true;
+    this.outboxLeaderRelease?.();
+    this.outboxLeaderRelease = void 0;
     for (const stream of this.streams.values()) {
       stream.handle.fail(Object.assign(new Error("LunoraClient closed"), { code: "CLIENT_CLOSED" }));
     }
@@ -1375,6 +1583,10 @@ class LunoraClient {
         clearTimeout(conn.reconnectTimer);
         conn.reconnectTimer = void 0;
       }
+      if (conn.connectTimer !== void 0) {
+        clearTimeout(conn.connectTimer);
+        conn.connectTimer = void 0;
+      }
       this.stopHeartbeat(conn);
       if (conn.socket) {
         try {
@@ -1397,9 +1609,83 @@ class LunoraClient {
     this.authTokenListeners.clear();
     this.statusListeners.clear();
     this.tokenExpiredListeners.clear();
+    this.mutationSettledListeners.clear();
+    this.pendingChangeListeners.clear();
     this.whisperHandlers.clear();
+    this.shapeSubscriptions.clear();
+    this.pokeBuffers.clear();
   }
   // --- Internals ----------------------------------------------------------
+  /**
+   * Persist a mutation that can't go out on the wire right now (offline, or
+   * mid-reconnect after a prior connect). The optimistic update has already
+   * been applied by `mutation`; this only chooses the durable write path and
+   * rolls the optimistic write back if persistence is rejected.
+   *
+   * Two paths: when an `outbox` sink is wired (the `@lunora/db` executor) it
+   * owns persistence + at-least-once replay, so we delegate and return
+   * 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, optimisticConfirms) {
+    const issuingIdentity = this.identityFingerprint();
+    if (this.outbox) {
+      this.outboxMutationCounter += 1;
+      const outboxMutationId = this.outboxMutationCounter;
+      try {
+        await this.outbox.enqueue({
+          args: argsRecord,
+          clientId: this.clientId,
+          functionPath: function_.__lunoraRef,
+          idempotencyKey: `${this.clientId}:${String(outboxMutationId)}`,
+          identity: issuingIdentity,
+          mutationId: outboxMutationId,
+          shardKey
+        });
+      } catch (error) {
+        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);
+          reject(error instanceof Error ? error : new Error(String(error)));
+        },
+        resolve,
+        shardKey
+      };
+      this.offlineQueue.enqueue(entry);
+      if (entry.id !== void 0) {
+        this.queuedIdentities.set(entry.id, issuingIdentity);
+      }
+    });
+  }
   /**
    * Restore offline mutations persisted in a prior session and open a socket
    * for each shard they target so they flush once the WS reconnects. Failures
@@ -1414,6 +1700,38 @@ class LunoraClient {
     } catch {
     }
   }
+  /**
+   * Re-queue the durable offline writes — but only as the multi-tab LEADER. The
+   * persisted queue is shared across a profile's tabs; without coordination
+   * every tab would re-queue and replay the same writes (correct only because
+   * the server dedups by idempotency key, but wasteful + racy). A Web Lock makes
+   * exactly one tab hydrate; it holds the lock for its lifetime, so when it
+   * closes another tab acquires the lock and takes over. Falls back to
+   * unconditional hydration where Web Locks are unavailable (React Native, older
+   * browsers, SSR) — single-context there, so no coordination is needed.
+   */
+  hydrateAsOutboxLeader() {
+    const hydrate = () => {
+      this.hydratePersistedQueue().catch(() => void 0);
+    };
+    const locks = globalThis.navigator?.locks;
+    if (!locks) {
+      hydrate();
+      return;
+    }
+    locks.request(`lunora:outbox-leader:${this.url}`, () => {
+      if (!this.closed) {
+        hydrate();
+      }
+      return new Promise((resolve) => {
+        if (this.closed) {
+          resolve();
+          return;
+        }
+        this.outboxLeaderRelease = resolve;
+      });
+    }).catch(hydrate);
+  }
   /**
    * Load every cached query into {@link hydratedQueryCache} so the next
    * `subscribe()` for each key seeds its initial value off disk. A
@@ -1428,6 +1746,10 @@ class LunoraClient {
     try {
       const entries = await this.queryCache.load();
       for (const { key, ...entry } of entries) {
+        if (isStaleVersion(this.persistenceVersion, entry.version)) {
+          this.queryCache.remove(key).catch(() => void 0);
+          continue;
+        }
         this.hydratedQueryCache.set(key, entry);
       }
     } catch {
@@ -1456,7 +1778,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);
@@ -1464,8 +1787,9 @@ class LunoraClient {
       identity: this.identityFingerprint(),
       serverCursor: state.serverCursor,
       ts: Date.now(),
-      value: state.lastValue,
-      ...state.serverEpoch === void 0 ? {} : { serverEpoch: state.serverEpoch }
+      value: authoritative,
+      ...state.serverEpoch === void 0 ? {} : { serverEpoch: state.serverEpoch },
+      ...this.persistenceVersion === void 0 ? {} : { version: this.persistenceVersion }
     });
     this.cacheFlushTimer ??= setTimeout(() => {
       this.flushQueryCacheWrites().catch(() => void 0);
@@ -1504,48 +1828,70 @@ 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 every subscription that matches the
-   * mutation's function ref, shard key, and args, returning the rollback
-   * callbacks to invoke if the mutation later fails. Scoping to the same
-   * (fn, shardKey, args) keeps one user's mutation from clobbering another
-   * subscriber's value on the same function (e.g. two users on different rooms).
+   * 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.
+   *
+   * The registry is already indexed by exactly this triple via
+   * `SubscriptionRegistry.key`, so at most one subscription can match. A direct
+   * O(1) keyed lookup replaces the former O(N) linear scan over all subscriptions.
+   *
+   * `shardKey` normalization: both `undefined` and `""` map to the empty string
+   * inside `SubscriptionRegistry.key` (via `?? ""`), so a mutation fired without
+   * a shardKey correctly matches a subscription registered without one regardless
+   * 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 mutationArgsKey = stableStringify(argsRecord);
-    for (const state of this.subscriptions.all()) {
-      if (state.fn.__lunoraRef !== functionRef || state.shardKey !== mutationShardKey || state.argsKey !== mutationArgsKey) {
-        continue;
-      }
-      const rollback = applyOptimisticToState(state, optimistic);
-      if (rollback) {
-        optimisticRollbacks.push(rollback);
+    const matchKey = SubscriptionRegistry.key(functionRef, argsRecord, mutationShardKey);
+    const state = this.subscriptions.get(matchKey);
+    if (state) {
+      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 {
@@ -1555,6 +1901,7 @@ class LunoraClient {
       return;
     }
     optimisticRollbacks.push(...rollbacks);
+    optimisticConfirms.push(...confirms);
   }
   getConnection(shardKey) {
     return this.connections.get(connectionKey(shardKey));
@@ -1564,6 +1911,7 @@ class LunoraClient {
     let conn = this.connections.get(key);
     if (!conn) {
       conn = {
+        connectTimer: void 0,
         heartbeatTimer: void 0,
         pendingUnsubscribes: [],
         reconnect: createReconnect(this.reconnectOptions),
@@ -1607,6 +1955,12 @@ class LunoraClient {
     if (flags.mutationId) {
       headers["x-lunora-mutation-id"] = flags.mutationId;
     }
+    if (flags.clientId !== void 0) {
+      headers["x-lunora-client-id"] = flags.clientId;
+    }
+    if (flags.clientSeq !== void 0) {
+      headers["x-lunora-client-seq"] = flags.clientSeq.toString();
+    }
     if (flags.attachBookmark) {
       const bookmark = this.bookmark.get();
       if (bookmark) {
@@ -1647,6 +2001,8 @@ class LunoraClient {
       const statusText = response.statusText ? ` ${response.statusText}` : "";
       throw new Error(`LunoraClient: request failed (status ${response.status.toString()}${statusText})`);
     }
+    flags.onMutationAck?.(body.lastMutationId);
+    flags.onCommitCursor?.(body.commitCursor);
     return body.result;
   }
   /**
@@ -1737,11 +2093,27 @@ class LunoraClient {
   sendConnectEnvelope(conn) {
     const context = this.effectiveConnectionContext(connectionKey(conn.shardKey));
     sendOn(conn, {
+      // Lets the server scope this connection's `__client_watermark` so
+      // custom-mutator pokes can echo this client's `lastMutationId`.
+      clientId: this.clientId,
       id: "connect",
       type: "connect",
       ...context === void 0 ? {} : { context }
     });
   }
+  /**
+   * Re-send every shape subscription bound to `shardKey` over its (now open)
+   * socket. Each frame carries the shape's last applied checkpoint, so the
+   * server resumes from it — or re-seeds when the cursor fell below CDC
+   * retention or the epoch forked.
+   */
+  resendShapeSubscriptions(shardKey) {
+    for (const state of this.shapeSubscriptions.values()) {
+      if (connectionKey(state.shardKey) === connectionKey(shardKey)) {
+        this.sendShapeSubscribeIfOpen(state);
+      }
+    }
+  }
   ensureSocket(shardKey) {
     if (this.closed || this.WebSocketImpl === void 0) {
       return;
@@ -1754,7 +2126,27 @@ class LunoraClient {
     this.emitConnectionStatus();
     const socket = new this.WebSocketImpl(this.wsUrlFor(shardKey));
     conn.socket = socket;
+    if (this.connectTimeoutMs > 0) {
+      conn.connectTimer = setTimeout(() => {
+        conn.connectTimer = void 0;
+        if (conn.socket !== socket || conn.wsState !== "connecting") {
+          return;
+        }
+        try {
+          socket.close();
+        } catch {
+        }
+        this.handleDisconnect(conn);
+      }, this.connectTimeoutMs);
+    }
     socket.addEventListener("open", () => {
+      if (conn.socket !== socket) {
+        return;
+      }
+      if (conn.connectTimer !== void 0) {
+        clearTimeout(conn.connectTimer);
+        conn.connectTimer = void 0;
+      }
       conn.wsState = "open";
       conn.wasEverConnected = true;
       conn.reconnect.reset();
@@ -1766,11 +2158,12 @@ class LunoraClient {
           this.sendSubscribeIfOpen(state);
         }
       }
+      this.resendShapeSubscriptions(shardKey);
       if (conn.pendingUnsubscribes.length > 0) {
         const pending = conn.pendingUnsubscribes;
         conn.pendingUnsubscribes = [];
-        for (const id of pending) {
-          sendOn(conn, { id, type: "unsubscribe" });
+        for (const { id, type } of pending) {
+          sendOn(conn, { id, type });
         }
       }
       if (conn.pendingStreams && conn.pendingStreams.length > 0) {
@@ -1793,12 +2186,18 @@ class LunoraClient {
       this.handleServerMessage(event.data, shardKey);
     });
     socket.addEventListener("close", (event) => {
+      if (conn.socket !== socket) {
+        return;
+      }
       if (event?.code === 4001) {
         this.notifyTokenExpired();
       }
       this.handleDisconnect(conn);
     });
     socket.addEventListener("error", () => {
+      if (conn.socket !== socket) {
+        return;
+      }
       if (conn.wsState === "connecting" || conn.wsState === "open") {
         this.handleDisconnect(conn);
       }
@@ -1812,6 +2211,10 @@ class LunoraClient {
       return;
     }
     this.stopHeartbeat(conn);
+    if (conn.connectTimer !== void 0) {
+      clearTimeout(conn.connectTimer);
+      conn.connectTimer = void 0;
+    }
     conn.socket = void 0;
     conn.wsState = "idle";
     this.emitConnectionStatus();
@@ -1885,6 +2288,21 @@ class LunoraClient {
       type: "subscribe"
     });
   }
+  sendShapeSubscribeIfOpen(state) {
+    const conn = this.getConnection(state.shardKey);
+    if (conn?.wsState !== "open") {
+      return;
+    }
+    sendOn(conn, {
+      id: state.id,
+      shape: { name: state.name, ...state.args === void 0 ? {} : { args: state.args } },
+      type: "shape_subscribe",
+      // Resume from the last applied checkpoint when we hold one; a cold
+      // subscribe omits it and the server seeds the full membership.
+      ...state.serverCursor === void 0 ? {} : { sinceCheckpoint: state.serverCursor },
+      ...state.serverEpoch === void 0 ? {} : { sinceEpoch: state.serverEpoch }
+    });
+  }
   handleServerMessage(raw, shardKey) {
     const text = decodeServerFrame(raw);
     if (text === void 0) {
@@ -1923,10 +2341,26 @@ class LunoraClient {
         this.handleErrorMessage(message);
         break;
       }
+      case "pokeEnd": {
+        this.handlePokeEnd(message);
+        break;
+      }
+      case "pokePart": {
+        this.handlePokePart(message);
+        break;
+      }
+      case "pokeStart": {
+        this.handlePokeStart(message);
+        break;
+      }
       case "resume": {
         this.handleResumeMessage(message);
         break;
       }
+      case "settled": {
+        this.handleSettledMessage(message);
+        break;
+      }
       case "whisper": {
         this.dispatchWhisper(message, shardKey);
         break;
@@ -1948,12 +2382,79 @@ class LunoraClient {
     }
     const state = id === void 0 ? void 0 : this.subscriptions.getById(id);
     if (state) {
-      const error = buildSubscriptionError(message);
-      for (const errorCallback of state.errorCallbacks) {
-        try {
-          errorCallback(error);
-        } catch {
-        }
+      fanSubscriptionError(state.errorCallbacks, buildSubscriptionError(message));
+      return;
+    }
+    const shapeState = id === void 0 ? void 0 : this.shapeSubscriptions.get(id);
+    if (shapeState) {
+      fanSubscriptionError(shapeState.errorCallbacks, buildSubscriptionError(message));
+    }
+  }
+  handlePokeStart(message) {
+    if (this.pokeBuffers.size >= LunoraClient.MAX_POKE_BUFFERS) {
+      const oldest = this.pokeBuffers.keys().next().value;
+      if (oldest !== void 0) {
+        this.pokeBuffers.delete(oldest);
+      }
+    }
+    this.pokeBuffers.set(message.pokeId, { baseCheckpoint: message.baseCheckpoint, epoch: message.epoch, lastMutationId: /* @__PURE__ */ new Map(), parts: /* @__PURE__ */ new Map() });
+  }
+  handlePokePart(message) {
+    const buffer = this.pokeBuffers.get(message.pokeId);
+    if (!buffer) {
+      return;
+    }
+    const existing = buffer.parts.get(message.shapeId) ?? [];
+    existing.push(...message.rowsPatch);
+    buffer.parts.set(message.shapeId, existing);
+    if (message.lastMutationId !== void 0) {
+      buffer.lastMutationId.set(message.shapeId, message.lastMutationId);
+    }
+  }
+  handlePokeEnd(message) {
+    const buffer = this.pokeBuffers.get(message.pokeId);
+    if (!buffer) {
+      return;
+    }
+    this.pokeBuffers.delete(message.pokeId);
+    for (const [shapeId, ops] of buffer.parts) {
+      const state = this.shapeSubscriptions.get(shapeId);
+      if (!state) {
+        continue;
+      }
+      const epochForked = buffer.epoch !== void 0 && state.serverEpoch !== void 0 && buffer.epoch !== state.serverEpoch;
+      const baseDiverged = buffer.baseCheckpoint !== void 0 && state.serverCursor !== void 0 && state.serverCursor !== buffer.baseCheckpoint;
+      if (epochForked || baseDiverged) {
+        state.rows.clear();
+        state.serverCursor = void 0;
+        state.serverEpoch = void 0;
+        this.emitShapeRows(state);
+        this.sendShapeSubscribeIfOpen(state);
+        continue;
+      }
+      applyRowOpsToView(state.rows, ops);
+      if (message.checkpoint !== void 0) {
+        state.serverCursor = message.checkpoint;
+      }
+      if (message.epoch !== void 0) {
+        state.serverEpoch = message.epoch;
+      }
+      const watermark = buffer.lastMutationId.get(shapeId);
+      if (watermark !== void 0) {
+        state.lastMutationId = watermark;
+      }
+      this.emitShapeRows(state);
+      state.onCheckpoint?.({ checkpoint: state.serverCursor, mutationId: state.lastMutationId });
+    }
+  }
+  /** Materialize a shape's keyed view to an array and invoke its callbacks. */
+  // eslint-disable-next-line class-methods-use-this -- a pure state→callback fan-out kept beside the shape-subscription pipeline it serves.
+  emitShapeRows(state) {
+    const rows = [...state.rows.values()];
+    for (const shapeCallback of state.callbacks) {
+      try {
+        shapeCallback(rows);
+      } catch {
       }
     }
   }
@@ -1964,8 +2465,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;
     }
@@ -1973,12 +2473,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
@@ -1993,15 +2489,51 @@ class LunoraClient {
     if (!state) {
       return;
     }
+    this.ackAndAdvanceCursor(state, message.cursor, message.epoch);
+  }
+  /**
+   * Handle a `settled` frame: a write touched one of this subscription's read
+   * tables but produced a byte-identical result, so the server suppressed the
+   * data frame. Like {@link handleResumeMessage} the value didn't change — we
+   * advance the resume position and re-persist — but we ALSO surface the echoed
+   * custom-mutator watermark via `onCheckpoint` so a `@lunora/db` list
+   * collection drops the optimistic overlay for the confirmed write (otherwise
+   * its checkpoint gate, fed only by data frames, would hang forever). Sent
+   * only to custom-mutator clients; plain `useQuery` subscribers leave
+   * `onCheckpoint` unset and this is a near no-op.
+   */
+  handleSettledMessage(message) {
+    const state = this.subscriptions.getById(message.id);
+    if (!state) {
+      return;
+    }
+    this.ackAndAdvanceCursor(state, message.cursor, message.epoch);
+    if (message.lastMutationId !== void 0) {
+      state.lastMutationId = message.lastMutationId;
+    }
+    for (const onCheckpoint of state.checkpointCallbacks) {
+      onCheckpoint({ checkpoint: state.serverCursor, mutationId: state.lastMutationId });
+    }
+  }
+  /**
+   * Mark `state` acked and, when the frame carries a newer cursor/epoch than
+   * the cached position, advance the resume watermark and re-persist. Shared by
+   * the `resume` and `settled` frame handlers — both acknowledge "nothing the
+   * client must re-render changed, but the resume position may have moved".
+   */
+  ackAndAdvanceCursor(state, cursor, epoch) {
     state.acked = true;
-    if (message.cursor !== void 0 && message.cursor !== state.serverCursor || message.epoch !== void 0 && message.epoch !== state.serverEpoch) {
-      if (message.cursor !== void 0) {
-        state.serverCursor = message.cursor;
+    if (cursor !== void 0 && cursor !== state.serverCursor || epoch !== void 0 && epoch !== state.serverEpoch) {
+      if (cursor !== void 0) {
+        state.serverCursor = cursor;
       }
-      if (message.epoch !== void 0) {
-        state.serverEpoch = message.epoch;
+      if (epoch !== void 0) {
+        state.serverEpoch = epoch;
       }
       this.persistQueryValue(state);
+      if (dropConfirmedLayers(state, state.serverCursor)) {
+        notifySubscription(state, foldOptimistic(state.serverBase, state.optimisticLayers));
+      }
     }
   }
   /**
@@ -2022,8 +2554,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;
       }
@@ -2045,12 +2577,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);
@@ -2081,6 +2608,9 @@ class LunoraClient {
   // `null` is the distinct "signed out" identity (separate from `undefined`,
   // which means "not stamped / hydrated"); the two must not be conflated.
   identityFingerprint() {
+    if (this.authSubject !== void 0) {
+      return this.authSubject === null ? null : `subj:${this.authSubject}`;
+    }
     const token = this.authToken;
     if (token === null) {
       return null;
@@ -2107,9 +2637,25 @@ 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();
   }
+  /**
+   * Migrate every live identity stamp from `from` to `to` — used when the auth
+   * identity label changes but the underlying credential (token) does NOT, e.g.
+   * the user id resolves a tick after the token was set. The in-memory
+   * `queuedIdentities` map is the flush-time source of truth, so re-stamping it
+   * keeps the in-flight writes replayable under the new (more stable) identity
+   * instead of the flush guard discarding them as a mismatch.
+   */
+  restampQueuedIdentity(from, to) {
+    for (const [id, stamp] of this.queuedIdentities) {
+      if (stamp === from) {
+        this.queuedIdentities.set(id, to);
+      }
+    }
+  }
   /**
    * Drop the durable read cache on an identity change so a cached value stamped
    * under the previous identity can never hydrate into a new session. Clears
@@ -2142,17 +2688,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));