@lunora/client 1.0.0-alpha.2 → 1.0.0-alpha.21

package/dist/packem_shared/{LunoraClient-UiULzH_1.mjs → LunoraClient-kXpHNyaE.mjs}

@@ -1,17 +1,295 @@
+import { LunoraError } from '@lunora/errors';
+import { S as SubscriptionRegistry, s as stableStringify } from './subscription-BjynOXCU.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 './createInMemoryQueryCache-B1PQ9Twl.mjs';
+import { isMutationDelta, applyDelta } from './applyDelta-CRKZ1PBt.mjs';
+import { a as applyOptimisticLayer, d as dropConfirmedLayers, n as notifySubscription, f as foldOptimistic, c as createLocalStore } from './local-store-BveBeFEo.mjs';
+import { O as OfflineQueue, n as nextId, i as isStaleVersion, r as reportPersistenceError } from './offline-queue-B9vfdSqp.mjs';
+import { resolvePersistenceAdapter } from './createInMemoryPersistence-DZ2VHWgm.mjs';
+import { resolveQueryCacheAdapter, queryCacheKey } from './createInMemoryQueryCache-DiaGZkA2.mjs';
 import { createReconnect } from './createReconnect-Di_-oHH7.mjs';
-import { createStream } from './DEFAULT_MAX_BUFFER-BDkqO5PW.mjs';
-import { SubscriptionRegistry } from './SubscriptionRegistry-B-Qx_Gux.mjs';
+import { createStream } from './DEFAULT_MAX_BUFFER-7hFnzNk9.mjs';
+
+const MAX_BATCH_ENTRIES = 500;
+
+const evictOldestEntry = (map, capacity) => {
+  if (map.size < capacity) {
+    return;
+  }
+  const oldest = map.keys().next().value;
+  if (oldest !== void 0) {
+    map.delete(oldest);
+  }
+};
+
+const TAG = "$lunora.wire$";
+const MAX_DEPTH = 64;
+const MAX_BIGINT_DIGITS = 1024;
+const UNSAFE_KEY = "__proto__";
+const TYPED_ARRAY_CTORS = {
+  BigInt64Array,
+  BigUint64Array,
+  Float32Array,
+  Float64Array,
+  Int8Array,
+  Int16Array,
+  Int32Array,
+  Uint8Array,
+  Uint8ClampedArray,
+  Uint16Array,
+  Uint32Array
+};
+const ERROR_CTORS = {
+  Error,
+  EvalError,
+  RangeError,
+  ReferenceError,
+  SyntaxError,
+  TypeError,
+  URIError
+};
+const toBase64 = (bytes) => {
+  let binary = "";
+  const chunk = 32768;
+  for (let index = 0; index < bytes.length; index += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(index, index + chunk));
+  }
+  return btoa(binary);
+};
+const fromBase64 = (base64) => {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.codePointAt(index) ?? 0;
+  }
+  return bytes;
+};
+const encodeWire = (value, depth = 0) => {
+  if (depth > MAX_DEPTH) {
+    throw new RangeError(`wire-codec: value nesting exceeds the ${MAX_DEPTH}-level limit`);
+  }
+  if (value === void 0) {
+    return [TAG, "undefined"];
+  }
+  if (value === null) {
+    return null;
+  }
+  const kind = typeof value;
+  if (kind === "bigint") {
+    return [TAG, "bigint", value.toString()];
+  }
+  if (kind === "number") {
+    const numeric = value;
+    if (Number.isNaN(numeric)) {
+      return [TAG, "nan"];
+    }
+    if (numeric === Infinity) {
+      return [TAG, "inf"];
+    }
+    if (numeric === -Infinity) {
+      return [TAG, "-inf"];
+    }
+    return numeric;
+  }
+  if (kind !== "object") {
+    return value;
+  }
+  if (value instanceof Date) {
+    return [TAG, "date", encodeWire(value.getTime(), depth + 1)];
+  }
+  if (value instanceof Error) {
+    const error = value;
+    const properties = {};
+    for (const key of Object.keys(error)) {
+      if (error[key] !== void 0) {
+        properties[key] = encodeWire(error[key], depth + 1);
+      }
+    }
+    const encodedError = [TAG, "error", error.name, error.message, properties];
+    if (error.cause !== void 0) {
+      encodedError.push(encodeWire(error.cause, depth + 1));
+    }
+    return encodedError;
+  }
+  if (value instanceof URL) {
+    return [TAG, "url", value.href];
+  }
+  if (value instanceof Map) {
+    return [TAG, "map", [...value.entries()].map(([k, v]) => [encodeWire(k, depth + 1), encodeWire(v, depth + 1)])];
+  }
+  if (value instanceof Set) {
+    return [TAG, "set", [...value].map((item) => encodeWire(item, depth + 1))];
+  }
+  if (value instanceof ArrayBuffer) {
+    return [TAG, "bytes", toBase64(new Uint8Array(value)), "ArrayBuffer"];
+  }
+  if (ArrayBuffer.isView(value)) {
+    const view = value;
+    const ctorName = view.constructor.name;
+    const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);
+    return ctorName === "Uint8Array" ? [TAG, "bytes", toBase64(bytes)] : [TAG, "bytes", toBase64(bytes), ctorName];
+  }
+  if (Array.isArray(value)) {
+    const encoded = value.map((item) => encodeWire(item, depth + 1));
+    return encoded.length > 0 && encoded[0] === TAG ? [TAG, "arr", encoded] : encoded;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== null && proto !== Object.prototype) {
+    const name = value.constructor?.name ?? "value";
+    throw new TypeError(
+      `wire-codec: cannot encode a ${name} over the Lunora wire — only plain objects, arrays, and the supported built-ins (Date, Error, URL, Map, Set, ArrayBuffer/typed arrays, bigint) round-trip`
+    );
+  }
+  const source = value;
+  const result = {};
+  for (const key of Object.keys(source)) {
+    const field = source[key];
+    if (field !== void 0) {
+      result[key] = encodeWire(field, depth + 1);
+    }
+  }
+  return result;
+};
+const decodeWire = (value, depth = 0) => {
+  if (depth > MAX_DEPTH) {
+    throw new RangeError(`wire-codec: value nesting exceeds the ${MAX_DEPTH}-level limit`);
+  }
+  if (value === null || typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    if (value[0] === TAG) {
+      const tag = value[1];
+      switch (tag) {
+        case "-inf": {
+          return -Infinity;
+        }
+        case "arr": {
+          return value[2].map((item) => decodeWire(item, depth + 1));
+        }
+        case "bigint": {
+          const raw = value[2];
+          if (typeof raw !== "string" || raw.length > MAX_BIGINT_DIGITS || !/^-?\d+$/.test(raw)) {
+            throw new RangeError(`wire-codec: invalid or over-long bigint (max ${MAX_BIGINT_DIGITS} digits)`);
+          }
+          return BigInt(raw);
+        }
+        case "date": {
+          return new Date(decodeWire(value[2], depth + 1));
+        }
+        case "map": {
+          return new Map(value[2].map(([k, v]) => [decodeWire(k, depth + 1), decodeWire(v, depth + 1)]));
+        }
+        case "set": {
+          return new Set(value[2].map((item) => decodeWire(item, depth + 1)));
+        }
+        case "url": {
+          return new URL(value[2]);
+        }
+        case "error": {
+          const name = value[2];
+          const message = value[3];
+          const Ctor = (Object.hasOwn(ERROR_CTORS, name) ? ERROR_CTORS[name] : void 0) ?? Error;
+          const error = new Ctor(message);
+          if (error.name !== name) {
+            Object.defineProperty(error, "name", { configurable: true, value: name, writable: true });
+          }
+          const props = decodeWire(value[4], depth + 1);
+          for (const key of Object.keys(props)) {
+            if (key === UNSAFE_KEY) {
+              Object.defineProperty(error, key, { configurable: true, enumerable: true, value: props[key], writable: true });
+            } else {
+              error[key] = props[key];
+            }
+          }
+          if (value.length > 5) {
+            Object.defineProperty(error, "cause", { configurable: true, value: decodeWire(value[5], depth + 1), writable: true });
+          }
+          return error;
+        }
+        case "bytes": {
+          const bytes = fromBase64(value[2]);
+          const ctorName = value[3] ?? "Uint8Array";
+          if (ctorName === "ArrayBuffer") {
+            return bytes.buffer.byteLength === bytes.byteLength ? bytes.buffer : bytes.slice().buffer;
+          }
+          const Ctor = Object.hasOwn(TYPED_ARRAY_CTORS, ctorName) ? TYPED_ARRAY_CTORS[ctorName] : void 0;
+          return Ctor ? new Ctor(bytes.slice().buffer) : bytes;
+        }
+        case "inf": {
+          return Infinity;
+        }
+        case "nan": {
+          return Number.NaN;
+        }
+        case "undefined": {
+          return void 0;
+        }
+        default: {
+          return value.map((item) => decodeWire(item, depth + 1));
+        }
+      }
+    }
+    return value.map((item) => decodeWire(item, depth + 1));
+  }
+  const source = value;
+  const result = {};
+  for (const key of Object.keys(source)) {
+    const decoded = decodeWire(source[key], depth + 1);
+    if (key === UNSAFE_KEY) {
+      Object.defineProperty(result, key, { configurable: true, enumerable: true, value: decoded, writable: true });
+    } else {
+      result[key] = decoded;
+    }
+  }
+  return result;
+};
+
+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 RPC_BATCH_PATH = "/_lunora/rpc-batch";
 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";
