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

package/dist/index.d.mts

@@ -5740,6 +5740,39 @@ declare abstract class ShardDO {
   */
   private resolveReactiveOutcome;
   /**
+  * SECURITY BOUNDARY for cross-socket reactive dedup. A read is
+  * identity-INDEPENDENT only when its result cannot vary by the caller's
+  * verified identity — i.e. the admin/reserved introspection reads, which
+  * route to {@link executeAdminSubscription} and ignore the
+  * {@link SubscriptionIdentity} entirely.
+  *
+  * Everything else is identity-DEPENDENT and must NEVER be shared across
+  * sockets: a user query may be `rls()` / `ctx.auth`-scoped (different rows
+  * per identity), and a flag read ({@link FLAGS_FUNCTION_PREFIX}) evaluates
+  * the provider with the subscriber's identity (per-user targeting). Sharing
+  * one socket's result with another would leak one identity's rows/flags to a
+  * different identity, so this predicate gates {@link resolveReactiveOutcomeDeduped}
+  * shut for them.
+  */
+  protected isIdentityIndependent(functionPath: string): boolean;
+  /**
+  * Memoizing wrapper over {@link resolveReactiveOutcome}: flush-local sharing across sockets.
+  * Within a single {@link refreshSubscriptions} pass, N sockets subscribed to
+  * the SAME identity-independent `(functionPath, args)` re-run the query N
+  * times today (see the Case-6 fan-out characterization). When the read is
+  * identity-independent (admin/reserved — see {@link isIdentityIndependent})
+  * its result is the same for every socket, so the first run is cached (by its
+  * in-flight Promise, since the bounded worker pool runs sockets in parallel)
+  * and shared with the rest — collapsing N runs to ONE.
+  *
+  * Identity-DEPENDENT reads are passed straight through, UNCACHED: each socket
+  * must evaluate under its own by-value identity (RLS / `ctx.auth` / per-user
+  * flags), so they never share a result. The `cache` is created fresh per
+  * flush by the caller, so a result is never reused across passes (it would go
+  * stale after the next write).
+  */
+  private resolveReactiveOutcomeDeduped;
+  /**
   * Constant-time bearer check against `env.LUNORA_ADMIN_TOKEN`. Returns
   * `false` (closed) when the token is unset so admin introspection is
   * opt-in rather than exposed by default.
@@ -5919,8 +5952,30 @@ declare abstract class ShardDO {
   */
   private collectShapePokeParts;
   /**
+  * Drain the op-log range `(sinceSeq, upTo]` for `table` into the latest op per
+  * row id (collapsing multiple ops on the same row to the newest). Within one
+  * flush, every shape over the SAME `(table, sinceSeq, upTo)` reads the
+  * identical changelog slice, so the drained map is memoized in the
+  * caller-supplied `cache` (created fresh per flush) — N shapes on a table
+  * share ONE changelog drain instead of re-scanning it per shape. The
+  * per-shape membership probe still runs per shape (its predicate is
+  * identity/args-specific), so only the shared op read is collapsed.
+  */
+  private readShapeOpRange;
+  /**
+  * Read one page of the `__cdc_log` for a shape diff (table-scoped). A thin
+  * protected seam over {@link readCdcChanges}: it isolates the single
+  * changelog read that {@link readShapeOpRange} memoizes per flush, and gives
+  * tests a point to count the reads the op-range cache collapses.
+  */
+  protected readShapeCdcPage(sql: SqlExec, sinceSeq: number, tables: ReadonlySet<string>): {
+    changes: CdcChange[];
+    cursor: number;
+  };
+  /**
   * Build the row-ops for a shape over the op range `(sinceSeq, upTo]`. Reads
-  * the changelog (drained across pages), collapses to the latest op per row,
+  * the changelog (drained across pages via {@link readShapeOpRange}, shared
+  * across same-range shapes in a flush), collapses to the latest op per row,
   * then runs ONE membership probe ({@link selectShapeMemberIds}) over the
   * changed ids: a row still in the set → upsert with its post-image doc
   * (projected to the shape's columns); a row that left the set, or any delete,

package/dist/index.d.ts

@@ -5740,6 +5740,39 @@ declare abstract class ShardDO {
   */
   private resolveReactiveOutcome;
   /**
+  * SECURITY BOUNDARY for cross-socket reactive dedup. A read is
+  * identity-INDEPENDENT only when its result cannot vary by the caller's
+  * verified identity — i.e. the admin/reserved introspection reads, which
+  * route to {@link executeAdminSubscription} and ignore the
+  * {@link SubscriptionIdentity} entirely.
+  *
+  * Everything else is identity-DEPENDENT and must NEVER be shared across
+  * sockets: a user query may be `rls()` / `ctx.auth`-scoped (different rows
+  * per identity), and a flag read ({@link FLAGS_FUNCTION_PREFIX}) evaluates
+  * the provider with the subscriber's identity (per-user targeting). Sharing
+  * one socket's result with another would leak one identity's rows/flags to a
+  * different identity, so this predicate gates {@link resolveReactiveOutcomeDeduped}
+  * shut for them.
+  */
+  protected isIdentityIndependent(functionPath: string): boolean;
+  /**
+  * Memoizing wrapper over {@link resolveReactiveOutcome}: flush-local sharing across sockets.
+  * Within a single {@link refreshSubscriptions} pass, N sockets subscribed to
+  * the SAME identity-independent `(functionPath, args)` re-run the query N
+  * times today (see the Case-6 fan-out characterization). When the read is
+  * identity-independent (admin/reserved — see {@link isIdentityIndependent})
+  * its result is the same for every socket, so the first run is cached (by its
+  * in-flight Promise, since the bounded worker pool runs sockets in parallel)
+  * and shared with the rest — collapsing N runs to ONE.
+  *
+  * Identity-DEPENDENT reads are passed straight through, UNCACHED: each socket
+  * must evaluate under its own by-value identity (RLS / `ctx.auth` / per-user
+  * flags), so they never share a result. The `cache` is created fresh per
+  * flush by the caller, so a result is never reused across passes (it would go
+  * stale after the next write).
+  */
+  private resolveReactiveOutcomeDeduped;
+  /**
   * Constant-time bearer check against `env.LUNORA_ADMIN_TOKEN`. Returns
   * `false` (closed) when the token is unset so admin introspection is
   * opt-in rather than exposed by default.
@@ -5919,8 +5952,30 @@ declare abstract class ShardDO {
   */
   private collectShapePokeParts;
   /**
+  * Drain the op-log range `(sinceSeq, upTo]` for `table` into the latest op per
+  * row id (collapsing multiple ops on the same row to the newest). Within one
+  * flush, every shape over the SAME `(table, sinceSeq, upTo)` reads the
+  * identical changelog slice, so the drained map is memoized in the
+  * caller-supplied `cache` (created fresh per flush) — N shapes on a table
+  * share ONE changelog drain instead of re-scanning it per shape. The
+  * per-shape membership probe still runs per shape (its predicate is
+  * identity/args-specific), so only the shared op read is collapsed.
+  */
+  private readShapeOpRange;
+  /**
+  * Read one page of the `__cdc_log` for a shape diff (table-scoped). A thin
+  * protected seam over {@link readCdcChanges}: it isolates the single
+  * changelog read that {@link readShapeOpRange} memoizes per flush, and gives
+  * tests a point to count the reads the op-range cache collapses.
+  */
+  protected readShapeCdcPage(sql: SqlExec, sinceSeq: number, tables: ReadonlySet<string>): {
+    changes: CdcChange[];
+    cursor: number;
+  };
+  /**
   * Build the row-ops for a shape over the op range `(sinceSeq, upTo]`. Reads
-  * the changelog (drained across pages), collapses to the latest op per row,
+  * the changelog (drained across pages via {@link readShapeOpRange}, shared
+  * across same-range shapes in a flush), collapses to the latest op per row,
   * then runs ONE membership probe ({@link selectShapeMemberIds}) over the
   * changed ids: a row still in the set → upsert with its post-image doc
   * (projected to the shape's columns); a row that left the set, or any delete,

package/dist/index.mjs

@@ -23,7 +23,7 @@ export { RLS_UNWRAP_SYMBOL, RlsRequiredError, guardWriter } from './packem_share
 export { buildFtsMatch, ftsTableName, scoreDocument, stringifySearchText, tokenizeSearch } from './packem_shared/buildFtsMatch-BLEMawrp.mjs';
 export { M as MIN_ADMIN_TOKEN_LENGTH, a as MIN_AUTH_SECRET_LENGTH, b as buildSecurityAudit } from './packem_shared/security-audit-CucgBice.mjs';
 export { SESSION_DO_TTL_DEFAULT, SessionDO } from './packem_shared/SESSION_DO_TTL_DEFAULT-ilPZsVwu.mjs';
-export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-DKwBF3Jp.mjs';
+export { ROOT_DO_SIZE_WARN_BYTES, ROOT_SHARD_NAME, ShardDO } from './packem_shared/ROOT_DO_SIZE_WARN_BYTES-CM5_hVnA.mjs';
 export { SHARD_REGISTRY_DO_NAME, ShardRegistryDO } from './packem_shared/SHARD_REGISTRY_DO_NAME-BsAbi5Mn.mjs';
 export { MAX_SQL_ROWS, assertReadonly, runReadonlySql } from './packem_shared/MAX_SQL_ROWS-dDcFE1YZ.mjs';
 export { createSystemReader } from './packem_shared/createSystemReader-8CzSZP9V.mjs';

package/dist/packem_shared/{ROOT_DO_SIZE_WARN_BYTES-DKwBF3Jp.mjs → ROOT_DO_SIZE_WARN_BYTES-CM5_hVnA.mjs}

@@ -403,6 +403,23 @@ const buildPokeFrames = (parts, meta) => {
   return frames;
 };
 
+const runSocketPool = async (items, processOne, concurrency = 8) => {
+  let cursor = 0;
+  const worker = async () => {
+    let item = items[cursor];
+    cursor += 1;
+    while (item !== void 0) {
+      try {
+        await processOne(item);
+      } catch {
+      }
+      item = items[cursor];
+      cursor += 1;
+    }
+  };
+  await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
+};
+
 const DANGLING_SCAN_CAP = 5e3;
 const DANGLING_RESULT_CAP = 500;
 const DOC_COLUMN = "__doc__";
@@ -1374,6 +1391,9 @@ class ShardDO {
       }
       const result = await this.handleRpc(payload.functionPath, payload.args ?? {});
       this.recordPostDispatchBookkeeping(result, mutatorClass);
+      if (mutatorClass?.kind === "next") {
+        this.advanceClientMutationWatermark();
+      }
       const durationMs = Date.now() - dispatchStartedAt;
       this.recordFunctionCall(payload.functionPath, durationMs, void 0, this.currentScannedTables, this.currentIndexHits);
       this.flushStmtSamples();
@@ -3091,16 +3111,16 @@ class ShardDO {
       return jsonResponse({ error: { code: error.code, message: error.message } }, error.status);
     }
     if (error && typeof error === "object" && error.name === "ValidationError") {
-      const message2 = error instanceof Error ? error.message : "validation failed";
-      return jsonResponse({ error: { code: "VALIDATION_ERROR", message: message2 } }, 400);
+      const message = error instanceof Error ? error.message : "validation failed";
+      return jsonResponse({ error: { code: "VALIDATION_ERROR", message } }, 400);
     }
     if (error && typeof error === "object" && error.name === "LunoraError") {
       const lunoraError = error;
       const status = typeof lunoraError.status === "number" ? lunoraError.status : 500;
       return jsonResponse({ error: { code: lunoraError.code ?? "INTERNAL", message: lunoraError.message ?? "internal error" } }, status);
     }
-    const message = error instanceof Error ? error.message : "unknown error";
-    return jsonResponse({ error: { code: "RPC_FAILED", message } }, 500);
+    console.error("[@lunora/do] unhandled RPC error:", error);
+    return jsonResponse({ error: { code: "RPC_FAILED", message: "internal error" } }, 500);
   }
   /**
    * Serve a reserved admin-introspection RPC (`__lunora_admin__:*`) for the
@@ -3920,6 +3940,54 @@ class ShardDO {
     }
     return this.executeSubscription(functionPath, args, identity);
   }
+  /**
+   * SECURITY BOUNDARY for cross-socket reactive dedup. A read is
+   * identity-INDEPENDENT only when its result cannot vary by the caller's
+   * verified identity — i.e. the admin/reserved introspection reads, which
+   * route to {@link executeAdminSubscription} and ignore the
+   * {@link SubscriptionIdentity} entirely.
+   *
+   * Everything else is identity-DEPENDENT and must NEVER be shared across
+   * sockets: a user query may be `rls()` / `ctx.auth`-scoped (different rows
+   * per identity), and a flag read ({@link FLAGS_FUNCTION_PREFIX}) evaluates
+   * the provider with the subscriber's identity (per-user targeting). Sharing
+   * one socket's result with another would leak one identity's rows/flags to a
+   * different identity, so this predicate gates {@link resolveReactiveOutcomeDeduped}
+   * shut for them.
+   */
+  // eslint-disable-next-line class-methods-use-this, @typescript-eslint/member-ordering -- pure predicate over the function path; a protected method so the security boundary lives in one named place (and tests can probe it), co-located with the reactive dedup it gates rather than hoisted away from its only caller
+  isIdentityIndependent(functionPath) {
+    return functionPath.startsWith(ADMIN_FUNCTION_PREFIX);
+  }
+  /**
+   * Memoizing wrapper over {@link resolveReactiveOutcome}: flush-local sharing across sockets.
+   * Within a single {@link refreshSubscriptions} pass, N sockets subscribed to
+   * the SAME identity-independent `(functionPath, args)` re-run the query N
+   * times today (see the Case-6 fan-out characterization). When the read is
+   * identity-independent (admin/reserved — see {@link isIdentityIndependent})
+   * its result is the same for every socket, so the first run is cached (by its
+   * in-flight Promise, since the bounded worker pool runs sockets in parallel)
+   * and shared with the rest — collapsing N runs to ONE.
+   *
+   * Identity-DEPENDENT reads are passed straight through, UNCACHED: each socket
+   * must evaluate under its own by-value identity (RLS / `ctx.auth` / per-user
+   * flags), so they never share a result. The `cache` is created fresh per
+   * flush by the caller, so a result is never reused across passes (it would go
+   * stale after the next write).
+   */
+  resolveReactiveOutcomeDeduped(functionPath, args, isAdmin, identity, cache) {
+    if (!this.isIdentityIndependent(functionPath)) {
+      return this.resolveReactiveOutcome(functionPath, args, isAdmin, identity);
+    }
+    const key = reactiveCacheKey(functionPath, args, null);
+    const cached = cache.get(key);
+    if (cached !== void 0) {
+      return cached;
+    }
+    const pending = this.resolveReactiveOutcome(functionPath, args, isAdmin, identity);
+    cache.set(key, pending);
+    return pending;
+  }
   /**
    * Constant-time bearer check against `env.LUNORA_ADMIN_TOKEN`. Returns
    * `false` (closed) when the token is unset so admin introspection is
@@ -3944,6 +4012,7 @@ class ShardDO {
    * 4. On normal completion send `{type:"complete"}`; on throw send
    * `{type:"error"}`. Either way drop the controller.
    */
+  // eslint-disable-next-line sonarjs/cognitive-complexity -- the stream lifecycle (ack → chunk pump → complete/error) plus the structured-vs-redacted error branch is the wire protocol and reads clearer inline than split across helpers sharing the controller + socket
   async handleStream(ws, id, functionPath, args) {
     const iterable = this.executeStream(functionPath, args);
     if (!iterable) {
@@ -3984,10 +4053,15 @@ class ShardDO {
       }
     } catch (error) {
       const { code } = error;
-      const message = error instanceof Error ? error.message : String(error);
+      const isStructured = typeof code === "string";
+      if (!isStructured) {
+        console.error("[@lunora/do] unhandled stream error:", error);
+      }
+      const rawMessage = error instanceof Error ? error.message : String(error);
+      const message = isStructured ? rawMessage : "internal error";
       ws.send(
         JSON.stringify({
-          error: { code: typeof code === "string" ? code : "INTERNAL_SERVER_ERROR", message },
+          error: { code: isStructured ? code : "INTERNAL_SERVER_ERROR", message },
           id,
           type: "error"
         })
@@ -4121,6 +4195,7 @@ class ShardDO {
     const sockets = [...this.state.getWebSockets()];
     const frameCursor = this.currentCdcCursor();
     const frameEpoch = this.currentCdcEpoch();
+    const reactiveRunCache = /* @__PURE__ */ new Map();
     const refreshOne = async (ws) => {
       if (this.isSocketExpired(ws)) {
         this.dropExpiredSocket(ws);
@@ -4138,10 +4213,13 @@ class ShardDO {
           continue;
         }
         try {
-          const outcome = await this.resolveReactiveOutcome(functionPath, query.args ?? {}, isAdmin, {
-            identity: attachment.identity,
-            userId: attachment.userId
-          });
+          const outcome = await this.resolveReactiveOutcomeDeduped(
+            functionPath,
+            query.args ?? {},
+            isAdmin,
+            { identity: attachment.identity, userId: attachment.userId },
+            reactiveRunCache
+          );
           if (!outcome) {
             continue;
           }
@@ -4152,18 +4230,7 @@ class ShardDO {
         }
       }
     };
-    const concurrency = 8;
-    let cursor = 0;
-    const worker = async () => {
-      let socket = sockets[cursor];
-      cursor += 1;
-      while (socket !== void 0) {
-        await refreshOne(socket);
-        socket = sockets[cursor];
-        cursor += 1;
-      }
-    };
-    await Promise.all(Array.from({ length: Math.min(concurrency, sockets.length) }, () => worker()));
+    await runSocketPool(sockets, refreshOne);
   }
   /**
    * Seed a freshly-registered subscription with its first value. Runs the
@@ -4321,6 +4388,7 @@ class ShardDO {
     const sockets = [...this.state.getWebSockets()];
     const checkpoint = frameCursor ?? this.currentCdcCursor() ?? 0;
     const sql = this.sql;
+    const opRangeCache = /* @__PURE__ */ new Map();
     const pokeOne = async (ws) => {
       if (this.isSocketExpired(ws)) {
         this.dropExpiredSocket(ws);
@@ -4331,32 +4399,24 @@ class ShardDO {
       if (!shapes) {
         return;
       }
-      const identity = { identity: attachment.identity, userId: attachment.userId };
-      const { emptyAdvanced, partAdvanced, parts } = this.collectShapePokeParts(ws, shapes, identity, changed, checkpoint, sql);
-      for (const subId of emptyAdvanced) {
-        this.recordShapeMemo(ws, subId, checkpoint);
-      }
-      if (parts.length > 0) {
-        await awaitWsDrain(ws);
-        if (this.sendPoke(ws, parts, checkpoint, frameEpoch, void 0)) {
-          for (const subId of partAdvanced) {
-            this.recordShapeMemo(ws, subId, checkpoint);
+      try {
+        const identity = { identity: attachment.identity, userId: attachment.userId };
+        const { emptyAdvanced, partAdvanced, parts } = this.collectShapePokeParts(ws, shapes, identity, changed, checkpoint, sql, opRangeCache);
+        for (const subId of emptyAdvanced) {
+          this.recordShapeMemo(ws, subId, checkpoint);
+        }
+        if (parts.length > 0) {
+          await awaitWsDrain(ws);
+          if (this.sendPoke(ws, parts, checkpoint, frameEpoch, void 0)) {
+            for (const subId of partAdvanced) {
+              this.recordShapeMemo(ws, subId, checkpoint);
+            }
           }
         }
+      } catch {
       }
     };
-    const concurrency = 8;
-    let index = 0;
-    const worker = async () => {
-      let socket = sockets[index];
-      index += 1;
-      while (socket !== void 0) {
-        await pokeOne(socket);
-        socket = sockets[index];
-        index += 1;
-      }
-    };
-    await Promise.all(Array.from({ length: Math.min(concurrency, sockets.length) }, () => worker()));
+    await runSocketPool(sockets, pokeOne);
   }
   /**
    * Diff every op-log-backed shape a socket holds against this flush, splitting
@@ -4367,7 +4427,7 @@ class ShardDO {
    * diffs advance unconditionally; part-bearing shapes advance only once the
    * caller confirms the poke was delivered.
    */
-  collectShapePokeParts(ws, shapes, identity, changed, checkpoint, sql) {
+  collectShapePokeParts(ws, shapes, identity, changed, checkpoint, sql, opRangeCache) {
     const parts = [];
     const emptyAdvanced = [];
     const partAdvanced = [];
@@ -4378,7 +4438,7 @@ class ShardDO {
           continue;
         }
         const memoCursor = this.shapeMemos.get(ws)?.get(subId)?.cursor ?? 0;
-        const rowsPatch = this.buildShapeDiff(sql, resolved, memoCursor, checkpoint);
+        const rowsPatch = this.buildShapeDiff(sql, resolved, memoCursor, checkpoint, opRangeCache);
         if (rowsPatch.length > 0) {
           parts.push({ rowsPatch, shapeId: subId });
           partAdvanced.push(subId);
@@ -4392,21 +4452,26 @@ class ShardDO {
     return { emptyAdvanced, partAdvanced, parts };
   }
   /**
-   * Build the row-ops for a shape over the op range `(sinceSeq, upTo]`. Reads
-   * the changelog (drained across pages), collapses to the latest op per row,
-   * then runs ONE membership probe ({@link selectShapeMemberIds}) over the
-   * changed ids: a row still in the set → upsert with its post-image doc
-   * (projected to the shape's columns); a row that left the set, or any delete,
-   * → `delete(key)` (a delete carries no post-image, so membership is
-   * unknowable from the op alone — the client no-ops an unknown key).
+   * Drain the op-log range `(sinceSeq, upTo]` for `table` into the latest op per
+   * row id (collapsing multiple ops on the same row to the newest). Within one
+   * flush, every shape over the SAME `(table, sinceSeq, upTo)` reads the
+   * identical changelog slice, so the drained map is memoized in the
+   * caller-supplied `cache` (created fresh per flush) — N shapes on a table
+   * share ONE changelog drain instead of re-scanning it per shape. The
+   * per-shape membership probe still runs per shape (its predicate is
+   * identity/args-specific), so only the shared op read is collapsed.
    */
-  // eslint-disable-next-line class-methods-use-this -- a pure op-page→membership-diff transform that reads only its args; kept a private method to sit beside the shape-poke pipeline it belongs to.
-  buildShapeDiff(sql, resolved, sinceSeq, upTo) {
+  readShapeOpRange(sql, table, sinceSeq, upTo, cache) {
+    const key = `${table}\0${String(sinceSeq)}\0${String(upTo)}`;
+    const cached = cache?.get(key);
+    if (cached !== void 0) {
+      return cached;
+    }
     const latest = /* @__PURE__ */ new Map();
-    const tables = /* @__PURE__ */ new Set([resolved.table]);
+    const tables = /* @__PURE__ */ new Set([table]);
     let from = sinceSeq;
     for (; ; ) {
-      const { changes, cursor } = readCdcChanges(sql, { sinceSeq: from, tables });
+      const { changes, cursor } = this.readShapeCdcPage(sql, from, tables);
       for (const change of changes) {
         latest.set(change.id, change);
       }
@@ -4415,6 +4480,31 @@ class ShardDO {
       }
       from = cursor;
     }
+    cache?.set(key, latest);
+    return latest;
+  }
+  /**
+   * Read one page of the `__cdc_log` for a shape diff (table-scoped). A thin
+   * protected seam over {@link readCdcChanges}: it isolates the single
+   * changelog read that {@link readShapeOpRange} memoizes per flush, and gives
+   * tests a point to count the reads the op-range cache collapses.
+   */
+  // eslint-disable-next-line class-methods-use-this, @typescript-eslint/member-ordering -- thin pass-through seam over the module-level reader; a protected method so the op-range cache + tests share one read point, co-located with the poke path it serves rather than hoisted away from its only caller
+  readShapeCdcPage(sql, sinceSeq, tables) {
+    return readCdcChanges(sql, { sinceSeq, tables });
+  }
+  /**
+   * Build the row-ops for a shape over the op range `(sinceSeq, upTo]`. Reads
+   * the changelog (drained across pages via {@link readShapeOpRange}, shared
+   * across same-range shapes in a flush), collapses to the latest op per row,
+   * then runs ONE membership probe ({@link selectShapeMemberIds}) over the
+   * changed ids: a row still in the set → upsert with its post-image doc
+   * (projected to the shape's columns); a row that left the set, or any delete,
+   * → `delete(key)` (a delete carries no post-image, so membership is
+   * unknowable from the op alone — the client no-ops an unknown key).
+   */
+  buildShapeDiff(sql, resolved, sinceSeq, upTo, opRangeCache) {
+    const latest = this.readShapeOpRange(sql, resolved.table, sinceSeq, upTo, opRangeCache);
     if (latest.size === 0) {
       return [];
     }
@@ -4753,6 +4843,10 @@ class ShardDO {
     const existing = memos.get(subId);
     if (existing?.lastJson === json) {
       existing.tables = outcome.tables;
+      const settledWatermark = this.socketClientWatermark(ws);
+      if (settledWatermark !== void 0) {
+        trySendFrame(ws, `{"type":"settled","id":${JSON.stringify(subId)},"lastMutationId":${String(settledWatermark)}${cursorSuffix}}`);
+      }
       return;
     }
     const deltaFrames = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/do",
-  "version": "1.0.0-alpha.10",
+  "version": "1.0.0-alpha.12",
   "description": "Lunora Durable Objects: ShardDO (SQLite, OCC, hibernated WebSocket subscriptions) and SessionDO",
   "keywords": [
     "cloudflare",