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

package/dist/auth/index.d.mts

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

package/dist/auth/index.d.ts

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

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-DzEWBYeP.mjs";
-export { type C as CachedQuery, type e as ClientMessage, type f as ClientShapeSubscribeMessage, type g as ClientShapeUnsubscribeMessage, type h as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type i as FunctionArgumentDescriptor, type j as FunctionDescriptor, type G as GlobalFacetResult, type k as GlobalFacetValue, type l as GlobalFilterClause, type m as GlobalTableInfo, type n as GlobalTablePage, L as LunoraClient, type o as LunoraClientOptions, type p as OptimisticLocalStore, type q as OptimisticUpdate, type r as OutboxMutation, type s as OutboxSink, type t as PersistedMutation, type P as Preloaded, type u as RowOp, type v as RpcEnvelope, type w as RpcResponseBody, type x as ScheduleRecord, type y as SchedulerPoolStatus, type z as SchedulerStatus, type E as ServerMessage, type H as ServerPokeEndMessage, type I as ServerPokePartMessage, type J as ServerPokeStartMessage, type K as ShardTrafficEntry, type N as ShardTrafficResult, type T as StorageListPage, type V as StorageObject, type W as StreamHandle, type X as StreamIterable, type Y as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, Z as SubscriptionRegistry, type _ as SubscriptionState, type $ as SyncWatermark, type a as Unsubscribe, type U as User, type a0 as WorkflowInstanceAction, type a1 as WorkflowInstanceDetail, type a2 as WorkflowInstancePage, type a3 as WorkflowInstanceStatus, type a4 as WorkflowInstanceSummary, type a5 as WorkflowStepDetail, a6 as createLocalStore, a7 as createStream } from "./packem_shared/lunora-client.d-DzEWBYeP.mjs";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-DuYqEQ5J.mjs";
+import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-CeUZ8lE1.mjs";
+export { type C as CachedQuery, type e as ClientMessage, type f as ClientShapeSubscribeMessage, type g as ClientShapeUnsubscribeMessage, type h as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type i as FunctionArgumentDescriptor, type j as FunctionDescriptor, type G as GlobalFacetResult, type k as GlobalFacetValue, type l as GlobalFilterClause, type m as GlobalTableInfo, type n as GlobalTablePage, L as LunoraClient, type o as LunoraClientOptions, type p as OptimisticLocalStore, type q as OptimisticUpdate, type r as OutboxMutation, type s as OutboxSink, type t as PersistedMutation, type P as Preloaded, type u as RowOp, type v as RpcEnvelope, type w as RpcResponseBody, type x as ScheduleRecord, type y as SchedulerPoolStatus, type z as SchedulerStatus, type E as ServerMessage, type H as ServerPokeEndMessage, type I as ServerPokePartMessage, type J as ServerPokeStartMessage, type K as ShardTrafficEntry, type N as ShardTrafficResult, type T as StorageListPage, type V as StorageObject, type W as StreamHandle, type X as StreamIterable, type Y as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, Z as SubscriptionRegistry, type _ as SubscriptionState, type $ as SyncWatermark, type a as Unsubscribe, type U as User, type a0 as WorkflowInstanceAction, type a1 as WorkflowInstanceDetail, type a2 as WorkflowInstancePage, type a3 as WorkflowInstanceStatus, type a4 as WorkflowInstanceSummary, type a5 as WorkflowStepDetail, a6 as createLocalStore, a7 as createStream } from "./packem_shared/lunora-client.d-CeUZ8lE1.mjs";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-DipqU0PI.mjs";
 export type { AuthCapabilities, AuthImpersonation, AuthPage, AuthSession, AuthUser, CronJobInfo, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
 /**
 * The slice of React Native's `AsyncStorage` (or any async key/value store —

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-DzEWBYeP.js";
-export { type C as CachedQuery, type e as ClientMessage, type f as ClientShapeSubscribeMessage, type g as ClientShapeUnsubscribeMessage, type h as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type i as FunctionArgumentDescriptor, type j as FunctionDescriptor, type G as GlobalFacetResult, type k as GlobalFacetValue, type l as GlobalFilterClause, type m as GlobalTableInfo, type n as GlobalTablePage, L as LunoraClient, type o as LunoraClientOptions, type p as OptimisticLocalStore, type q as OptimisticUpdate, type r as OutboxMutation, type s as OutboxSink, type t as PersistedMutation, type P as Preloaded, type u as RowOp, type v as RpcEnvelope, type w as RpcResponseBody, type x as ScheduleRecord, type y as SchedulerPoolStatus, type z as SchedulerStatus, type E as ServerMessage, type H as ServerPokeEndMessage, type I as ServerPokePartMessage, type J as ServerPokeStartMessage, type K as ShardTrafficEntry, type N as ShardTrafficResult, type T as StorageListPage, type V as StorageObject, type W as StreamHandle, type X as StreamIterable, type Y as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, Z as SubscriptionRegistry, type _ as SubscriptionState, type $ as SyncWatermark, type a as Unsubscribe, type U as User, type a0 as WorkflowInstanceAction, type a1 as WorkflowInstanceDetail, type a2 as WorkflowInstancePage, type a3 as WorkflowInstanceStatus, type a4 as WorkflowInstanceSummary, type a5 as WorkflowStepDetail, a6 as createLocalStore, a7 as createStream } from "./packem_shared/lunora-client.d-DzEWBYeP.js";
-export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-CmMMC-wm.js";
+import { c as PersistenceAdapter, B as BookmarkStorage, F as FunctionReference, A as ArgsOf, M as MutationCallOptions, R as ReturnOf, O as OfflineQueueOptions, Q as QueryCacheAdapter, d as ReconnectOptions } from "./packem_shared/lunora-client.d-CeUZ8lE1.js";
+export { type C as CachedQuery, type e as ClientMessage, type f as ClientShapeSubscribeMessage, type g as ClientShapeUnsubscribeMessage, type h as ConnectionStatus, D as DEFAULT_MAX_BUFFER, type i as FunctionArgumentDescriptor, type j as FunctionDescriptor, type G as GlobalFacetResult, type k as GlobalFacetValue, type l as GlobalFilterClause, type m as GlobalTableInfo, type n as GlobalTablePage, L as LunoraClient, type o as LunoraClientOptions, type p as OptimisticLocalStore, type q as OptimisticUpdate, type r as OutboxMutation, type s as OutboxSink, type t as PersistedMutation, type P as Preloaded, type u as RowOp, type v as RpcEnvelope, type w as RpcResponseBody, type x as ScheduleRecord, type y as SchedulerPoolStatus, type z as SchedulerStatus, type E as ServerMessage, type H as ServerPokeEndMessage, type I as ServerPokePartMessage, type J as ServerPokeStartMessage, type K as ShardTrafficEntry, type N as ShardTrafficResult, type T as StorageListPage, type V as StorageObject, type W as StreamHandle, type X as StreamIterable, type Y as SubscriptionCallback, type S as SubscriptionError, type b as SubscriptionErrorCallback, Z as SubscriptionRegistry, type _ as SubscriptionState, type $ as SyncWatermark, type a as Unsubscribe, type U as User, type a0 as WorkflowInstanceAction, type a1 as WorkflowInstanceDetail, type a2 as WorkflowInstancePage, type a3 as WorkflowInstanceStatus, type a4 as WorkflowInstanceSummary, type a5 as WorkflowStepDetail, a6 as createLocalStore, a7 as createStream } from "./packem_shared/lunora-client.d-CeUZ8lE1.js";
+export { p as preloadQuery, a as preloadedQueryResult } from "./packem_shared/preload.d-CzHLgVfw.js";
 export type { AuthCapabilities, AuthImpersonation, AuthPage, AuthSession, AuthUser, CronJobInfo, VectorIndexSummary, VectorQueryMatch } from '@lunora/runtime';
 /**
 * The slice of React Native's `AsyncStorage` (or any async key/value store —

package/dist/index.mjs

@@ -3,7 +3,7 @@ export { default as createInMemoryBookmarkStorage } from './packem_shared/create
 export { applyDelta, isMutationDelta } from './packem_shared/applyDelta-4jFGTPA3.mjs';
 export { CONFLICT_ERROR_CODE, isConflictError } from './packem_shared/CONFLICT_ERROR_CODE-aUdVbEDw.mjs';
 export { createLocalStore } from './packem_shared/createLocalStore-DSUfoLqY.mjs';
-export { LunoraClient } from './packem_shared/LunoraClient-DhwA_5Kj.mjs';
+export { LunoraClient } from './packem_shared/LunoraClient-Bsv8immC.mjs';
 export { createMutationRunner } from './packem_shared/createMutationRunner-BqsavzvG.mjs';
 export { createMutatorRunner } from './packem_shared/createMutatorRunner-BETvCd0p.mjs';
 export { OfflineQueue } from './packem_shared/OfflineQueue-D-ASeqL7.mjs';

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

@@ -1341,6 +1341,7 @@ class LunoraClient {
         args: argsRecord,
         argsKey,
         callbacks: /* @__PURE__ */ new Set(),
+        checkpointCallbacks: /* @__PURE__ */ new Set(),
         errorCallbacks: /* @__PURE__ */ new Set(),
         fn: function_,
         id,
@@ -1356,6 +1357,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);
@@ -1370,6 +1374,9 @@ 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;
@@ -2197,6 +2204,10 @@ class LunoraClient {
         this.handleResumeMessage(message);
         break;
       }
