@lunora/client 1.0.0-alpha.10 → 1.0.0-alpha.12

package/dist/packem_shared/{LunoraClient-CgZ6FhKP.mjs → LunoraClient-wh6w9Ivn.mjs}

@@ -1,12 +1,231 @@
-import { S as SubscriptionRegistry, s as stableStringify } from './subscription-C1Jy7HiF.mjs';
+import { S as SubscriptionRegistry, s as stableStringify } from './subscription-DoyO04-2.mjs';
 import createInMemoryBookmarkStorage from './createInMemoryBookmarkStorage-BoN7a7TH.mjs';
 import { isMutationDelta, applyDelta } from './applyDelta-4jFGTPA3.mjs';
 import { a as applyOptimisticLayer, d as dropConfirmedLayers, n as notifySubscription, f as foldOptimistic, c as createLocalStore } from './local-store-BNgN3Dw3.mjs';
 import { O as OfflineQueue, n as nextId, i as isStaleVersion, r as reportPersistenceError } from './offline-queue-7Wc4onA0.mjs';
-import { queryCacheKey } from './createInMemoryQueryCache-B1PQ9Twl.mjs';
+import { resolvePersistenceAdapter } from './createInMemoryPersistence-DlFjWtOm.mjs';
+import { resolveQueryCacheAdapter, queryCacheKey } from './createInMemoryQueryCache-4AkTV38-.mjs';
 import { createReconnect } from './createReconnect-Di_-oHH7.mjs';
 import { createStream } from './DEFAULT_MAX_BUFFER-BDkqO5PW.mjs';
 
+const MAX_BATCH_ENTRIES = 500;
+
+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 });
+          }
+          Object.assign(error, decodeWire(value[4], depth + 1));
+          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) {
@@ -33,6 +252,7 @@ class Listeners {
 }
 
 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) => {
@@ -170,6 +390,34 @@ 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);
+  }
+  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;
@@ -319,9 +567,9 @@ class LunoraClient {
     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.persistence = resolvePersistenceAdapter(options.persistence, options.outbox === void 0);
     this.persistenceVersion = options.persistenceVersion;
-    this.queryCache = options.queryCache === false ? void 0 : options.queryCache;
+    this.queryCache = resolveQueryCacheAdapter(options.queryCache);
     this.onPersistenceError = options.offlineQueue?.onPersistenceError;
     this.offlineQueue = new OfflineQueue(options.offlineQueue, {
       onEvict: (entry, error) => {
@@ -330,7 +578,7 @@ class LunoraClient {
       onSizeChange: (size) => {
         this.pendingChangeListeners.emit(size);
       },
-      persistence: options.persistence,
+      persistence: this.persistence,
       version: options.persistenceVersion
     });
     this.outbox = options.outbox;
@@ -649,7 +897,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" });
     }
   }
   /**
@@ -722,6 +970,62 @@ class LunoraClient {
     }
     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 Error("LunoraClient is closed");
+    }
+    if (!this.fetchImpl) {
+      throw new Error("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 Error(`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 Error(`LunoraClient: batch request failed (status ${response.status.toString()})`);
+    }
+    return demuxBatchResults(body.results ?? [], calls.length);
+  }
   /**
    * Invoke a mutation. Errors propagate as rejections.
    *
@@ -1548,7 +1852,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);
@@ -1974,7 +2285,10 @@ class LunoraClient {
     }
     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"
     });
@@ -1992,9 +2306,7 @@ class LunoraClient {
       throw new Error(`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}` : "";
@@ -2002,7 +2314,7 @@ class LunoraClient {
     }
     flags.onMutationAck?.(body.lastMutationId);
     flags.onCommitCursor?.(body.commitCursor);
-    return body.result;
+    return decodeWire(body.result);
   }
   /**
    * Authenticated request to a non-RPC admin endpoint (the scheduler list /
@@ -2324,7 +2636,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": {
@@ -2404,7 +2716,9 @@ class LunoraClient {
       return;
     }
     const existing = buffer.parts.get(message.shapeId) ?? [];
-    existing.push(...message.rowsPatch);
+    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);
@@ -2550,9 +2864,9 @@ 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;
+    const delta = decodeWire(message.delta);
     if (isMutationDelta(delta) && state.serverBase !== void 0) {
       const merged = applyDelta(state.serverBase, delta);
       if (merged !== void 0) {
@@ -2567,9 +2881,10 @@ 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 {
       }
     }
@@ -2673,24 +2988,123 @@ 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);
-        this.emitItemSettled(item, "rejected", 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.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 {
         let commitCursor;
         const value = await this.rpc(item.functionPath, item.args, item.shardKey, {
@@ -2700,22 +3114,116 @@ class LunoraClient {
             commitCursor = cursor;
           }
         });
-        this.unpersist(item.id);
-        item.onCommit?.(commitCursor);
-        item.resolve(value);
-        this.emitItemSettled(item, "committed");
+        this.settleReplaySuccess(item, value, commitCursor);
       } catch (error) {
         if (error.code !== void 0) {
-          this.unpersist(item.id);
-          item.reject(error);
-          this.emitItemSettled(item, "rejected", 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 };