@@ -38,6 +316,9 @@ const GLOBAL_TABLE_PATH = "/_lunora/admin/global/table";
 const GLOBAL_FACET_PATH = "/_lunora/admin/global/facet";
 const VECTOR_INDEXES_PATH = "/_lunora/admin/vector/indexes";
 const VECTOR_QUERY_PATH = "/_lunora/admin/vector/query";
+const KV_NAMESPACES_PATH = "/_lunora/admin/kv/namespaces";
+const KV_KEYS_PATH = "/_lunora/admin/kv/keys";
+const KV_VALUE_PATH = "/_lunora/admin/kv/value";
 const AUTH_USERS_PATH = "/_lunora/admin/auth/users";
 const AUTH_SESSIONS_PATH = "/_lunora/admin/auth/sessions";
 const AUTH_CREATE_USER_PATH = "/_lunora/admin/auth/users/create";
@@ -61,24 +342,26 @@ const AUTH_ORG_MEMBERS_PATH = "/_lunora/admin/auth/organizations/members";
 const AUTH_ORG_INVITATIONS_PATH = "/_lunora/admin/auth/organizations/invitations";
 const AUTH_REMOVE_MEMBER_PATH = "/_lunora/admin/auth/organizations/members/remove";
 const AUTH_CANCEL_INVITATION_PATH = "/_lunora/admin/auth/organizations/invitations/cancel";
+const AUTH_CONFIG_PATH = "/_lunora/admin/auth/config";
+const AUTH_CREATE_ORG_PATH = "/_lunora/admin/auth/organizations/create";
+const AUTH_UPDATE_ORG_PATH = "/_lunora/admin/auth/organizations/update";
+const AUTH_REMOVE_ORG_PATH = "/_lunora/admin/auth/organizations/remove";
+const AUTH_ADD_MEMBER_PATH = "/_lunora/admin/auth/organizations/members/add";
+const AUTH_INVITE_MEMBER_PATH = "/_lunora/admin/auth/organizations/members/invite";
+const AUTH_MEMBER_ROLE_PATH = "/_lunora/admin/auth/organizations/members/role";
+const AUTH_ORG_TEAMS_PATH = "/_lunora/admin/auth/organizations/teams";
+const AUTH_CREATE_TEAM_PATH = "/_lunora/admin/auth/organizations/teams/create";
+const AUTH_UPDATE_TEAM_PATH = "/_lunora/admin/auth/organizations/teams/update";
+const AUTH_REMOVE_TEAM_PATH = "/_lunora/admin/auth/organizations/teams/remove";
+const AUTH_ORG_TEAM_MEMBERS_PATH = "/_lunora/admin/auth/organizations/teams/members";
+const AUTH_ADD_TEAM_MEMBER_PATH = "/_lunora/admin/auth/organizations/teams/members/add";
+const AUTH_REMOVE_TEAM_MEMBER_PATH = "/_lunora/admin/auth/organizations/teams/members/remove";
+const AUTH_ORG_ROLES_PATH = "/_lunora/admin/auth/organizations/roles";
+const AUTH_CREATE_ROLE_PATH = "/_lunora/admin/auth/organizations/roles/create";
+const AUTH_UPDATE_ROLE_PATH = "/_lunora/admin/auth/organizations/roles/update";
+const AUTH_REMOVE_ROLE_PATH = "/_lunora/admin/auth/organizations/roles/remove";
 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,47 +386,12 @@ 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;
   const nestedMessage = typeof errorEnvelope?.message === "string" ? errorEnvelope.message : void 0;
   const messageText = (typeof message.message === "string" ? message.message : void 0) ?? nestedMessage ?? "stream error";
-  return Object.assign(new Error(messageText), code === void 0 ? void 0 : { code });
+  return code === void 0 ? new Error(messageText) : new LunoraError(code, messageText);
 };
 const buildSubscriptionError = (message) => {
   const errorEnvelope = message.error;
@@ -152,6 +400,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") {
@@ -173,7 +429,43 @@ const sendOn = (conn, message) => {
     return false;
   }
 };
