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

package/dist/packem_shared/{LunoraClient-DHMV-94j.mjs → LunoraClient-DhwA_5Kj.mjs}

@@ -2,7 +2,7 @@ import { S as SubscriptionRegistry, s as stableStringify } from './subscription-
 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 { OfflineQueue, nextId, reportPersistenceError } from './OfflineQueue-D-ASeqL7.mjs';
 import { queryCacheKey } from './createInMemoryQueryCache-B1PQ9Twl.mjs';
 import { createReconnect } from './createReconnect-Di_-oHH7.mjs';
 import { createStream } from './DEFAULT_MAX_BUFFER-BDkqO5PW.mjs';
@@ -10,6 +10,20 @@ import { createStream } from './DEFAULT_MAX_BUFFER-BDkqO5PW.mjs';
 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;
@@ -137,6 +151,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") {
@@ -159,6 +181,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;
@@ -173,6 +197,25 @@ class LunoraClient {
   /** 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;
   /** Durable read cache (Pillar 2); `undefined` when `queryCache` is omitted or `false`. */
@@ -252,6 +295,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);
@@ -269,6 +317,8 @@ class LunoraClient {
     this.queryCache = options.queryCache === false ? void 0 : options.queryCache;
     this.onPersistenceError = options.offlineQueue?.onPersistenceError;
     this.offlineQueue = new OfflineQueue(options.offlineQueue, options.persistence);
+    this.outbox = options.outbox;
+    this.clientId = options.clientId ?? `client-${nextId()}`;
     if (this.persistence) {
       queueMicrotask(() => {
         this.hydratePersistedQueue().catch(() => void 0);
@@ -307,6 +357,67 @@ class LunoraClient {
   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
@@ -566,7 +677,7 @@ class LunoraClient {
       throw new Error("LunoraClient is closed");
     }
     const argsRecord = args;
-    const mutationId = nextId();
+    const mutationId = options.mutationId ?? nextId();
     const optimisticRollbacks = this.applyOptimisticUpdates(function_.__lunoraRef, argsRecord, options.shardKey, options.optimistic);
     if (options.optimisticUpdate) {
       this.applyOptimisticUpdate(options.optimisticUpdate, args, options.shardKey, optimisticRollbacks);
@@ -580,40 +691,12 @@ 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);
     }
     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]?.();
-      }
+      rollbackOptimistic(optimisticRollbacks);
       throw error;
     }
   }
@@ -1291,12 +1374,52 @@ class LunoraClient {
         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(...)`);
@@ -1400,8 +1523,66 @@ class LunoraClient {
     this.statusListeners.clear();
     this.tokenExpiredListeners.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) {
+    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));
+      }
+      return void 0;
+    }
+    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);
+          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
@@ -1514,22 +1695,27 @@ class LunoraClient {
     }
   }
   /**
-   * 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 = [];
     if (!optimistic) {
       return optimisticRollbacks;
     }
-    const mutationArgsKey = stableStringify(argsRecord);
-    for (const state of this.subscriptions.all()) {
-      if (state.fn.__lunoraRef !== functionRef || state.shardKey !== mutationShardKey || state.argsKey !== mutationArgsKey) {
-        continue;
-      }
+    const matchKey = SubscriptionRegistry.key(functionRef, argsRecord, mutationShardKey);
+    const state = this.subscriptions.get(matchKey);
+    if (state) {
       const rollback = applyOptimisticToState(state, optimistic);
       if (rollback) {
         optimisticRollbacks.push(rollback);
@@ -1610,6 +1796,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) {
@@ -1650,6 +1842,7 @@ class LunoraClient {
       const statusText = response.statusText ? ` ${response.statusText}` : "";
       throw new Error(`LunoraClient: request failed (status ${response.status.toString()}${statusText})`);
     }
+    flags.onMutationAck?.(body.lastMutationId);
     return body.result;
   }
   /**
@@ -1740,11 +1933,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;
@@ -1789,11 +1998,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) {
@@ -1918,6 +2128,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) {
@@ -1956,6 +2181,18 @@ 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;
@@ -1981,12 +2218,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 {
       }
     }
   }

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

@@ -4,7 +4,11 @@ const nextId = () => {
     return crypto.randomUUID();
   }
   idCounter += 1;
-  return `m_${Date.now().toString(36)}_${idCounter.toString(36)}`;
+  const entropy = typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function" ? [...crypto.getRandomValues(new Uint8Array(8))].map((byte) => byte.toString(16).padStart(2, "0")).join("") : (
+    // eslint-disable-next-line sonarjs/pseudo-random -- non-cryptographic uniqueness entropy, not a security token; only reached when neither crypto.randomUUID nor crypto.getRandomValues exists
+    Math.random().toString(16).slice(2, 12)
+  );
+  return `m_${Date.now().toString(36)}_${idCounter.toString(36)}_${entropy}`;
 };
 const reportPersistenceError = (handler, operation, error, mutationId) => {
   if (handler) {

package/dist/packem_shared/createMutatorRunner-BETvCd0p.mjs

@@ -0,0 +1,31 @@
+const createMutatorRunner = (handle, sinks) => {
+  let inFlight = 0;
+  let latestInvocation = 0;
+  const mutate = async (args) => {
+    latestInvocation += 1;
+    const invocation = latestInvocation;
+    inFlight += 1;
+    sinks.setPending(true);
+    try {
+      await handle(args).isPersisted.promise;
+      if (invocation === latestInvocation) {
+        sinks.setError(void 0);
+      }
+    } catch (error) {
+      const normalized = error instanceof Error ? error : new Error(String(error));
+      if (invocation === latestInvocation) {
+        sinks.setError(normalized);
+      }
+      throw normalized;
+    } finally {
+      inFlight -= 1;
+      sinks.setPending(inFlight > 0);
+    }
+  };
+  const reset = () => {
+    sinks.setError(void 0);
+  };
+  return { mutate, reset };
+};
+
+export { createMutatorRunner };

package/dist/packem_shared/{createServerClient-DMh-2UDv.mjs → createServerClient-XahK8bPv.mjs}

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