+      case "settled": {
+        this.handleSettledMessage(message);
+        break;
+      }
       case "whisper": {
         this.dispatchWhisper(message, shardKey);
         break;
@@ -2330,13 +2341,46 @@ 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);
     }

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

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

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

@@ -476,6 +476,29 @@ interface ServerResumeMessage {
   lastMutationId?: number;
   type: "resume";
 }
+/**
+* Settled acknowledgement for a **list** subscription: a write touched one of
+* the subscription's read tables but produced a byte-identical result, so the
+* server suppressed the data frame. Sent ONLY to a `@lunora/db` custom-mutator
+* client (one that announced a `clientId`, hence has a server-side
+* `__client_watermark`) so its optimistic list overlay drops even when no data
+* frame arrives. Plain `useQuery` subscribers never receive it, and an older
+* client safely ignores the unknown frame.
+*/
+interface ServerSettledMessage {
+  cursor?: number;
+  /** The CDC epoch this settled frame's cursor belongs to (see {@link CachedQuery.serverEpoch}). */
+  epoch?: string;
+  id: string;
+  /**
+  * The highest custom-mutator `mutationId` from this client the server has
+  * now applied (the per-client `__client_watermark`). Forwarded to a
+  * collection's `onCheckpoint` so it can drop the overlay for the confirmed
+  * write whose result didn't change this list.
+  */
+  lastMutationId?: number;
+  type: "settled";
+}
 interface ServerErrorMessage {
   error?: unknown;
   id?: string;
@@ -543,7 +566,7 @@ interface ServerPokeStartMessage {
 }
 /** One shape's slice of an in-flight poke: the row-ops to apply for `shapeId`. */
 interface ServerPokePartMessage {
-  /** Per-client custom-mutator watermark carried with this slice (see {@link ServerDataMessage.lastMutationId}). */
+  /** Per-client custom-mutator watermark carried with this slice (see {@link ServerSettledMessage.lastMutationId}). */
   lastMutationId?: number;
   pokeId: string;
   /** Ordered row-level changes for this shape, applied in sequence at `pokeEnd`. */
@@ -566,7 +589,7 @@ interface ServerPokeEndMessage {
   pokeId: string;
   type: "pokeEnd";
 }
-type ServerMessage = ServerAckMessage | ServerChunkMessage | ServerCompleteMessage | ServerDataMessage | ServerErrorMessage | ServerPokeEndMessage | ServerPokePartMessage | ServerPokeStartMessage | ServerResumeMessage | ServerWhisperMessage;
+type ServerMessage = ServerAckMessage | ServerChunkMessage | ServerCompleteMessage | ServerDataMessage | ServerErrorMessage | ServerPokeEndMessage | ServerPokePartMessage | ServerPokeStartMessage | ServerResumeMessage | ServerSettledMessage | ServerWhisperMessage;
 /**
 * The authenticated user as exposed client-side, mirroring better-auth's
 * `user` row (the `user` field of the `get-session` response). Kept minimal
@@ -808,10 +831,34 @@ interface SubscriptionState {
   */
   readonly argsKey: string;
   readonly callbacks: Set<SubscriptionCallback>;
+  /**
+  * Notified when a `settled` frame advances this subscription's watermark — a
+  * write touched the subscription's tables but the result was byte-identical,
+  * so the server suppressed the data frame. A `@lunora/db` list collection
+  * uses this to drop the optimistic overlay for the confirmed write.
+  *
+  * A SET (not a single slot) because `SubscriptionState` is SHARED across
+  * every subscriber to the same `(fn, args, shardKey)`: a `@lunora/db`
+  * collection may subscribe to a query a plain `useQuery` already opened, so
+  * each subscriber registers its own callback (mirroring `callbacks` /
+  * `errorCallbacks`) and a `settled` frame fans out to all of them. Plain
+  * `useQuery` consumers register nothing, leaving the set empty.
+  */
+  readonly checkpointCallbacks: Set<(watermark: {
+    checkpoint?: number;
+    mutationId?: number;
+  }) => void>;
   /** Notified when the server rejects this subscription (e.g. admin auth). */
   readonly errorCallbacks: Set<SubscriptionErrorCallback>;
   readonly fn: FunctionReference;
   readonly id: string;
+  /**
+  * The highest custom-mutator `mutationId` from this client the server has
+  * applied, captured from the last `settled` frame (the suppressed-list-frame
+  * watermark). Forwarded to {@link SubscriptionState.checkpointCallbacks}.
+  * Absent until a `settled` frame arrives.
+  */
+  lastMutationId?: number;
   /** Last known value, used to short-circuit `useQuery`-style consumers. */
   lastValue: unknown;
   /**
@@ -1699,6 +1746,7 @@ declare class LunoraClient {
     userId?: string;
   }): Promise<AuthPage<AuthSession>>;
   subscribe<F extends FunctionReference>(function_: F, args: ArgsOf<F>, callback: (data: ReturnOf<F>) => void, options?: {
+    onCheckpoint?: (watermark: SyncWatermark) => void;
     onError?: SubscriptionErrorCallback;
     shardKey?: string;
   }): Unsubscribe;
@@ -1902,6 +1950,25 @@ declare class LunoraClient {
   */
   private handleResumeMessage;
   /**
+  * 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.
+  */
+  private handleSettledMessage;
+  /**
+  * 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".
+  */
+  private ackAndAdvanceCursor;
+  /**
   * Resolve the value to publish for a `data`/`delta` frame.
   *
   * A `data` frame is an authoritative snapshot (the server re-execution path)

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

@@ -476,6 +476,29 @@ interface ServerResumeMessage {
   lastMutationId?: number;
   type: "resume";
 }
+/**
+* Settled acknowledgement for a **list** subscription: a write touched one of
+* the subscription's read tables but produced a byte-identical result, so the
+* server suppressed the data frame. Sent ONLY to a `@lunora/db` custom-mutator
+* client (one that announced a `clientId`, hence has a server-side
+* `__client_watermark`) so its optimistic list overlay drops even when no data
+* frame arrives. Plain `useQuery` subscribers never receive it, and an older
+* client safely ignores the unknown frame.
+*/
+interface ServerSettledMessage {
+  cursor?: number;
+  /** The CDC epoch this settled frame's cursor belongs to (see {@link CachedQuery.serverEpoch}). */
+  epoch?: string;
+  id: string;
+  /**
+  * The highest custom-mutator `mutationId` from this client the server has
+  * now applied (the per-client `__client_watermark`). Forwarded to a
+  * collection's `onCheckpoint` so it can drop the overlay for the confirmed
+  * write whose result didn't change this list.
+  */
+  lastMutationId?: number;
+  type: "settled";
+}
 interface ServerErrorMessage {
   error?: unknown;
   id?: string;
@@ -543,7 +566,7 @@ interface ServerPokeStartMessage {
 }
 /** One shape's slice of an in-flight poke: the row-ops to apply for `shapeId`. */
 interface ServerPokePartMessage {
-  /** Per-client custom-mutator watermark carried with this slice (see {@link ServerDataMessage.lastMutationId}). */
+  /** Per-client custom-mutator watermark carried with this slice (see {@link ServerSettledMessage.lastMutationId}). */
   lastMutationId?: number;
   pokeId: string;
   /** Ordered row-level changes for this shape, applied in sequence at `pokeEnd`. */
@@ -566,7 +589,7 @@ interface ServerPokeEndMessage {
   pokeId: string;
   type: "pokeEnd";
 }
-type ServerMessage = ServerAckMessage | ServerChunkMessage | ServerCompleteMessage | ServerDataMessage | ServerErrorMessage | ServerPokeEndMessage | ServerPokePartMessage | ServerPokeStartMessage | ServerResumeMessage | ServerWhisperMessage;
+type ServerMessage = ServerAckMessage | ServerChunkMessage | ServerCompleteMessage | ServerDataMessage | ServerErrorMessage | ServerPokeEndMessage | ServerPokePartMessage | ServerPokeStartMessage | ServerResumeMessage | ServerSettledMessage | ServerWhisperMessage;
 /**
 * The authenticated user as exposed client-side, mirroring better-auth's
 * `user` row (the `user` field of the `get-session` response). Kept minimal
@@ -808,10 +831,34 @@ interface SubscriptionState {
   */
   readonly argsKey: string;
   readonly callbacks: Set<SubscriptionCallback>;
+  /**
+  * Notified when a `settled` frame advances this subscription's watermark — a
+  * write touched the subscription's tables but the result was byte-identical,
+  * so the server suppressed the data frame. A `@lunora/db` list collection
+  * uses this to drop the optimistic overlay for the confirmed write.
+  *
+  * A SET (not a single slot) because `SubscriptionState` is SHARED across
+  * every subscriber to the same `(fn, args, shardKey)`: a `@lunora/db`
+  * collection may subscribe to a query a plain `useQuery` already opened, so
+  * each subscriber registers its own callback (mirroring `callbacks` /
+  * `errorCallbacks`) and a `settled` frame fans out to all of them. Plain
+  * `useQuery` consumers register nothing, leaving the set empty.
+  */
+  readonly checkpointCallbacks: Set<(watermark: {
+    checkpoint?: number;
+    mutationId?: number;
+  }) => void>;
   /** Notified when the server rejects this subscription (e.g. admin auth). */
   readonly errorCallbacks: Set<SubscriptionErrorCallback>;
   readonly fn: FunctionReference;
   readonly id: string;
+  /**
+  * The highest custom-mutator `mutationId` from this client the server has
+  * applied, captured from the last `settled` frame (the suppressed-list-frame
+  * watermark). Forwarded to {@link SubscriptionState.checkpointCallbacks}.
+  * Absent until a `settled` frame arrives.
+  */
+  lastMutationId?: number;
   /** Last known value, used to short-circuit `useQuery`-style consumers. */
   lastValue: unknown;
   /**
@@ -1699,6 +1746,7 @@ declare class LunoraClient {
     userId?: string;
   }): Promise<AuthPage<AuthSession>>;
   subscribe<F extends FunctionReference>(function_: F, args: ArgsOf<F>, callback: (data: ReturnOf<F>) => void, options?: {
+    onCheckpoint?: (watermark: SyncWatermark) => void;
     onError?: SubscriptionErrorCallback;
     shardKey?: string;
   }): Unsubscribe;
@@ -1902,6 +1950,25 @@ declare class LunoraClient {
   */
   private handleResumeMessage;
   /**
+  * 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.
+  */
+  private handleSettledMessage;
+  /**
+  * 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".
+  */
+  private ackAndAdvanceCursor;
+  /**
   * Resolve the value to publish for a `data`/`delta` frame.
   *
   * A `data` frame is an authoritative snapshot (the server re-execution path)

package/dist/packem_shared/{preload.d-CmMMC-wm.d.ts → preload.d-CzHLgVfw.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-DzEWBYeP.js";
+import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-CeUZ8lE1.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/packem_shared/{preload.d-DuYqEQ5J.d.mts → preload.d-DipqU0PI.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-DzEWBYeP.mjs";
+import { F as FunctionReference, L as LunoraClient, A as ArgsOf, R as ReturnOf, P as Preloaded } from "./lunora-client.d-CeUZ8lE1.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/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-DzEWBYeP.mjs";
-export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-DzEWBYeP.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-CeUZ8lE1.mjs";
+export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-CeUZ8lE1.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-DzEWBYeP.js";
-export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-DzEWBYeP.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-CeUZ8lE1.js";
+export type { b as SubscriptionErrorCallback } from "../packem_shared/lunora-client.d-CeUZ8lE1.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-DzEWBYeP.mjs";
-export type { A as ArgsOf, F as FunctionReference, R as ReturnOf } from "../packem_shared/lunora-client.d-DzEWBYeP.mjs";
-export { p as preloadQuery, a as preloadedQueryResult } from "../packem_shared/preload.d-DuYqEQ5J.mjs";
+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 '@lunora/runtime';
 /**
 * Structural shape of a better-auth `getSession` call's resolved value.

package/dist/ssr/index.d.ts

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

package/dist/ssr/index.mjs

@@ -1,4 +1,4 @@
 export { getServerSession } from '../packem_shared/getServerSession-8jXewqxd.mjs';
 export { deserializePreloaded, serializePreloaded } from '../packem_shared/deserializePreloaded-C0eJTY_W.mjs';
-export { createServerClient } from '../packem_shared/createServerClient-XahK8bPv.mjs';
+export { createServerClient } from '../packem_shared/createServerClient-DucOyOz3.mjs';
 export { preloadQuery, preloadedQueryResult } from '../packem_shared/preloadQuery-lobFkD2Z.mjs';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/client",
-  "version": "1.0.0-alpha.6",
+  "version": "1.0.0-alpha.8",
   "description": "Lunora browser SDK: WebSocket transport, optimistic updates, and an offline mutation queue",
   "keywords": [
     "cloudflare",