+const reconstructError = (errorBody) => {
+  const error = new Error(errorBody.message ?? "request failed");
+  error.code = errorBody.code;
+  if (errorBody.data !== void 0) {
+    error.data = decodeWire(errorBody.data);
+  }
+  if (errorBody.hint !== void 0) {
+    error.hint = errorBody.hint;
+  }
+  if (errorBody.docsUrl !== void 0) {
+    error.docsUrl = errorBody.docsUrl;
+  }
+  return error;
+};
+const encodeCallArgs = (payload, label) => {
+  try {
+    return encodeWire(payload);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new TypeError(`LunoraClient: cannot encode ${label} — ${reason}`, error instanceof Error ? { cause: error } : void 0);
+  }
+};
+const demuxBatchResults = (rawResults, count) => {
+  const slots = Array.from({ length: count });
+  for (const entry of rawResults) {
+    if (typeof entry.id !== "number" || entry.id < 0 || entry.id >= count) {
+      continue;
+    }
+    const inner = entry.body;
+    slots[entry.id] = inner && "error" in inner && inner.error ? { error: reconstructError(inner.error), ok: false } : { ok: true, value: decodeWire(inner?.result) };
+  }
+  return slots.map((slot) => slot ?? { error: new Error("batch call returned no result"), ok: false });
+};
+const TRANSIENT_BATCH_ERROR_CODES = /* @__PURE__ */ new Set(["SHARD_ERROR", "SHARD_UNAVAILABLE"]);
 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 +475,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 +550,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 +568,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 +594,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 +610,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 +645,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 LunoraError("INTERNAL", `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`
@@ -519,7 +942,7 @@ class LunoraClient {
     this.ensureSocket(options.shardKey);
     const conn = this.getConnection(options.shardKey);
     if (conn) {
-      sendOn(conn, { data, topic, type: "whisper" });
+      sendOn(conn, { data: encodeCallArgs(data ?? null, `whisper data for topic '${topic}'`), topic, type: "whisper" });
     }
   }
   /**
@@ -531,10 +954,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,19 +970,107 @@ 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 = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     return await this.rpc(function_.__lunoraRef, args, options.shardKey, { attachBookmark: true });
   }
+  /**
+   * Batch several independent calls into ONE round trip (plan 088). Each call is
+   * dispatched server-side exactly as an individual RPC — per-shard
+   * authorization, `(identity, mutationId)` idempotency, and custom-mutator
+   * watermark ordering are all preserved — and the worker splits the batch by
+   * shard so calls to different shards fan out to their own DOs. Results are
+   * demuxed back in input order; a failing call does NOT fail the batch (its
+   * slot carries `{ ok: false, error }`, with `.code`/`.data` reconstructed like
+   * a single call). Args/results ride the value codec (bytes/bigint survive).
+   *
+   * No promise pipelining and no capability passing — a call's args cannot
+   * reference another call's result (see plan 088 §fence; capabilities are
+   * incompatible with DO hibernation).
+   */
+  async batch(calls) {
+    if (this.closed) {
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
+    }
+    if (!this.fetchImpl) {
+      throw new LunoraError("INTERNAL", "LunoraClient: no `fetch` implementation available");
+    }
+    if (calls.length === 0) {
+      return [];
+    }
+    const response = await this.fetchImpl(joinUrl(this.url, RPC_BATCH_PATH), {
+      body: JSON.stringify({
+        calls: calls.map((call, index) => {
+          return {
+            args: encodeCallArgs(call.args ?? {}, `args for batch call '${call.fn.__lunoraRef}'`),
+            functionPath: call.fn.__lunoraRef,
+            id: index,
+            shardKey: call.shardKey
+          };
+        })
+      }),
+      headers: this.rpcRequestHeaders({ attachBookmark: true }),
+      method: "POST"
+    });
+    const bookmark = response.headers.get("x-d1-bookmark");
+    if (bookmark) {
+      this.bookmark.set(bookmark);
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      throw new LunoraError("INTERNAL", `LunoraClient: batch response was not JSON (status ${response.status.toString()})`);
+    }
+    if (!response.ok || body.error && !body.results) {
+      if (body.error) {
+        throw reconstructError(body.error);
+      }
+      throw new LunoraError("INTERNAL", `LunoraClient: batch request failed (status ${response.status.toString()})`);
+    }
+    return demuxBatchResults(body.results ?? [], calls.length);
+  }
   /**
    * Invoke a mutation. Errors propagate as rejections.
    *
@@ -575,13 +1083,18 @@ class LunoraClient {
    */
   async mutation(function_, args, options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "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,46 +1105,29 @@ 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;
     }
   }
   async action(function_, args, options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     return await this.rpc(function_.__lunoraRef, args, options.shardKey);
   }
@@ -648,7 +1144,7 @@ class LunoraClient {
    */
   async shardTraffic(table) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SHARD_TRAFFIC_PATH, "POST", { table });
     return { failed: body.failed ?? 0, ok: body.ok ?? 0, shards: body.shards ?? [] };
@@ -663,7 +1159,7 @@ class LunoraClient {
    */
   async listScheduledJobs() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_PATH, "GET");
     return body.records ?? [];
@@ -679,7 +1175,7 @@ class LunoraClient {
    */
   async schedulerStatus() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_STATUS_PATH, "GET");
     return {
@@ -691,7 +1187,7 @@ class LunoraClient {
   /** Cancel a pending scheduled job by id. Returns whether a job was removed. */
   async cancelScheduledJob(id) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_CANCEL_PATH, "POST", { id });
     return { cancelled: body.cancelled === true };
@@ -706,7 +1202,7 @@ class LunoraClient {
    */
   async listDeadJobs() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_DEAD_PATH, "GET");
     return body.records ?? [];
@@ -718,7 +1214,7 @@ class LunoraClient {
    */
   async retryDeadJob(id) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_DEAD_RETRY_PATH, "POST", { id });
     return { retried: body.retried === true };
@@ -730,7 +1226,7 @@ class LunoraClient {
    */
   async removeDeadJob(id) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(SCHEDULED_DEAD_CANCEL_PATH, "POST", { id });
     return { removed: body.removed === true };
@@ -739,12 +1235,16 @@ 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) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const query = new URLSearchParams({ name: options.name });
     if (options.status !== void 0) {
@@ -757,12 +1257,18 @@ 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) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const query = new URLSearchParams({ id: options.id, name: options.name });
     const body = await this.adminFetch(`${WORKFLOWS_INSTANCE_PATH}?${query.toString()}`, "GET");
@@ -781,7 +1287,7 @@ class LunoraClient {
   /** Pause / resume / terminate a workflow instance (`/_lunora/admin/workflows/status`). Needs an Edit-scoped Cloudflare token. */
   async setWorkflowInstanceStatus(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(WORKFLOWS_STATUS_PATH, "POST", { action: options.action, id: options.id, name: options.name });
     return { status: body.status ?? "unknown" };
@@ -796,7 +1302,7 @@ class LunoraClient {
    */
   subscribeScheduledJobs(onJobs) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     if (this.WebSocketImpl === void 0) {
       return () => void 0;
@@ -852,7 +1358,7 @@ class LunoraClient {
    */
   async listFunctions() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(FUNCTIONS_PATH, "GET");
     return body.functions ?? [];
@@ -868,7 +1374,7 @@ class LunoraClient {
    */
   async getCronJobs() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(CRON_JOBS_PATH, "GET");
     return body.jobs ?? [];
@@ -884,7 +1390,7 @@ class LunoraClient {
    */
   async runCronJob(name) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(CRON_JOBS_RUN_PATH, "POST", { name });
     return { name: body.name ?? name, ran: body.ran === true };
@@ -899,7 +1405,7 @@ class LunoraClient {
    */
   async fetchOpenApi() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     return await this.adminFetch(OPENAPI_PATH, "GET");
   }
@@ -915,7 +1421,7 @@ class LunoraClient {
    */
   async fetchOpenRpc() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     return await this.adminFetch(OPENRPC_PATH, "GET");
   }
@@ -929,7 +1435,7 @@ class LunoraClient {
    */
   async listStorageObjects(options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const params = new URLSearchParams();
     if (options.prefix !== void 0 && options.prefix !== "") {
@@ -957,7 +1463,7 @@ class LunoraClient {
    */
   async deleteStorageObject(key, options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const path = `${STORAGE_PATH}?key=${encodeURIComponent(key)}${bucketQuery(options?.bucket)}`;
     const body = await this.adminFetch(path, "DELETE");
@@ -971,7 +1477,7 @@ class LunoraClient {
    */
   async listStorageBuckets() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(STORAGE_BUCKETS_PATH, "GET");
     return body.buckets ?? [];
@@ -985,7 +1491,7 @@ class LunoraClient {
    */
   async uploadStorageObject(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const path = `${STORAGE_PATH}?key=${encodeURIComponent(options.key)}${bucketQuery(options.bucket)}`;
     const body = await this.adminFetch(path, "PUT", options.body, options.contentType);
@@ -1004,7 +1510,7 @@ class LunoraClient {
    */
   async signedStorageUrl(key, options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const expiresInSeconds = options?.expiresInSeconds;
     const expiryQuery = expiresInSeconds === void 0 ? "" : `&expiresIn=${encodeURIComponent(expiresInSeconds.toString())}`;
@@ -1024,7 +1530,7 @@ class LunoraClient {
    */
   async listGlobalTables() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     return await this.adminFetch(GLOBAL_TABLES_PATH, "GET");
   }
@@ -1036,7 +1542,7 @@ class LunoraClient {
    */
   async readGlobalTablePage(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const params = new URLSearchParams({ table: options.table });
     if (options.limit !== void 0) {
@@ -1059,7 +1565,7 @@ class LunoraClient {
    */
   async facetGlobalColumn(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const params = new URLSearchParams({ column: options.column, table: options.table });
     if (options.limit !== void 0) {
@@ -1082,7 +1588,7 @@ class LunoraClient {
    */
   async listVectorIndexes() {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(VECTOR_INDEXES_PATH, "GET");
     return body.indexes ?? [];
@@ -1096,11 +1602,77 @@ class LunoraClient {
    */
   async queryVectorIndex(options) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const body = await this.adminFetch(VECTOR_QUERY_PATH, "POST", options);
     return body.matches ?? [];
   }
+  // --- KV namespace admin -------------------------------------------------
+  /**
+   * List the worker's registered Workers KV namespaces (binding names). Hits
+   * the admin-gated `GET /_lunora/admin/kv/namespaces` endpoint — the worker
+   * must be built with a `kvIntrospector` and `adminToken`. Powers the
+   * studio's KV browser.
+   */
+  async listKvNamespaces() {
+    if (this.closed) {
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
+    }
+    const body = await this.adminFetch(KV_NAMESPACES_PATH, "GET");
+    return body.namespaces ?? [];
+  }
+  /**
+   * List keys in a KV namespace, optionally filtered by `prefix` and
+   * paginated via `cursor`. Hits the admin-gated
+   * `GET /_lunora/admin/kv/keys` endpoint.
+   */
+  async listKvKeys(options) {
+    if (this.closed) {
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
+    }
+    const path = withQuery(KV_KEYS_PATH, {
+      cursor: options.cursor,
+      limit: options.limit,
+      namespace: options.namespace,
+      prefix: options.prefix
+    });
+    return await this.adminFetch(path, "GET");
+  }
+  /**
+   * Read a KV value (as text) and its metadata. Hits the admin-gated
+   * `GET /_lunora/admin/kv/value` endpoint. Returns `{ value: null, metadata: null }`
+   * when the key is absent.
+   */
+  async getKvValue(options) {
+    if (this.closed) {
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
+    }
+    const path = withQuery(KV_VALUE_PATH, { key: options.key, namespace: options.namespace });
+    return await this.adminFetch(path, "GET");
+  }
+  /**
+   * Write a string value to a KV namespace. Accepts an absolute `expiration`
+   * (Unix seconds) or a relative `expirationTtl`, plus optional `metadata` —
+   * re-send the loaded values on edit so a save preserves rather than clears
+   * them. Hits the admin-gated `PUT /_lunora/admin/kv/value` endpoint.
+   */
+  async putKvValue(options) {
+    if (this.closed) {
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
+    }
+    await this.adminFetch(KV_VALUE_PATH, "PUT", options);
+  }
+  /**
+   * Delete a key from a KV namespace. No-op when the key is absent. Hits the
+   * admin-gated `DELETE /_lunora/admin/kv/value` endpoint.
+   */
+  async deleteKvKey(options) {
+    if (this.closed) {
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
+    }
+    const path = withQuery(KV_VALUE_PATH, { key: options.key, namespace: options.namespace });
+    await this.adminFetch(path, "DELETE");
+  }
   // --- Auth admin ---------------------------------------------------------
   /**
    * List authenticated users, paged and optionally searched / filtered / sorted.
@@ -1110,7 +1682,7 @@ class LunoraClient {
    */
   async listAuthUsers(options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const path = withQuery(AUTH_USERS_PATH, {
       filterField: options.filterField,
@@ -1222,10 +1794,90 @@ class LunoraClient {
   async cancelAuthOrgInvitation(input) {
     await this.adminFetch(AUTH_CANCEL_INVITATION_PATH, "POST", input);
   }
+  /**
+   * Report the deployment's auth configuration — enabled plugins, sign-in
+   * methods, user-settable create-user fields, organization sub-features
+   * (teams / roles), and session / rate-limit policy. Drives the config panel
+   * and the dynamic create-user form. Never carries a secret.
+   */
+  async getAuthConfig() {
+    return await this.adminFetch(AUTH_CONFIG_PATH, "GET");
+  }
+  /** Create an organization; optionally seed an `owner` member for `ownerId`. */
+  async createAuthOrganization(input) {
+    return await this.adminFetch(AUTH_CREATE_ORG_PATH, "POST", input);
+  }
+  /** Update an organization's name/slug/logo/metadata. */
+  async updateAuthOrganization(input) {
+    return await this.adminFetch(AUTH_UPDATE_ORG_PATH, "POST", input);
+  }
+  /** Delete an organization and cascade its members, invitations, teams, and custom roles. */
+  async deleteAuthOrganization(input) {
+    await this.adminFetch(AUTH_REMOVE_ORG_PATH, "POST", input);
+  }
+  /** Directly add an existing user to an organization (no invitation/acceptance). */
+  async addAuthOrgMember(input) {
+    return await this.adminFetch(AUTH_ADD_MEMBER_PATH, "POST", input);
+  }
+  /** Create a pending email invitation to an organization. */
+  async inviteAuthOrgMember(input) {
+    return await this.adminFetch(AUTH_INVITE_MEMBER_PATH, "POST", input);
+  }
+  /** Change a member's role. */
+  async setAuthOrgMemberRole(input) {
+    return await this.adminFetch(AUTH_MEMBER_ROLE_PATH, "POST", input);
+  }
+  /** List an organization's teams (requires the organization plugin with teams enabled). */
+  async listAuthOrgTeams(input) {
+    const path = withQuery(AUTH_ORG_TEAMS_PATH, { limit: input.limit, offset: input.offset, organizationId: input.organizationId });
+    return await this.adminFetch(path, "GET");
+  }
+  /** Create a team under an organization. */
+  async createAuthOrgTeam(input) {
+    return await this.adminFetch(AUTH_CREATE_TEAM_PATH, "POST", input);
+  }
+  /** Rename a team. */
+  async updateAuthOrgTeam(input) {
+    return await this.adminFetch(AUTH_UPDATE_TEAM_PATH, "POST", input);
+  }
+  /** Delete a team and its memberships. */
+  async removeAuthOrgTeam(input) {
+    await this.adminFetch(AUTH_REMOVE_TEAM_PATH, "POST", input);
+  }
+  /** List a team's members. */
+  async listAuthOrgTeamMembers(input) {
+    const path = withQuery(AUTH_ORG_TEAM_MEMBERS_PATH, { limit: input.limit, offset: input.offset, teamId: input.teamId });
+    return await this.adminFetch(path, "GET");
+  }
+  /** Add a user to a team. */
+  async addAuthOrgTeamMember(input) {
+    return await this.adminFetch(AUTH_ADD_TEAM_MEMBER_PATH, "POST", input);
+  }
+  /** Remove a member from a team. */
+  async removeAuthOrgTeamMember(input) {
+    await this.adminFetch(AUTH_REMOVE_TEAM_MEMBER_PATH, "POST", input);
+  }
+  /** List an organization's custom roles (requires the organization plugin with dynamic access control). */
+  async listAuthOrgRoles(input) {
+    const path = withQuery(AUTH_ORG_ROLES_PATH, { limit: input.limit, offset: input.offset, organizationId: input.organizationId });
+    return await this.adminFetch(path, "GET");
+  }
+  /** Create a custom org role with a permission grant (a `resource -> actions[]` map). */
+  async createAuthOrgRole(input) {
+    return await this.adminFetch(AUTH_CREATE_ROLE_PATH, "POST", input);
+  }
+  /** Replace a custom org role's permission grant. */
+  async updateAuthOrgRole(input) {
+    return await this.adminFetch(AUTH_UPDATE_ROLE_PATH, "POST", input);
+  }
+  /** Delete a custom org role. */
+  async deleteAuthOrgRole(input) {
+    await this.adminFetch(AUTH_REMOVE_ROLE_PATH, "POST", input);
+  }
   /** List auth sessions, paged and optionally filtered to one user. */
   async listAuthSessions(options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const params = new URLSearchParams();
     if (options.userId !== void 0 && options.userId !== "") {
@@ -1243,7 +1895,7 @@ class LunoraClient {
   // --- Subscriptions ------------------------------------------------------
   subscribe(function_, args, callback, options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     const argsRecord = args ?? {};
     const key = SubscriptionRegistry.key(function_.__lunoraRef, argsRecord, options.shardKey);
@@ -1260,12 +1912,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 +1929,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 +1946,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 LunoraError("INTERNAL", "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(...)`);
@@ -1319,10 +2019,10 @@ class LunoraClient {
    */
   stream(function_, args, options = {}) {
     if (this.closed) {
-      throw new Error("LunoraClient is closed");
+      throw new LunoraError("INTERNAL", "LunoraClient is closed");
     }
     if (this.WebSocketImpl === void 0) {
-      throw new Error("LunoraClient: streams require a WebSocket implementation");
+      throw new LunoraError("INTERNAL", "LunoraClient: streams require a WebSocket implementation");
     }
     this.nextStreamId += 1;
     const id = `stream_${this.nextStreamId.toString()}`;
@@ -1343,7 +2043,14 @@ class LunoraClient {
     const conn = this.getConnection(shardKey);
     const message = {
       id,
-      query: { args: argsRecord, functionPath: function_.__lunoraRef, shardKey },
+      // Wire-encode the stream args so `bigint`/bytes survive the send (raw
+      // `JSON.stringify` throws on a bigint); the shard `decodeWire`s them
+      // before invoking the stream handler.
+      query: {
+        args: encodeCallArgs(argsRecord, `stream args for '${function_.__lunoraRef}'`),
+        functionPath: function_.__lunoraRef,
+        shardKey
+      },
       type: "stream"
     };
     const sentImmediately = conn?.wsState === "open" && sendOn(conn, message);
@@ -1354,9 +2061,7 @@ class LunoraClient {
         const droppedId = dropped?.id;
         const droppedStream = droppedId ? this.streams.get(droppedId) : void 0;
         if (droppedStream) {
-          droppedStream.handle.fail(
-            Object.assign(new Error("stream-start frame evicted while socket was unreachable"), { code: "STREAM_QUEUE_OVERFLOW" })
-          );
+          droppedStream.handle.fail(new LunoraError("STREAM_QUEUE_OVERFLOW", "stream-start frame evicted while socket was unreachable"));
           this.streams.delete(droppedId);
         }
       }
@@ -1366,8 +2071,10 @@ 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" }));
+      stream.handle.fail(new LunoraError("CLIENT_CLOSED", "LunoraClient closed"));
     }
     this.streams.clear();
     for (const conn of this.connections.values()) {
@@ -1375,6 +2082,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 +2108,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 +2199,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 +2245,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 +2277,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 +2286,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 +2327,70 @@ class LunoraClient {
       return;
     }
     this.lastStatus = next;
-    for (const listener of this.statusListeners) {
-      try {
-        listener(next);
-      } catch {
-      }
-    }
+    this.statusListeners.emit(next);
   }
   /**
-   * 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).
+   * Build a {@link MutationSettledEvent} from a queued entry and emit it on the
+   * {@link onMutationSettled} channel. `item.id` is always assigned by the time
+   * a write settles (`enqueue`/`hydrate` guarantee it), so the `?? ""` fallback
+   * is unreachable — present only to satisfy the optional queue-id type.
+   */
+  emitItemSettled(item, status, error) {
+    this.mutationSettledListeners.emit({
+      args: item.args,
+      code: error === void 0 ? void 0 : error.code,
+      error,
+      functionPath: item.functionPath,
+      hadAwaiter: item.liveAwaiter ?? false,
+      id: item.id ?? "",
+      shardKey: item.shardKey,
+      status
+    });
+  }
+  /**
+   * Apply an optimistic update to the subscription that matches the mutation's
+   * `(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);
     try {
       optimisticUpdate(store, args);
     } catch {
@@ -1555,6 +2400,7 @@ class LunoraClient {
       return;
     }
     optimisticRollbacks.push(...rollbacks);
+    optimisticConfirms.push(...confirms);
   }
   getConnection(shardKey) {
     return this.connections.get(connectionKey(shardKey));
@@ -1564,6 +2410,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 +2454,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) {
@@ -1617,11 +2470,14 @@ class LunoraClient {
   }
   async rpc(functionPath, args, shardKey, flags = {}) {
     if (!this.fetchImpl) {
-      throw new Error("LunoraClient: no `fetch` implementation available");
+      throw new LunoraError("INTERNAL", "LunoraClient: no `fetch` implementation available");
     }
     const headers = this.rpcRequestHeaders(flags);
     const response = await this.fetchImpl(joinUrl(this.url, RPC_PATH), {
-      body: JSON.stringify({ args, functionPath, shardKey }),
+      // `encodeWire` tags leaves plain JSON can't carry (`bigint`,
+      // `ArrayBuffer`/typed arrays, `NaN`/±Infinity); a pure-JSON `args`
+      // encodes byte-identically, so a pre-codec server still interops.
+      body: JSON.stringify({ args: encodeCallArgs(args, `args for '${functionPath}'`), functionPath, shardKey }),
       headers,
       method: "POST"
     });
@@ -1636,18 +2492,18 @@ class LunoraClient {
       body = await response.json();
     } catch {
       const statusText = response.statusText ? ` ${response.statusText}` : "";
-      throw new Error(`LunoraClient: response was not JSON (status ${response.status.toString()}${statusText})`);
+      throw new LunoraError("INTERNAL", `LunoraClient: response was not JSON (status ${response.status.toString()}${statusText})`);
     }
     if ("error" in body) {
-      const error = new Error(body.error.message);
-      error.code = body.error.code;
-      throw error;
+      throw reconstructError(body.error);
     }
     if (!response.ok) {
       const statusText = response.statusText ? ` ${response.statusText}` : "";
-      throw new Error(`LunoraClient: request failed (status ${response.status.toString()}${statusText})`);
+      throw new LunoraError("INTERNAL", `LunoraClient: request failed (status ${response.status.toString()}${statusText})`);
     }
-    return body.result;
+    flags.onMutationAck?.(body.lastMutationId);
+    flags.onCommitCursor?.(body.commitCursor);
+    return decodeWire(body.result);
   }
   /**
    * Authenticated request to a non-RPC admin endpoint (the scheduler list /
@@ -1657,7 +2513,7 @@ class LunoraClient {
    */
   async adminFetch(path, method, payload, contentType) {
     if (!this.fetchImpl) {
-      throw new Error("LunoraClient: no `fetch` implementation available");
+      throw new LunoraError("INTERNAL", "LunoraClient: no `fetch` implementation available");
     }
     const headers = {};
     if (this.authToken) {
@@ -1686,7 +2542,7 @@ class LunoraClient {
       body = await response.json();
     } catch {
       const statusText = response.statusText ? ` ${response.statusText}` : "";
-      throw new Error(`LunoraClient: response was not JSON (status ${response.status.toString()}${statusText})`);
+      throw new LunoraError("INTERNAL", `LunoraClient: response was not JSON (status ${response.status.toString()}${statusText})`);
     }
     if (typeof body === "object" && body !== null && "error" in body) {
       const envelope = body.error;
@@ -1696,7 +2552,7 @@ class LunoraClient {
     }
     if (!response.ok) {
       const statusText = response.statusText ? ` ${response.statusText}` : "";
-      throw new Error(`LunoraClient: admin request failed (status ${response.status.toString()}${statusText})`);
+      throw new LunoraError("INTERNAL", `LunoraClient: admin request failed (status ${response.status.toString()}${statusText})`);
     }
     return body;
   }
@@ -1737,11 +2593,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 +2626,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 +2658,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 +2686,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,10 +2711,21 @@ 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();
     this.markShardPendingAck(conn.shardKey);
+    const pendingStreamIds = new Set((conn.pendingStreams ?? []).map((message) => message.id));
+    for (const [id, stream] of this.streams) {
+      if (connectionKey(stream.shardKey) === connectionKey(conn.shardKey) && !pendingStreamIds.has(id)) {
+        stream.handle.fail(new LunoraError("STREAM_DISCONNECTED", "stream terminated: WebSocket disconnected"));
+        this.streams.delete(id);
+      }
+    }
     if (this.WebSocketImpl === void 0) {
       return;
     }
@@ -1885,6 +2795,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) {
@@ -1907,7 +2832,7 @@ class LunoraClient {
       case "chunk": {
         const { data, id } = message;
         const stream = this.streams.get(id);
-        stream?.handle.push(data);
+        stream?.handle.push(decodeWire(data));
         return;
       }
       case "complete": {
@@ -1923,10 +2848,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 +2889,76 @@ 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) {
+    evictOldestEntry(this.pokeBuffers, LunoraClient.MAX_POKE_BUFFERS);
+    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) ?? [];
+    for (const op of message.rowsPatch) {
+      existing.push(op.value === void 0 ? op : { ...op, value: decodeWire(op.value) });
+    }
+    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 +2969,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 +2977,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 +2993,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));
+      }
     }
   }
   /**
@@ -2019,11 +3055,11 @@ class LunoraClient {
   // eslint-disable-next-line class-methods-use-this -- instance method for symmetry with the other message handlers; reads no shared client state
   resolveDataPayload(message, state) {
     if ("data" in message && message.data !== void 0) {
-      return message.data;
+      return decodeWire(message.data);
     }
-    const { delta } = message;
-    if (isMutationDelta(delta) && state.lastValue !== void 0) {
-      const merged = applyDelta(state.lastValue, delta);
+    const delta = decodeWire(message.delta);
+    if (isMutationDelta(delta) && state.serverBase !== void 0) {
+      const merged = applyDelta(state.serverBase, delta);
       if (merged !== void 0) {
         return merged;
       }
@@ -2036,21 +3072,17 @@ class LunoraClient {
     if (!handlers) {
       return;
     }
+    const data = decodeWire(message.data);
     for (const handler of handlers) {
       try {
-        handler(message.data, message.from);
+        handler(data, message.from);
       } catch {
       }
     }
   }
   /** 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,16 +3113,59 @@ 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;
     }
-    let hash = 2166136261;
+    return this.hashToken(token);
+  }
+  /**
+   * Stable token-hash fingerprint of a bearer token (the `&lt;len>:&lt;fnv>:&lt;djb2>`
+   * format a token-stamped queued write carries). Extracted so the replay gate
+   * can recompute the hash of the current credential and recognise a write
+   * stamped under it — even after the fingerprint was relabelled to a subject.
+   *
+   * Two independent 32-bit passes (FNV-1a + djb2) give a ~64-bit digest, so
+   * two distinct equal-length tokens are astronomically unlikely to share a
+   * fingerprint. A single 32-bit hash collides ~1-in-4e9 per equal-length
+   * pair — enough that, on a shared device, user B could hydrate A's cached
+   * reads. Different algorithms (not the same FNV with a different seed, which
+   * would be affine-related) keep the two passes genuinely independent.
+   * Still synchronous (no crypto) and stable across surrogate pairs.
+   */
+  // eslint-disable-next-line class-methods-use-this -- pure helper; a method for locality with identityFingerprint, reads no shared state
+  hashToken(token) {
+    let fnv = 2166136261;
+    let djb2 = 5381;
     for (let index = 0; index < token.length; index += 1) {
-      hash ^= token.charCodeAt(index);
-      hash = Math.imul(hash, 16777619);
+      const code = token.charCodeAt(index);
+      fnv ^= code;
+      fnv = Math.imul(fnv, 16777619);
+      djb2 = Math.imul(djb2, 33) + code;
+    }
+    return `${token.length.toString(36)}:${(fnv >>> 0).toString(36)}:${(djb2 >>> 0).toString(36)}`;
+  }
+  /**
+   * True when `stamped` is a token-hash of the SAME credential still held now,
+   * even though the live identity has since been relabelled to a subject. Covers
+   * `setAuthToken(token, userId)` where the subject resolved a tick after the
+   * token was set: a write persisted (or requeued) under the token hash must
+   * still replay — the credential never changed, only its label — instead of
+   * being dropped as an identity mismatch. This is the durable counterpart to
+   * {@link restampQueuedIdentity}, which only relabels the in-memory live stamp
+   * (consumed on the first flush) and never touches `item.identity` or the
+   * persisted record, so a reload or a transient-failure requeue would otherwise
+   * fall back to the stale token-hash and wrongly reject the same user's write.
+   */
+  isSameCredentialUnderTokenHash(stamped) {
+    if (stamped === null || stamped.startsWith("subj:")) {
+      return false;
     }
-    return `${token.length.toString(36)}:${(hash >>> 0).toString(36)}`;
+    const token = this.authToken;
+    return token === null ? false : this.hashToken(token) === stamped;
   }
   /**
    * Drain every in-memory offline write and reject it because the auth
@@ -2107,9 +3182,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
@@ -2128,38 +3219,242 @@ class LunoraClient {
   async flushOfflineQueue(shardKey) {
     const key = connectionKey(shardKey);
     const drained = this.offlineQueue.drain((item) => connectionKey(item.shardKey) === key);
-    for (let index = 0; index < drained.length; index += 1) {
-      const item = drained[index];
-      if (!item) {
-        continue;
+    if (drained.length === 0) {
+      return;
+    }
+    const currentIdentity = this.identityFingerprint();
+    const sendable = [];
+    for (const item of drained) {
+      if (this.passesReplayIdentityGate(item, currentIdentity)) {
+        sendable.push(item);
       }
-      const currentIdentity = this.identityFingerprint();
-      const liveStamp = item.id === void 0 ? void 0 : this.queuedIdentities.get(item.id);
-      const stamped = liveStamp === void 0 ? item.identity : liveStamp;
-      if (stamped !== void 0 && stamped !== currentIdentity) {
-        this.queuedIdentities.delete(item.id ?? "");
-        this.unpersist(item.id);
-        const error = new Error("offline mutation skipped: auth identity changed before replay");
-        error.code = "OFFLINE_IDENTITY_CHANGED";
-        item.reject(error);
-        continue;
+    }
+    if (sendable.length === 0) {
+      return;
+    }
+    const encodable = this.encodableOrSettleTerminal(sendable);
+    if (encodable.length === 0) {
+      return;
+    }
+    if (encodable.length === 1) {
+      await this.replaySequential(encodable);
+      return;
+    }
+    const toRequeue = [];
+    for (let start = 0; start < encodable.length; start += MAX_BATCH_ENTRIES) {
+      const chunk = encodable.slice(start, start + MAX_BATCH_ENTRIES);
+      const outcome = await this.replayBatched(chunk);
+      toRequeue.push(...outcome.requeue);
+      if (outcome.stop) {
+        toRequeue.push(...encodable.slice(start + MAX_BATCH_ENTRIES));
+        break;
       }
+    }
+    if (toRequeue.length > 0) {
+      this.offlineQueue.requeue(toRequeue);
+    }
+  }
+  /**
+   * Partition already-gated writes into the encodable ones (returned) and reject
+   * the rest terminally. A write whose args can't be wire-encoded (e.g. a RegExp
+   * or class instance in a `v.any()` field) can NEVER replay — the codec failure
+   * is deterministic, not transient. Rejecting here is essential: otherwise
+   * `encodeWire` throws mid-flush, is classified as transient (a codec error has
+   * no `.code`), and re-queues forever — a silent hang where the caller's Promise
+   * never settles and the optimistic write never rolls back. Encoding is cheap;
+   * the flush is the slow reconnect path.
+   */
+  encodableOrSettleTerminal(items) {
+    const encodable = [];
+    for (const item of items) {
+      try {
+        encodeCallArgs(item.args, `args for '${item.functionPath}'`);
+        encodable.push(item);
+      } catch (error) {
+        this.settleReplayTerminal(item, error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+    return encodable;
+  }
+  /**
+   * Identity guard for one queued write about to replay: a write stamped under
+   * one identity must never replay under another. The live `queuedIdentities`
+   * map is the source of truth for the current session; a hydrated write whose
+   * id isn't in the map falls back to the stamp persisted with the record
+   * (`item.identity`), so a reload can't replay another user's queued writes.
+   * Only legacy records (persisted before stamps were durable —
+   * `item.identity === undefined`) replay under whatever identity is current.
+   *
+   * `Map.get` returns `undefined` for unstamped/hydrated ids and `item.identity`
+   * is `undefined` for legacy records; a persisted `null` (queued while signed
+   * out) is a real value that must not collapse into `undefined` — hence the
+   * explicit `=== undefined` check rather than `??`. Returns `true` when the
+   * write may replay; otherwise settles it `OFFLINE_IDENTITY_CHANGED` and returns
+   * `false`. Either way the live stamp is consumed.
+   */
+  passesReplayIdentityGate(item, currentIdentity) {
+    const liveStamp = item.id === void 0 ? void 0 : this.queuedIdentities.get(item.id);
+    const stamped = liveStamp === void 0 ? item.identity : liveStamp;
+    if (stamped !== void 0 && stamped !== currentIdentity && !this.isSameCredentialUnderTokenHash(stamped)) {
       this.queuedIdentities.delete(item.id ?? "");
+      this.unpersist(item.id);
+      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);
+      return false;
+    }
+    this.queuedIdentities.delete(item.id ?? "");
+    return true;
+  }
+  /** Settle a write that replayed successfully: confirm its optimistic layer against the echoed commit cursor BEFORE resolving, so the gapless drop is in place when the awaiter (and any confirming frame) observes the settle. */
+  settleReplaySuccess(item, value, commitCursor) {
+    this.unpersist(item.id);
+    item.onCommit?.(commitCursor);
+    item.resolve(value);
+    this.emitItemSettled(item, "committed");
+  }
+  /** Settle a write the server reached a coded verdict on: replaying would re-trigger the same failure (a poison-message loop), so drop it. */
+  settleReplayTerminal(item, error) {
+    this.unpersist(item.id);
+    item.reject(error);
+    this.emitItemSettled(item, "rejected", error);
+  }
+  /**
+   * Replay already-identity-gated writes one at a time on the single-call `/rpc`
+   * path, preserving FIFO order (parallel `.then()` chains would race the
+   * ordering callers depend on). Each replays under its stable `mutationId` so
+   * the server dedups a write it already committed (exactly-once). A coded error
+   * is a server verdict (drop it); a codeless (transport/transient) failure stops
+   * the flush and re-queues this write and every unreplayed one for the next
+   * reconnect — their callers stay pending, and the identity guard re-applies on
+   * retry via each record's persisted stamp.
+   */
+  async replaySequential(items) {
+    for (let index = 0; index < items.length; index += 1) {
+      const item = items[index];
+      if (!item) {
+        continue;
+      }
       try {
-        const value = await this.rpc(item.functionPath, item.args, item.shardKey, { captureBookmark: true, mutationId: item.id });
-        this.unpersist(item.id);
-        item.resolve(value);
+        let commitCursor;
+        const value = await this.rpc(item.functionPath, item.args, item.shardKey, {
+          captureBookmark: true,
+          mutationId: item.id,
+          onCommitCursor: (cursor) => {
+            commitCursor = cursor;
+          }
+        });
+        this.settleReplaySuccess(item, value, commitCursor);
       } catch (error) {
         if (error.code !== void 0) {
-          this.unpersist(item.id);
-          item.reject(error);
+          this.settleReplayTerminal(item, error);
           continue;
         }
-        this.offlineQueue.requeue(drained.slice(index));
+        this.offlineQueue.requeue(items.slice(index));
         return;
       }
     }
   }
+  /**
+   * Coalesce already-identity-gated writes for a single shard into ONE
+   * `/_lunora/rpc-batch` round trip (plan 088 follow-on). The worker forwards
+   * them to the shard DO, which replays each through its single-call dispatch, so
+   * per-entry `mutationId` idempotency and in-order application are inherited from
+   * the proven path. Per-slot demux mirrors {@link replaySequential}'s
+   * classification: success confirms the optimistic layer against the echoed
+   * `commitCursor`; a coded application verdict is terminal; a transient shard
+   * failure (`SHARD_UNAVAILABLE`/`SHARD_ERROR`), a missing slot, or a whole-batch
+   * transport failure re-queues for the next reconnect (never dropping a durable
+   * write). A whole-batch coded rejection (bad request / authorization denial the
+   * server reached a verdict on) is terminal for every entry.
+   *
+   * Returns the writes that must be re-queued and `stop` — `true` when the whole
+   * chunk failed at the transport level, so the caller leaves later chunks queued
+   * rather than sending on. The caller re-queues once, in order, so requeuing is
+   * NOT done here.
+   */
+  async replayBatched(items) {
+    if (!this.fetchImpl) {
+      return { requeue: items, stop: true };
+    }
+    let response;
+    try {
+      response = await this.fetchImpl(joinUrl(this.url, RPC_BATCH_PATH), {
+        body: JSON.stringify({
+          calls: items.map((item, index) => {
+            return {
+              args: encodeCallArgs(item.args, `args for '${item.functionPath}'`),
+              functionPath: item.functionPath,
+              id: index,
+              // Stable per-write key so the DO dedups a write it already
+              // committed (exactly-once), exactly as the single-call replay.
+              mutationId: item.id,
+              shardKey: item.shardKey
+            };
+          })
+        }),
+        headers: this.rpcRequestHeaders({ attachBookmark: true }),
+        method: "POST"
+      });
+    } catch {
+      return { requeue: items, stop: true };
+    }
+    const bookmark = response.headers.get("x-d1-bookmark");
+    if (bookmark) {
+      this.bookmark.set(bookmark);
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      return { requeue: items, stop: true };
+    }
+    if (!body.results) {
+      if (body.error) {
+        const error = reconstructError(body.error);
+        for (const item of items) {
+          this.settleReplayTerminal(item, error);
+        }
+        return { requeue: [], stop: false };
+      }
+      return { requeue: items, stop: true };
+    }
+    return { requeue: this.settleReplayBatchSlots(items, body.results), stop: false };
+  }
+  /**
+   * Demux a `/_lunora/rpc-batch` reply back onto the queued writes it replayed,
+   * in input order. Each slot's envelope classifies its write the same way
+   * {@link replaySequential} does: a success confirms the optimistic layer
+   * against the echoed `commitCursor`; a coded application verdict is terminal;
+   * a transient shard failure ({@link TRANSIENT_BATCH_ERROR_CODES}) or a slot the
+   * server never returned is returned for the caller to re-queue.
+   * @returns the writes that must be re-queued (transient slots), in input order
+   */
+  settleReplayBatchSlots(items, results) {
+    const bySlot = /* @__PURE__ */ new Map();
+    for (const entry of results) {
+      if (typeof entry.id === "number" && entry.body !== void 0) {
+        bySlot.set(entry.id, entry.body);
+      }
+    }
+    const requeue = [];
+    for (const [index, item] of items.entries()) {
+      const inner = bySlot.get(index);
+      if (inner === void 0) {
+        requeue.push(item);
+      } else if ("error" in inner) {
+        if (TRANSIENT_BATCH_ERROR_CODES.has(inner.error.code)) {
+          requeue.push(item);
+        } else {
+          this.settleReplayTerminal(item, reconstructError(inner.error));
+        }
+      } else {
+        this.settleReplaySuccess(item, decodeWire(inner.result), inner.commitCursor);
+      }
+    }
+    return requeue;
+  }
 }
 
 export { LunoraClient };